# 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 预构建镜像

### 镜像名称
```bash
xiaoxia-ci-python:3.12
```

### 构建脚本
```bash
infra/scripts/build-ci-image.sh
```

### 构建方式
在 Gitea Runner 所在服务器执行：
```bash
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 秒完成

---

## 本地验证

推送前建议先跑：

### 运行测试
```bash
pytest tests/integration/ -v --cov=packages --cov=apps --cov-report=html
```

### 代码格式化检查
```bash
black --check packages/ apps/ tests/
```

### 静态检查
```bash
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 任务消费情况

### 健康检查失败
查看：
```bash
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 镜像闭环验证