Skip to content

Latest commit

 

History

History
432 lines (301 loc) · 42.3 KB

PROCESS.md

File metadata and controls

432 lines (301 loc) · 42.3 KB

HotFactory 工作进度记录(PROCESS)

最后更新:2026-11-16 17:30(GMT+8) 用途:跨会话共享的进度台账。架构契约以 hot-factory-overview-design.md 为唯一真源,本文只记录进度、状态、验证事实与待办,不重复定义接口和状态字段。 维护约定:完成一项即更新状态;只记有长期价值的事实,不记临时路径、一次性报错与中间产物。


1. 当前状态(一句话)

第一版(= 三阶段路线的第一阶段)工程骨架已可运行;已用真实 MoneyPrinterTurbo 产出一条 39.6 秒、9:16、带中文配音与烧录字幕的 MP4,且同一条命令可批量复现。架构文档已收敛为 v1.0:只保留现行架构,历史沿革与废弃方案全部移出 docs/。

维度 当前值
阶段 第一阶段「跑通视频生产」——垂直链路已打通,功能仍在补齐
架构版本 v1.0(现行架构单一真源,2026-11-13 冻结)
运行形态 本机三进程直跑(FastAPI / Worker / MPT 8080 API);Docker Compose 为目标形态,本机未装 Docker
出片能力 真实引擎已验证;当前画面是 ffmpeg 测试彩条,待换自有素材
测试 后端 pytest 110 passed;前端 vue-tsc + vite build 通过
阻塞项 无硬阻塞;DeepSeek Key / Pexels Key / 抖音 Scope 均有降级路径

2. 阶段进度

阶段 目标 状态 说明
0. 技术基线与规范 冻结技术栈、目录、providers 接口、测试约定 已完成 架构文档 v1.0;AGENTS.md / CLAUDE.md / 配置样例落地
1. 工程骨架 Vue 3、FastAPI、SQLite、三程序 已完成 43 个源码文件,按 api/core/models/schemas/services/providers/workers 分层
2. 热点中心 热点采集、快照、去重 未开始 一等降级:手工主题 / topics.json;抖音 Scope 未申请
3. AI 选题 DeepSeek 分类、评分、推荐理由 未开始 目标态能力,见架构文档 3.x
4. 内容创作 结构化脚本、分镜、平台文案、版本 部分完成 结构化脚本已落盘、可手改、可 --from-script 复用;分镜与平台文案字段已定义但未用于生产
5. 视频生产 MPT 集成、Worker 状态翻译、ffprobe 质检 已完成 全链路打通,真实引擎出片成功
6. 审核中心 预览、修改、通过、驳回 部分完成 预览 + 审核通过 + 驳回即删除已可用;脚本二次编辑 / 封面未做
7. 发布预置 接口抽象、数据表、页面占位 未开始 第三阶段实现真实发布
第二阶段 多模板 / 多音色 / 字幕增强 / 封面 / 质量评分 / 每日推荐 未开始 不提前实现
第三阶段 抖音 / 快手 / 小红书 / 视频号 / B 站发布 未开始 官方 API 优先,保留人工确认

3. 已完成工作(2026-11-13,同一天)

3.1 文档与契约

  1. 把概要设计从 Java + Spring Boot + PostgreSQL + Redis 基线整体改写为 Python + Vue 3 基线,保留合规、平台调研与验收章节。
  2. 新增 docs/runbook/weekend-slice.md 执行切片,核实 MPT 已内置配音 / 字幕 / 素材 / 异步进度,指出蓝图存在重复建设。
  3. 把「复用优先」写成正式契约:删除 TTS_SYNTHESIS、providers/tts/、自研字幕与第二套进度体系;任务类型 7 → 4;补 run 抽象、ManualHotSource、降级矩阵与表分期。
  4. 本机实测官方 mpt 1.3.10 后,把三处会卡死真片的错误写进契约并修代码:state = -1/1/4、videos 返回 /tasks/<id>/final-1.mp4 相对 URI、video_source=local 必须带 video_materials。
  5. 本轮收敛:docs/ 两份文档重写为 v1.0 现行架构与当前运行手册,清除历史沿革、废弃方案对照与已过期的时间盒;README.md 同步版本号、章节引用与测试数量。

3.2 工程实现

模块 落地内容
backend/app/models SQLAlchemy 5 张表(task / topic / script / video_task / video_file),SQLite WAL + busy_timeout
backend/app/api 9 个路由:健康检查、任务创建 / 列表 / 轮询 / 重试 / 取消 / 审核、成片列表 / 流式预览
backend/app/services 任务生命周期;Worker 用原子 UPDATE ... WHERE status='PENDING' 认领
backend/app/providers/llm fake(零凭据)/ deepseek(结构化 JSON)两套实现 + 工厂
backend/app/providers/video mock(真实 ffmpeg 出测试片)/ mpt(HTTP 适配器)+ 工厂
backend/app/providers/qc ffprobe 基础质检(流、时长、分辨率、大小、文件可读性)
backend/app/workers runner.py 独立进程、pipeline.py 流水线、cli.py 批量出片薄封装
frontend/src Vue 3 + TS + Element Plus:主题输入、素材上传、一键生成、进度轮询、成片预览、审核通过

3.3 成片命名与页面素材上传(2026-11-13 17:30 补)

  1. 成片按主题命名:引擎产出的 final-1.mp4 落库前改为 data/videos/{task_id}/{主题}.mp4,规则在 core/naming.py(去 Windows 非法字符、按字符截断、保留名兜底);TaskOut.topic 由 payload.topic 派生,任务列表新增「主题」「成片」两列。
  2. 页面手动上传素材:POST /api/materials 转发引擎 POST /api/v1/video_materials,不新建素材库;上传后文件随任务 payload.materials 提交,只使用选中的素材,解决「测试彩条混进成片」;一个不传才回落引擎库全集。
  3. 新增 python-multipart 依赖(FastAPI 表单上传必需),backend/requirements.txt 已补。
  4. 测试:新增 test_naming.py(12 例)、test_materials.py(4 例)、流水线素材透传与改名断言,合计 pytest 50 passed;前端 vue-tsc + vite build 通过。
  5. 实测:真实引擎下上传一张 10KB PNG → 引擎目录落成 fc846bec….png,GET /api/materials 可见(测试文件已删除)。 | 部署 | docker-compose.yml(Web + Worker)、backend/Dockerfile、backend/run-dev.sh、run-dev.sh | | 配置 | config/env.example、config/topics.example.json、.gitignore、THIRD-PARTY-NOTICES.md |

关键取舍:不另写独立 pipeline.py 或第二套流水线。 批量 CLI 只做「批量入队 + 汇总报告」,复用同一张 task 表、run_one()、providers 与 ffprobe 质检。

3.4 真实验证(都实际跑过,非纸面结论)

# 验证 结果
1 后端 pytest 32 passed(含 8 个 MPT 契约用例、4 个 CLI 用例)
2 前端类型检查与构建 vue-tsc 无错、vite build 成功(Element Plus 全量引入有约 1 MB chunk 警告)
3 本机 HTTP 联调 uvicorn + 独立 Worker 进程:POST /api/tasks 201 → WAITING_REVIEW/100 → GET /stream 200 video/mp4
4 mock 批量出片 3 条主题 → 3/3 WAITING_REVIEW,3 条 1080×1920 / H.264+AAC MP4,ffprobe 全项通过
5 真实 MPT 出片 WAITING_REVIEW / 100 / qc=PASS,耗时 5 分 26 秒,39.6 秒 / 1080×1920 / H.264+AAC / 30fps / 7.2 MB;Edge TTS 39 秒中文配音、Edge 时间戳字幕、3 张本地图合成并烧录字幕,抽帧确认中文字幕无乱码
6 文档结构校验 三份 Markdown 代码围栏成对、表格列数一致、docs/ 内无临时脚本

过程中修掉的具体错误:

  • mock 引擎 ffmpeg 参数 testsrc=size=1080:1920 冒号被当选项分隔符 → 改 1080x1920,并把 stderr 带进异常信息。
  • MPT 适配器按 README 猜测的 state 0/1/2/3 会让失败态被当成处理中,一直轮询到超时 → 按源码 app/const.py 改为 -1/1/4。
  • 成片地址当本地路径拼接 → 改为从引擎 HTTP 下载 /tasks/... 相对 URI。
  • video_source=local 未传 video_materials 会生成空片 → 改为调引擎 GET /api/v1/video_materials 取文件名。

3.5 成片时长与配音语速(2026-11-13 18:15 补)

项 结论
引擎是否支持总时长 不支持。TaskVideoRequest 只有 video_clip_duration(单片段时长),成片长度 = 配音长度 = 字数 ÷ 语速
实现方式 TaskCreate.duration_seconds / voice_rate → payload → core/duration.trim_script 换算字数预算(时长 × 4.5 × 语速)后裁稿,裁在完整句子边界,scenes 同步重切
语速 透传引擎 voice_rate(Edge TTS 转百分比,services/voice.py::convert_rate_to_percent);Gemini / MiMo / VoxCPM 不支持数值语速,引擎只告警不生效
实测 同一篇约 330 字稿件 + duration_seconds=30、voice_rate=1.2 → 裁到 148 字、成片 27.7 秒 / 1080×1920 / 6.84MB、质检通过;148 ÷ 27.672 = 5.35 字/秒,是基准 4.5 的 1.19 倍,证明语速与裁剪预算用的是同一个倍率
过载事故 用户把整份 1654 字分镜脚本粘进口播稿 → 配音 366.456 秒 → 74 段拼接 + libx264 重编码,10 分钟只到 75%,被误判为「卡死」,已手动停止并说明原因
连带修复 ① Worker 被终端回收后没人回写进度 → main.py 加 Web 看门狗(HF_WEB_RECOVERY_SECONDS,默认 180 秒)把长时间无更新的活动任务重新入队;② 稿子框下方实时显示字数与预估秒数,超目标则提示会被截断
  • README 里「素材放 data/assets/」与实测结论矛盾 → 统一为 MPT 自己的 storage/local_videos/。

3.6 最近任务增加创建时间列(2026-11-13 18:40 补)

项 结论
改动 frontend/src/api/tasks.ts 增加时间解析 / 格式化纯函数(沿用该文件已有 baseName 展示辅助的惯例,不新建模块);frontend/src/views/TaskBoard.vue 的「最近任务」表首列新增「创建时间」,短格式 MM-DD HH:mm:ss,悬停显示完整本地时间与「距今多久」
关键坑 后端 created_at 是 naive UTC(models/db.py::utc_naive),Pydantic 序列化后不带时区,形如 2026-11-13T10:30:14.608962。JS 直接 new Date(...) 会按本地时区解释,北京时间下显示成 10:30(少 8 小时)→ 统一补 Z 再按访问者本地时区格式化;带 Z / +08:00 / 空格分隔 / 空值 / 非法值都要兼容
验证 11 条时间函数断言全过(本机 Asia/Shanghai);vue-tsc + vite build 通过;后端 pytest 69 passed;Edge 无头浏览器访问真实 8000 服务取数:表头「创建时间」存在、13 行任务时间均按本地时间渲染(最新一条 11-13 18:30:14,UTC 源值 10:30:14)、tooltip 显示「7 分钟前」;1440 / 768 两档截图确认无挤压,窄屏下首列仍完整可见(右侧列走表格既有横向滚动)
范围 纯展示,未改接口、状态字段、任务逻辑与交互;行点击是既有功能

4. 当前架构速览(供确认)

一句话: 自研 Python 业务编排 + DeepSeek 结构化脚本 + MoneyPrinterTurbo 一次性完成配音 / 字幕 / 素材 / 合成 + ffprobe 质检 + 人工审核。

层 选型
前端 Vue 3 + TypeScript + Vite + Element Plus
后端 Python 3.12+ / FastAPI / SQLAlchemy
数据库 SQLite 单文件 data/hotfactory.db(WAL + busy_timeout)
AI DeepSeek(模型标识配置化,以官方当前可用名称为准)
配音 / 字幕 / 素材 / 合成 / 异步进度 全部由 MoneyPrinterTurbo 提供,本系统只透传配置、翻译状态
质检 本系统 providers/qc.py + ffprobe(引擎不产出质检报告)
任务 SQLite 任务表 + 单 Worker 原子认领 + 前端轮询
部署目标 Docker Compose,三个核心程序:hotfactory-web / hotfactory-worker / MoneyPrinterTurbo

三个程序里 Web 与 Worker 共用 backend/app/ 代码库,只换启动入口;它们通过任务表和共享 data/ 交换数据,不引入 RPC 或消息队列。

硬约束:新增任何模块前先查上游是否已提供;已提供的只做配置透传或状态翻译,不重写。


5. 已废弃 / 明确不做(决策留痕,不属于现行架构)

类别 内容 原因
已废弃技术栈 Java 21 + Spring Boot、MyBatis、PostgreSQL、Redis、Nginx、独立 video-worker HTTP 服务 项目重心是 AI / 视频编排,同语言可直接复用 MPT;单人使用无需数据库服务与缓存
已废弃设计 7 类任务、TTS_SYNTHESIS、自研 TTS / 字幕 provider、13 张表先行、第二套进度体系 上游已提供,属重复建设
明确不引入 Kafka / RabbitMQ / Celery / Kubernetes / 微服务拆分 第一版模块化单体足够;并发增长再评估
第一版不做 真实多平台发布、自动无人值守发布、多用户 / 多租户、自研剪辑引擎 按三阶段路线,发布在第三阶段
尚未采用 官方抖音热点 API、hot-search-crawler、PostFlow、short-video-maker 权限 / 阶段 / 适配度原因,仅列为未来候选,不是当前依赖

6. 已知限制与风险

  • 真片画面是 ffmpeg 测试彩条,只证明链路可用;出内容片需替换 MPT storage/local_videos/ 里的素材并填 DeepSeek Key。
  • 长句字幕换行处略挤,可调引擎 font_size / subtitle_position。
  • 基础质检只覆盖元数据;黑屏 / 静音语义检测、自动质量评分属第二阶段。
  • 前端全量引入 Element Plus,构建产物约 1 MB,有分包优化空间。
  • 无用户认证,管理接口只应监听本机;MPT 8080 默认免认证,不得暴露公网。
  • docker-compose.yml 只编排 Web + Worker;MPT 按上游方式单独启动并通过 HF_MPT_API_BASE 接入,未编造上游镜像名。
  • 本机环境:Python 3.13.14 / uv 0.12.5 / Node 22.22.2 / FFmpeg 9.0.1 / Windows + Git Bash;Docker 未安装。
  • Remotion 出片帧中 LineCharacter 只显示头与躯干、四肢未渲染(改动前既有缺陷;路径标记几何与 bundle 字符串均完整,根因未定),单独排查,不影响链路验收。

7. 下一步待办(按优先级)

# 待办 前置条件
1 把测试彩条换成 3~10 张自有图片 / 录屏,出一条真正的内容片 无
2 填 DeepSeek Key,验证 HF_LLM_PROVIDER=deepseek 的结构化脚本链路 DeepSeek Key
3 补齐脚本二次编辑、封面与质检语义检测(审核驳回已落地为「驳回即删除」,见第 19 节) 无
4 引入 HotSource 抽象与官方抖音热点(当前手工主题已是一等降级) 抖音 Scope 审批
5 前端按需引入 Element Plus / 分包,消除 1 MB chunk 无
6 Docker 就绪后固定 MPT 镜像 digest,把第三个程序编入 Compose 安装 Docker

8. 2026-11-16 视频分镜协议增量

已落地:

  • backend/app/storyboard/:Storyboard v1.0 的 Pydantic 协议、素材/动作/动画白名单和脚本到分镜的确定性构造器;
  • Worker 在提交 MPT 前生成并保存 data/scripts/{task_id}/storyboard.json;
  • GET /api/tasks/{id}/storyboard 提供分镜快照读取;
  • 前端任务详情展示模板、画布参数、场景时长、旁白和动画预设;
  • 新增协议校验、流水线快照和 API 测试。

未改变:配音、字幕、素材上传、异步进度和 MP4 合成继续由 MoneyPrinterTurbo 提供;本次没有引入第二套 TTS/字幕/进度体系,也没有复制 Remotion 或上游源码。

验证:backend 全量 pytest 69 passed;frontend npm run typecheck 和 npm run build 通过。真实 MPT + Edge TTS 需在本机启动引擎后按第 4 章实测,当前会话未再次调用外部引擎。

9. 2026-11-16 Remotion 动态信息图渲染器

已落地:

  • video-renderer/ 独立 Remotion 工程,消费 Storyboard v1.0;
  • 暗色渐变/网格背景、暖黄色发光 SVG 小人、电脑/电池/时钟/文档等图标;
  • 标题、旁白字幕条、进度条和 title / character / infographic 场景;
  • fade_in、slide_up、slide_left、scale_in、draw_and_move、pulse、shake 等动画预设;
  • Worker 新增 remotion VideoEngine,渲染后复用 .mpt-venv 的 Edge TTS 生成旁白,再由 FFmpeg 封装音轨并进入原有 ffprobe 质检和 Web 预览;
  • start.bat 在 HF_VIDEO_PROVIDER=remotion 时自动安装 video-renderer 依赖。

实测:固定分镜渲染 14 秒、1080×1920、30fps、H.264 + AAC MP4;Worker 端到端任务进入 WAITING_REVIEW,质检六项通过。Remotion 依赖首次运行会下载 Chromium Headless Shell。

当前边界:Remotion 模式已具备旁白音轨,但不生成逐句字幕;字幕仍由 MoneyPrinterTurbo 兼容模式提供。MoneyPrinterTurbo 保留为整片兼容模式,不负责默认 SVG 动态画面。


10. 2026-11-16 主题内容驱动 SVG 分镜

已落地:

  • Web 输入收敛为主题 + 内容,补充横屏 1920×1080 / 竖屏 1080×1920 选择;
  • 后端按 AI 返回的文案分段生成 2~8 段确定性 SVG,场景标题、视觉描述和图标跟随文案;
  • SVG 包含 bg / mid / fg / ui / text / character 图层、渐变、网格、路径描边、粒子、发光滤镜和线条小人;
  • Remotion 按帧修改 stroke-dashoffset,生成路径生长、粒子显现、字幕淡入和进度条动画;
  • 15 秒 Demo:data/city-pulse-demo-15s.mp4,1920×1080 / 30fps / H.264 + AAC / 14.93 秒,抽帧确认画面可见。

当前边界:Remotion 模式的旁白通过 .mpt-venv Edge TTS 生成并由 FFmpeg 封装;真实城市环境采样和逐句字幕仍不在本项目自研范围内。


11. 2026-11-16 产出物与日志目录重构

问题:数据库、成片、分镜、Remotion 中间件、日志全塞在 data/ 下,找成片要先猜 task_id,清理产物又怕误删数据库。

改动:

  • 三分目录:data/(数据库 + 上传素材,唯一需备份)、output/(产出物)、logs/(日志);
  • output/videos/{task_id}/{主题}.mp4、output/scripts/{task_id}/、output/reports/、output/_build/remotion/;
  • 日志落盘由程序负责:core/logging_setup.py 给根 logger 挂控制台 + 5MB×3 轮转文件,Web 写 logs/web.log、Worker 写 logs/worker.log;
  • 新增配置项 HF_OUTPUT_DIR、HF_LOG_DIR,路径统一由 core/config.py 派生,业务代码不拼路径;
  • docker-compose.yml 增加 ./output、./logs 挂载;.gitignore 忽略这两个目录;
  • 清理:删除旧的 data/ 运行残留(videos / scripts / remotion_jobs / logs / smoke / tmp / 散落 mp4 与 json,约 155MB)并重置数据库,旧任务记录不再保留;
  • 根目录草稿 findings.md / progress.md / task_plan.md 归位到 docs/progress/planning-2026-11-16/。

12. 2026-11-16 出片质量五项修复

问题:Remotion 链路能出片,但存在五处质量缺陷——裁稿丢掉 AI 视觉设计、分镜时长与配音真实长度错位、SVG 与 React 重复渲染文字/角色、竖屏固定像素与非等比拉伸、信息框恒画假数据。

改动(每项一个提交):

  • 裁稿保留视觉设计:core/duration.trim_script 重切场景时按原文句继承 visual / title / stage / animation 等字段,短视频不再退回关键词猜测(7dce4f2);
  • 质检时长上限对齐任务 schema:providers/qc.check_video 上限 300→600 秒,与 TaskCreate.duration_seconds 一致(0956f4c);
  • 分镜时长对齐真实音频:Remotion 模式先合成旁白,再按各场景旁白字数比例分配整帧(30fps),总帧数 = ceil(旁白秒数 × 30),单场景上限 120 秒;ffprobe 实测容器时长 == 旁白时长,末段分镜不再被裁掉(342d7bf);
  • 去重复层:SVG 不再画文字层与角色层,标题/旁白/角色只由 React 渲染一次;stage 改结构化标签(开场 / 要点 N / 收尾),不再带城市时段(8437004);
  • 竖屏画布适配:React 层尺寸全部按画布比例推导;SVG 视觉布局竖屏纵排;背景装饰改等比缩放加居中裁切;头图/标题/副标题提升到 SVG 背景层之上,修复文字发暗(a627bed);
  • 移除假数据信息框:删除恒画 38/62/84 的角落框,真实信息图由 SVG visual 布局按真实数据渲染;React 旁白条/进度条随 scene.visual.accent 配色;types.ts 补 VisualSpec 协议(bdb1b68)。

验证:backend 全量 pytest 100 passed(含裁稿保留 visual、整帧分配、装饰等比缩放等新增回归断言);renderer typecheck 通过;用真实脚本 + 真实 Edge TTS 旁白(25.56 秒)横竖各渲一条,抽帧目视确认无黑边、无文字溢出、无拉伸、单层文字、末段场景可见、配色随 visual。

未验证 / 遗留:LineCharacter 四肢在出片帧中不渲染(既有缺陷,根因未定,单独排查);提示词收敛到受控 DSL 并强制 visual、热点采集等仍在待办,本轮未动。


13. 2026-11-16 Docker 部署补齐(阿里云 ACR + Linux 宿主)

目标:把「本机三进程直跑」之外的容器交付补齐——一条 Dockerfile 出 web / worker 两个镜像,推阿里云 ACR,Linux 服务器只拉镜像部署。

改动:

  • backend/Dockerfile 重写为多阶段 + 双 target:frontend-build(node 22 构建 dist)、renderer-build(npm ci + remotion browser ensure 预下 Chrome Headless Shell)、py-base(依赖、非 root 用户、TZ、tzdata)、web(托管 dist,HEALTHCHECK 打 /api/health)、worker(ffmpeg/ffprobe、fonts-noto-cjk、Chrome 运行库、edge-tts、node 二进制 + video-renderer)。构建参数 APP_VERSION / GIT_COMMIT / BUILD_TIME / UID / GID / NPM_REGISTRY / PIP_INDEX 全部带默认值,不传也能构建。
  • docker-compose.yml 改为源码构建版(context 为仓库根),新增 docker-compose.prod.yml 只读 ACR 镜像;端口与绑定地址变量化(当时默认只监听 127.0.0.1,后按部署需求改为公网,见第 14 节),两服务加 restart: unless-stopped、healthcheck、日志轮转(10MB×3),worker 加 shm_size: 1gb 与 depends_on: service_healthy。
  • 新增 .dockerignore(排除 .git、node_modules、data/ output/ logs/、config/.env);根 .env.example 列全 compose 与推送变量,真实 .env 不入库。
  • scripts/docker-push.sh:读 .env、ACR 登录密码走 stdin、--platform、--provenance=false --sbom=false(ACR 个人版不收 attestation)、推版本 tag + latest、版本 tag 已存在则拒绝覆盖(--force 放开)、--save 导出离线 tar。
  • scripts/docker-deploy.sh:建目录并对齐属主 → pull → up -d → 轮询 healthy → 打印镜像与 health → 比对 /api/health 的 build_version 与 HF_IMAGE_TAG。
  • /api/health 增加 build_version / git_commit / build_time(对应 HF_BUILD_*),部署后用它核对线上跑的到底是哪个 tag / commit;test_health 补断言。

验证:pytest 100 passed(含 health 新字段断言);bash -n 两个脚本通过;两个 compose 文件 YAML 解析通过。

未验证:本机(Windows)没有 Docker,镜像构建、ACR 推送、容器启动均未实跑。首次在目标机执行后必须确认 docker compose -f docker-compose.prod.yml ps 两个服务 healthy,且 /api/health 的 build_version 等于 HF_IMAGE_TAG;worker 首次真实渲染还要确认 Chrome 能在容器内启动(沙箱受限按 runbook 9.2 处理)。

遗留:MPT 仍不编入 compose(上游没有官方镜像,不编造镜像名);latest 的定时自动更新未配,升级靠显式改 HF_IMAGE_TAG。


14. 2026-11-16 发布链路改为 GitHub Actions + 公网监听

目标:本机没有 Docker,发布不该依赖本机装 Docker Desktop。改为推 tag 由 GitHub Actions 构建推送 ACR;Web 端口按部署需求改为公网直连。

改动:

  • 新增 .github/workflows/docker.yml:push v* tag 或手动 workflow_dispatch 触发;meta job 解析版本(tag 去 v 前缀,手动留空则 manual-<短 commit>)并校验 ACR 四件套 secret;build job 用 matrix 并行构建 web / worker(linux/amd64、provenance=false、sbom=false、gha 分层缓存);verify job 用 imagetools inspect 确认两个 manifest 都在。版本 tag 沿用不可变策略,已存在则失败,手动触发可勾 overwrite。
  • CI 凭据与 kudu-console 统一命名:ACR_REGISTRY / ACR_NAMESPACE / ACR_USERNAME / ACR_PASSWORD 四个 Repository secrets,ACR_REPO 可选 variable(默认 hot-factory)。地址与密码不入库;粘贴带入的换行/空格先清掉,域名带 https:// 或路径直接报错,登录失败给出固定密码/用户名/域名不一致三类原因。
  • 监听默认值 HF_WEB_BIND 由 127.0.0.1 改为 0.0.0.0(.env.example、.env、两个 compose 文件同步)。系统自身无认证,暴露范围改由云安全组与反代控制;README 与 runbook 均标明三种收口方式。
  • 保留 scripts/docker-push.sh 作为本机有 Docker 时的备选路径,产物与 CI 一致。

验证:两个 compose 与 workflow 均通过 YAML 解析(jobs / needs / outputs / matrix 结构逐项核对);pytest 100 passed;脚本 bash -n 通过。

未验证:GitHub Actions 尚无实际运行记录,ACR 推送、容器启动、容器内 Chrome 渲染均未实跑。首次发布以 Actions 日志与服务器 /api/health 的 build_version 为准。(本节写下的"未验证"已在 v0.1.1 补齐:四个 job 全绿、两个镜像进 ACR,见第 16 节。)

明确不做:不配 cron 自动拉 latest,worker 重建会打断正在出片的任务。 (原写的"不采用 ghcr + ACR 双推——worker 1.5GB 跨洋推收益低"已于第 16 节推翻:仓库是 public,ghcr 不计费,实测推送开销可接受。)


15. 2026-11-16 首次发布失败:凭据经 outputs 被 GitHub 丢弃

首次推 v0.1.0 后 Actions 失败,两个 build job 都挂在 Login to ACR:

##[warning]Skip output 'registry' since it may contain secret.
##[warning]Skip output 'namespace' since it may contain secret.
env:  REG:
Error: Get "https://registry-1.docker.io/v2/": unauthorized: incorrect username or password

根因:meta job 把 registry / namespace 作为 job outputs 传给 build。这两个值等于 secret 的字面值,GitHub 出于防泄露会直接丢弃这类 output,下游拿到空串;docker login "" 于是落到默认的 Docker Hub,用 ACR 账号密码当然 401——报错信息指向的 registry 和真实问题完全无关,极易误判成密码填错。

修复:

  • 凭据不再经过任何 job / step output。meta 只输出版本信息(tag / commit / build_time / latest / overwrite,均为非机密);build 与 verify 各自在第一步把凭据归一化后写 $GITHUB_ENV(REG / NS / REPO),后续步骤用 shell 变量。
  • 镜像 tags 也改为 shell 里拼:原实现用 docker/build-push-action 的 tags: 输入,而该输入来自一个含 registry 的 step output,同样会被丢弃。现在直接调 docker buildx build --push,--cache-from/--cache-to type=gha 缓存照旧。
  • 凭据取值改为 vars 优先、回退 secrets,两种填法都能跑;变量名与 kudu-console 保持一致。
  • 去空白更精确:registry / namespace 删全部空白(不可能含空格);用户名与密码只删换行与首尾空白,中间字符原样保留——原先 tr -d '[:space:]' 会删掉密码中间的空格,把密码静默改掉。
  • verify 增加 REG 非空兜底,避免空值再次落到 Docker Hub。
  • 按规范 §6「影响产物的默认值要显式写进 workflow」pin 掉 buildx 版本(v0.38.2),不吃「当前最新」——buildx 默认 manifest 行为一变,就会出现「以前能推现在不能推」。
  • meta 里的 ACR 校验步骤整体删掉,校验前移到使用凭据的 job。

验证:workflow YAML 解析通过;用 Git Bash + 假 docker 实跑了 Normalize(正常 / 混空白 / 带协议头 / 带路径 / 缺 namespace 五种输入)、Login(用户名带换行、密码 pa ss\tword 中间空白保留)、Refuse to overwrite、Build and push(latest=true 两个 tag、latest=false 一个 tag,provenance/sbom 关闭,三个 build-arg 与三个 OCI label、按 target 分 cache scope)。未验证:真实构建与 ACR 推送仍待下一次 Actions 运行。

顺带:本地调试时误把 GITHUB_STEP_SUMMARY 指向 NUL,在仓库根创建了一个名为 NUL 的文件。Windows 把它当设备名,rm / Remove-Item / unlink / DeleteFileW 全部拒绝删除,已在 .gitignore 加 /NUL 阻止入库。


16. 2026-11-16 发布补推 GitHub Packages(ghcr)

v0.1.1 首跑全绿:resolve version 5s / web 1m24s / worker 6m44s / verify manifests 21s,日志实测 Login Succeeded(08:23:37)→ hot-factory-web:0.1.1 不存在,可以推送 → 已推送 .../hot-factory-web:0.1.1(08:24:43)。ACR 侧两个镜像到位。

问题:GitHub 仓库右侧 Packages 是空的——原设计只推 ACR,docker-build-push 的 tag 也只有 ACR 路径,公开镜像无从引用。第 14 节曾把"双推"标为明确不做,理由是 worker 1.5GB 跨洋推收益低;实际前提变了:仓库是 public,公共容器包不计存储与流量费,实测单镜像推送未拖长构建。

改法(一条构建、两个仓库,不重复构建):

  • Normalize 里拼 GHCR="ghcr.io/<owner 转小写>",GHCR 随 REG/NS/REPO 一起进 $GITHUB_ENV;NS / REPO 一并转小写(ACR 与 ghcr 都只接受小写)。
  • build job 声明 permissions: { contents: read, packages: write },新增 Login to GHCR(GITHUB_TOKEN + --password-stdin,不需要额外 secret);verify job 声明 packages: read。
  • 构建命令仍是单条 docker buildx build --push,ARGS 里追加 ghcr 的 -t(版本 tag 与 latest 同步)。
  • Refuse to overwrite 从单 ref 改成遍历两个 ref;verify 增加 GHCR manifests exist 步骤——只查主仓会出现"ACR 有、公开副本没有"却整条绿的假象。
  • 开关:仓库 Variables PUSH_GHCR=false 可关掉公开副本(私有仓库计费场景)。
  • 顺手修:${GHCR:+ + ${GHCR}/...-{web,worker}} 这种写法里含字面量 {},bash 会在第一个 } 提前闭合,PUSH_GHCR=false 时多打印一个 }。改成 if 分支。

验证:workflow YAML 解析(job 权限、新增步骤的 if 条件);替身 docker 实跑 Normalize(正常 / owner 大写 / PUSH_GHCR=false / REPO 大写)、Login to GHCR(登录到 ghcr.io,token 走 stdin)、Refuse(两个都不存在 → 通过;仅 ghcr 存在 → 报错并点名)、Build and push(双推 latest=true 四个 -t、latest=false 两个 -t;PUSH_GHCR=false 时只有 ACR 两个 -t;构建上下文 . 在位)。未验证:真实 ghcr 推送、包可见性、包与仓库的关联,需下一次 tag 实跑确认。


17. 2026-11-16 角色按场景按需出现

问题:构造器给每场无条件挂小人,位置恒为 (0.5, 0.68)、scale 0.8,成片构图刻板;引述场景里躯干还穿过居中引文。

改动:

  • _scene_visuals 无人物语义时返回 None(动作提示命中,或 visualDescription/旁白含「人物 / 小人 / 角色 / 主角」才算有人);
  • 新增 _scene_character 决策:场景显式 character 指定 > 动作/人物语义 > quote 布局(thinking),其余场景 character=None,画面留白给信息图;
  • quote 布局小人让到右侧 (0.8, 0.62)、scale 0.6,避免穿过引文;其余布局保持原站位;
  • 渲染层本就按 scene.character 条件渲染,本次未改 React。

验证:backend pytest 101 passed(新增回归:五场景断言 exhausted / thinking / None / happy / working 与 quote 站位);真实脚本 + 真实 Edge TTS 旁白(25.56 秒)横竖各渲一条,ffprobe 容器时长 == 旁白时长;抽帧确认开场 / 流程 / 对比六场无小人、构图平衡,仅引述场有小人且不穿引文。

遗留:LineCharacter 四肢不渲染仍是既有缺陷(见第 6 节),与本次出场规则无关。


18. 2026-11-16 拆开两个 env:部署参数与应用配置不再同名

问题:仓库根 .env(compose 插值用)与 config/.env(应用配置)同名、同 HF_ 前缀。compose 把根 .env 里那几项注入成容器进程环境变量,而 pydantic-settings 的优先级是「进程环境变量 > dotenv」,于是 config/.env 的同名键被静默忽略——不报错、只是不生效。当前重叠项:

  • HF_MPT_API_BASE:两边都有,容器内实际取根 .env 的值;
  • HF_DATABASE_PATH / HF_DATA_DIR / HF_OUTPUT_DIR / HF_LOG_DIR:compose 固定为 /hotfactory/*,改 config/.env 无效。

改法:

  • 根 .env → deploy.env,.env.example → deploy.env.example(git mv,历史保留);.gitignore 加 deploy.env,同时保留 .env 一条防误建。
  • 三个脚本(docker-push.sh / docker-deploy.sh / docker-update.sh)改读 deploy.env;COMPOSE 统一带 --env-file deploy.env;deploy 脚本额外两条提示——缺 config/.env 时说明会用 fake LLM,发现遗留根 .env 时提示已不再读取。
  • config/env.example 头部写清分工与「容器内被覆盖的四个路径键 + HF_MPT_API_BASE」;deploy.env.example 头部写清 compose 不自动读它、必须 --env-file。
  • README 部署章新增两个 env 的对照表与优先级说明;runbook §9.1 新增「两个 env 的分工 + 改 LLM 的完整动作」,原排错顺延为 §9.2。
  • 没选「把应用配置改名」:compose 的根 .env 约定会被其他工具自动读取,把部署参数命名为显式的 deploy.env、应用配置留在 config/ 下更不容易混。
  • 运维手册 docs/runbook/docker-deploy-upgrade.md 同步改名:cp deploy.env.example deploy.env、7 处 compose 命令补 --env-file deploy.env、§2.2 改写为「两个配置文件」并补同名键覆盖说明、§6.3 增 3 行排错(旧名 .env、漏 --env-file、改 config/.env 的 MPT 地址无效)。

验证:bash -n 三个脚本通过;两个 compose 与 workflow 的 YAML 解析通过;全仓库 grep 确认无 cp .env.example 与裸 .env 残留(仅剩 config/.env、deploy.env 与「旧名 .env」的说明性引用);pytest 未受影响。未验证:真实 docker compose --env-file 插值(本机无 Docker),首次在服务器执行 deploy 时确认。


19. 2026-11-16 审核不通过:驳回即删除

需求:审核处原先只有「审核通过」,不通过的片子只能留在列表里占位。用户决定驳回不保留 REJECTED 中间态,连任务一起删干净。

改动:

  • task_service.reject_task:仅 WAITING_REVIEW 可驳回;先删 output/videos/{task_id}、output/scripts/{task_id}、output/_build/remotion/{task_id} 与 {engine_job_id} 目录,再删 video_file / video_task / script / task 四表记录;文件删不掉抛 RejectError(409),数据库原样保留、关掉预览可重试。
  • 删除范围防护:基准目录先 resolve,目标 resolve 后的父目录必须仍等于基准,带 ../ 的 id 删不到产物根之外。首版用 target.parent.resolve() 当基准,会把 ../ 一起规范化掉而失效,被越界测试抓出后修正。
  • POST /api/tasks/{id}/reject 返回 204;前端 request 增加 204 空响应分支,新增 rejectTask。
  • 前端「审核不通过」danger 按钮 + 确认弹窗:列成片文件名与不可恢复警告,手输主题名匹配才放行,「一键填入」省掉打字;确认后清空当前任务与分镜快照、刷新列表。

验证:backend pytest 110 passed(新增 6 个 service 用例 + 3 个 API 用例,含越界删除防护、删不掉文件时数据库不动、驳回不影响其它任务);前端 vue-tsc + vite build 通过;隔离临时目录起 Web + Worker(mock 引擎)用 Playwright 实点,22 项断言全过:1440 主路径删除、768 取消分支不删、375 弹窗不溢出、驳回后磁盘目录与接口记录消失、无 console 错误;1440 / 768 / 375 截图确认布局。

未验证:真实 Remotion / MPT 引擎下的驳回(本次用 mock 引擎;删除只依赖落库路径与配置目录,与引擎实现无关)。


20. 2026-11-16 部署简化为 GHCR 单源(去掉阿里云 ACR)

  • 触发:服务器实测 docker pull ghcr.io/999bug/hot-factory-worker:0.1.3 可用,ACR 这条线不再有存在价值;而 ACR 侧的跨境登录偶发 read: connection reset by peer,v0.1.2 就是因为这个整条发布失败(web job 挂在 Login to ACR,worker 正常)。
  • workflow 只推 ghcr:删掉 ACR_* 全部环境变量、登录步骤、tag 占用检查与 manifest 校验中的 ACR 分支;PUSH_GHCR / PUSH_ACR 开关一并删除(单目标无需开关),新增 IMAGE_PREFIX(默认 hot-factory)决定镜像名前缀。CI 从 v0.1.3 起不需要任何 Repository secret。
  • 登录保留 3 次重试(5s/10s 退避),针对偶发网络抖动。
  • scripts/docker-push.sh 从「推 ACR」改为「推 ghcr」,凭据改用 HF_REGISTRY_USER/PASSWORD(PAT 勾 write:packages);docker-deploy.sh / docker-update.sh 的登录也统一到 HF_REGISTRY_*(旧名 DOCKER_REGISTRY_* 仍作回退),并加 3 次重试与「公开包匿名拉取」提示。
  • deploy.env.example 默认 HF_IMAGE_REPO=ghcr.io/999bug/hot-factory;删掉 HF_PUSH_IMAGE_REPO 与 ACR 凭据示例。
  • 文档整体简化:README 部署章从 155 行压到约 55 行(发布 → 首次部署 → 升级回滚 → 校验,ACR 与 secrets 表全部删除);docs/runbook/docker-deploy-upgrade.md 从 280 行压到约 190 行并去掉「升级 Docker 引擎」一章;weekend-slice.md §9 同步单源、排错表删掉 4 行 ACR 相关项。

验证:workflow YAML 解析通过;替身 docker 实跑 Normalize(owner 大写、IMAGE_PREFIX 带空格与大写均归一为小写)、Login(目标 ghcr.io/<owner>、token 走 stdin)、Refuse(不存在→放行;存在→点名报错)、Build and push(latest=true 两个 -t、false 一个;--provenance=false --sbom=false、三个 build-arg、三条 label、缓存 scope 到位);三个脚本 bash -n 通过;两个 compose 解析通过。未验证:真实 ghcr 推送(待 v0.1.4)、服务器拉取与容器启动。


21. 2026-11-16 文档收敛:GHCR 镜像手册 + 清掉 ACR 残留

  • 触发:第 20 节把部署简化为 GHCR 单源,但文档没跟上——runbook 仍按「部署 / 升级」两段写,"镜像怎么来、怎么验、公开还是私有"散在 README 与 weekend-slice.md;docker-deploy-upgrade.md 装 Docker 还指着阿里云 apt 源(服务器能直连官方源,没必要留)。
  • docs/runbook/docker-deploy-upgrade.md 重写为**「GHCR 镜像使用、部署与升级」单一手册**:新增 §1(两个镜像与 linux/amd64 限制、tag 规则与不可变、包 Public/Private 与 PAT 的取舍、不部署先验证镜像、发布链路);§2 装 Docker 改回 download.docker.com 官方源,不再指定任何国内镜像厂商;§4 升级补磁盘回收与「latest 只用于解析真实版本」;§6 排错补 ARM exec format error、镜像占盘两行;§1.4 给可直接跑的三条验证命令 + 冒烟 docker run。
  • README.md 部署章:链接文案改为「GHCR 镜像怎么拉」,新增「发布成没成,不用部署就能验」三条命令,验证状态更新到 v0.1.4(GHCR 单源、verify manifests 全绿)。
  • docs/runbook/weekend-slice.md §9 的指向同步。
  • ACR 已在第 20 节从 CI / 脚本 / deploy.env / workflow 中删除;第 13~19 节只作历史留痕(为什么起 ACR、v0.1.0/v0.1.2 为什么挂),不是现行做法,勿照做。

验证:本轮只改文档,无代码改动。v0.1.4 Actions 实跑 success(1m49s,verify manifests 通过,两个镜像进 GHCR),公开包可匿名拉取(用户服务器已实测 0.1.3);容器启动仍未验证(本机无 Docker)。


22. 文档索引

文件 用途
docs/design/hot-factory-overview-design.md 架构单一真源(v1.0):接口、状态字段、能力边界、三阶段路线
docs/runbook/docker-deploy-upgrade.md GHCR 镜像与部署唯一手册:镜像清单与 tag 规则、公开/私有拉取、装 Docker、首次部署、升级、回滚、排错
docs/runbook/operations.md 当前运行与出片手册(原 weekend-slice.md):启动、配置、批量命令、降级矩阵、实测契约
README.md 安装、快速开始、端到端实测、部署速览、接口一览
docs/progress/PROCESS.md 本文:进度、验证事实、已知限制与待办
docs/design/release-docker-module-v2.md 给 ai-dev-standards 的 release-docker.md v2 候选稿(待合入:Part 1 可直接覆盖模块,Part 3 是事故证据、不进规范;文中 ACR 只作通用示例,与项目部署无关。合入后可删)
.workbuddy/memory/ 工作区长期笔记与每日日志