xiaoxia-saas/docs/CI-CD.md

CI/CD Configuration

Gitea Actions

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

工作流文件

1. .gitea/workflows/tests.yml - 自动化测试

触发条件：

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

包含任务：

• test - 运行集成测试，生成覆盖率报告
• lint - 运行 Black / Flake8 / MyPy

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

触发条件：

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

实际行为：

• runner 在部署主机本机执行 workflow
• workflow 将仓库同步到 /var/lib/xiaoxia-saas-staging/repo 或 /var/lib/xiaoxia-saas-production/repo
• 读取服务器本地真实 .env
• 本机构建 API / Worker 镜像
• 使用 infra/docker/compose.yml 启动 postgres / redis / api / worker
• 部署后用 /api/v1/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

---

本地验证

推送前建议先跑：

运行测试

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 已启用
• act_runner 已注册并持续运行
• staging 可手工部署并已完成真实业务闭环验证
• 当前 CI/CD 的关键目标是让 Gitea push 后自动完成同机部署，而不是只保留占位 YAML

---

故障排查

Actions 触发了但 checkout 失败

优先检查 runner 能否从 job 容器访问 Gitea 实例地址；如果 Gitea 挂在 /git 这类子路径下，优先使用手写 git fetch，不要依赖 actions/checkout 自动拼接仓库地址。

Deploy 成功但业务链不通

优先检查：

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

健康检查失败

查看：

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

---

最后更新: 2026-06-15
状态: CI/CD 已接入真实主机部署模型，待 push 后持续验证稳定性