full-stack-fastapi/deploy-tencent.md

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

目录

1. 架构概览
2. 服务器准备
3. 配置环境变量
4. 创建数据库
5. 手动首次部署
6. 在 1Panel 中配置 OpenResty
7. DNS 解析配置
8. 配置 Gitea Actions CI/CD
9. 验证部署
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 创建部署目录

# 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 远程仓库：

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 在服务器上创建生产环境文件

cd /opt/fastapi-app

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

3.2 修改关键配置

nano .env.production

必须修改的项：

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

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

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

---

4. 创建数据库

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

# 方法一：使用 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

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

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 克隆代码到服务器

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 构建和启动

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 验证容器状态

# 查看运行状态
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 / 块中添加：

# 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

# 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，关键修改：

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

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

8.3 注册 Runner

# 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 设置为系统服务（推荐）

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 配置文件中添加：

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

修改后重启 Gitea 容器：

docker restart 1Panel-gitea-FSXv

---

9. 验证部署

9.1 本地访问测试

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

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

9.2 域名访问测试

# 前端
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 测试

# 在本地开发机上
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. 日常运维

查看日志

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            # 全部日志

重启服务

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

手动重新部署

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 资源

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

数据库备份

# 备份
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