docs: close phase7 deployment ci validation

2026-06-20 21:38:50 +08:00
parent ba06c95b16
commit 71d7913f2f
2 changed files with 105 additions and 34 deletions
@@ -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 镜像闭环验证
@@ -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 生成专项或下一阶段规划。** ✅