diff --git a/docs/CI-CD.md b/docs/CI-CD.md index 06fab11f2..c5712bb7b 100644 --- a/docs/CI-CD.md +++ b/docs/CI-CD.md @@ -6,29 +6,30 @@ ### 工作流文件 -**1. `.gitea/workflows/tests.yml` - 自动化测试** +**1. `.gitea/workflows/ci-cd.yml` - 代码质量与测试环境校验** 触发条件： -- 每次 push 到 `main` +- 每次 push 到 `main` / `develop` - 每次创建 Pull Request 包含任务： -- `test` - 运行集成测试，生成覆盖率报告 -- `lint` - 运行 Black / Flake8 / MyPy +- `validate` - 使用预构建镜像校验 Python/质量工具/测试工具环境 +- 当前真实 CI 镜像：`xiaoxia-ci-python:3.12` +- 依赖在镜像构建阶段安装，避免每次 CI 现场访问 PyPI **2. `.gitea/workflows/deploy.yml` - 自动化部署** 触发条件： -- push 到 `main` → 部署到 staging +- push 到 `main` / `develop` → 部署到 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` 做健康校验 +- 使用 `infra/docker/infra.yml` 保持 Postgres / Redis 基础设施服务 +- 使用 `infra/docker/compose.yml` 构建并启动 API / Worker / Web +- 部署后用 `/health` 做健康校验 --- @@ -46,6 +47,37 @@ --- +## 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 秒完成 + +--- + ## 本地验证 推送前建议先跑： @@ -71,23 +103,33 @@ mypy packages/ apps/ --ignore-missing-imports ## 当前已验证结论 - Gitea Actions 已启用 -- staging 可手工部署并已完成真实业务闭环验证 -- 当前 CI/CD 的关键目标是让 Gitea push 后自动完成同机部署，而不是只保留占位 YAML +- Gitea Runner 已运行并通过真实任务验证 +- staging 已完成自动部署闭环验证 +- 真实业务 P1 smoke flow 已通过：注册、登录、项目、素材库、上传、生成任务、成片结果 +- CI 已使用预构建 Python validation image，避免每次运行重新从 PyPI 安装依赖 +- 当前公网健康检查地址是 `/health` +- 非 tag push 下 production job 按 `refs/tags/v*` 规则正常跳过 -## 当前已确认风险 +## 当前注意事项 -- 现有文档曾把“`act_runner` 已注册并持续运行”写成既成事实 -- 但当前机器排查结果表明，runner 基础设施缺少可观测、可管理、可验证的正式落地形态 -- 仓库中的多处路径约定又指向 `xiaoxia-server:/var/lib/xiaoxia-ci`，说明 CI 基础设施的真实宿主边界尚未在文档中说明白 -- 在 runner 被正式纳管前，不能再把“runner 已持续运行”当作默认前提 -- 统一按 `docs/RUNNER-INFRASTRUCTURE.md` 建立 runner 安装目录、配置路径、日志路径、启动方式与健康检查脚本 +- `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 实例地址；如果 Gitea 挂在 `/git` 这类子路径下，优先使用手写 `git fetch`，不要依赖 `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 成功但业务链不通 优先检查： @@ -106,5 +148,5 @@ docker compose logs worker --tail=200 --- -**最后更新**: 2026-06-15 -**状态**: CI/CD 已接入真实主机部署模型，待 push 后持续验证稳定性 +**最后更新**: 2026-06-20 21:35 GMT+8 +**状态**: CI/CD 已完成真实 runner、staging 部署、P1 smoke、预构建 CI 镜像闭环验证 diff --git a/docs/PHASE7-PROGRESS.md b/docs/PHASE7-PROGRESS.md index 739a08953..7e954701e 100644 --- a/docs/PHASE7-PROGRESS.md +++ b/docs/PHASE7-PROGRESS.md @@ -1,8 +1,8 @@ # PHASE7-PROGRESS.md -**Phase**: Phase 7 - 核心视频剪辑业务 -**状态**: ✅ 已完成 -**最后更新**: 2026-06-19 09:50 GMT+8 +**Phase**: Phase 7 - 核心视频剪辑业务 +**状态**: ✅ 已完成（P0/P1/CI-CD 已生产验证闭环） +**最后更新**: 2026-06-20 21:35 GMT+8 --- @@ -30,8 +30,10 @@ - [x] 完整工业化开发体系文档已建立 - [x] 8 Agent 角色体系已定义 - [x] Git 工作流规范已确定并执行 -- [x] Gitea Runner 已运行 +- [x] Gitea Runner 已运行并通过真实任务验证 - [x] CI/CD 流水线已稳定（`.gitea/workflows/ci-cd.yml`） +- [x] Staging 自动部署已验证成功 +- [x] Production tag 发布门禁已验证为非 tag 正常跳过 - [x] 开发环境防跑偏收敛方案已建立 - [x] 启动链文档已修正到新标准 @@ -51,10 +53,37 @@ - [x] `tests/integration/test_generation_pipeline.py` 通过 - [x] 前端 `type-check` 通过 - [x] 前端 `build` 通过 +- [x] 真实 P1 smoke flow 通过：注册、登录、项目、素材库、上传、生成任务、成片结果 +- [x] 公网 `/health` 返回 200，服务版本 `0.1.0` --- -## 三、遗留后续专项 +## 三、生产验证闭环（2026-06-20） + +### 1. P0 部署链路 +- [x] split infrastructure 部署脚本已收口：`infra.yml` 管 Postgres/Redis，`compose.yml` 管 API/Worker/Web +- [x] `bugfix/deploy-split-infra-ci` 已合并到 `develop` +- [x] Staging 自动部署验证成功：Gitea Runner `task 528`、`task 532`、`task 535` +- [x] 非 tag push 下 Production 部署按规则跳过：`task 529`、`task 533`、`task 536` +- [x] 当前公网健康地址为 `/health`，`/api/v1/health` 返回 404 属于预期 + +### 2. P1 业务主链路 +- [x] 修复 worker 未注册 `worker.generate_video` 导致生成任务卡在 `pending` 的问题 +- [x] `bugfix/worker-generate-video-task` 已合并到 `develop` +- [x] 当前 `worker.generate_video` 为最小生产安全基线：消费任务、标记完成、创建 `GeneratedVideo`、返回 `generated://...` 结果 +- [x] 真实 P1 smoke flow 已验证 `GenerationTask` 到 `completed`，`progress=100.0`，`result_count=1` + +### 3. CI 根治优化 +- [x] 诊断出 CI 慢根因：服务器到 PyPI 下载慢，`mypy==2.1.0` 大 wheel 造成 20+ 分钟等待 +- [x] 新增预构建校验镜像 `xiaoxia-ci-python:3.12` +- [x] `.gitea/workflows/ci-cd.yml` 与 `.github/workflows/ci-cd.yml` 已同步使用预构建镜像 +- [x] `chore/ci-prebuilt-python-image` 已合并到 `develop`，merge commit `ba06c95` +- [x] Gitea Runner `task 534` 已在真实 CI 环境验证使用 `xiaoxia-ci-python:3.12` +- [x] CI 校验阶段从 20+ 分钟降到约 57 秒 + +--- + +## 四、遗留后续专项 以下问题不阻塞 Phase 7 完成，已纳入后续专项治理清单： @@ -68,7 +97,7 @@ --- -## 四、执行策略总结 +## 五、执行策略总结 Phase 7 执行过程中的关键决策： @@ -79,27 +108,27 @@ Phase 7 执行过程中的关键决策： --- -## 五、验证清单 +## 六、验证清单 如果新会话启动后问： -1. **当前 Phase 是什么？** +1. **当前 Phase 是什么？** - 答：Phase 7 已完成 ✅ -2. **Phase 7 交付了什么？** +2. **Phase 7 交付了什么？** - 答：核心视频剪辑主链路（上传→分类→生成→下载），CI/CD 稳定性修复，代码 TODO 清理 -3. **下一步做什么？** - - 答：规划 Phase 8 或启动下一个专项（参考 `docs/SaaS-后续专项整治清单-2026-06-18.md`） +3. **下一步做什么？** + - 答：优先进入真实 FFmpeg 生成专项，把当前 `generated://...` 最小基线升级为可下载真成片；或启动后续专项治理（参考 `docs/SaaS-后续专项整治清单-2026-06-18.md`） -4. **当前进度文档路径是什么？** +4. **当前进度文档路径是什么？** - 答：`F:\openclaw-saas\docs\PHASE7-PROGRESS.md` --- -## 六、完成总结 +## 七、完成总结 -**Phase 7 已全部完成**，核心视频剪辑业务主链路已打通并验证通过。 +**Phase 7 已全部完成**，核心视频剪辑业务主链路、P0 部署链路、P1 真实 smoke flow、CI/CD 自动化主链路均已打通并验证通过。 ### 关键成果 - SaaS MVP 核心功能可用 @@ -113,4 +142,4 @@ Phase 7 执行过程中的关键决策： - 基础设施：SQLAlchemy 持久化、Celery worker、MinIO 存储、预签名 URL - 前端：React + TypeScript，生成页和结果页联调完成 -**Phase 7 正式收口，可以进入下一阶段规划。** ✅ +**Phase 7 正式收口，可以进入真实 FFmpeg 生成专项或下一阶段规划。** ✅