# 部署指南：腾讯云 + 1Panel + OpenResty + Gitea CI/CD

## 目录

1. [架构概览](#1-架构概览)
2. [服务器准备](#2-服务器准备)
3. [配置环境变量](#3-配置环境变量)
4. [创建数据库](#4-创建数据库)
5. [手动首次部署](#5-手动首次部署)
6. [在 1Panel 中配置 OpenResty](#6-在-1panel-中配置-openresty)
7. [DNS 解析配置](#7-dns-解析配置)
8. [配置 Gitea Actions CI/CD](#8-配置-gitea-actions-cicd)
9. [验证部署](#9-验证部署)
10. [日常运维](#10-日常运维)

---

## 1. 架构概览

```
用户浏览器
    │
    ▼
OpenResty (1Panel 管理, SSL, 端口 80/443)
    │
    ├── makefire.fun       → 127.0.0.1:3001 (Frontend Nginx 容器)
    └── api.makefire.fun   → 127.0.0.1:8000 (Backend FastAPI 容器)
                                    │
                                    ▼
                            PostgreSQL (1Panel 已有容器, 1panel-network)
```

**关键设计决策：**
- 后端和前端容器只绑定 `127.0.0.1`，不对外暴露，由 OpenResty 统一反代
- 所有容器加入 `1panel-network`，可直接通过 `postgresql` 主机名访问已有数据库
- 不使用 Traefik（用 1Panel 自带的 OpenResty 替代）
- 不启动独立 PostgreSQL 容器（复用已有的）

---

## 2. 服务器准备

### 2.1 创建部署目录

```bash
# SSH 登录服务器后执行
sudo mkdir -p /opt/fastapi-app
sudo chown $USER:$USER /opt/fastapi-app
```

### 2.2 初始化 Git 仓库（在 Gitea 上）

1. 登录 Gitea（`http://your-server-ip:3000`）
2. 创建新仓库，例如 `full-stack-fastapi`
3. 在本地开发机上添加 Gitea 远程仓库：

```bash
cd /Users/weifeng/Workspace/full-stack-fastapi-template

# 添加 Gitea 远程
git remote add gitea http://your-server-ip:3000/your-username/full-stack-fastapi.git

# 推送代码
git push gitea main
```

---

## 3. 配置环境变量

### 3.1 在服务器上创建生产环境文件

```bash
cd /opt/fastapi-app

# 复制示例文件（首次需要从代码仓库获取）
cp .env.production.example .env.production
```

### 3.2 修改关键配置

```bash
nano .env.production
```

**必须修改的项：**

```bash
# 生成强随机密钥
SECRET_KEY=$(openssl rand -hex 32)
echo "生成的 SECRET_KEY: $SECRET_KEY"

# 设置强管理员密码
FIRST_SUPERUSER_PASSWORD=你的强密码
```

> ⚠️ `SECRET_KEY` 和 `FIRST_SUPERUSER_PASSWORD` 不能使用默认值 `changethis`，否则生产环境会报错。

---

## 4. 创建数据库

在已有的 PostgreSQL 中为本项目创建专用数据库：

```bash
# 方法一：使用 docker exec
docker exec -it 1Panel-postgresql-bxrK psql -U user_ZPKMQ6 -c "CREATE DATABASE app;"

# 验证数据库是否创建成功
docker exec -it 1Panel-postgresql-bxrK psql -U user_ZPKMQ6 -c "\l" | grep app
```

如果你想创建专用用户（更安全，可选）：

```bash
docker exec -it 1Panel-postgresql-bxrK psql -U user_ZPKMQ6 -c "
CREATE USER fastapi_user WITH PASSWORD 'your_strong_password';
GRANT ALL PRIVILEGES ON DATABASE app TO fastapi_user;
ALTER DATABASE app OWNER TO fastapi_user;
"
```

> 如果使用专用用户，记得更新 `.env.production` 中的 `POSTGRES_USER` 和 `POSTGRES_PASSWORD`。

---

## 5. 手动首次部署

### 5.1 克隆代码到服务器

```bash
cd /opt/fastapi-app
git clone http://localhost:3000/your-username/full-stack-fastapi.git .
# 或者如果已经有代码
git pull origin main
```

### 5.2 复制环境变量文件

确保 `.env.production` 在 `/opt/fastapi-app/` 目录下。

### 5.3 构建和启动

```bash
cd /opt/fastapi-app

# 构建镜像
docker compose -f compose.prod.yml build

# 启动服务
docker compose -f compose.prod.yml up -d

# 查看日志
docker compose -f compose.prod.yml logs -f
```

### 5.4 验证容器状态

```bash
# 查看运行状态
docker compose -f compose.prod.yml ps

# 测试后端
curl http://127.0.0.1:8000/api/v1/utils/health-check/

# 测试前端
curl -I http://127.0.0.1:3001
```

---

## 6. 在 1Panel 中配置 OpenResty

### 6.1 创建前端网站

1. 打开 1Panel → **网站** → **创建网站**
2. 选择 **反向代理**
3. 配置：
   - **主域名**: `makefire.fun`
   - **代理地址**: `http://127.0.0.1:3001`
4. 点击创建

### 6.2 创建后端 API 网站

1. **网站** → **创建网站** → **反向代理**
2. 配置：
   - **主域名**: `api.makefire.fun`
   - **代理地址**: `http://127.0.0.1:8000`
3. 点击创建

### 6.3 配置 SSL 证书

对每个网站：

1. 点击网站名称进入设置
2. 选择 **HTTPS** 标签
3. 选择 **申请证书** → **Let's Encrypt**
4. 勾选 **自动续签**
5. 勾选 **HTTP → HTTPS 强制跳转**

### 6.4 修改后端网站配置（可选优化）

进入 `api.makefire.fun` 网站设置 → **配置文件**，在 `location /` 块中添加：

```nginx
# WebSocket 支持
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

# 请求体大小限制
client_max_body_size 10m;

# 超时
proxy_connect_timeout 60s;
proxy_send_timeout 60s;
proxy_read_timeout 60s;
```

> 完整参考配置见项目根目录的 `openresty-example.conf`。

---

## 7. DNS 解析配置

在你的域名 DNS 管理处（腾讯云 DNS 或其他）添加：

| 记录类型 | 主机记录 | 记录值 | TTL |
|---------|---------|--------|-----|
| A | @ | 你的服务器 IP | 600 |
| A | api | 你的服务器 IP | 600 |

> 如果使用腾讯云域名，进入 **DNS 解析 DNSPod** 配置。

---

## 8. 配置 Gitea Actions CI/CD

### 8.1 安装 Gitea Actions Runner

```bash
# 1. 下载 Gitea Actions Runner
# 访问 https://gitea.com/gitea/act_runner/releases 获取最新版本
wget https://gitea.com/gitea/act_runner/releases/download/v0.2.11/act_runner-0.2.11-linux-amd64
chmod +x act_runner-0.2.11-linux-amd64
sudo mv act_runner-0.2.11-linux-amd64 /usr/local/bin/act_runner

# 2. 生成配置文件
cd /opt
act_runner generate-config > act_runner_config.yaml
```

### 8.2 修改 Runner 配置

编辑 `/opt/act_runner_config.yaml`，关键修改：

```yaml
runner:
  # 标签，决定 workflow 中 runs-on 可以匹配的值
  labels:
    - "ubuntu-latest:host"
    # ↑ 使用 host 模式，直接在服务器上运行（不在 Docker 中套 Docker）
```

> **为什么用 `host` 模式？** 因为 workflow 需要执行 `docker compose` 命令来管理服务器上的容器。若在容器中运行，需要额外配置 Docker-in-Docker，对低内存服务器更加不友好。

### 8.3 注册 Runner

```bash
# 1. 在 Gitea 中获取 Runner Token
#    进入仓库 → Settings → Actions → Runners → 点击 "Create new runner"
#    复制显示的 Token

# 2. 注册
act_runner register \
  --instance http://localhost:3000 \
  --token YOUR_RUNNER_TOKEN \
  --name my-runner \
  --labels "ubuntu-latest:host" \
  --config /opt/act_runner_config.yaml \
  --no-interactive

# 3. 启动（测试）
act_runner daemon --config /opt/act_runner_config.yaml
```

### 8.4 设置为系统服务（推荐）

```bash
sudo tee /etc/systemd/system/gitea-runner.service << 'EOF'
[Unit]
Description=Gitea Actions Runner
After=network.target docker.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/fastapi-app
ExecStart=/usr/local/bin/act_runner daemon --config /opt/act_runner_config.yaml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable gitea-runner
sudo systemctl start gitea-runner

# 查看状态
sudo systemctl status gitea-runner
```

### 8.5 配置 Gitea Secrets

在 Gitea 仓库中配置环境变量密钥：

1. 进入仓库 → **Settings** → **Actions** → **Secrets**
2. 添加以下 Secrets：

| Secret 名称 | 值 |
|-------------|-----|
| `DOMAIN` | `makefire.fun` |
| `FRONTEND_HOST` | `https://makefire.fun` |
| `PROJECT_NAME` | `Full Stack FastAPI Project` |
| `STACK_NAME` | `full-stack-fastapi-project` |
| `BACKEND_CORS_ORIGINS` | `https://makefire.fun,https://api.makefire.fun` |
| `SECRET_KEY` | *(用 `openssl rand -hex 32` 生成)* |
| `FIRST_SUPERUSER` | `admin@makefire.fun` |
| `FIRST_SUPERUSER_PASSWORD` | *(你的强密码)* |
| `SMTP_HOST` | *(留空或填写)* |
| `SMTP_USER` | *(留空或填写)* |
| `SMTP_PASSWORD` | *(留空或填写)* |
| `EMAILS_FROM_EMAIL` | `info@makefire.fun` |
| `SMTP_TLS` | `True` |
| `SMTP_SSL` | `False` |
| `SMTP_PORT` | `587` |
| `POSTGRES_SERVER` | `postgresql` |
| `POSTGRES_PORT` | `5432` |
| `POSTGRES_DB` | `app` |
| `POSTGRES_USER` | `user_ZPKMQ6` |
| `POSTGRES_PASSWORD` | `password_CYmsGt` |
| `SENTRY_DSN` | *(留空)* |
| `DOCKER_IMAGE_BACKEND` | `backend` |
| `DOCKER_IMAGE_FRONTEND` | `frontend` |

### 8.6 启用 Gitea Actions

1. 进入仓库 → **Settings** → **Repository**
2. 确保 **Actions** 功能已启用
3. 如果 Gitea 全局未启用 Actions，需要在 Gitea 配置文件中添加：

```ini
; 在 /opt/1panel/apps/gitea/gitea/data/gitea/conf/app.ini 中
[actions]
ENABLED = true
```

修改后重启 Gitea 容器：

```bash
docker restart 1Panel-gitea-FSXv
```

---

## 9. 验证部署

### 9.1 本地访问测试

```bash
# 后端健康检查
curl http://127.0.0.1:8000/api/v1/utils/health-check/

# 前端页面
curl -I http://127.0.0.1:3001
```

### 9.2 域名访问测试

```bash
# 前端
curl -I https://makefire.fun

# 后端 API 文档
curl -I https://api.makefire.fun/docs

# 后端健康检查
curl https://api.makefire.fun/api/v1/utils/health-check/
```

### 9.3 CI/CD 测试

```bash
# 在本地开发机上
cd /Users/weifeng/Workspace/full-stack-fastapi-template
echo "# test" >> README.md
git add .
git commit -m "test: trigger CI/CD"
git push gitea main
```

然后在 Gitea 仓库的 **Actions** 标签中查看运行状态。

---

## 10. 日常运维

### 查看日志

```bash
cd /opt/fastapi-app
docker compose -f compose.prod.yml logs -f backend   # 后端日志
docker compose -f compose.prod.yml logs -f frontend   # 前端日志
docker compose -f compose.prod.yml logs -f            # 全部日志
```

### 重启服务

```bash
docker compose -f compose.prod.yml restart backend
docker compose -f compose.prod.yml restart frontend
```

### 手动重新部署

```bash
cd /opt/fastapi-app
git pull origin main
docker compose -f compose.prod.yml build
docker compose -f compose.prod.yml down
docker compose -f compose.prod.yml up -d
```

### 清理 Docker 资源

```bash
# 清理无用镜像（释放磁盘空间）
docker image prune -f
docker system prune -f
```

### 数据库备份

```bash
# 备份
docker exec 1Panel-postgresql-bxrK pg_dump -U user_ZPKMQ6 app > backup_$(date +%Y%m%d).sql

# 恢复
docker exec -i 1Panel-postgresql-bxrK psql -U user_ZPKMQ6 app < backup_20260311.sql
```