docs(ci): 记录生产流水线决策与运行手册

固化 Tag 发布策略、Runner 信任边界、Secret 位置、数据库回滚限制，以及 Runner 安装、发布、验证和故障恢复步骤。
2026-07-17 12:41:47 +08:00
parent 745811cc6d
commit db85487b73
3 changed files with 145 additions and 0 deletions
@@ -0,0 +1,90 @@
+# 生产 CI/CD 运行手册
+
+## 流水线约定
+
+- Runner：`easyai-gateway-act-runner.service`
+- Runner 标签：`easyai-gateway-linux:host`
+- Runner 状态：`/var/lib/easyai-gateway-runner`
+- 工具链：`/opt/easyai-gateway-ci`
+- Gitea：`https://git.51easyai.com/BCAI/easyai-ai-gateway`
+- 生产入口：`https://ai.51easyai.com`
+- 部署目录：`/root/easyai-ai-gateway-deploy`
+
+PR、`main` Push 和版本 Tag 都会执行格式、Go vet/test、govulncheck、前端 lint/test/build、依赖审计、Compose 校验、Trivy 扫描与 API/Web 镜像构建。只有版本 Tag 会执行最后的生产发布步骤。
+
+## 首次安装或修复 Runner
+
+从 Gitea 仓库设置的 Actions Runner 页面取得一次性仓库注册 Token，在服务器可信 checkout 中执行：
+
+```bash
+RUNNER_REGISTRATION_TOKEN='<一次性 Token>' ./scripts/provision-ci-runner.sh
+```
+
+Token 只通过进程环境传入。生成的 `/var/lib/easyai-gateway-runner/.runner` 必须保持 `0600`，不得复制到仓库、报告或聊天记录。
+
+验证：
+
+```bash
+systemctl is-active easyai-gateway-act-runner.service
+systemctl is-enabled easyai-gateway-act-runner.service
+journalctl -u easyai-gateway-act-runner.service --since '15 minutes ago'
+```
+
+Runner 使用 `daemon --once`。每个 Job 结束后进程自然退出，再由 systemd 启动新的长轮询进程。
+
+## 发布生产版本
+
+1. 合并到 `main`，等待 `ci / verify (push)` 成功。
+2. 在已验证的 `main` 提交上创建语义版本 Tag。
+3. 推送 Tag，等待同一 CI Job 完成镜像扫描、发布、数据库备份、迁移和公共健康检查。
+
+```bash
+git switch main
+git pull --ff-only
+git tag -a v0.1.1 -m 'release: v0.1.1'
+git push origin v0.1.1
+```
+
+流水线会部署 Tag 指向提交的完整 Git SHA，而不是 `latest` 或版本号镜像。
+
+## 发布后验证
+
+```bash
+curl -fsS https://ai.51easyai.com/gateway-api/healthz
+curl -fsS https://ai.51easyai.com/gateway-api/readyz
+ssh root@110.42.51.33 'cd /root/easyai-ai-gateway-deploy && ./gateway-ops.sh ps'
+```
+
+同时检查服务器磁盘、API 日志和数据库容器健康状态。发布后的首小时如出现错误率翻倍、P95 延迟增加 50%、数据完整性或安全问题，应立即回滚。
+
+## 应用回滚
+
+发布失败时脚本会自动恢复 `.release.env` 中的上一组 API/Web 镜像并重复健康检查。人工回滚到一个仍存在于本机或 Registry 的历史 Git SHA：
+
+```bash
+sudo /usr/local/sbin/easyai-ai-gateway-release <40 位历史 Git SHA>
+```
+
+该操作也会先创建数据库备份。不要把 `latest`、分支名或版本号传给发布助手。
+
+## 数据库恢复
+
+备份位于 `/var/backups/easyai-ai-gateway`，默认只保留最近 5 份。应用回滚不会自动恢复数据库。只有确认需要回退数据且已经停止写入后，才能由操作员选择备份执行 `pg_restore`；恢复前必须再保留当前数据库副本。
+
+## Runner 故障恢复
+
+重启前先确认没有构建、扫描或部署子进程：
+
+```bash
+ps -u easyai-gateway-runner -o pid,ppid,etime,cmd --forest
+systemctl status easyai-gateway-act-runner.service --no-pager
+```
+
+确认空闲后才执行：
+
+```bash
+systemctl restart easyai-gateway-act-runner.service
+journalctl -u easyai-gateway-act-runner.service -n 50 --no-pager
+```
+
+不要因为日志暂时没有新增就用定时器重启 Runner；镜像构建和扫描可长时间无输出。