nex_animation/README.md

888 lines
74 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# Nex Animation Studio · 长视频编导平台
面向 AI 长视频创作的本地工作台:**人物与声音资产库 → 分镜与脚本管理 → 视频模型调度中心 → 长视频合成引擎**,
底层由统一任务编排(队列 / 重试 / 断点续跑 / 并发限流)与项目数据库支撑,完整实现业务流程图的 12 个节点。
> 📖 **[图文使用手册](frontend/src/pages/Help.tsx)** —— 已搬进站内:启动后访问 <http://127.0.0.1:5173/help>,或点工作台顶栏的「手册」
>
> 手册包含模型管理中心、资产独立生成与镜头关联、分镜检查器、调度、质检、时间线和导出流程的实际截图。
>
> 🧹 动代码或打部署包之前先读 **[工程规范与部署数据边界](docs/工程规范.md)**:
> 目录职责、`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 直出)
```
### 仓库目录与脚本职责
```text
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):
```text
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 需在跑):
```bash
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|voice` | 项目 `draft` |
| 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,适合开发、演示、自检)
**一条命令搞定前后端:**
```bash
./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`,启动时会把本机与局域网地址一起打出来:
```text
界面 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,而不是卡在健康检查超时。
手工启动(想单独控制某个进程时):
```bash
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(默认**一个容器**:前端和后端同一个端口)
```bash
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、新镜头另存一处」——文件都在,只是没人指过去。先停再搬,别边写边搬:
```bash
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 层):
```bash
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 放别的机器):
```bash
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/*` 在默认鉴权下需要先拿会话:
```bash
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`,所以开发与测试行为完全不变。
```bash
# ---- 开发机:数据集 → 打包(内容白名单 + 体检,体检不过直接报错不产出包)----
.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` 之后,
服务器上要多跑一次才会对齐:
```bash
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 进库才有审计与探测记录。
```bash
# 首次接入新机器:页面「+ 登记模型」→ 选 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` |
```jsonc
// 克隆: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`](https://github.com/yolain/ComfyUI-Easy-IndexTTS2),安装模型与 Python
依赖后重启 ComfyUI;`/object_info` 必须出现 `easy downloadIndexTTSAndLoadModel` 与
`easy indexTTSGenerateSimple`,要用音色描述直出还得多两个
`easy indexTTSGenerate`、`easy indexTTSEmotionText`(诊断接口会把缺的节点逐个列出来)。
Nex 不会在未经授权时远程安装节点或下载大模型。
在 9200 的 ComfyUI 主机上安装节点:
```bash
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/`。重启后可检查:
```bash
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`):
```bash
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,进程内,无需起服务)
```bash
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 实测)
```bash
# 终端 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 前端构建
```bash
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 的「否」分支。