xiaoxia-saas/docs/CI-CD.md

CI/CD Configuration

Gitea Actions

本项目使用 Gitea Actions + 本机 act_runner 实现 CI/CD。

工作流文件

1. .gitea/workflows/ci-cd.yml - 代码质量与测试环境校验

触发条件：

• 每次 push 到 main / develop
• 每次创建 Pull Request

包含任务：

• validate - 使用预构建镜像校验 Python/质量工具/测试工具环境
• 当前真实 CI 镜像：xiaoxia-ci-python:3.12
• 依赖在镜像构建阶段安装，避免每次 CI 现场访问 PyPI

2. .gitea/workflows/deploy.yml - 自动化部署

触发条件：

• push 到 main / develop → 部署到 staging
• push tag v* → 部署到 production

实际行为：

• runner 在部署主机本机执行 workflow
• workflow 将仓库同步到 /var/lib/xiaoxia-saas-staging/repo 或 /var/lib/xiaoxia-saas-production/repo
• 读取服务器本地真实 .env
• 使用 infra/docker/infra.yml 保持 Postgres / Redis 基础设施服务
• 使用 infra/docker/compose.yml 构建并启动 API / Worker / Web
• 部署后用 /health 做健康校验

---

部署目录约定

Staging

• 环境根目录：/var/lib/xiaoxia-saas-staging
• 真实环境文件：/var/lib/xiaoxia-saas-staging/.env
• Actions 同步代码目录：/var/lib/xiaoxia-saas-staging/repo

Production

• 环境根目录：/var/lib/xiaoxia-saas-production
• 真实环境文件：/var/lib/xiaoxia-saas-production/.env
• Actions 同步代码目录：/var/lib/xiaoxia-saas-production/repo

---

CI 预构建镜像

镜像名称

xiaoxia-ci-python:3.12

构建脚本

infra/scripts/build-ci-image.sh

构建方式

在 Gitea Runner 所在服务器执行：

cd /var/lib/xiaoxia-saas-staging/repo
bash infra/scripts/build-ci-image.sh

维护原则

• 修改 requirements*.txt 后，如 CI 依赖发生变化，必须重新构建 xiaoxia-ci-python:3.12
• .gitea/workflows/ci-cd.yml 是真实 Gitea Runner 使用的 CI 源
• .github/workflows/ci-cd.yml 必须保持同步，防止双平台工作流漂移
• 不要在每次 CI 里重新 pip install 全量依赖；网络慢的问题应在镜像构建阶段集中处理

已验证效果

• 旧问题：服务器到 PyPI 下载慢，CI 依赖安装可拖到 20+ 分钟
• 新结果：Gitea Runner task 534 使用 xiaoxia-ci-python:3.12，CI 校验阶段约 57 秒完成

---

本地验证

推送前建议先跑：

运行测试

pytest tests/integration/ -v --cov=packages --cov=apps --cov-report=html

代码格式化检查

black --check packages/ apps/ tests/

静态检查

flake8 packages/ apps/ tests/ --max-line-length=120 --extend-ignore=E203,W503
mypy packages/ apps/ --ignore-missing-imports

---

当前已验证结论

• Gitea Actions 已启用
• Gitea Runner 已运行并通过真实任务验证
• staging 已完成自动部署闭环验证
• 真实业务 P1 smoke flow 已通过：注册、登录、项目、素材库、上传、生成任务、成片结果
• CI 已使用预构建 Python validation image，避免每次运行重新从 PyPI 安装依赖
• 当前公网健康检查地址是 /health
• 非 tag push 下 production job 按 refs/tags/v* 规则正常跳过

当前注意事项

• xiaoxia-ci-python:3.12 是服务器本地 Docker 镜像；更换 runner 主机或清理镜像后，必须先执行 infra/scripts/build-ci-image.sh
• worker.generate_video 当前是最小生产安全基线，会生成 generated://... 结果；真实 FFmpeg 成片生成仍是后续业务专项
• 生产部署只应通过 v* tag 触发，普通 develop / main push 不应触发 production
• 统一按 docs/RUNNER-INFRASTRUCTURE.md 管理 runner 安装目录、配置路径、日志路径、启动方式与健康检查脚本

---

故障排查

Actions 触发了但 checkout 失败

优先检查 runner 能否从 job 容器访问 Gitea 实例地址；如果 job 镜像缺少 git，可使用 Python/wget 下载 Gitea archive 并解压，避免为了 checkout 单独安装 git。

CI 又开始变慢

优先检查：

• job 是否仍使用 container: xiaoxia-ci-python:3.12
• runner 主机是否存在该本地镜像：docker image inspect xiaoxia-ci-python:3.12
• workflow 是否重新引入了每次运行的全量 pip install
• 依赖变更后是否忘记重建 CI 镜像

Deploy 成功但业务链不通

优先检查：

• /var/lib/xiaoxia-saas-staging/.env
• OSS_ENDPOINT
• DATABASE_URL
• worker 日志中的 Celery 任务消费情况

健康检查失败

查看：

docker compose ps
docker compose logs api --tail=200
docker compose logs worker --tail=200

---

最后更新: 2026-06-20 21:35 GMT+8 状态: CI/CD 已完成真实 runner、staging 部署、P1 smoke、预构建 CI 镜像闭环验证