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