长动画交付流水线
 
 
 
 
 
Go to file
mula.liu 41febc241b docs(reports): 阶段 4–45 实施报告入仓 + 按新规则放行的取证尺
`reports/*.md` 是要留的验收报告,`reports/ui_evidence/` 里放行的只有尺子与手册
(`.py`/`.mjs`/`vo/README.md`),截图与日志等可再生证据本体照旧不进仓——这条边界
由上一个 `chore(仓库)` 提交的 `.gitignore` 定义。

- 40 份阶段报告:NEX 阶段 4–45(含 8.5、8.5.1、22.5 三轮小数号),每份都是
  「改了什么 / 复用了什么 / 偏离了哪条 / 实跑读数 / 未完成」五段式;
  外加两篇 2026-10-26 的验收报告与 `UI审计与调整`。
- 202 份取证工装:`nex-p8`…`nex-p44` 各阶段的探针脚本、读屏腿(`vo6.py`、
  `run_t1.py`、`spinpreflight.py`、`gateselftest.py`、`mdtablecheck.py`)、
  Bundle 尺(`closure.mjs`、`eagergraph.mjs`、`lazykit.mjs`、`attribbucket.mjs`)
  与 `vo/README.md` 手册。`UI规范.md` 与这些报告里点名的路径在新克隆里从此真实存在。
- 报告里「未 commit」那类句子已统一加时点限定(阶段 44、45 两份本轮改的就是这个口径)。
2026-11-12 10:22:03 +08:00
backend perf(交付面): 按 media type 压缩 + 哈希产物长期缓存,后端与 nginx 同一套口径 2026-11-12 10:21:17 +08:00
docs docs(规范): 阶段 9–45 口径入册(含 §13.14 执行过程那条)+ 台账 E11 与落地追记 2026-11-12 10:21:58 +08:00
frontend feat(前端): 阶段 9–45 呈现层落地——环节资产同构、图标两级表、kit 分包与四处交互收口 2026-11-12 10:21:29 +08:00
nex_design_system@10ccdc164c chore(仓库): 证据目录只放行尺子与手册 + nex_design_system 登记为 submodule 2026-11-12 10:20:59 +08:00
reports docs(reports): 阶段 4–45 实施报告入仓 + 按新规则放行的取证尺 2026-11-12 10:22:03 +08:00
scripts test(闸门): 常驻探针补两只新闸与凭据口径,14 道全绿 2026-11-12 10:21:48 +08:00
.dockerignore 打成 Docker 只留一个容器:前端产物与后端同进程同端口,Postgres/Redis/Celery 收成可选扩容层 2026-11-05 17:39:12 +08:00
.env.example fix(配置): 初始管理员口令三处对齐到 admin@123,测试不再抄第二遍口令 2026-11-12 10:21:03 +08:00
.gitignore chore(仓库): 证据目录只放行尺子与手册 + nex_design_system 登记为 submodule 2026-11-12 10:20:59 +08:00
.gitmodules chore(仓库): 证据目录只放行尺子与手册 + nex_design_system 登记为 submodule 2026-11-12 10:20:59 +08:00
AGENTS.md docs(规范): 阶段 9–45 口径入册(含 §13.14 执行过程那条)+ 台账 E11 与落地追记 2026-11-12 10:21:58 +08:00
Dockerfile 依赖下载点全部配国内源,并修掉「镜像里没有中文字体」这个字幕坑 2026-11-05 19:36:32 +08:00
README.md docs(规范): 阶段 9–45 口径入册(含 §13.14 执行过程那条)+ 台账 E11 与落地追记 2026-11-12 10:21:58 +08:00
docker-compose.scale.yml 模型配置全部交给数据库,.env 只管进程参数;media 从库里搬出来单独一个挂载点 2026-11-05 18:18:00 +08:00
docker-compose.yml fix(配置): 初始管理员口令三处对齐到 admin@123,测试不再抄第二遍口令 2026-11-12 10:21:03 +08:00
nex.config.yaml docs(规范): 阶段 9–45 口径入册(含 §13.14 执行过程那条)+ 台账 E11 与落地追记 2026-11-12 10:21:58 +08:00

README.md

Nex Animation Studio · 长视频编导平台

面向 AI 长视频创作的本地工作台:人物与声音资产库 → 分镜与脚本管理 → 视频模型调度中心 → 长视频合成引擎, 底层由统一任务编排(队列 / 重试 / 断点续跑 / 并发限流)与项目数据库支撑,完整实现业务流程图的 12 个节点。

📖 图文使用手册 —— 已搬进站内:启动后访问 http://127.0.0.1:5173/help,或点工作台顶栏的「手册」

手册包含模型管理中心、资产独立生成与镜头关联、分镜检查器、调度、质检、时间线和导出流程的实际截图。

🧹 动代码或打部署包之前先读 工程规范与部署数据边界: 目录职责、scripts/ 准入规则、测试规范、改动后的最低验收三连,以及服务器上「什么该搬、什么不该搬」。

┌─────────── Browser (React 18 + Ant Design 5 + Vite + Zustand + Router 6) ─────────────┐
│ 项目总览 │ 资产库 │ 分镜与脚本 │ 调度中心 │ 质检与审核 │ 时间线合成 │ 导出与成本          │
└─────────────────────────────────────┬───────────────────────────────────────────────────┘
                                      │ REST / JSON + multipart  (vite proxy 或 nginx)
┌─────────────────────────────────────▼───────────────────────────────────────────────────┐
│ FastAPI (backend/app/api)  system · library · storyboard · pipeline · delivery · agent   │
│  services: importer prompt preflight dispatch execution quality timeline compose agent  │
│            costing ffmpeg audio storage events status daemon                            │
│  providers: mock · http_generic · comfyui(含 IndexTTS2 配音)+ provider_models 模型注册表   │
└───────┬───────────────────────────────────────────────┬─────────────────────────────────┘
        │ TASK_EXECUTOR=celery                          │ TASK_EXECUTOR=inline(单机自检)
┌───────▼───────────────┐                    ┌──────────▼───────────────┐
│ Redis + Celery        │                    │ 进程内线程池 +           │
│ worker(generate/audio/│                    │ 守护线程(周期派发 +     │
│ qc/compose/io)+ beat │                    │ 断点续跑)               │
└───────┬───────────────┘                    └──────────┬───────────────┘
        └───────────────► FFmpeg / ffprobe(转场、混音、响度、质检) ─◄──┘
                             │  Postgres / SQLite  +  MEDIA_ROOT 媒体库(/media 直出)

仓库目录与脚本职责

backend/    FastAPI 应用:app/api 路由 · app/services 编排 · app/providers 模型适配 · tests 回归用例
frontend/   React 18 + Ant Design 5 + Vite + Zustand + React Router 6 工作台
            (图文手册 = src/pages/Help.tsx,截图在 public/help/)
scripts/    只放启动 / 部署 / 运维脚本(下表);一次性验证探针不进这个目录
docs/       UI 规范、工程规范、H3 性能诊断记录
media/      产物库(MEDIA_ROOT)    models/ whisper 词级对齐权重    reports/ 阶段验收证据
.local/     开发态日志与 pid        .trash/ 删除暂存(两者都不进 git,删掉就没了)
.env        本机配置与密钥(不进部署包)    nex_animation.db  开发库

frontend/src/ 分层(依赖只允许自上而下,页面之间不互相 import):

api/        唯一的 fetch 出口:信封自动拆包、detail 统一成 Error、401 跳登录
app/        应用外壳:router.tsx 路由表(唯一一份)· layout/ 顶栏侧栏与 nav.tsx 两级导航表 · 鉴权闸门
pages/      页面与项目子页(项目详情里的业务子页走 <Outlet/>,不是外壳页签),一屏一文件;
            页面私有的类名常量/子组件留在文件底部
components/ 页面只从这里取组件,三个目录按职责分:
            ui/ antd 的唯一封装层 + 自绘版式件(Button/Input/Checkbox/Menu/Overlay/Status
                + Field/Ctlbar/FormGrid/Table/Steps/Tabs/Pager/Rows…)
            forms/ 选择器族(Select/MultiSelect/SecretInput + toOptions,本体是 antd Select)
            media/ 带全局状态的媒体件(MediaThumb/AudioPlay/RecordAudio/MediaLightbox/VersionPanel…)
theme/      只剩 antd.ts 一个文件,它是本站对 antd 的唯一改动清单:buildAntdTheme() 品牌色 + 表面色
            + 少数结构性 ComponentToken(几何/字阶/圆角/间距/断点一律用 antd 默认)· applyRootVars()
            在 createRoot 之前把同一批 token 以 --ant-* 的名字铺到 :root · HEADER_HEIGHT 顶栏高度
stores/     zustand 切片:auth · theme · notice · project · models · system · audio · preview · recording
hooks/      use-async / use-polling / use-auto-refresh / use-local-storage(浮层外点关闭交给 antd,不再自己实现)
lib/        纯函数与适配器:cn · format · media · pipeline · recorder · versions · layers
styles/     index.css(Tailwind @theme:语义名 → antd 落下来的 --ant-*,零像素,圆角与字阶只是别名)
            · app.css(语义布局类 + 标签度量 --tag-* + 全站唯一允许写 .ant-* 的地方)

新增页面只做三件事:在 pages/ 落文件 → 在 app/router.tsx 注册 → 复用 components/* 原语, 缺原语就补进 components/(不要复制粘贴样式)。加一类新母版、加一个项目环节(改 app/layout/nav.tsx 那张两级导航表 + app/router.tsx 子路由)、加一个页面内部页签同理:改表不改逻辑(见 docs/工程规范.md §1.1)。

控件统一用 Ant Design 5(2026-11-02 定案,此前「Radix primitives + 自有皮肤」那一版已废弃): 浮层定位、翻边避让、焦点圈定与归还、键盘、Esc 分层、锁滚动这些行为不再自己实现—— 自己实现时「字段标题与控件不对齐」「下拉面板该翻不翻被压成 35px」这类问题修不完, 而每一项都是组件库早就解决过的。尺子也交还给 antd:自造的 metrics.ts / palette.ts / css-vars.ts 三把尺子已删,theme/antd.ts 一处写完两件事——buildAntdTheme(mode) 只改品牌色、 表面色和少数结构性 ComponentToken(几何、字阶、圆角、间距、断点全用 antd 默认档位), applyRootVars(mode) 在 createRoot 之前把 antd 算出来的 token 以 --ant-* 铺到 :root; Tailwind 的 @theme 只是把 --ant-* 转发成语义类名,控件与自绘区读同一批变量,不可能漂成两套。 硬边界:全仓库只有 theme/ · app/(providers.tsx 与外壳 layout/ 四件套直接铺 Layout.*, 外壳没有第二份实现,包一层只会多一个名字)· components/{ui,forms} 可以 import 'antd'—— R8,探针第 5 道闸逐行扫,不再只写在文档里(吐司自绘后 stores/notice.ts 已从白名单摘掉); .ant-* 选择器只准出现在 styles/app.css;pages/ 与 app/ 里一个原生 <button> / <input> / <select> / <textarea> 都没有,也不许给控件拼 bg-/border-/rounded-。裸 <button> 只许留在 「自定义表面族」里,判据是几何而不是长相:宽高由所在那块媒体/容器决定、antd 三档 24/32/40 套不进去的才算。 白名单就 7 个文件(classaudit.mjs:CUSTOM_SURFACES)——ui/Controls(Chip / TagChip 的叉)、 ui/Overlay(Scrim 整屏遮罩)、media/MediaThumb(封面角标与删除叉)、media/AudioPlay(走带键)、 media/MediaLightbox(灯箱翻页钮)、media/VersionPanel(版本缩略热区)、pages/project/Storyboard; 另有宿主标签不写字面量的 ui/Tile(<As>,见 HOST_ELEMENT)。 自绘区只剩三块并已在规范里登记边界:Table、Steps、媒体区(缩略图 / 播放条 / 录音 / 灯箱 / 时间线)。 再加一条 ref 契约(R10):kit 组件一律 forwardRef,交给页面的 ref 只能是真实 DOM 节点, antd 的 InputRef / TextAreaRef 在 kit 内部折掉(lib/ref.ts)——React 18 的函数组件收不到 ref, tsc 不报错、像素不变,四处「点了不聚焦」就是这么静默死掉的(报告 26.6)。 这些边界都不靠自觉,两道闸各管一头:

  • node scripts/ui/classaudit.mjs——源码用词(静态,七道检查,退出码 = 七项违规之和): Tailwind 生成不出规则的死类名(v4 改过名的 break-anywhere 这类静默失效)/ 绕过图标登记表的 @ant-design/icons import(只许 components/icons/index.ts 一处)/ 未收口的裸 <button>(白名单外即违规;白名单文件一个 nex-* 标记都不写了也违规——说明这一族 已被 antd 取代,条目该从表里删)/ 浮层底部动作条口径(不写 size、type="primary" ≤1、 danger 必须同带 type="primary"、最后一颗是主行动)/ 越界的 import 'antd'(R8)/ 绕开反馈四级表面(R19:window.confirm · window.alert · Modal.confirm · message · notification · 裸 <Alert> 一律点名)/ 标题前置图形(R20:一级标题前不挂图标与色块);
  • .venv/bin/python scripts/ui/visualcheck.py——渲染结果(浏览器实测,逐路由 × 逐档宽度 × 明暗两色, 八类断言 + console / pageerror,逐条口径见 docs/UI规范.md §15.2):先把 chromeless 的登录页量一遍再登录 (登录后访问 /login 会被鉴权守卫弹回首页,登录后再量只会得到假故障);:root 上的 --ant-* 是否真的铺到、文字行高有没有塌成 px、侧栏选中态是否跟路由走(≤768 侧栏折叠,二级项在 hover 浮层里, 探针会把浮层打开确认那一条真的带 .ant-menu-item-selected)、请求的路由有没有被 path:'*' 静默重定向、 display utility 有没有被组件样式静默盖掉(R13 那条层叠陷阱)、横向溢出(祖先横向滚动盒或程序滚动的 裁切盒接住的不算——antd 页签条收溢出页签用的正是后者)、overflow:hidden 切掉的字、 控件标签被省略号截掉(分段 / 页签 / 按钮 / 下拉当前值)、4xx/5xx(按 URL 分诊:素材文件在 开发库里缺失的 404 单独计数,接口 404 判失败并点名发出它的路由)。

选型理由、四层分工、咬过人的陷阱见 docs/UI规范.md §0(二十条硬规矩 R1–R20)与 §1。 旧的手写规范探针(scripts/ui/legacy/{audit,metrics,vocab}.py)已作废归档。

改过控件、表单或主题,提交前跑一遍 UI 体检(前端 5173 与后端 8000 需在跑):

cd frontend && npx tsc --noEmit && npm run build
node scripts/ui/classaudit.mjs                                                          # 源码用词闸(不用起服务)
NEX_WIDTHS=1440,992,768,430 NEX_THEMES=dark,light \
  .venv/bin/python -u scripts/ui/visualcheck.py                                         # 渲染结果体检 + 截图
.venv/bin/python -u scripts/ui/aligncheck.py                                            # 同一行同心 + 只读胶囊字重(R3 · R20)
.venv/bin/python -u scripts/ui/symmetrycheck.py                                         # 跨页同一把尺:门牌标题左缘 / 标题行中线 / 主操作右缘三个集合必须各是单值(R20)
.venv/bin/python -u scripts/ui/feedbackcheck.py                                         # 吐司 / 确认框运行时复验(R19,明暗各一遍)
.venv/bin/python -u scripts/ui/projectswitchcheck.py                                    # 改了项目数据生命周期(详情 store / 切换与轮询)再跑这条:换项目不残留、404 认错、静置不闪

体检默认量 dev server(5173):console 那一项只能在 dev 上量——React 与 antd 的告警是 DEV-only,拿 NEX_UI_BASE=:4173 量构建产物时它恒为 0,别把那份绿当证据。

脚本 干什么 在哪儿跑
scripts/dev.sh 开发态前后端两个进程(后端 8000 + Vite 5173),缺 .env / .venv / node_modules 自己补 开发机
scripts/server.sh 服务形态全生命周期:install build start stop restart status verify logs systemd 服务器
scripts/deploy.sh 打部署包(白名单 + 体检),或直接 rsync 上服务器并自动安装、重启 开发机
scripts/seed.py 迁移「模型配置 + 加密主密钥 + 管理员」:doctor 体检数据集与代码是否对得上、export --fix 校准并导出、install 装前自动体检再幂等落地、boundary 数据边界一览 两端
scripts/e2e_selfcheck.py 图2 全 12 节点端到端自检(真实 HTTP + ffprobe 实测产物) 两端
scripts/evidence_prune.py 清理 reports/ 下过期的验收证据目录 开发机

1. 图1 模块规划 → 代码实现

模块 后端服务 / 接口 前端页面 关键能力
① 人物与声音资产库 app/api/platform.py、app/api/library.py、services/storage.py、services/audio.py pages/AssetLibrary.tsx、pages/project/Library.tsx 平台级人物 / 场景 / 声线母版创建时始终全局,不绑定项目;项目目标只在「引入项目」时选择。母版可上传、AI 生成、编辑,项目资产可反向「上架平台」。图片支持大图预览,每个媒体可单独删除,不必删除母版。声线在创建时只录入基础设定,生成试听时再选真实模型;项目内继续维护定妆图/三视图/服装/表情、场景图、声线与项目素材;每次上传生成新版本,删除留痕
② 分镜与脚本管理 app/api/storyboard.py、services/importer.py、services/prompt.py、services/preflight.py pages/project/Storyboard.tsx(分镜工作台) Markdown/CSV/TSV/JSON/纯文本脚本导入 + 图片按镜号自动匹配关键帧(支持 zip);shots/preview 与 dry_run 先预览后落库;镜头增删改/排序、人物场景绑定、提示词组装与版本留痕、首尾帧/参考图上传;shots/board 轻量看板(逐镜预检)、shots/bulk 批量复制/移动/改参/删除、shots/export 反向导出 md/csv/json
③ 视频模型调度中心 app/api/pipeline.py、services/dispatch.py、services/capacity.py、services/execution.py、services/daemon.py、app/providers/* pages/project/Dispatch.tsx 任务清单(预检驱动,可解释「为什么跳过/阻塞」)→ 入队 → 按 provider/model 并发槽位与 RPM 限流派发(一个模型一行,视频与 TTS 各自的限额互不串台) → 指数退避重试 → 中断任务断点续跑;模型注册表在线启停/设默认/调并发/调限流/注入故障演练
④ 长视频合成引擎 app/api/delivery.py、services/timeline.py、services/compose.py、services/ffmpeg.py、services/quality.py pages/project/Review.tsx、Timeline.tsx、Delivery.tsx 自动质检 7 项打分;人工审核合格/驳回重做;时间线(片段裁剪/转场/排序/字幕/配音/BGM/响度归一化);交付预检报告;4 档出片预设 + 校验和留档;成本台账与生成记录可复现
底层:任务编排 + 项目数据库 app/models/*、app/db.py、services/events.py、services/status.py、services/costing.py pages/Dashboard.tsx、pages/ProjectDetail.tsx、pages/project/Overview.tsx 12 张表(项目/人物/场景/声线/素材/素材版本/镜头/任务/审核/时间线/片段/字幕/音轨/导出/成本/生成记录/事件);任务幂等键、心跳、错误历史、检查点;全流程事件流与流程进度视图

2. 图2 业务流程 → 状态机与接口

流程节点定义在 backend/app/services/status.py:PIPELINE_STAGES,每个项目/镜头/任务的真实状态收敛成 GET /api/projects/{id} 的 workflow[](pending/active/done/failed),前端 components/media/WorkflowBar.tsx 直接渲染。

# 节点 主要接口 镜头状态流转
1 创建视频项目(可顺带勾选资源库母版 platform_assets:[{owner_type,asset_id}]) POST /api/projects(返回 imported_assets/import_failures)、`GET /api/platform/assets?owner_type=human scene
2 导入分镜图片与脚本 POST /projects/{id}/shots/preview、POST /projects/{id}/import(dry_run/replace/keep_existing/images[]/archive);看板与批量:GET /projects/{id}/shots/board、POST /projects/{id}/shots/bulk、GET /projects/{id}/shots/export 新建镜头 → ready
3 绑定人物/场景与声音资产 POST /projects/{id}/shots/{sid}/bindings、/assets、/characters/{cid}/assets binding → ready
4 生成分镜任务清单 GET /projects/{id}/tasklist、POST /projects/{id}/tasks ready → planned
5 检查素材与参数 GET /projects/{id}/preflight(逐镜头 issues[{code,field,message,severity}]) 阻塞项阻止入队(可 allow_unready)
6 任务队列调度 POST /projects/{id}/dispatch(limit/drain/timeout)、GET /projects/{id}/queue planned → queued → running
7 调用视频模型 任务执行 app/jobs/tasks.py → providers/* running(进度/心跳/尝试次数)
8 下载并保存视频 同上(产物落 MEDIA_ROOT 并注册资产) running → generated
9 质量检查 GET /projects/{id}/qc、POST /projects/{id}/shots/{sid}/qc?drain= generated → qc_passed(失败 → generated + quality_check_failed)
10 人工审核 GET /projects/{id}/reviews、POST .../approve、POST .../reject qc_passed → approved / rejected
11 调整提示词重新生成(驳回回路) reject 携带 prompt/negative_prompt/regenerate → 自动重排任务;POST /projects/{id}/voiceover 补配音 rejected → planned → running
12 时间线合成 + 配音/字幕/混音 → 导出 POST /projects/{id}/timeline、/timeline/segments/{id}、/timeline/reorder、/timeline/subtitles、/timeline/audio、/timeline/settings、GET /timeline/report、POST /compose、GET /exports、GET /api/exports/{id}/download 项目 composing → delivered

失败与恢复:POST /api/tasks/{id}/retry|cancel、POST /projects/{id}/tasks/retry-failed、/tasks/cancel-active、 /projects/{id}/resume(running 超过 STALE_RUNNING_SECONDS 视为中断并带上 checkpoint 续跑)。

2.1 项目主页 LLM 总控台(pages/project/Overview.tsx)

项目主页顶部提供自然语言总控台:使用系统注册并启用的默认真实 LLM 盘点镜头、关键帧、模型能力和 当前阻塞,先落库为可审阅的执行计划,再由用户确认执行。LLM 不直接操作媒体或数据库,后端只接受 resume / rewrite_shots / generate_keyframes / generate_shots / quality_check / approve_passed / build_timeline / compose 八个白名单动作。主题或剧情变化时,rewrite_shots 会整组替换分镜、 按引用补齐缺失场景/人物、作废旧镜头产物并重建后续时间线;创建/删除项目、任意改资产文件或调用 任意 URL 仍不可用。

端点 用途
POST /api/projects/{id}/agent/plan 将自然语言目标转换为结构化计划并持久化
GET /api/projects/{id}/agent/runs 查看当前与历史调度记录
GET /api/projects/{id}/agent/runs/{run_id} 查询分步执行状态与结果
POST /api/projects/{id}/agent/runs/{run_id}/execute 用户确认后执行,默认异步轮询
POST /api/projects/{id}/agent/runs/{run_id}/cancel 请求在当前步骤结束后取消

审核门禁默认开启:未勾选「质检合格后允许 AI 代审」时,计划只能推进到人工审核前;只有用户显式授权后, approve_passed 才会以 kind=agent 单独留痕,绝不冒充人工审核。调度器拒绝 Mock LLM 和 Mock 媒体模型, 不会在真实模型缺失时静默回退。已完成且产物有效的步骤会跳过,失败步骤可从断点继续;实现见 backend/app/services/agent.py,契约测试见 backend/tests/test_agent_orchestrator.py。

2.2 分镜工作台(pages/project/Storyboard.tsx)

分镜是几十上百镜的大页面,所以列表不走返回全字段的 GET /shots,而是按用途拆成三层:

端点 用途 关键字段
GET /projects/{id}/shots/board 看板/分镜表首屏,一次请求带齐指标与逐镜预检 每镜 ready + issues[{code,field,message,severity}]、缩略图地址、QC 分、绑定摘要;不含 prompt 正文、版本、素材明细
GET /projects/{id}/shots/{sid} 选中某镜时按需拉全量详情喂给检查器 prompt / 素材 / QC 明细 / 配音 / effective_*
GET /projects/{id}/shots/export?fmt=md|csv|json 导出给编剧或外部工具 md 与导入格式双向可逆,导出文件可直接再导回
POST /projects/{id}/assets/generate 分镜关键帧 / 尾帧 / 参考图走独立图像模型 target_type=shot、当前镜头提示词、人物/场景/镜头参考图;生成结果覆盖同一关键帧槽位的新版本

批量操作统一走 POST /projects/{id}/shots/bulk(action=duplicate|delete|move|patch):一次请求一个事务, 避免 N 个镜头触发 N 次全项目预检。duplicate 插在来源之后并重排镜号、不继承产物;move 支持 index(绝对落点)与 delta(相对位移);patch 拒绝批量改镜号(镜号需唯一)并在改到摄影参数后重算提示词。 写接口侧的约束也一并收紧:枚举字段与 duration>0 校验不过一律 400(原先静默写脏值)、镜号冲突返回 400 而非 500、 seed 允许显式清空、删除镜头后镜号自动续排。回归见 backend/tests/test_storyboard_workbench.py。

页面交互:网格 / 分镜表双视图(选择记在 localStorage)、搜索 + 状态/模式/排序筛选 + 仅看阻塞/缺关键帧、 HTML5 拖拽改镜序、Shift 范围勾选、批量复制/移到最前/统一改参数/删除。选中镜头后打开独立右侧宽抽屉, 四页签(镜头 / 资产 / 提示词 / 产物)不再挤压分镜看板;关键帧、尾帧、参考图、视频和配音均可在 图片 / 视频 / 音频统一灯箱中预览,并可直接打开原文件。资产页签内置「AI 生成关键帧」, 显示并选择当前真实图像模型,自动带入场景图、人物定妆图和镜头参考图,生成后直接成为 i2v 首帧。 检查器带脏标记与 ⌘S 保存,快捷键 J/K 切镜、X 勾选、Esc 关闭。 卡片上的「生成」「审核」带 ?shot= 深链到调度中心 / 审核页并自动选中该镜。

3. 启动方式

3.1 单机模式(无需 Redis/Postgres,适合开发、演示、自检)

一条命令搞定前后端:

./scripts/dev.sh                 # 启动前后端(缺 .env / .venv / node_modules 会自己补)
./scripts/dev.sh status          # 端口 / 健康 / 当前默认模型 / ComfyUI 连通性
./scripts/dev.sh logs            # 同时跟踪前后端日志(logs backend|frontend 看单个)
./scripts/dev.sh stop            # 停止(按进程组回收,不留孤儿 vite / uvicorn worker)
./scripts/dev.sh restart --reload

选项:--backend-only --frontend-only --reload --no-install --backend-port N --frontend-port N --host ADDR(换端口时 Vite 代理目标自动跟随)。 日志在 .local/logs/,pid 在 .local/run/。

局域网访问(手机 / 同事的电脑打开同一套平台)

dev.sh 默认监听 0.0.0.0,启动时会把本机与局域网地址一起打出来:

界面     http://127.0.0.1:5173     (Vite → 代理 /api、/media 到后端)
接口     http://127.0.0.1:8000/docs
局域网   http://192.168.2.19:5173   (同网段设备可直接打开)
局域网   http://192.168.2.19:8000/docs
  • 同一网段的设备直接开 http://<本机IP>:5173 即可:/api、/media 都由 Vite 代理回后端, 接口返回的又都是相对路径,不会出现「图片只在这台机器上能看」。
  • 只想给本机用:./scripts/dev.sh --host 127.0.0.1(NEX_HOST 环境变量同样生效)。
  • mDNS 机器名(http://<名>.local:5173)已在 frontend/vite.config.ts 的 server.allowedHosts: ['.local'] 里放行;换成自定义域名仍需显式加白名单, 否则 Vite 会返回 403 Blocked request. This host (...) is not allowed.。
  • 🔒 鉴权默认开启(AUTH_ENABLED=true):首次启动自动播种管理员 admin / 初始口令 admin@123 (app/services/auth.py:bootstrap,登录后应立即改密),会话走 nex_session Cookie, 脚本也可以用 Authorization: Bearer <token>。模型配置与账号管理(/api/providers、/api/users) 只有管理员能写,观摩/制作角色可看可拍但不能改全平台配置。 本地调试嫌麻烦可在 .env 设 AUTH_ENABLED=false 关掉,但别把关掉鉴权的实例裸露在公网上。
  • 登录页(/login,chromeless)是左右分栏:左栏写「这个系统做什么、账号角色分别能做什么」, 右栏才是表单(窄于 lg 左栏整列收起,品牌行回到卡片顶部)。用户名/密码不预填后端下发的 种子账号;勾了「记住我」才把账号与口令写进本机 localStorage(键 nex-login, 口令是明文,共用电脑别勾)。会话本身仍然只走 HttpOnly Cookie, 刷新页面靠 /api/auth/state 复原,前端不存 token。版式与取舍见 docs/UI规范.md §13.4。

脚本干了四件手工启动容易漏掉的事(都是踩过的坑): ① 统一从仓库根 --app-dir backend 启动,保证根目录 .env 一定被读到 (.env 被静默忽略时平台照旧跑 mock 且不报错); ② 用独立会话拉起进程,脚本/终端退出不会把服务一起带走; ③ Vite 加 --strictPort,端口冲突直接报错而不是悄悄换端口把前端代理和 e2e 自检打空; ④ 端口被外部进程占用时报出具体 pid,而不是卡在健康检查超时。

手工启动(想单独控制某个进程时):

cp .env.example .env
# 后端(SQLite + 进程内线程池 + 内置守护调度器);.env 已配好 SQLite/inline,可零环境变量启动
../.venv/bin/pip install -r backend/requirements.txt
../.venv/bin/uvicorn app.main:app --app-dir backend --reload --port 8000
# 前端(另一个终端)
cd frontend && npm install && npm run dev      # http://localhost:5173

TASK_EXECUTOR=inline 时 POST /dispatch、/compose 会同步排空队列并直接返回结果,页面无需等待 worker; /health 的 executor、daemon.running 可确认当前后端。

前端开发态代理:frontend/vite.config.ts 必须把 /api、/health、/media、/docs、 /openapi.json 五条路径一起代理到后端。少代理任意一条,Vite 的 SPA 回退会用 index.html 应答,前端拿到 200 却没有字段,对应面板就静默失效(侧边栏曾因此整块显示 「任务执行 —/ffmpeg 缺失/字幕烧录 滤镜缺失/调度守护 未运行」)。src/stores/system.ts 现在会 校验 typeof health.status === 'string',一旦代理缺失直接抛出可读错误而不是假装健康。

后端换地址/换端口:手工起前端用 NEX_BACKEND=http://127.0.0.1:8010 npm run dev,无需改代码; 用 ./scripts/dev.sh 的话改 .env 里 BACKEND_PORT 就行,脚本会把代理目标一起带着走。 SQLite 路径的父目录由 app/db.py 自动创建,DATABASE_URL='sqlite://////tmp/nex_ui/ui.db' 可直接使用(注意 SQLite URL 是 6 个斜杠:3 个协议分隔 + 绝对路径根)。

3.2 打成 Docker(默认一个容器:前端和后端同一个端口)

cp .env.example .env          # 或直接复用开发机那份:compose 会把 .env 整份注入容器
docker compose up -d --build  # 只起一个容器 nex-animation,对外端口 = .env 的 HOST_PORT(默认 8000)
docker compose logs -f app    # 首启会打印「导入部署数据包:seed.py install --only-missing」
docker compose ps             # STATUS 到 healthy 才算起来(探的是 /health)

.env 是「每台机器一份」的文件:仓库根那份是你开发机的配置(SQLite、开发端口、本机口令), 它 gitignored、不在部署包里;服务器上是 cp .env.example .env 生成的另一份。对外暴露的端口就配在 服务器那份 .env 的 HOST_PORT= 一行,不在 compose 文件里(compose 只引用它:先替 ${HOST_PORT} 插值得到 ports 映射,再把整份 .env 注入容器当环境变量)。容器内永远监听 8000,改 HOST_PORT 改的只是对外的映射,而且必须重跑 docker compose up -d——restart 沿用旧容器配置,不换端口。 .env 里还有四行在 Docker 形态下改了没反应:DATABASE_URL、MEDIA_ROOT、SERVE_FRONTEND、 TASK_EXECUTOR 被 compose 的 environment 覆盖(所以模板里干脆不写后两条,要挪容器内的落点改 APP_DATABASE_URL / APP_MEDIA_ROOT)。

端口一共三个键,按形态分,别混用:

键 管谁 谁读它
HOST_PORT 部署形态对外的端口:Docker 的端口映射、裸机 server.sh 的监听 compose 插值 / server.sh 回读
BACKEND_PORT 开发形态的后端 uvicorn dev.sh 回读(并同步 Vite 代理目标)
FRONTEND_PORT 开发形态的前端 Vite(独立进程,必须与后端错开) dev.sh 回读

取值优先级统一是 命令行参数 > 同名环境变量 > .env > 默认值(server.sh 是 --port, dev.sh 是 --backend-port / --frontend-port)。开发机与容器同机时记得错开 HOST_PORT, 本仓开发机用的是 HOST_PORT=8010,因为 8000 坐着开发后端。

compose 里的 comfyui 服务默认不参与:它带 profiles: ["comfy"], docker compose up -d 只起 app 一个容器(docker compose config --services 可验证)。 你的 ComfyUI 在算力机上,靠「模型管理中心」里的 base_url 连过去,跟这个 profile 无关; 它只是「算力恰好装在同一台机器、想用容器跑一份 ComfyUI」时的备选开关。

镜像里是后端代码 + 前端构建产物 + ffmpeg(两段式:node 阶段 npm ci && npm run build, 运行阶段 python:3.12-slim 装 ffmpeg 与 pip 依赖)。库用 SQLite、任务用 TASK_EXECUTOR=inline, 也就是 §3.1 那套单机形态——没有 nginx 容器、没有 Redis、没有独立 worker/beat: 后端自己托管 frontend/dist(SERVE_FRONTEND=on + SPA history 回落),周期派发由进程内的 app/services/daemon.py 守护线程做。换句话说,docker 形态和 §3.4 的裸机部署只差一层镜像, 跑的是同一份配置,一个容器就是一个项目。

数据全在四处 bind mount 里,换镜像不动数据:

挂载 内容 为什么这么放
./data SQLite 库(容器内 DATABASE_URL,产物不再落在这里) 唯一会被写坏的目录:小、每次备份都划算
./media 出片产物与上传素材(容器内 MEDIA_ROOT=/app/media,页面经 /media/* 直出) 只涨不跌,迟早要单独挪大盘、单独做增量备份、被 rsync 或剪辑软件直接读——和库分开,做这些才不用停服拷整目录
./scripts/seed 模型配置 + 加密主密钥 + 管理员(只读) .dockerignore 刻意排除它:进镜像 = 把机密烘进层里,谁拉镜像谁拿到主密钥
./models whisper 听写权重(可选) 465 MB 不该进镜像层

分家的代价是备份清单变成两条:./data 一天一备(几 MB~几百 MB), ./media 走增量(rsync -a ./media/ backup:nex_animation/media/)。 少备 ./media 不丢配置,但成片要重跑——按 H3 单卡 18 分钟/镜头算,那比配置贵得多。

从上一版镜像升级要搬一次产物:MEDIA_ROOT 早先是 /app/data/media,服务器上已经跑过 的产物就在 ./data/media/。换镜像后新产物落 ./media/,旧目录原地不动的话会看到 「历史镜头全部 404、新镜头另存一处」——文件都在,只是没人指过去。先停再搬,别边写边搬:

docker compose down
mkdir -p media && mv data/media/* media/ && rmdir data/media   # 只搬产物,库文件留在 data/ 里
docker compose up -d

裸机部署(scripts/server.sh)不受影响:它一直用的就是仓库根的 ./media。

首启由 scripts/docker-entrypoint.sh 拿 seed 目录把库灌好,之后交给 AUTO_SEED 三种取值: only-missing(默认,只补库里没有的模型,不动服务器上人工调过的默认位)、 force(包里说的算)、off(跳过)。灌失败只告警不拦启动——页面和 API 本身是好的。

常用改动都不用在 Dockerfile 里写死:

想改什么 改哪里
对外端口 .env 里的 HOST_PORT(部署形态:Docker 的映射、裸机 server.sh 的监听都读它)。容器内固定 8000,改 HOST_PORT 改的只是对外映射,且要重跑 up -d;开发形态另用 BACKEND_PORT / FRONTEND_PORT,详见 §3.2 的端口表
装包慢 / 源不通 见下面「依赖下载点与国内源」:PIP_INDEX_URL、NPM_REGISTRY、APT_MIRROR 默认已是国内源,只有拉不到 docker.io 时才需要动 BASE_IMAGE、NODE_IMAGE
换 ComfyUI / 换 GPU 机 不在 .env 里改:登录后进左侧栏「模型管理中心」,改那几条模型的 base_url 并点 🔌 探测,改完即生效、不用重启。指宿主机写 http://host.docker.internal:9200(extra_hosts 已备 host-gateway),写 127.0.0.1 指向的是容器自己
顺带起一个自建 ComfyUI docker compose --profile comfy up -d(默认不起,算力在远端时不用管),再把 base_url 指 http://comfyui:8188

依赖下载点与国内源(默认即国内,零配置)

构建 + 安装全链路一共只有五个下载点。镜像构建里没有 huggingface:465M 的听写权重不进镜像层 (.dockerignore 排掉了 models/,requirements.txt 里也没有任何 whisper/hub 包)。

下载点 什么时候发生 键(环境变量 / .env / --build-arg) 默认值
基础镜像 python:3.12-slim、node:22-alpine docker build BASE_IMAGE / NODE_IMAGE docker.io 官方 tag。服务器上已有就不管:compose 不加 --pull 就用本地 tag,不联网
npm 依赖 docker build 第 1 阶段;server.sh install、dev.sh NPM_REGISTRY https://registry.npmmirror.com(package-lock.json 的 211 条 resolved 本身就锁在 npmmirror,npm ci 天然走国内)
apt:ffmpeg fontconfig fonts-noto-cjk docker build 第 2 阶段 APT_MIRROR mirrors.tuna.tsinghua.edu.cn(直连 deb.debian.org 实测这一层 200+ 秒)
pip 依赖(8 个包) docker build;server.sh install、dev.sh PIP_INDEX_URL https://pypi.tuna.tsinghua.edu.cn/simple
whisper 听写权重 ggml-small.bin(465M,可选) 只有裸机 server.sh install(--no-asr 跳过,且没装 whisper-cli 时自动跳过) ASR_DOWNLOAD_URL https://hf-mirror.com/ggerganov/whisper.cpp/resolve/main/ggml-small.bin(huggingface.co 国内实测连接直接被重置)

境外机器把上面四个源显式传回官方值即可,Dockerfile 不用改。 最后一处外部依赖在浏览器侧:frontend/index.html 引 fonts.googleapis.com 的 DM Sans + Noto Sans SC, 只影响访问者的网络,与服务器/构建无关(本机实测 0.3s 可达);要彻底离线得自托管字体,目前没做。

拉不到 docker.io 时不用改 Dockerfile,把两个基础镜像指到能通的 registry 就行(本机实测可用, 构建一次约 5 分钟,之后改代码只重跑 COPY 层):

BASE_IMAGE=swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/python:3.12-slim \
NODE_IMAGE=swr.cn-north-4.myhuaweicloud.com/ddn-k8s/docker.io/library/node:22-alpine \
docker compose up -d --build

镜像里没有 whisper-cli:成片台词听写这项质检在容器里会自动跳过(services/asr.py 探测不到就 报告原因,不影响出片),所以 Docker 形态下没有任何理由去下载那 465M 权重。要它在容器里可用, 得自己加一个构建阶段编译 whisper.cpp(并把 ./models 挂进来,compose 已备 :ro 挂载), 或者走 §3.4 裸机形态。

镜像里有中文字体(fonts-noto-cjk):这是烧字幕的硬依赖。libass 找不到中文字形不报错, 直接把字幕画成一片豆腐块,且质检也会跟着误判。镜像里 fc-list :charset=4e2d 查不到字体就是这个问题。

要扩容再叠一层(多 GPU、多人同时出片、worker 放别的机器):

docker compose -f docker-compose.yml -f docker-compose.scale.yml up -d --build
# app + db(postgres) + redis + worker + beat —— 页面仍由 app 一个容器提供

compose 的 environment 是按键合并、后面的文件赢,所以叠加只是把 DATABASE_URL 换成 Postgres、 TASK_EXECUTOR 换成 celery,周期派发从 app 内的守护线程交回 beat。本机进程版同命令: celery -A app.worker.celery_app worker -Q generate,audio,qc,compose,io,default -c 2 与 celery -A app.worker.celery_app beat。frontend/Dockerfile + nginx.conf 留给「前端单独发到 nginx/CDN」的部署形态,单容器用不到它。

3.3 冒烟自检

/health 与 /api/auth/state 免登录(监控探针和登录页要用),其余 /api/* 在默认鉴权下需要先拿会话:

curl -s localhost:8000/health | jq '.executor,.ffmpeg_capabilities,.auth_enabled,.frontend'
curl -s localhost:8000/api/auth/state | jq '.auth_enabled,.login_hint'   # 未登录也返回 200
# 读业务接口前先登录拿 Cookie(账号口令就是首启播种的那一对):
curl -s -c /tmp/nex.jar -H 'content-type: application/json' \
  -d '{"username":"admin","password":"admin@123"}' localhost:8000/api/auth/login > /dev/null
curl -s -b /tmp/nex.jar localhost:8000/api/meta | jq '.presets,.options.transition'

AUTH_ENABLED=false 时可以省掉登录那两步直接 curl。 端到端业务自检(不只是接口活着)见 §6.2。

3.4 服务器部署(一台机器一个端口)

开发态是「Vite 5173 + 后端 8000」两个进程;服务器上不需要 Vite—— SERVE_FRONTEND=on 让同一个进程既出 API 又发 frontend/dist, React Router 的 history 回退已经处理好(地址栏直接刷 /projects/3 不会 404), 反向代理只需转发一处,/api、/media、/docs 与页面同源。 SERVE_FRONTEND 默认 off,所以开发与测试行为完全不变。

# ---- 开发机:数据集 → 打包(内容白名单 + 体检,体检不过直接报错不产出包)----
.venv/bin/python scripts/seed.py doctor           # 量一遍「开发库数据集 vs 当前代码」,只读
.venv/bin/python scripts/seed.py export --fix     # 补齐能力位/工作流键 → 体检 → 导出 scripts/seed/
./scripts/deploy.sh --check                       # 只看会带上什么、排掉什么、数据能不能装
./scripts/deploy.sh                               # → .local/deploy/nex_animation-<时间戳>.tar.gz
./scripts/deploy.sh --host deploy@10.0.0.8 \
    --path /opt/nex_animation                     # 上传 + 远端 install + restart + status

# ---- 服务器:落地 ----
tar -xzf nex_animation-*.tar.gz && cd nex_animation
./scripts/server.sh install      # venv + 依赖 + npm build + 听写模型 + 体检 + 建表灌种子数据
./scripts/server.sh start        # 单进程 uvicorn;端口取 .env 的 HOST_PORT(默认 :8000,--port 覆盖)
./scripts/server.sh verify       # 图2 全 12 节点真实 HTTP + ffprobe 自检
./scripts/server.sh status       # 端口 / 健康 / 默认模型 / ComfyUI 连通性 / 数据边界
sudo ./scripts/server.sh systemd > /etc/systemd/system/nex-animation.service \
  && sudo systemctl daemon-reload && sudo systemctl enable --now nex-animation

install 首次生成的 .env 是单机版(SQLite + TASK_EXECUTOR=inline + SERVE_FRONTEND=on), 只写跑起来必需的那几行;.env.example 现在也是同一套默认值,所以 cp 一份裸跑同样起得来, 两种写法等价,差的是注释多寡和键的多少(旧版模板默认 Postgres + Celery,cp 过去会因为 连不上 DB/Redis 而起不来,那个坑已经填了)。inline 的调度守护线程跑在进程内,所以服务形态固定单进程, 加 --workers 等于 N 份守护线程抢同一批任务重复派发;要横向扩展就切 celery 另起 worker。

部署包里只有代码,没有你跑出来的内容(deploy.sh 逐条体检,缺的多的直接 die):

随包走 不随包走
表结构:应用首启 app/db.py:init_db() 自己 create_all + 补列 media/ 产物库——换环境是「迁移」不是「部署」,单独 rsync
模型配置 model_specs + 加密主密钥 model_secret_keys(scripts/seed/) 项目 / 分镜 / 任务等业务数据(开发库全是过程产物)
管理员账号 users(仅 admin,沿用导出的口令哈希) .env——数据库串、媒体目录、鉴权开关是机器相关的(模型配置不在 .env 里,见 §4.0)
启动脚本与 DEPLOY-INFO.txt(包里有什么、服务器三步、默认位是哪几个) backend/tests、reports/、.git/、models/(听写权重远端下载)、frontend/dist(远端 build;--with-dist 可带上)

主密钥跟包走是有意的:model_specs.api_key 是密文,换机器解不开就等于每台服务器都要重录一遍 各家 Key。代价是 scripts/seed/ 属于机密——已 gitignore、随包走、包内是密文但主密钥也在里面, 按密钥对待。装完 seed.py install 会自检解密并打印当前默认模型;install --only-missing (seed.py 与 server.sh 都收这个开关)只补缺、不覆盖同名配置,--dry-run 先看将要发生什么, 主密钥冲突时区分「没有解密依赖 → 换」与「有依赖 → 中止等你决策」。

管理员口令走同一套保守口径:install 默认不改已存在账号的口令(这台机器可能早改过, 覆盖成开发机的口令是反直觉的倒退)。所以在开发机改了 admin 口令、重新 export 之后, 服务器上要多跑一次才会对齐:

docker compose exec app python scripts/seed.py install --only-missing --reset-password

新库(./data 是空的)不需要这条:数据包里没有的账号会按包里的哈希直接建出来。

数据集与代码必须对得上:deploy.sh --check、deploy.sh 打包、seed.py install 装库之前, 跑的都是同一个 doctor(列对得上表结构 / 适配器在代码里注册过 / modes 不比适配器声明的能力少 / 每类能力有且仅有一个默认 / 包里的密文能被包里的主密钥解开)。任何一条 error 就停住, 因为数据集旧的后果不是报错而是功能在页面上凭空消失——比如 modes 少一个 voice_instruct,「音色描述直出」整块就不渲染,而 ComfyUI 侧看起来一切正常。 修复动作永远在开发机:seed.py doctor --fix(只补缺,不动人工调过的值)→ 重新 export --fix → 重新打包。

服务器上没有 whisper-cli / 听写模型时,只有「台词听写质检」这一项不生效,其余流程照常; server.sh status 会把它标成黄色告警而不是静默降级。--no-asr 可以跳过下载(465M 权重)。

同一份部署包也能直接跑 Docker:deploy.sh 的必带清单里已经包含 Dockerfile、.dockerignore、 docker-compose.yml、docker-compose.scale.yml、scripts/docker-entrypoint.sh,解包后 docker compose up -d --build 就是 §3.2 那个单容器形态。两条路的区别只剩「依赖装在哪」—— server.sh install 装在宿主机上,docker build 装在镜像层里;.env、scripts/seed/、 数据目录四处的相对位置完全一样,所以先用裸机跑起来、之后想切容器不用搬任何东西 (反过来也一样:容器用久了想落回裸机,./data 里的 SQLite 与 ./media 里的产物 直接就能被 server.sh 读——它俩本来就和裸机部署用的是同两个目录名)。

4. 模型与供应商

4.0 真实模型:ComfyUI · MiniMax H3(已实跑通过)

模型接入地址 http://10.100.53.199:9200(ComfyUI 0.42 / GB10 单卡)。

配置的唯一事实源是数据库 model_specs 表:地址、模型名、步数、超时、并发与 RPM、 画布像素、LoRA、单价、默认位,全在那条模型行的列与 config_json 里, 页面入口:左侧栏「模型管理中心」(顶级项,不在项目菜单里)。.env 里不放模型配置(v0.1.1 起取消),三条理由: 改模型不该要求重启进程;API / worker / beat 必须读同一份事实;地址与 Key 进库才有审计与探测记录。

# 首次接入新机器:页面「+ 登记模型」→ 选 comfyui 适配器 → 填 base_url → 点 🔌 探测
# 换服务器:开发机 .venv/bin/python scripts/seed.py export --fix → 随部署包带过去
#           (容器首启 AUTO_SEED=only-missing 自动灌库;裸机 server.sh install 同义)
# 开发机临时试另一台 ComfyUI:用逃生门,只在这条模型还没登记过时才生效
COMFYUI_BASE_URL=http://10.100.53.199:9200 ./scripts/dev.sh

app/config.py 里仍留有 comfyui_* / video_* / tts_* 字段,但它们是代码级兜底, 不是配置入口:只在「空库自检」和「首次登记某条模型」时被读到, 已存在的行永远以库为准(app/providers/registry.py:seed_specs 的 ensure 见 key 就返回)。 所以「模型连不上」的正确排查顺序是:页面点 🔌 探测 → 看那条模型的 base_url 与 config, 而不是回去翻 .env。

cd backend && ../.venv/bin/uvicorn app.main:app --port 8000 之后, 调度中心 → 模型注册表里 comfyui/minimax-h3 的 🔌 探测会列出机器上真实存在的 UNET / CLIP / VAE 文件名,可直接照着改 config,不必猜 unet_name。

项 实机口径
节点 MiniMaxH3ImageToVideo(首帧/首尾帧/t2v)· MiniMaxH3ReferenceToVideo(参考图 r2v)
画布 模型原生 16:9 → 1312×736(短边 768 档,最长边 ≤1344,边长必须是 32 的倍数);1080p 是交付档:出片仍按原生像素,合成端 lanczos 放大(capabilities.upscale_to),不额外花卡时
时长 帧数必须落在 17k+5 网格:5s→124 帧(5.17s)… 15s→362 帧;模型只在 124–362 帧上训练过
音轨 原生音画同步:VAEDecode + VAEDecodeAudio → CreateVideo(fps=24) → 一次成片自带 AAC
耗时 5s / 20 步 ≈ 18 分钟/镜头(步数在该模型行 config.steps 里;单卡串行:并发上限与 RPM 是这条模型行的列,在模型管理中心改;心跳每 STALE_RUNNING_SECONDS/3 续租,不会误判重跑)
反向提示词 H3 无独立入口,适配器把 negative_prompt 折进提示词末尾的自然语言子句

踩过的两个坑(已修 + 已锁测试,改适配器前请先读):

  1. 参考图是 ComfyUI 的 autogrow 槽位(COMFY_AUTOGROW_V3)。ComfyUI 3.x 的 API prompt 必须使用 “父输入.槽位”扁平键:H3 为 ref_images.ref_image_0,Qwen-Image 为 images.image_1。传嵌套字典不会报错,但会被静默解析成空参考集,最终成图/成片与参考图无关。
  2. 时长窗口不能只看节点参数下限(节点 min=5 帧)。低于 124 帧的时长虽然能对齐到 17k+5 网格(4s→107 帧、3s→73 帧),却落在模型训练区间之外,属于「语法合法但模型没见过」 的静默劣化,而且已经花掉一次真实渲染。因此 capabilities 的上下限必须满足: 两端对齐到帧网格后仍落在 124–362 帧内(tests/test_comfyui_adapter.py)。

真实模型端到端验证走平台内链路:模型管理中心对 comfyui/minimax-h3 点 🔌 探测确认权重到位, 然后新建项目 → 分镜 → 派发,产物用 ffprobe 复核时长与音轨;单个镜头失败就在镜头详情里 「重新生成」,不必整项目重跑。整套 12 节点的自动化版本是 §6.2 的 scripts/e2e_selfcheck.py (mock 适配器,不烧卡时)。早期那些直连 ComfyUI 的一次性探针 (comfyui_e2e.py / predator_meal_e2e.py / platform_full_e2e.py)已完成使命, 归档在 .trash/2026-11-01/scripts/,不再进 scripts/。

4.0.1 台词的语音来源:默认由 H3 直出原声(音画同步)

H3 是原生音画同步模型,人声是对着口型生成在产物音轨里的。所以时间线出厂默认 voice_source="native":镜头产物自带音轨时,台词直接用原声,片段时长 = 产物时长, 不再生成 TTS 覆盖(dispatch 把这类镜头的配音计划标成 skip 并给出理由)。 以前的「单独 TTS + ffmpeg 合成」链路保留为 dub,随时可在 时间线 → 台词语音来源 切回。

错位的根因是口径不一致,不是 ffmpeg 混音不准:TTS 长度与停顿与画面无关,旧逻辑却把 片段拉到 max(画面, 配音+留白) 并定格补帧,于是出现「画面里人物闭着嘴、声音还在说」 (实测旧链路一条 5s 片段里 57% 是静音);改走原声后同一段产物 silencedetect -35dB/0.35s 测不出静音段,音画长度天然相等。

音色不是模型随机挑的嗓子:生成时平台把本镜每个说话人声线的克隆样本按台词顺序喂进 MiniMaxH3ReferenceToVideo.ref_audios.ref_audio_{0,1,2}(prompt.reference_voice_audios, 上限 Capabilities.max_reference_audios=3)。用基频中位数 f0 做 A/B(shot26「俊杰」, 音色样本 120.3 Hz,同 seed 配对):

喂进 ref_audios 的内容 产物 f0_med 相对本人音色样本
不喂任何参考音频 216.2 Hz +11.2 半音(模型自己挑了把嗓子)
俊杰本人的音色样本 131.1 Hz +1.5 半音 ✅
俊杰本人的音色样本 + <Audio 1> 标签 135.6 Hz +2.1 半音(标签无增益)
紫小慧的音色样本(女声喂男画面) 177.8 Hz 画面优先,性别冲突时以人物为准

要点:参考音频真的能锁音色(同性别误差 2 半音内);不给参考就会跑调; 性别冲突时模型以画面人物为准,所以 speaker→声线 的绑定必须准确(预检里 voice_identity_risk 就是盯这个)。产物确实没有音轨时自动回退配音,不会把台词变成哑巴。

一镜多人说话(shot.lines 里有多个 character_id)时,上面的表不够用了: MiniMaxH3ReferenceToVideo 只有一个 prompt 文本入口,「这一句是谁说的」只能靠官方 语音标记表达——<Audio j><d>台词</d> 表示这段用 ref_audio_j 的嗓子(文本编码器 把标签与 prompt 裸拼,见 comfy_text_encoders_minimax.py)。因此 caption 里的说话人 只走标签,绝不写角色名(「俊杰台词:」会被原样念出来,见 4.0.2)。三处必须同时成立:

环节 位置 断掉的后果
按逐句说话人收集音色,顺序=开口顺序 prompt.dialogue_voices 第二个人没有参考音频,全片一个人说话
序号来自同一份列表 prompt.joint_voice_names → compose_joint_caption 标签把台词安到别人的嗓子上
只在「本镜不同说话人 ≤ 1」时才兜底标 <Audio 1> compose_joint_caption.audio_label 单人音色被套给整段对白

漏绑不报错,只会静默换声,所以预检加了 joint_speaker_unbound:某句台词的说话人拿不到 自己的参考音频(角色没设默认声线 / 声线缺克隆样本 / 超出 3 条上限)时点名告警。

4.0.2 联合音视频模型的提示词契约:整段 caption 既被「看」也被「听」

H3 的文字入口只有一个 prompt 字段,没有 chat 模板、没有 system/user 之分, 文本编码器把整段文字同时当画面脚本和声音脚本。凡句子里出现「说/台词/配音/口型/ 音画不同步/必须/严禁/为准」这类关于声音或下指令的说法,它就去念给你听—— 项目 11《告诉你个小秘密第1期》v2 成片逐镜 ASR 实测:开头那两句莫名其妙的 「是这一镜的画面和石腰准和碍」,正是 <Picture 1>是这一镜的画面。<Picture 2>是俊杰, 高大,和蔼 被原样朗读(drop_topic/sanitize_visual 负责剔除)。

因此 prompt.compose_joint_caption 与通用提示词分道,规则是「只写看得见的东西」:

规则 做法
身份锚定不能写成句子 定语 <Picture 3>中的紫小慧,… 而非 <Picture 3>是紫小慧(JOINT_REF_STYLE="prefix" 可回退旧写法做 A/B)
时长/画幅不进文字 它们是 length/width/height 结构化入参,写成「时长约 9 秒」就会被念出来
「谁在说话」不进文字 由首帧构图决定(keyframe_speech_note 只给图像模型)+ <Audio n> 标签;speaking_subject_note 那句构图描述写进 H3 文字就会被朗读
台词是最后一段 官方 <d>…</d> 段落,段间不补句号(会被当成句子结束、各配一段气口)
表情里的「嘴」要改写 「嘴角上扬」→「面带笑意」:发声器官词会诱发即兴人声
台词时长按实测语速 JOINT_CPS_CJK=5.0 字/秒(TTS 口径 4.3 + 标点停顿会多留 2s 空档,模型拿来念提示词),并允许短于分镜时长;帧数还要落在 n % 17 == 5@24fps 格点

回归用例:tests/test_joint_caption.py、tests/test_speaking_subject.py、 tests/test_comfyui_adapter.py::test_joint_av_model_never_gets_a_spoken_negative。

4.1 真实配音:IndexTTS2(克隆 + 音色描述直出)

音频模型只有 comfyui_tts(IndexTTS2)这一条真实链路,跑在部署机的 ComfyUI 上。 以前还有一个 macos_say(macOS 系统 say):部署服务器是 Linux,那台机器上根本没有 say 命令,登记在库里等于永远挂着一个选了就报错的「mac 本地」模型,因此整体下线; registry.seed_specs() 顺带删除历史遗留的 macos-say 行,若被删的正是默认模型, 默认位顺延给同能力里最早登记的模型。声线的 tuning.params.effect(外星低吼) 是那个适配器独有的滤镜,一并退役。

IndexTTS2 有两种定音色的方式,两种都会落进统一 TTS 任务、字幕对齐与混音链路:

方式 什么时候走 节点图
参考音频克隆(zero-shot) 声线绑了真人参考音频,或表单里手动指定了一段 easy indexTTSGenerateSimple
音色描述直出 没有参考音频,但声线填了「音色描述」 easy indexTTSGenerate(全参)+ easy indexTTSEmotionText
// 克隆:provider_voice_id 存参考音频(平台会自动上传到 ComfyUI input 目录)
{ "name": "女主角 · 真人录音", "provider": "comfyui_tts",
  "provider_voice_id": "/abs/path/reference.wav", "language": "zh-CN",
  "description": "二十多岁,明亮偏软,语速中等" }

// 描述词直出:没有录过音也能出试听,音色由 description 决定
{ "name": "旁白 · 描述词", "provider": "comfyui_tts",
  "provider_voice_id": "", "language": "zh-CN",
  "description": "低沉老年男性,气声重,语速偏慢" }

描述词必须走全参节点:easy indexTTSGenerateSimple 不接 emotions 输入, 把描述词写进去等于没写。easy indexTTSEmotionText 的 reference_audio 是必填项, 所以描述词模式仍以模型配置的默认参考音频作底声锚点,音色由描述词决定—— 9200 实机同一句台词两组描述词的中位基频 241.4 Hz ↔ 189.2 Hz,锚点相同而嗓子不同。 全参节点的十个必填项取节点自身默认值,模型配置 generate_full_inputs 可逐项覆盖。

「资产库 → 声线」创建时只填写名称、语言、语速与音色描述,模型选择 移到「生成试听」步骤,并只列出真实 TTS 模型(Mock 不作为资产生成选项)。未就绪的模型仍可 选择并查看状态,生成时会返回具体缺失节点或服务错误,避免“探测失败就直接禁用”导致 IndexTTS2 无法选。参考音频可上传一段音频,也可选择资产已有的音频;项目资产库同样 支持从当前声线的音频素材中选择参考音色。单独删除参考音频时会同步清理声线里失效的路径绑定; 若历史数据仍指向已删除文件,适配器会自动回退到模型配置的默认参考音频。既没有参考音频 也没有音色描述时明确报错,不再悄悄用模型默认参考出一个和角色无关的嗓子。适配器会用 ffmpeg 统一转为 24kHz 单声道 PCM WAV 并校验时长;ComfyUI 缺少 IndexTTS2 节点时会明确报错, 不会再生成只有 0.01 秒的静默文件。

IndexTTS2 是 ComfyUI 自定义节点,不是 Nex 内置推理器。目标 ComfyUI 需安装 ComfyUI-Easy-IndexTTS2,安装模型与 Python 依赖后重启 ComfyUI;/object_info 必须出现 easy downloadIndexTTSAndLoadModel 与 easy indexTTSGenerateSimple,要用音色描述直出还得多两个 easy indexTTSGenerate、easy indexTTSEmotionText(诊断接口会把缺的节点逐个列出来)。 Nex 不会在未经授权时远程安装节点或下载大模型。

在 9200 的 ComfyUI 主机上安装节点:

cd /dep/Bfmodeltest/ComfyUI-H3/custom_nodes
git clone https://github.com/yolain/ComfyUI-Easy-IndexTTS2
cd ComfyUI-Easy-IndexTTS2
/dep/Bfmodeltest/ComfyUI-H3/.conda-env/bin/pip install -r requirements.txt
# 重启启动 /dep/Bfmodeltest/ComfyUI-H3/main.py 的 ComfyUI 进程

注意:9200 当前运行 Python 3.13。pynini==2.1.6 没有 cp313 wheel,应先在同一 conda 环境执行 conda install -c conda-forge "pynini=2.1.7";transformers 需限制在 >=4.50,<5,否则 IndexTTS2 vendored 的 4.x generation 实现无法导入;同时需要 WeTextProcessing 与 accelerate。9200 上已按此组合安装并完成真实参考音色生成验收。

节点首次生成时可按 modelscope 下载 IndexTTS-2 模型;也可按项目 README 将模型预置到 ComfyUI/models/IndexTTS-2/。重启后可检查:

curl -fsS 'http://10.100.53.199:9200/object_info/easy%20downloadIndexTTSAndLoadModel'
curl -fsS 'http://10.100.53.199:9200/object_info/easy%20indexTTSGenerateSimple'

Qwen-Image 生成同样支持参考图:平台和项目资产卡片都可选择当前人物/场景已有图片,或临时上传 一张图。适配器通过 LoadImage 和 TextEncodeQwenImage21 的 images.image_N autogrow 扁平槽位提交,并使用编码器输出的参考 latent;不选参考图时仍走 原有纯文生图流程。参考图存在时,输出画布会跟随第一张参考图的宽高比,这是该节点的原生行为。 Qwen Image 2.1 还要求提示词显式引用图片槽位;用户只写“参考图”时,适配器会自动在指令前 补充 以<image1>为参考,按以下要求生成或编辑:。室内/内景类短提示还会自动补充“镜头移到 建筑内部、不要展示外立面或室外庭院”的机位约束,否则模型常沿用参考图的外景构图。生成种子 同时由提示词、参考图和画布尺寸共同派生;用户未固定 seed 时,再次生成会得到新的随机结果, 不会因为平台资产 ID 相同而永久复用同一张图。 分镜关键帧从「分镜 → 资产 → AI 生成关键帧」发起,走同一个真实图像模型与 AssetGenRequest 链路;生成前会同步当前镜头的版本化提示词,结果写入镜头的 keyframe 资产槽位并递增版本, 因此后续 H3 i2v 会立即使用新首帧,无需手工再上传一次。

4.2 三关键帧真实成片示例(平台内跑法)

这条链路已经在真实 H3 上跑通过:三张关键帧 → 角色/场景/声线 → 真人报菜名 → 外星语回应 → H3 三段出片 → 审核 → 时间线混音 → 1080p 导出。现在直接在界面上走:

  1. 资产库录角色定妆图 / 场景图 / 声线;新建项目时可勾选要引入的资源库,避免每次重录;
  2. 分镜写三段镜头:有台词(真人)、有台词(外星语 + 变声)、无台词空镜各一段—— 无台词是正常形态,平台不会为它编一句旁白;
  3. 每段先出关键帧,再用 H3 i2v 出片;voice_source=native 时带原生音轨的镜头不再叠加 TTS(§4.0.1);
  4. 质检 + 人工审核通过后,时间线混音、挂字幕,导出 1080p。

固化的 predator_meal_e2e.py 探针已归档到 .trash/2026-11-01/scripts/;它当年靠 「跳过已成功镜头」省卡时,今天这件事由平台的断点续跑与单镜头重新生成承担。

  • 默认 mock 适配器:不依赖任何供应商即可跑通全流程。视频以关键帧/定妆图为底图按运镜参数生成真实可播放的测试片段,配音按文本长度生成占位人声 WAV,因此质检、时长对账、转场、混音都能被完整验证。它是流水线验证工具,不是 AI 视频模型。
  • http_generic 适配器:供应商协议骨架(提交任务 → 轮询 → 下载),各家(Veo/Kling/可灵/即梦等)请求体差异需实现各自的 adapter,不要假定开箱兼容。
  • 模型注册表 provider_models:GET/POST/PATCH/DELETE /api/providers,可设默认模型、每模型并发上限与 RPM、时长/分辨率能力、每秒单价;调度中心页面支持💥注入 failure_rate=1.0 做故障演练。
  • 真实大模型:在「模型控制台 → 大模型」登记 OpenAI 兼容端点(如 https://api.deepseek.com/v1 / deepseek-v4-pro),填写密钥并设为默认;密钥只以密文落库, 页面回显掩码。大模型只承担 chat / prompt 文本能力,不再提供文生图端点、图像模型或尺寸配置; 旧数据中的 t2i 模式、参考图/画幅字段和 config.image 会在保存或启动迁移时自动清理。 图像生成统一使用独立图像模型。Mock LLM 应在登记真实模型后停用,避免文本补全误走占位结果。
  • 真实供应商通常要求参考图公网可读,请自行接入对象存储并注入签名 URL。

5. 质检与合成参数

项 默认 配置
质检打分 解码完整性 30 / 时长偏差 20 / 分辨率 15 / 码率 10 / 黑屏 8 / 冻结 9 / 帧率 8,硬失败项(severity=error)直接判不合格 QC_DURATION_TOLERANCE、QC_MIN_BITRATE_KBPS、QC_BLACK_THRESHOLD
出片预设 draft_720p(1280×720) · vertical_720p(720×1280) · web_1080p(1920×1080) · vertical_1080p(1080×1920) · hq_1080p(CRF18 slow) · uhd_4k(3840×2160 CRF18 slow) services/ffmpeg.py:EXPORT_PRESETS
时间线 fps/width/height、subtitle_mode、subtitle_style、voice_source(native/auto/dub,见 §4.0.1)、keep_shot_audio、voice_gain_db、bgm_gain_db、duck_bgm、target_lufs、lead/tail_padding_ms、hold_last_frame PATCH /timeline/settings
转场 xfade(有转场滤镜时)或直切;XFADE_MAX_DURATION_MS 限制 TARGET_LUFS 控制 loudnorm 目标响度

FFmpeg 能力探测:GET /health 返回 ffmpeg_capabilities,字段为 available / drawtext / subtitle_burn / subtitle_filter / xfade / concat / loudnorm / blackdetect / freezedetect / font。当 subtitle_burn=false(本机 ffmpeg 未编译 subtitles/ass 滤镜)时:

  • 走时间线默认设置的字幕会被自动降级为「外挂字幕」,导出照常成功,并写入 compose.subtitle_skipped 警告事件(合成报告与事件流可见),不会让任务失败;
  • 只有导出时显式传 burn_subtitle=true 才会中止任务并给出可执行的修复建议—— 用户点名要烧字幕时绝不静默忽略;
  • 外挂字幕随时可取:GET /projects/{id}/timeline/subtitles?fmt=srt|ass; 要真正烧录请换用带 libass 的 ffmpeg 构建(侧边栏此时以黄色标注「降级为外挂字幕」, 而缺 ffmpeg 本体才是红色「阻断合成」)。

6. 测试与自检

改完代码的最低验收(完整约定见 docs/工程规范.md):

cd backend && ../.venv/bin/python -m pytest -q     # 全量回归,约 3 分钟,必须全绿
bash -n scripts/*.sh                               # 脚本语法(shellcheck 没装也别跳过这条)
cd frontend && npm run build                       # 类型与打包(tsc --noEmit && vite build)
node scripts/ui/classaudit.mjs                # 前端用词闸(源码,秒级)
NEX_WIDTHS=1440,992,768,430 .venv/bin/python -u scripts/ui/visualcheck.py   # UI 体检 + 截图

碰到派发 / 合成 / 部署链路的改动,再补一次 §6.2 的端到端自检——pytest 用 TestClient 在进程内测契约,测不出「这台机器上这套服务能不能交付」。

6.1 单元/接口回归(pytest + TestClient,进程内,无需起服务)

cd backend
DATABASE_URL='sqlite://////tmp/nex_tests/t.db' TASK_EXECUTOR=inline MEDIA_ROOT=/tmp/nexmeta \
  ../.venv/bin/python -m pytest -q        # 12 个测试文件 / 115 个用例,全绿

覆盖:系统/健康/枚举、资产库与素材版本、脚本导入与图片匹配、 提示词组装与版本、入队预检与幂等、失败重试与错误留痕、断点续跑、质检打分、审核回路、 时间线重算与交付预检、导出成片与成本台账,以及 tests/test_regression_fixes.py (14 个用例,专门锁定端到端验证中发现并修掉的缺陷:Markdown 文档标题误判为镜头、重复镜号触发 UNIQUE 500、上传响应回吐过期版本、黑场 转场常量拼写、流程节点按镜头计数导致 5/4 分母、 review_state 与审核记录 verdict 必须同源且无产物不得放行、局部生成失败被整体成功掩盖 (失败镜头的旧产物仍在磁盘上时,节点 8/9 也必须转红并从可用产物计数里扣除)、 限流容量行按 (provider, model) 去重且媒体类型跟随模型规格、项目队列不得混入其他项目任务、 平台人物创建时保持全局、单媒体删除及文件清理、IndexTTS2 参考音色上传与项目引入时的本地副本等)。 tests/test_comfyui_adapter.py 还会用本地假 ComfyUI 完整走一遍 IndexTTS2 节点探测、参考音频上传、 节点图提交、音频下载与产物校验,并锁定“缺少节点时不得提交任务”以及 Qwen 参考图 autogrow 连线与参考 latent 的行为。Qwen 参考图节点图已在 9200 实机生成验证。 tests/test_agent_orchestrator.py 覆盖 LLM 结构化计划、全流程白名单执行、Mock 拒绝、越权动作拒绝、 AI 审核授权门禁、空项目阻塞、已完成项目的幂等诊断,以及 kind=agent 审核审计隔离。 tests/test_index_tts_instruct.py 锁定音频模型整类的两条口径:库里不得再出现 macos-say(历史行会被清理、默认位顺延),以及音色描述直出的节点图形状 (全参节点 + emotions 连线 + 底声锚点)与参考音频优先于描述词的解析顺序。Python 需 3.11+ (系统自带 3.9 无法运行本项目)。

6.2 端到端业务自检(打真实服务 + ffprobe 实测)

# 终端 A:起后端(无需 Redis / Postgres / 供应商密钥)
cd backend && DATABASE_URL='sqlite://////tmp/nex_ui/ui.db' MEDIA_ROOT=/tmp/nex_ui/media \
  TASK_EXECUTOR=inline MAX_SHOT_RETRIES=2 RETRY_BACKOFF_BASE_SECONDS=1 \
  RETRY_BACKOFF_MAX_SECONDS=2 ../.venv/bin/uvicorn app.main:app --port 8000
  # 后三个变量只是把「失败重试」的退避从默认几十秒压到 1~2s,让第 16 步不必干等
# 终端 B:跑图2 全 12 节点
NEX_BASE=http://127.0.0.1:8000 ../.venv/bin/python scripts/e2e_selfcheck.py

scripts/e2e_selfcheck.py 会新建一个独立项目,按图2 顺序跑完 12 个节点(含「生成失败重试」 与「审核驳回 → 改提示词 → 重新生成」两条回路),并真的下载产物用 ffprobe 校验镜头与成片 (时长 / 分辨率 / 编码 / 音轨),任一环节不符合预期就打印接口原文并以退出码 1 结束。 它只依赖 HTTP 与本机 ffprobe,不需要知道后端 MEDIA_ROOT。也可 NEX_BASE=http://127.0.0.1:5173 走前端代理,顺带验证代理配置是否正确。服务端开着鉴权(默认值)时脚本会先自动登录换 Cookie (账号取 NEX_USER / NEX_PASS,缺省用 /api/auth/state 回传的初始管理员), 所以部署完在服务器上直接 ./scripts/server.sh verify 就能跑,不用手工准备会话。

第 [16] 步用 PATCH /api/providers/{id} 给 mock 视频模型注入 failure_rate=1.0,验证节点 8 判定为「否」时的完整链路:按上限重试并逐次留痕 → 镜头落 failed 且不产脏数据 → 流程节点转红 并写明原因 → 修复配置后 POST /tasks/retry-failed 一键重跑 → 节点重新全绿,跑完自动把注入复原。 开跑前的 [00] 步还会先清掉上一轮中断残留的注入,因此脚本可以反复执行。

6.3 前端构建

cd frontend && npm run build     # tsc --noEmit && vite build
# 当前 103 modules → 17 个 chunk,JS 合计 ~907 KB(gzip ~296 KB)+ CSS 98 KB(gzip 19 KB)
# 首屏只下载 index(~411 KB/131 KB gzip) + 共享原语 ui(~80 KB/26 KB gzip) + 当前页 chunk;
# 手册 /help 也是懒加载页面(Help chunk 42 KB / 12 KB gzip),不再是一份独立静态 HTML

7. 边界与说明

  • 平台保证的是工程可靠性(幂等、重试、断点续跑、限流、质检、留痕),不保证供应商永不失败,也不保证模型生成的人物绝对一致——一致性靠资产库定妆图 + 提示词约束 + 人工审核共同兜底。
  • 登录鉴权(会话 Cookie + 角色闸门)与供应商密钥加密落库已内置并默认开启,页面只回显掩码; 公网部署仍建议放在 HTTPS 反代后面,并把 MEDIA_ROOT 放在受控存储上。关掉鉴权只适合可信内网。
  • 媒体文件一律由后端 /media/* 直出,前端不拼本地路径;导出记录保留 checksum、size_bytes、elapsed_ms 便于对账。
  • 变更类接口统一返回 {ok, result, summary}(前端 src/api/client.ts 自动拆包),错误体统一读 detail;只读接口大多直接返回资源对象,两个例外是 GET /api/projects/{id} 与 GET /api/projects/{id}/summary——它们也带信封(前端已统一处理,写脚本时记得拆开或自动拆)。

7.1 前后端契约(已用回归用例锁死,改动前请先跑 tests/test_regression_fixes.py)

  • review_state ∈ pending / pass / fail(app/constants.py:ReviewVerdict,与 ReviewRecord.verdict 同源)。它和镜头 status(approved/rejected/…)是两个字段, 分镜卡片按前者显示人工结论;写成 approved 会让每个合格镜头都标红成「被驳回」。
  • 人工审核必须在产物之后:镜头没有 output_path 时 POST /approve 直接 400, 对应图2「质检(9)→ 人工审核(10)」的先后顺序。
  • 流程节点计数按镜头去重:workflow[] 每项是 {key,label,state,done,total,detail}, 同一镜头驳回重做会产生多条任务,计数必须按镜头去重(否则节点 6 永远 active、 节点 4 会出现 5/4);done 恒 ≤ total。
  • /health 是前端侧边栏的唯一数据源:{status, app, executor, ffmpeg, ffmpeg_capabilities{available,drawtext,subtitle_burn,subtitle_filter,xfade,concat,loudnorm, blackdetect,freezedetect,font}, database, model_specs, daemon{enabled,running,executor, inline_pending,loops,last_dispatched,last_error,last_tick}},前端会校验字段类型, 拿不到合法 JSON(例如代理漏配)时直接报错而不是显示「未知」。
  • 响应三套约定:写接口 = {ok, result, summary} 信封;绝大多数只读接口 = 裸资源对象 ({shots,count}、{timeline,report}、{preflight,summary}…);错误 = detail。 例外只有 GET /projects/{id} 与 GET /projects/{id}/summary 也走信封。 另外 PATCH /timeline/settings 的参数需要再包一层 {"settings": {...}}。
  • 交付文案里的项目名:workflow[0].detail 只在项目名不含 《 时补书名号,避免渲染成《《…》》。
  • 限流容量行 GET /api/projects/{id}/queue 的 capacity[]:一个 (provider, model) 只允许一行,media_type / concurrency_limit / rpm_limit / enabled 必须取自该模型的 ModelSpec。曾因任务派生的容量键一律写成 media_type="video",配音模型多出一行默认限额 (2 并发 / 30 RPM)的幽灵记录,并按 provider|model 覆盖掉真正的 TTS 行(4 / 120),派发时的 headroom() 与模型注册表的 load 一起被降级。
  • 局部失败不许被整体成功掩盖:节点 8「调用视频模型」/节点 9「下载并保存视频」的进度按 可用产物计数,停在 failed 的镜头即使磁盘上还留着上一次的旧产物也要从分子里扣掉, 且节点状态必须是 failed。曾因按「产物文件是否存在」直接计数,重做失败的镜头仍显示 「生成成功 4/4 [done]」,界面上完全看不见图2 节点 8 的「否」分支。