46 lines
4.8 KiB
Markdown
46 lines
4.8 KiB
Markdown
# 独立视频合成服务
|
||
|
||
只承接已确认的 EDL 合成。主项目保留用户鉴权、项目、分析选片、时间轴与最终对象存储归档；算力服务器下载原素材、校验内容 hash，用 FFmpeg 处理剪裁、速度、音量、转场、字幕和配乐。没有把完整主项目、数据库密码或云模型密钥复制到算力服务器。
|
||
|
||
## 运行
|
||
|
||
项目根目录执行 `node services/video-render/build.cjs`，生成不依赖主项目 node_modules 的 `dist/server.cjs`（Node 22，Zod 随包打包）。机器需要 FFmpeg/ffprobe、libx264、libass、中文字体。发布包放 `/opt/video-render/releases/<hash>/server.cjs`，`current` 指向当前版本。参见 `video-render.service`：专用低权限用户、单 worker、4 核 CPU 配额、6 GiB 内存软限制 / 8 GiB 硬限制。当前使用 CPU，不占用千问显卡。
|
||
|
||
`/etc/video-render.env` 权限 600，环境变量：
|
||
|
||
- `RENDER_API_TOKEN`：至少 32 字符随机凭据，不能提交 Git。
|
||
- `RENDER_HOST=127.0.0.1`、`RENDER_PORT=18340`。
|
||
- `RENDER_DATA_DIR=/var/lib/video-render`。
|
||
- `SMART_EDIT_CACHE_DIR=/var/lib/video-render/cache`。
|
||
- 可选 `RENDER_QWEN_URL=http://127.0.0.1:18231/v1`、`RENDER_QWEN_MODEL=qwen3.8-27b-q4-32k`。
|
||
|
||
主项目配置 `SMART_EDIT_RENDER_URL=http://127.0.0.1:18340` 和同值 `SMART_EDIT_RENDER_TOKEN`。只要配置远程服务，合成请求走远程；远程连接失败不会悄悄回退到主机 FFmpeg。已有远程任务绑定原服务地址，不能在恢复时切换到另一台重复提交。
|
||
|
||
两台服务器通过专用 SSH 反向隧道连接，参见 `video-render-tunnel.service`。48 上专用隧道用户只允许监听 `127.0.0.1:18340`，禁用命令、PTY、代理转发，主机公钥预先核对并固定；私钥仅留算力服务器，不使用或复制管理员私钥。合成 API 仍要求 Bearer 凭据。容器部署时 localhost 含义不同，必须显式配置宿主机访问方式。
|
||
|
||
## 接口
|
||
|
||
所有接口要求 `Authorization: Bearer <token>`，不接受浏览器直接访问。
|
||
|
||
- `GET /health`：队列数量、活动任务数、合成方式、文字助手是否配置。
|
||
- `POST /v1/renders`：`{id, tenant, plan}`；id 与 tenant 均为 SHA-256 十六进制标识，plan 使用 `lib/video-canvas/smart-edit/contract.ts`。
|
||
- `GET /v1/renders/:id`：`queued/running/succeeded/failed`、阶段、重试次数、结果尺寸及时长。
|
||
- `GET /v1/renders/:id/video`、`/subtitles`：鉴权下载产物，由主项目归档。
|
||
- `POST /v1/assist`：可选 `{instruction, context}` 文本辅助，返回建议文字；不自动改变剪辑方案、不执行生成的代码、不支持图片视频输入。并发 1，90 秒超时，不自动重试。普通合成不会调用千问。
|
||
|
||
任务 ID 由主项目持久任务号导出：重复 POST 返回同一记录，参数改变返回 409。写盘采用临时文件、fsync、rename 后再响应。单服务进程拥有此数据目录，不能启动多个副本共用目录。服务重启后运行中任务最多恢复两次；完成记录重启后仍可下载。主项目轮询超时保存编号继续查询，不受浏览器页面生命周期限制。
|
||
|
||
上限：请求 1 MiB，至多 30 个等待/运行任务，至多 200 个保留任务；完成/失败记录和产物保留 7 天，小时清理；原素材缓存按用户隔离，4 GiB / 7 天清理；素材 ≤125 MiB/份、≤180秒/份、≤12份且总长≤10分钟，成片≤300秒/12片段；6种比例（含21:9）、480P/720P/1080P，长边最高2520像素。磁盘可用不足10GiB拒绝重处理。外部素材禁止内网地址，DNS验证后绑定地址下载，每次重定向重新验证；FFmpeg禁用网络输入协议。
|
||
|
||
## 验证
|
||
|
||
`PATH=<ffmpeg目录>:$PATH node scripts/qa/video-canvas-smart-edit.cjs` 生成合成素材并验证 FFmpeg。设置 `SMART_EDIT_PYTHON` 可同时验证真实 PySceneDetect、RMS、librosa。
|
||
|
||
随后 `node services/video-render/build.cjs && PATH=<ffmpeg目录>:$PATH node scripts/qa/video-render-service.cjs` 验证真实 HTTP、鉴权、FFmpeg、进程强制中断/恢复、幂等、冲突拒绝和完成记录重启保留。用合成色块/正弦音，不调用付费模型。
|
||
|
||
依赖许可：Zod MIT；FFmpeg 许可取决于本机编译选项，Ubuntu libx264 构建含 GPL 组件。服务只运行本机已安装 FFmpeg，不把二进制混入仓库。代码与发布状态记录在 `docs/video-render-service-2026-09-17.md`。
|
||
|
||
## 字体包
|
||
|
||
构建会将 `public/fonts/smart-edit` 的真实字体和许可证复制到 `dist/fonts`，发布时必须与 `server.cjs` 一起携带。服务默认读取同目录 `fonts`，可用 `SMART_EDIT_FONTS_DIR` 指定绝对路径；主项目本地合成默认读取 `public/fonts/smart-edit`。缺失所选字体时返回明确错误，不悄悄使用其他字体。五种字体来自 Adobe/Google 官方仓库，来源、摘要和各自 SIL OFL 许可保存在字体目录。
|