services.printer/云台对接说明.md
liufumingren d42fa2d863 feat: 新增云台(PTZ)中转端点,入参口径与 OSD 一致
- 新增 POST /camera/ptzControl、/camera/ptzStop、/camera/ptzPresetGoto
  入参 { warehouse_id, rtspUrl, action, speed? } / { ... , presetId },不再需要 computerId
- 控制器抽出公用方法 _findRecordingClient / _pushToRecordingClient,
  setCameraOSD 改为复用(对外返回与日志逐字不变)
- HTTP 侧 method 换名为客户端 WS method:camera.ptzControl -> camera.ptz.control
  等;warehouse_id 仅用于选目标电脑,不下发给客户端
- 新增对接文档 云台对接说明.md(链路、端点、WS 契约、ISAPI 映射、排查手册)
2026-09-15 20:25:40 +08:00

12 KiB
Raw Permalink Blame History

云台(PTZ)通讯对接说明

适用版本:services.printer(服务端中转)+ printServer(打印/录制电脑客户端) 最后更新:2026-09-15 定位:services.printer 只是中转(method 换名 + data 透传),不校验执行结果、不做回执、不记状态。


一、整体链路

WMS 主服务
   │  ①HTTP POST /camera/ptzControl | /camera/ptzStop | /camera/ptzPresetGoto
   │    body: { warehouse_id, rtspUrl, action, speed? } / + presetId
   ▼
services.printer :4052                        ← 本仓库,仅做中转
   │  ②SCAN warehouse:{warehouse_id}:printer:* → 取 is_recording === 1 的那台
   │  ③WS sendTo(uniqueId, { method, data })   method 换名,data 透传
   ▼
printServer(仓库录制电脑)
   │  ④按 method 点分路由 → services/camera.ptz.*
   ▼
摄像头 / NVR(仓库内网,ISAPI)

入参风格与 OSD 完全一致:warehouse_id + rtspUrl + 业务参数,不需要 computerId(由打印服务自己按仓库挑录制电脑)。

关键语义:HTTP 返回 status: success 只代表「消息已写进 WS 房间」,不代表云台动了。执行结果只落客户端本地日志,不回传。


二、WMS → services.printer(HTTP,与 OSD 同风格)

三个独立端点,入参口径与 /camera/setOSD 一致:

端点 入参 说明
POST /camera/ptzControl warehouse_id、rtspUrl、action、speed?、channel?、port? 开始运动
POST /camera/ptzStop warehouse_id、rtspUrl、action、channel?、port? 停止运动
POST /camera/ptzPresetGoto warehouse_id、rtspUrl、presetId、channel?、port? 调用预置点
POST http://{services.printer 地址}:4052/camera/ptzControl
Content-Type: application/json
{
  "warehouse_id": 9,               // 必填,仓库 ID
  "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601",  // 必填(与 OSD 同一套 URL)
  "action": "left",                // 必填,见第三节
  "speed": 4                       // 可选,1~7,默认 4
}

返回

返回 含义
{ status:'success', message:'云台指令已下发', result:{ computer_id, method } } 已推送到该电脑的 WS 房间
{ status:'fail', message:'缺少必要参数: warehouse_id' } 入参不全(字段名会原样回显)
{ status:'fail', message:'仓库 9 中没有在线的录制电脑' } 该仓库没有 is_recording = 1 的在线电脑
{ status:'fail', message:'录制电脑不在线,消息发送失败' } sendTo 未命中房间(连接刚断)

目标电脑怎么定:SCAN warehouse:{warehouse_id}:printer:* → 取 is_recording === 1 的那台。与 /camera/setOSD 同一个公用方法(app/controller/hikvision.js#_pushToRecordingClient),所以两边行为天然一致。


三、services.printer → 客户端(WS 下发契约)

服务端会把 method 换名再下发(HTTP 侧 camera.ptzControl → WS 侧 camera.ptz.control),data 原样透传。下表就是客户端必须实现的入口。

method 用途 是否持续型
camera.ptz.control 开始运动(方向 / 变倍 / 聚焦 / 光圈) ✅ 必须另发 stop
camera.ptz.stop 停止运动 —
camera.ptz.presetGoto 调用预置点 ❌ 一次性
camera.ptz.presetSet 设置(保存)预置点 ❌ 一次性
camera.ptz.auto 自动巡航(autoPan)开关 ❌ 开关型

data 字段

字段 control stop presetGoto presetSet auto 说明
rtspUrl ✔ ✔ ✔ ✔ ✔ 设备 RTSP 地址;客户端从中解析 账号 / 密码 / 主机 / 通道号
action ✔ ✔ — — — 动作名或 SDK 索引,见下表。stop 必须与 start 同一个 action
speed ○ — — — — 1~7,默认 4
presetId — — ✔ ✔ — 预置点编号(1~256)
presetName — — — ○ — 预置点名称,默认 Preset{id}
on — — — — ✔ true 开启 / false 关闭
channel ○ ○ ○ ○ ○ 手动覆盖通道号(默认从 rtspUrl 解析)
port ○ ○ ○ ○ ○ 设备 ISAPI 端口,默认 80

action 取值

action 同义写法 SDK 索引 效果
up — 1 上
down — 2 下
left — 3 左
right — 4 右
upLeft up_left 5 左上
downLeft down_left 6 左下
upRight up_right 7 右上
downRight down_right 8 右下
zoomIn zoom_in 10 变倍 +
zoomOut zoom_out 11 变倍 −
focusIn focus_in / focusFar 12 聚焦 +
focusOut focus_out / focusNear 13 聚焦 −
irisIn iris_in 14 光圈 +
irisOut iris_out 15 光圈 −

索引 9(自动巡航)不在 control 里支持,请用 camera.ptz.auto。

HTTP 侧目前只暴露前 3 个方法(control / stop / presetGoto)。presetSet / auto 客户端已实现,但打印服务侧暂无 HTTP 入口 —— 需要时按同一模式加一个端点即可。

通道号来源

客户端从 rtspUrl 路径解析,规则:

rtspUrl 路径 通道号
/Streaming/Channels/101 1
/Streaming/Channels/601 6(末两位是码流号)
/Streaming/Channels/1201 12
/stream2 2

解析不准时用 channel 显式覆盖。


四、客户端侧实现(已完成)

printServer 仓库改动清单:

文件 改动
utils/cameraPtz.js 新增。ISAPI 云台控制,含认证握手、路径回退、路径缓存、文件日志
utils/cameraOsd.js 3 处 export(extractRTSPInfo / _isapiAuth / _isapiRequest)+ _isapiRequest、_isapiAuth 各加可选 port(默认 80,行为不变)
services/camera.js 新增 this.ptz = { control, stop, presetGoto, presetSet, auto },与已有 this.osd 平级

⚠️ 两条硬约束

  1. 这些方法一律不能有返回值。 core/wsClient.js 只要拿到非 undefined 的返回值,就会回发 {success:true, method, result} 给服务端;而服务端 app/controller/print.js 会把这条回显当成一次服务调用去路由,services.printer 里没有 camera.* 服务 → 刷一堆 服务路径 camera 不存在 的错误。 客户端日志里若出现该报错,说明有人给这些方法加了 return。

  2. 持续型动作必须由 WMS 补发 stop。 ISAPI /continuous 是「一次 PUT 后设备持续运动」。客户端不做自动停止,WMS 侧必须在鼠标抬起 / 移出画面 / 窗口失焦 / 关闭时下发 camera.ptz.stop(同一个 action)。

日志

日志 位置
云台 {getAppDataDir()}/cameraPtz.log(同时输出到控制台,前缀 [CameraPTZ])
OSD 同目录下的 cameraOsd.log

日志目录由客户端 utils/runtime.js#getAppDataDir() 决定:Windows 打包版 = %ProgramData%\printServer;Linux / 开发态 = 项目根目录(与 frpc.log 同级)。 ⚠️ 不要在客户端自己用 process.env.ProgramData 拼路径 —— Linux 下会落到字面量目录 /opt/printserver/C:/ProgramData/...。


五、动作 ↔ ISAPI 映射(客户端内部实现)

路径与报文对齐海康官方无插件 SDK(webVideoCtrl.js)。每种动作按候选顺序尝试,成功后缓存该设备可用的那一条。

动作 首选路径 回退路径
方向 / 变倍 /ISAPI/PTZCtrl/channels/{ch}/continuous /ISAPI/ContentMgmt/PTZCtrlProxy/channels/{ch}/continuous
聚焦 /ISAPI/Image/channels/{ch}/focus /ISAPI/ContentMgmt/ImageProxy/channels/{ch}/focus → /ISAPI/System/Video/inputs/channels/{ch}/focus
光圈 /ISAPI/Image/channels/{ch}/iris /ISAPI/ContentMgmt/ImageProxy/channels/{ch}/iris → /ISAPI/System/Video/inputs/channels/{ch}/iris
预置点调用 /ISAPI/PTZCtrl/channels/{ch}/presets/{id}/goto /ISAPI/ContentMgmt/PTZCtrlProxy/channels/{ch}/presets/{id}/goto
预置点设置 /ISAPI/PTZCtrl/channels/{ch}/presets/{id} /ISAPI/ContentMgmt/PTZCtrlProxy/channels/{ch}/presets/{id}
自动巡航 /ISAPI/PTZCtrl/channels/{ch}/autoPan /ISAPI/ContentMgmt/PTZCtrlProxy/channels/{ch}/autoPan

全部为 PUT;认证自适应 Basic / Digest(401 自动重新握手一次)。

报文与取值

速度换算(与 SDK 一致):speed < 7 → 15 × speed,speed ≥ 7 → 100;默认 speed = 4 → 60。停止 = 0。

<!-- 方向:action=left, speed=4 -->
<PTZData><pan>-60</pan><tilt>0</tilt></PTZData>
<!-- 方向停止:action=left -->
<PTZData><pan>0</pan><tilt>0</tilt></PTZData>
<!-- 变倍:action=zoomIn, speed=2 -->
<PTZData><zoom>30</zoom></PTZData>
<!-- 聚焦:action=focusOut(speed=4) -->
<FocusData><focus>-60</focus></FocusData>
<!-- 光圈:action=irisIn(speed=4) -->
<IrisData><iris>60</iris></IrisData>
<!-- 预置点设置:presetId=3, presetName=A点 -->
<PTZPreset><id>3</id><presetName>A点</presetName></PTZPreset>
<!-- 自动巡航 -->
<autoPanData><autoPan>100</autoPan></autoPanData>   <!-- 开;关为 0 -->

方向符号:pan 正 = 右、tilt 正 = 上。若实机方向相反,改 utils/cameraPtz.js 顶部:

const SIGNS = { pan: 1, tilt: 1, zoom: 1, focus: 1, iris: 1 };

预置点调用按 SDK 行为不带请求体。


六、WMS 需要发的完整调用序列

// 1) 按下:向左转
POST /camera/ptzControl
{ "warehouse_id": 9, "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601",
  "action": "left", "speed": 4 }

// 2) 松手:停止(action 必须与上面一致)
POST /camera/ptzStop
{ "warehouse_id": 9, "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601",
  "action": "left" }

// 3) 转到预置点(一次即可,不用 stop)
POST /camera/ptzPresetGoto
{ "warehouse_id": 9, "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601",
  "presetId": 3 }

七、排查手册

现象 原因 / 处理
三个端点返回 404 打印服务版本过旧,未包含 /camera/ptzControl 等路由 → 部署新版本
云台完全不动,服务端返回 success 客户端 method 路由未命中。看客户端日志 [WSClient] 方法路由: camera.ptz.control MISSING → 客户端版本过旧,未包含 services/camera.js 的 ptz
客户端日志 ISAPI 认证失败 设备账号密码不对(来自 rtspUrl)或设备不是海康系
全部候选接口失败(最后 HTTP 400/404) 路径不匹配:NVR 的 IP 通道、非 80 端口(用 port)、或非海康设备
云台转向相反 调 utils/cameraPtz.js 的 SIGNS
云台一直转不停 WMS 没发 camera.ptz.stop(或 action 与开始不一致)
动了但控制错了通道 用 channel 显式指定通道号
服务端出现 服务路径 camera 不存在 客户端给这些方法加了返回值,触发了回显 → 去掉 return

八、已知限制(按当前口径接受)

  1. 无回执、无状态:设备写失败、超时,WMS 一律看不到,只能靠客户端本地日志排查。
  2. 无自动停止:WMS 侧异常 / 断网 / 忘了发 stop,云台会持续转动。
  3. 无幂等/防重:重复下发即重复执行;预置点类幂等,方向类会叠加。
  4. 可攻击面:/camera/ptzControl、/camera/ptzStop、/camera/ptzPresetGoto、/camera/setOSD、/sendToRoom、/record/force 均未挂鉴权中间件,端口可达即可调用(app/middleware/jwtAuth.js 已存在但未启用)。
  5. ISAPI 端口默认 80,非 80 设备需显式传 port。

九、变更记录

日期 内容
2026-09-15 云台链路定稿:WMS 下发 start/stop,服务端只中转,无回执;客户端新增 utils/cameraPtz.js + services/camera.js#ptz
2026-09-15 口径改为与 OSD 同风格的三个独立端点(/camera/ptzControl、/camera/ptzStop、/camera/ptzPresetGoto),不再走 /sendToRoom 信封、不再传 computerId;服务端抽出 _findRecordingClient / _pushToRecordingClient 公用方法(/camera/setOSD 同时改为复用,输出不变)