xiaoxia-saas/docs/PHASE7-PROGRESS.md at develop

xiaoxia/xiaoxia-saas

Fork 0

Files

T

xiaoxia a6e85092ce fix: 统一 ENABLE_REDIS_SESSIONS 命名，修复登录因 AttributeError 导致 500

2026-06-27 17:05:48 +08:00

10 KiB

Raw Permalink Blame History

2026-06-21 Production Release v0.1.0

Tag：v0.1.0
Commit：bab6a812a6ee49f380e88e69954d641d899c4be7
Backup：/root/xiaoxia-backups/20260621-160021
Production deploy：Gitea Actions Deploy Production job succeeded
Production ports：API 8001，Web 3002，Postgres 5433，Redis 6380
Alembic：before 002，after 002
External smoke：Redis OK，OSS upload/download/delete OK，SMTP intentionally skipped
App smoke：/health OK，register/login//auth/me OK，workspace create OK
Rollback：未执行；备份可用，恢复计划脚本为 scripts/restore_postgres_plan.sh

Phase: Phase 7 - 核心视频剪辑业务状态: ✅ 已完成（P0/P1/CI-CD/真实 FFmpeg 生成已生产验证闭环） 最后更新: 2026-06-21 00:01 GMT+8

一、Phase 目标

根据 F:\openclaw-saas\docs\PHASE7-DESIGN.md，Phase 7 的目标是打通从：

上传素材
素材分类
发起生成
查看并下载成片

即完成 SaaS MVP 的核心视频剪辑主链路。

二、已完成交付清单

1. 核心业务能力

素材管理：上传、分类、查询、标签管理
视频生成：任务创建、自动触发 worker、真实 FFmpeg 生成、生成结果管理
成片下载：公网 video/mp4 成片 URL、规范化存储路径、宿主持久化
前端联调：生成页、结果页已接入并验证

2. 基础设施完善

完整工业化开发体系文档已建立
8 Agent 角色体系已定义
Git 工作流规范已确定并执行
Gitea Runner 已运行并通过真实任务验证
CI/CD 流水线已稳定（.gitea/workflows/ci-cd.yml）
Staging 自动部署已验证成功
Production tag 发布门禁已验证为非 tag 正常跳过
开发环境防跑偏收敛方案已建立
启动链文档已修正到新标准

3. 技术债务清理

代码 TODO 全部处理完成（session_id in JWT, repository injection）
CI/CD 稳定性专项完成并合并
领域模型收口完成
Repository 注入改为真实实现
前端类型检查和构建链恢复

4. 测试验证

tests/integration/test_asset_tags.py 通过
tests/integration/test_ingest_pipeline.py 通过
tests/integration/test_upload_pipeline.py 通过
tests/integration/test_classification_pipeline.py 通过
tests/integration/test_projects.py 通过
tests/integration/test_generation_pipeline.py 通过
前端 type-check 通过
前端 build 通过
真实 P1 smoke flow 通过：注册、登录、项目、素材库、上传、生成任务、成片结果
真实 FFmpeg smoke flow 通过：running → completed、result_count=1、生成 5 秒 MP4
公网成片下载验证通过：HTTP 200、Content-Type: video/mp4、MP4 文件头包含 ftypisom
公网 /health 返回 200，服务版本 0.1.0

三、生产验证闭环（2026-06-20）

1. P0 部署链路

split infrastructure 部署脚本已收口：infra.yml 管 Postgres/Redis，compose.yml 管 API/Worker/Web
bugfix/deploy-split-infra-ci 已合并到 develop
Staging 自动部署验证成功：Gitea Runner task 528、task 532、task 535
非 tag push 下 Production 部署按规则跳过：task 529、task 533、task 536
当前公网健康地址为 /health，/api/v1/health 返回 404 属于预期

2. P1 业务主链路

修复 worker 未注册 worker.generate_video 导致生成任务卡在 pending 的问题
bugfix/worker-generate-video-task 已合并到 develop
worker.generate_video 已从 generated://... 最小基线升级为真实 FFmpeg 生成
真实 P1 smoke flow 已验证 GenerationTask 到 completed，progress=100.0，result_count=1

3. 真实 FFmpeg 生成闭环

feature/real-ffmpeg-generation 已合并到 develop
Worker 使用 FFmpeg 生成真实 MP4 文件：5 秒、1280x720、25fps
无 OSS 配置时回退到本地 generated 文件持久化，不再因 OSS_ACCESS_KEY_ID 缺失失败
Nginx 已暴露 /generated-files/ 静态路径，避免成片 URL 命中前端 HTML 假 200
Docker generated 文件卷已绑定到宿主机 /var/lib/xiaoxia-saas-staging/generated
真实 smoke 验证结果：公网 URL 返回 HTTP 200、Content-Type: video/mp4、文件头包含 ftypisom

4. CI 根治优化

诊断出 CI 慢根因：服务器到 PyPI 下载慢，mypy==2.1.0 大 wheel 造成 20+ 分钟等待
新增预构建校验镜像 xiaoxia-ci-python:3.12
.gitea/workflows/ci-cd.yml 与 .github/workflows/ci-cd.yml 已同步使用预构建镜像
chore/ci-prebuilt-python-image 已合并到 develop，merge commit ba06c95
Gitea Runner task 534 已在真实 CI 环境验证使用 xiaoxia-ci-python:3.12
CI 校验阶段从 20+ 分钟降到约 57 秒

四、发布/运维完善（2026-06-21）

生产数据库备份 runbook 已脚本化：scripts/backup_postgres.sh
恢复计划脚本已脚本化且保持非破坏性：scripts/restore_postgres_plan.sh
Staging 临时库恢复演练已完成：backup → restore plan → restore to xiaoxia_restore_rehearsal → Alembic preflight → alembic upgrade head noop → cleanup
Bandit 已拆为 CI 独立 security scan quality gate
Staging strict 外部服务检查已执行：Redis session 通过；SMTP/OSS 因缺少真实凭证保持阻塞，不伪造验收
OSS lifecycle / 本地 fallback cleanup 策略已写入生产发布清单

五、最终收口清单（2026-06-21）

必须做（Phase 7 发布边界内）

生产 Web/API/Git 域名按 hostname 分离：saas.xiaoxiajianji.com、saas-api.xiaoxiajianji.com、git.xiaoxiajianji.com
生产 staging/production 基础设施分离：DB、Redis、端口、generated 路径、compose project 均独立
生产 auth/workspace/project/media 主链路验证：注册、登录、工作空间、项目、素材库、上传、入库、分类、生成、下载均通过
生产真实 FFmpeg 成片验证：公网下载返回 HTTP 200 和 Content-Type: video/mp4
前端主链路去 demo/manual internal id：项目上下文通过 workspace detail route state 与 sessionStorage 传递
结果页可测性增强：加载/错误状态、下载失败详情、文件大小、直链与复制 URL
部署脚本漂移修复：staging/production 均显式 rebuild Web image；.gitattributes 强制 shell 脚本 LF
Staging deploy 脚本支持 HOST_PREFIX，兼容 CI /host 容器环境和宿主机直接验收
回归测试覆盖 deploy script 关键约束：tests/unit/test_release_scripts.py

可延后（Phase 8/专项治理）

前端大 chunk 拆分与加载性能优化（当前 npm run build 通过，仅有 Vite warning）
测试覆盖率提升与更完整 E2E 自动化
监控告警体系完善
数据库字段命名进一步清理（当前有兼容映射）
SMTP 真实投递启用（MVP 明确 ENABLE_EMAIL_DELIVERY=false）

不做（Phase 7 冻结项）

不新增运营后台/订阅/成员高级管理等非核心剪辑功能
不把 unsupported UI 做成假成功；没有后端支持的入口保持禁用/暂未开放
不再手工 docker cp 前端静态文件作为发布方式；只能作为事故止血，不作为验收路径
不把 Git 服务挂到 API 域名路径下；继续坚持 Web/API/Git hostname 分离

当前验证备注

Clean staging deploy 已按 CI archive 风格执行到 Web 镜像构建阶段，证明脚本入口和 LF 问题已修复；服务器冷构建 FFmpeg/Node 依赖期间 load 一度升至 26+，SSH banner 超时，外部 Web 后恢复 HTTP 200。
最终发布前需在服务器负载恢复后补跑一次短 smoke：docker ps、staging Web chunk、/health、生产 Web/API health。此项是部署验收确认，不引入新功能。

六、遗留后续专项

以下问题不阻塞 Phase 7 完成，已纳入后续专项治理清单：

数据库字段重命名（当前通过映射兼容）
测试覆盖率提升
监控告警体系完善
前端构建优化
OpenClaw 子 Agent runtime 修复（当前暂停使用）

参考文档：docs/SaaS-后续专项整治清单-2026-06-18.md

七、执行策略总结

Phase 7 执行过程中的关键决策：

暂停 Agent 实跑：OpenClaw runtime 存在 continuation 问题，但不阻塞主线开发
保留全部开发规范：文档链、Git/CI/环境规则、质量门禁全部保持运作
主会话直接推进：在保持规范的前提下，由主会话直接完成开发
CI/CD 专项独立：发现的 CI 问题单独立项修复，不混入业务提交

八、验证清单

如果新会话启动后问：

当前 Phase 是什么？
- 答：Phase 7 已完成 ✅
Phase 7 交付了什么？
- 答：核心视频剪辑主链路（上传→分类→生成→下载），CI/CD 稳定性修复，代码 TODO 清理
下一步做什么？
- 答：Phase 7 已收口；下一步进入 Phase 8/运营后台/监控告警/测试覆盖率等后续专项规划（参考 docs/SaaS-后续专项整治清单-2026-06-18.md）
当前进度文档路径是什么？
- 答：F:\openclaw-saas\docs\PHASE7-PROGRESS.md

九、完成总结

Phase 7 已全部完成，核心视频剪辑业务主链路、P0 部署链路、P1 真实 smoke flow、CI/CD 自动化主链路、真实 FFmpeg 生成与公网成片下载均已打通并验证通过。

关键成果

SaaS MVP 核心功能可用
CI/CD 从不稳定收敛为可靠基础设施
代码质量债务清理完成
开发规范和文档体系建立完善

技术实现

领域模型：Asset / AssetLibrary / ClassificationJob / GenerationTask / GeneratedVideo
应用层：完整的 use case 和 repository 接口
基础设施：SQLAlchemy 持久化、Celery worker、OSS/本地 generated-files 存储、公开下载 URL
前端：React + TypeScript，生成页和结果页联调完成

Phase 7 正式收口，可以进入下一阶段规划。 ✅

10 KiB Raw Permalink Blame History Unescape Escape