888 lines
74 KiB
Markdown
888 lines
74 KiB
Markdown
# 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 的「否」分支。
|