最后更新:2026-11-16 17:30(GMT+8) 用途:跨会话共享的进度台账。架构契约以
hot-factory-overview-design.md为唯一真源,本文只记录进度、状态、验证事实与待办,不重复定义接口和状态字段。 维护约定:完成一项即更新状态;只记有长期价值的事实,不记临时路径、一次性报错与中间产物。
第一版(= 三阶段路线的第一阶段)工程骨架已可运行;已用真实 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 均有降级路径 |
| 阶段 | 目标 | 状态 | 说明 |
|---|---|---|---|
| 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 优先,保留人工确认 |
- 把概要设计从 Java + Spring Boot + PostgreSQL + Redis 基线整体改写为 Python + Vue 3 基线,保留合规、平台调研与验收章节。
- 新增
docs/runbook/weekend-slice.md执行切片,核实 MPT 已内置配音 / 字幕 / 素材 / 异步进度,指出蓝图存在重复建设。 - 把「复用优先」写成正式契约:删除
TTS_SYNTHESIS、providers/tts/、自研字幕与第二套进度体系;任务类型 7 → 4;补run抽象、ManualHotSource、降级矩阵与表分期。 - 本机实测官方
mpt1.3.10 后,把三处会卡死真片的错误写进契约并修代码:state = -1/1/4、videos返回/tasks/<id>/final-1.mp4相对 URI、video_source=local必须带video_materials。 - 本轮收敛:
docs/两份文档重写为 v1.0 现行架构与当前运行手册,清除历史沿革、废弃方案对照与已过期的时间盒;README.md同步版本号、章节引用与测试数量。
| 模块 | 落地内容 |
|---|---|
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:主题输入、素材上传、一键生成、进度轮询、成片预览、审核通过 |
- 成片按主题命名:引擎产出的
final-1.mp4落库前改为data/videos/{task_id}/{主题}.mp4,规则在core/naming.py(去 Windows 非法字符、按字符截断、保留名兜底);TaskOut.topic由payload.topic派生,任务列表新增「主题」「成片」两列。 - 页面手动上传素材:
POST /api/materials转发引擎POST /api/v1/video_materials,不新建素材库;上传后文件随任务payload.materials提交,只使用选中的素材,解决「测试彩条混进成片」;一个不传才回落引擎库全集。 - 新增
python-multipart依赖(FastAPI 表单上传必需),backend/requirements.txt已补。 - 测试:新增
test_naming.py(12 例)、test_materials.py(4 例)、流水线素材透传与改名断言,合计 pytest 50 passed;前端vue-tsc+vite build通过。 - 实测:真实引擎下上传一张 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 质检。
| # | 验证 | 结果 |
|---|---|---|
| 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取文件名。
| 项 | 结论 |
|---|---|
| 引擎是否支持总时长 | 不支持。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/。
| 项 | 结论 |
|---|---|
| 改动 | 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 两档截图确认无挤压,窄屏下首列仍完整可见(右侧列走表格既有横向滚动) |
| 范围 | 纯展示,未改接口、状态字段、任务逻辑与交互;行点击是既有功能 |
一句话: 自研 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 或消息队列。
硬约束:新增任何模块前先查上游是否已提供;已提供的只做配置透传或状态翻译,不重写。
| 类别 | 内容 | 原因 |
|---|---|---|
| 已废弃技术栈 | 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 | 权限 / 阶段 / 适配度原因,仅列为未来候选,不是当前依赖 |
- 真片画面是 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 字符串均完整,根因未定),单独排查,不影响链路验收。
| # | 待办 | 前置条件 |
|---|---|---|
| 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 |
已落地:
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 章实测,当前会话未再次调用外部引擎。
已落地:
video-renderer/独立 Remotion 工程,消费Storyboard v1.0;- 暗色渐变/网格背景、暖黄色发光 SVG 小人、电脑/电池/时钟/文档等图标;
- 标题、旁白字幕条、进度条和
title/character/infographic场景; fade_in、slide_up、slide_left、scale_in、draw_and_move、pulse、shake等动画预设;- Worker 新增
remotionVideoEngine,渲染后复用.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 动态画面。
已落地:
- 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 封装;真实城市环境采样和逐句字幕仍不在本项目自研范围内。
问题:数据库、成片、分镜、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/。
问题: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、热点采集等仍在待办,本轮未动。
目标:把「本机三进程直跑」之外的容器交付补齐——一条 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。
目标:本机没有 Docker,发布不该依赖本机装 Docker Desktop。改为推 tag 由 GitHub Actions 构建推送 ACR;Web 端口按部署需求改为公网直连。
改动:
- 新增
.github/workflows/docker.yml:push v*tag 或手动workflow_dispatch触发;metajob 解析版本(tag 去v前缀,手动留空则manual-<短 commit>)并校验 ACR 四件套 secret;buildjob 用 matrix 并行构建web/worker(linux/amd64、provenance=false、sbom=false、gha 分层缓存);verifyjob 用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 不计费,实测推送开销可接受。)
首次推 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 阻止入库。
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 都只接受小写)。buildjob 声明permissions: { contents: read, packages: write },新增Login to GHCR(GITHUB_TOKEN+--password-stdin,不需要额外 secret);verifyjob 声明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 实跑确认。
问题:构造器给每场无条件挂小人,位置恒为 (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 节),与本次出场规则无关。
问题:仓库根 .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 时确认。
需求:审核处原先只有「审核通过」,不通过的片子只能留在列表里占位。用户决定驳回不保留 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 引擎;删除只依赖落库路径与配置目录,与引擎实现无关)。
- 触发:服务器实测
docker pull ghcr.io/999bug/hot-factory-worker:0.1.3可用,ACR 这条线不再有存在价值;而 ACR 侧的跨境登录偶发read: connection reset by peer,v0.1.2就是因为这个整条发布失败(webjob 挂在 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)、服务器拉取与容器启动。
- 触发:第 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 排错补 ARMexec 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)。
| 文件 | 用途 |
|---|---|
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/ |
工作区长期笔记与每日日志 |