# 生产 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；镜像构建和扫描可长时间无输出。