业务赋能中心

本地网关协同

业务赋能视角下本地网关在上传、预览、录制、拆分和推送链路中的作用。

为什么需要本地网关

很多客户的视频文件不直接放在云端，而是在内网共享盘、NAS 或本地工作站附近。本地网关负责把这些本地环境能力接入云端业务流程。

使用者不需要每天操作网关，但要知道：上传、预览、直播录制、脚本分镜拆分和成片推送出现异常时，网关状态是必须排查的一环。

网关参与哪些业务

  • 素材、成片、工程文件上传和本地资源登记。
  • 访问链路解析、上传票据生成、上传结果登记。
  • 视频预览、封面获取、下载票据、合集下载和压缩包下载。
  • 外网 480p 预览缓存、Range 播放和分片上传合并。
  • 直播录制任务执行与录制状态回写。
  • 脚本分镜拆分任务执行、转写结果和分镜结果回写。
  • TTS 参考音频读取、语音合成执行、输出文件落盘和健康检查。
  • 成片推送任务认领、执行和结果回写。
  • Windows Print Agent 对接、打印机发现和远程打印任务执行。
  • 共享盘、预览目录、版本目录和 Syncthing 文件夹健康上报。

使用者应该关注什么

业务页面中通常不需要直接配置网关，但要关注这些表现：

  • 上传后文件是否能在资源库看到。
  • 预览或封面是否能正常打开。
  • 下载票据是否能打开，合集或批量下载是否能生成压缩包。
  • 直播录制是否能从待派发进入录制中。
  • 脚本分镜任务是否能从待处理进入处理中并完成。
  • TTS 任务是否能产出音频文件，音色参考音频是否已成功落盘。
  • 推送记录是否被网关认领并回写结果。
  • 打印机是否能从目标地区发现，打印任务是否经历已接收、准备中、打印中、完成等事件。
  • 运维中心里网关服务状态、组网链路状态、存储健康和业务任务风险是否一致。

当前进程和能力边界

本地网关不是一个单一脚本，而是一组本地执行进程：

进程主要职责常见端口或入口
Go GatewayHTTP API、签名校验、WSS 回连、文件预览、上传、推送、TTS 转发、打印转发9801 或 HTTPS 域名
Python Worker脚本分镜拆分、直播录制、弹幕采集、媒体处理Compose 内网
TTS 服务MOSS-TTS-Nano ONNX 本地语音合成Compose 内网
CaddyHTTPS 反向代理和证书入口443
Windows Print AgentWindows 打印机发现和打印队列提交宿主机 9811

健康排查时要分清是网关 HTTP 不通、WSS 回连异常、worker 异常、TTS 服务异常、共享盘不可写，还是 Print Agent 不可达。

异常排查顺序

  1. 先看当前业务记录状态。
  2. 再看本地网关是否在线。
  3. 检查共享盘路径、文件权限和磁盘空间。
  4. 检查访问链路解析是否返回了当前地区可用网关。
  5. 检查上传票据、下载票据或本地资源登记是否成功。
  6. 检查云端回调地址、TTS 健康接口或 Print Agent 是否能被网关访问。
  7. 最后看具体 worker、录制器、TTS 服务、Print Agent 或推送执行器日志。

运维中心里的状态怎么理解

运维中心现在会把网关问题拆成几层看：

  • 服务状态：网关进程、worker、共享盘、预览目录、TTS、打印代理等本地能力是否可用。
  • 链路状态：云端访问本地网关、浏览器访问本地网关、WSS 回连云端、外网媒体入口访问网关是否可达。
  • 业务状态：直播录制、TTS、远程打印、推送、脚本拆解等任务是否堆积或失败。
  • 综合风险：结合服务、链路、告警和任务数量给运维人员排序。

云端访问本地网关失败，不一定说明网关服务挂了。如果 WSS 仍在线，通常优先怀疑入站链路、base_url、NAT、防火墙、DNS、代理或内网穿透问题。只有拿到健康返回体后，才应该把 worker_ready、disk_root_ready、preview_root_ready 等字段判成正常或异常；拿不到健康返回体时，这些本地能力应理解为未知。

Syncthing 和存储健康

本地网关会围绕共享盘和同步目录提供健康信息，运维中心会关注：

  • disk_root、preview_root、version_root 是否存在、可写和容量充足。
  • 外网预览缓存是否启用，默认预览规格是否为 480p。
  • Syncthing 文件夹是否可查询，Host Header 和 TLS 策略是否符合当前部署。
  • 业务目录占用、剩余空间和同步风险是否影响上传、预览、脚本拆解或直播录制。

共享盘不可写、预览目录缺失、磁盘空间不足和 Syncthing 文件夹异常，都可能表现为“上传成功但无法预览”“直播完成但无文件”“外网预览不可用”或“分镜结果无法下载”。

VPN 或代理导致无法访问本地网关

如果电脑开启了 VPN、Clash、TUN 模式、全局代理或安全客户端，浏览器可能会把本地网关域名也送进代理链路。表现通常是：

  • 云端页面能打开，但资源预览、TTS 播放、下载或本地上传失败。
  • 网关服务本身在线，其他未开 VPN 的电脑可以访问。
  • 浏览器访问本地网关健康检查地址超时、证书异常或返回网络错误。

处理时不要改业务数据，先让本地网关地址走直连：

  1. 在 VPN 或代理软件里把本地网关域名加入 DIRECT、绕过代理或不走 TUN 的规则。
  2. 至少包含当前启用的网关域名，例如 changsha-gateway.studiox-mkt.com、shanghai-gateway.studiox-mkt.com，以及客户实际部署的本地网关域名或内网 IP。
  3. 如果代理软件支持 CIDR 规则，也把办公室内网网段加入直连。
  4. 如果使用 TUN 模式，确认规则对浏览器进程和系统 DNS 都生效；只配置系统代理绕过有时不够。
  5. 修改后重新打开浏览器，访问 https://对应网关域名/api/video-collab/local/health 验证。

现场排障可以先用系统路由做临时验证。

Windows 管理员 PowerShell：

$GatewayHost = "changsha-gateway.studiox-mkt.com"
$GatewayIp = ([System.Net.Dns]::GetHostAddresses($GatewayHost) | Where-Object { $_.AddressFamily -eq "InterNetwork" } | Select-Object -First 1).IPAddressToString
$LanGateway = "192.168.1.1"
route print 0.0.0.0
route add $GatewayIp mask 255.255.255.255 $LanGateway
curl.exe "https://$GatewayHost/api/video-collab/local/health"

macOS：

GATEWAY_HOST="changsha-gateway.studiox-mkt.com"
GATEWAY_IP="$(dig +short "$GATEWAY_HOST" A | head -n 1)"
LAN_GATEWAY="192.168.1.1"
netstat -rn | grep default
sudo route -n add -host "$GATEWAY_IP" "$LAN_GATEWAY"
curl -fsS "https://$GATEWAY_HOST/api/video-collab/local/health"

上面的 192.168.1.1 只是示例，实施时要替换成客户办公室真实默认网关。Windows 如果验证通过，可以用 route -p add 做持久化；macOS 临时路由重启后会失效，长期方案应优先在 VPN、Clash、Surge 或企业安全客户端里配置域名或 CIDR 直连。

只要健康检查无法从当前电脑访问，前端就不应该继续走本地网关预览或下载链路，而应回到外网降级或提示网络不可达。

这次更新后要理解的边界

  • 直播录制、脚本拆解、TTS、推送、远程打印 都是“云端发起，本地执行”的协同链路。
  • 上传、预览、下载、合集压缩 也依赖访问链路解析和本地网关。
  • 外网预览 不是把视频长期缓存到云端，而是通过统一媒体入口转发到地区本地网关，默认播放本地生成的 480p 预览。
  • 外网上传 仍然是浏览器分片上传到本地网关合并落盘，云端只负责票据、权限、元数据和审计。
  • 云端页面里的任务状态只是业务视图，不等于执行器已经真正完成所有本地动作。
  • TTS 和远程打印都依赖地区网关或宿主机能力，和普通纯云端表单不同，网络、共享盘和宿主机配置会直接影响结果。
  • 远程打印除了网关本身，还多了一层 Windows Print Agent；打印机能否被发现、Office/WPS 是否可用，都在这层完成。

适合写进客户交付说明的边界

  • 云端负责业务状态和权限。
  • 网关负责本地文件和执行动作。
  • Windows Print Agent 负责 Windows 宿主机打印机发现和打印队列提交。
  • 网关异常不会改变已经存在的业务权限，但会影响上传、预览、拆分、录制、TTS、推送和打印等动作。
  • 如果客户更换共享盘、服务器、域名或网络策略，需要重新验证网关联通性。