开发文档

本地网关

local-gateway 的职责、部署方式和与云端的协作边界。

项目定位

local-gateway/ 部署在共享盘所在机器上，用来把云端下发的授权请求转成可控的本地文件读写能力。

它当前承担三类职责：

  • 本地 HTTP 网关：健康检查、预览、封面、上传落盘
  • 推送执行器：接收云端通知并执行上传或回写
  • 脚本拆解执行器：在共享盘附近执行场景检测与转写

目录结构

local-gateway/
├─ gateway-go/   # Go 网关
└─ worker-py/    # Python AI worker

关键环境变量

  • VIDEO_COLLAB_DISK_ROOT
  • VIDEO_COLLAB_VERSION_ROOT
  • VIDEO_COLLAB_LOCAL_GATEWAY_REGION
  • VIDEO_COLLAB_GATEWAY_SIGNATURE_SECRET
  • VIDEO_COLLAB_PUSH_CLOUD_BASE_URL
  • VIDEO_COLLAB_PUSH_GATEWAY_ID
  • VIDEO_COLLAB_PUSH_GATEWAY_SHARED_SECRET
  • LOCAL_GATEWAY_WORKER_SHARED_SECRET

开发与部署建议

  • 开发优先用 Docker Compose 跑通完整链路
  • 需要单步调试时，再拆成 Go 与 Python 两个进程
  • 首次构建 worker 会下载较大依赖，后续命中缓存后会明显变快

与云端的接口边界

  • 云端负责业务记录、鉴权、任务编排和结果入库
  • 本地网关负责共享盘附近的执行动作
  • 脚本拆解结果通过 /api/video-collab/script-breakdown/callback 回写云端

常见排查顺序

上传或预览异常

  1. 先看 gateway 是否在线
  2. 再看共享盘根路径是否挂载正确
  3. 再确认签名密钥和云端地址是否一致

脚本拆解异常

  1. 看 worker 是否在线
  2. 看模型、ffmpeg 和 Python 依赖是否完整
  3. 看回调接口是否返回成功

推送任务异常

  1. 看网关是否收到云端通知
  2. 看当前节点标识和共享密钥是否正确
  3. 看回写云端时是否有鉴权或网络错误