47 lines
4.7 KiB
Markdown
47 lines
4.7 KiB
Markdown
# 独立视频高清服务
|
||
|
||
主项目负责用户/项目鉴权、持久任务、归档；此服务只下载视频并在独立 GPU 上逐帧超分。没有 CPU 回退，不使用千问显卡。当前部署固定 `CUDA_VISIBLE_DEVICES=3`，GPU 2 有硬件故障历史，不分配给本服务。
|
||
|
||
## 模型和环境
|
||
|
||
使用 [Real-ESRGAN](https://github.com/xinntao/Real-ESRGAN) 的 `realesr-general-x4v3`，官方 SRVGGNetCompact 架构（64 通道、32 卷积层、PReLU、4 倍输出）；源码与 BSD-3-Clause 许可位于 `vendor/`，来源 commit 见 `vendor/SOURCE.md`。不是 Topaz 模型。模型文件不提交仓库。
|
||
|
||
权重：[官方 v0.2.5.0 发布](https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesr-general-x4v3.pth)，SHA-256 `8dc7edb9ac80ccdc30c3a5dca6616509367f05fbc184ad95b731f05bece96292`，推理前强校验。
|
||
|
||
P40 环境实测：Python 3.12.3、PyTorch 2.5.1+cu121、NumPy 1.26.4、Pillow 10.4.0、系统 FFmpeg/ffprobe（libx264/AAC）。PyTorch 使用 CUDA 12.1 官方 wheel 源；必须固定此版本，不能未经 P40 验证直接升级 CUDA/PyTorch。FP32 推理，192px tile + 40px halo，整帧输出在 CPU 内存，避免全帧网络推理耗尽显存。每个服务同时处理一个任务。
|
||
|
||
## 部署与 API
|
||
|
||
构建：`node services/video-upscale/build.cjs`，将 `dist/` 内容放到 `/opt/video-upscale/app/`。环境位于 `/opt/video-upscale/venv/`，权重 `/opt/video-upscale/models/realesr-general-x4v3.pth`。参考 `video-upscale.service` 创建专用 `video-upscale` 用户和其拥有的 `/var/lib/video-upscale`。
|
||
|
||
`/etc/video-upscale.env` 权限 600，包含 `UPSCALE_API_TOKEN`（至少 32 字符）、`UPSCALE_HOST=127.0.0.1`、`UPSCALE_PORT=18341`、`UPSCALE_DATA_DIR=/var/lib/video-upscale`。禁止将凭据放进 Git 或浏览器。
|
||
|
||
所有 API 要求 `Authorization: Bearer <token>`：
|
||
|
||
- `GET /health`：服务、队列和 GPU 配置。
|
||
- `POST /v1/upscales`：`{id,tenant,plan:{url,resolution}}`，id/tenant 均为 SHA-256 标识，resolution 为 `1080P`/`2K`/`4K`。
|
||
- `GET /v1/upscales/:id`：状态、阶段、帧数/帧率/音轨、尺寸与时长。
|
||
- `GET /v1/upscales/:id/video`：鉴权读取结果。
|
||
|
||
48 服务器使用 `video-upscale-tunnel.service`，复用已有专用隧道账号和固定 known_hosts，只扩展该公钥的 `permitlisten` 到 `127.0.0.1:18341`；原 18340 合成隧道不变。主项目接入变量为 `VIDEO_UPSCALE_URL=http://127.0.0.1:18341` 和 `VIDEO_UPSCALE_TOKEN`，部署时从 root-only `/etc/video-upscale-client.env` 注入，不能依赖本机临时 SSH 转发。
|
||
|
||
任务落盘 fsync + rename；相同 ID/参数幂等，相同 ID/不同参数 409。服务重启保留 running 记录，最多恢复两次；`KillMode=mixed` 先通知 Node 保存关闭状态，再终止子进程，避免把正常重启误记为推理失败。主项目保存远程 ID/服务指纹，轮询超时、读取/归档失败继续查询同一任务。
|
||
|
||
## 处理边界
|
||
|
||
输入 ≤125 MiB、≤120 秒、≤60fps、≤4K 像素数；支持 MP4/MOV、Matroska/WebM、AVI、FLV、MPEG-TS。仅恒定帧率；VFR 明确拒绝，不能静默改变音画同步。手机 90/180/270 度旋转信息会归一化，保留帧数、帧率、音轨。音频重编码 AAC，视频 H.264/yuv420p + faststart。不做补帧。
|
||
|
||
目标以 1920×1080 / 2560×1440 / 3840×2160 为横屏边界，竖屏交换宽高，等比例缩放、偶数尺寸。目标必须大于原图且至多 4 倍；目标已满足或要求超过 4 倍时拒绝，不拿插值假称模型支持更高倍率。网络输出可能产生细节变化，不能保证真实细节还原。
|
||
|
||
单任务超时 2 小时；≤30 个在途任务，≤200 个保留任务，完成/失败保留 7 天；可用磁盘 <10 GiB 拒绝开始。输入禁止内网/DNS 重绑定/不安全重定向，FFmpeg 网络协议关闭；输出下载 ≤300 MiB。systemd 内存 8 GiB、CPU 4 核、任务/线程 256，滤镜线程固定 1，避免 128 核宿主机默认线程数导致编码失败。
|
||
|
||
## 验收
|
||
|
||
`scripts/qa/video-upscale-service.cjs` 验证真实 API、GPU、音轨/帧数/尺寸、重复提交、参数冲突、未鉴权下载及重启恢复。需设置 `VIDEO_UPSCALE_QA_URL`、`VIDEO_UPSCALE_QA_TOKEN`、`VIDEO_UPSCALE_QA_SOURCE`（960×540、2fps、1 秒、含音轨的合成测试片）；可选 `VIDEO_UPSCALE_QA_SSH_HOST` / `VIDEO_UPSCALE_QA_SSH_CONTROL` 执行独立服务重启。只重启视频高清服务，不重启千问或主项目。
|
||
|
||
测试素材生成示例（应上传到获准访问的测试存储域名）：
|
||
|
||
```sh
|
||
ffmpeg -f lavfi -i 'testsrc2=size=960x540:rate=2:duration=1' -f lavfi -i 'sine=frequency=440:sample_rate=48000:duration=1' -c:v libx264 -pix_fmt yuv420p -c:a aac -shortest landscape.mp4
|
||
```
|