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

固化 Tag 发布策略、Runner 信任边界、Secret 位置、数据库回滚限制，以及 Runner 安装、发布、验证和故障恢复步骤。

2026-07-17 12:41:47 +08:00

3.3 KiB

Raw Blame History

生产 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 中执行：

RUNNER_REGISTRATION_TOKEN='<一次性 Token>' ./scripts/provision-ci-runner.sh

Token 只通过进程环境传入。生成的 /var/lib/easyai-gateway-runner/.runner 必须保持 0600，不得复制到仓库、报告或聊天记录。

验证：

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 启动新的长轮询进程。

发布生产版本

合并到 main，等待 ci / verify (push) 成功。
在已验证的 main 提交上创建语义版本 Tag。
推送 Tag，等待同一 CI Job 完成镜像扫描、发布、数据库备份、迁移和公共健康检查。

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 或版本号镜像。

发布后验证

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：

sudo /usr/local/sbin/easyai-ai-gateway-release <40 位历史 Git SHA>

该操作也会先创建数据库备份。不要把 latest、分支名或版本号传给发布助手。

数据库恢复

备份位于 /var/backups/easyai-ai-gateway，默认只保留最近 5 份。应用回滚不会自动恢复数据库。只有确认需要回退数据且已经停止写入后，才能由操作员选择备份执行 pg_restore；恢复前必须再保留当前数据库副本。

Runner 故障恢复

重启前先确认没有构建、扫描或部署子进程：

ps -u easyai-gateway-runner -o pid,ppid,etime,cmd --forest
systemctl status easyai-gateway-act-runner.service --no-pager

确认空闲后才执行：

systemctl restart easyai-gateway-act-runner.service
journalctl -u easyai-gateway-act-runner.service -n 50 --no-pager

不要因为日志暂时没有新增就用定时器重启 Runner；镜像构建和扫描可长时间无输出。

3.3 KiB Raw Blame History Unescape Escape