74 KiB
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/iconsimport(只许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 会返回 403Blocked request. This host (...) is not allowed.。 - 🔒 鉴权默认开启(
AUTH_ENABLED=true):首次启动自动播种管理员admin/ 初始口令admin@123(app/services/auth.py:bootstrap,登录后应立即改密),会话走nex_sessionCookie, 脚本也可以用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 折进提示词末尾的自然语言子句 |
踩过的两个坑(已修 + 已锁测试,改适配器前请先读):
- 参考图是 ComfyUI 的 autogrow 槽位(
COMFY_AUTOGROW_V3)。ComfyUI 3.x 的 API prompt 必须使用 “父输入.槽位”扁平键:H3 为ref_images.ref_image_0,Qwen-Image 为images.image_1。传嵌套字典不会报错,但会被静默解析成空参考集,最终成图/成片与参考图无关。 - 时长窗口不能只看节点参数下限(节点
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 导出。现在直接在界面上走:
- 资产库录角色定妆图 / 场景图 / 声线;新建项目时可勾选要引入的资源库,避免每次重录;
- 分镜写三段镜头:有台词(真人)、有台词(外星语 + 变声)、无台词空镜各一段—— 无台词是正常形态,平台不会为它编一句旁白;
- 每段先出关键帧,再用 H3 i2v 出片;
voice_source=native时带原生音轨的镜头不再叠加 TTS(§4.0.1); - 质检 + 人工审核通过后,时间线混音、挂字幕,导出 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 的「否」分支。