API文档维护Agent
e2c68888e9
CI/CD Pipeline / Validate Code Quality And Tests (push) Has been cancelled
CI/CD Pipeline / Frontend Lint (push) Has been cancelled
Deploy / Deploy Staging (push) Has been cancelled
Deploy / Build Production Runtime Images (push) Has been cancelled
Deploy / Deploy Production (push) Has been cancelled
Deploy / Production Browser E2E (push) Has been cancelled
- .env.production: MINIO_* 环境变量全部改为 OSS_* 命名 - MINIO_ENDPOINT → OSS_ENDPOINT - MINIO_ACCESS_KEY → OSS_ACCESS_KEY_ID - MINIO_SECRET_KEY → OSS_ACCESS_KEY_SECRET - MINIO_BUCKET → OSS_BUCKET_NAME - MINIO_SECURE → OSS_SECURE - MINIO_PUBLIC_URL → OSS_PUBLIC_URL - .env.staging: 修正 section header 为 OSS 对象存储配置 - storage.py: 移除 MinIOService 和 get_minio_service() 向后兼容别名 - test_architecture_boundaries.py: 移除 storage.py 的 allowed 例外 - 更新文档中的 MINIO_* 示例为 OSS_*: - docs/CI-CD.md - docs/基础设施安装指南.md - docs/本地验证检查清单.md - docs/静态验证报告-2026-06-19.md
153 lines
4.7 KiB
Markdown
153 lines
4.7 KiB
Markdown
# 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 镜像闭环验证
|