- 新增 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 映射、排查手册)
12 KiB
云台(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 平级 |
⚠️ 两条硬约束
-
这些方法一律不能有返回值。
core/wsClient.js只要拿到非undefined的返回值,就会回发{success:true, method, result}给服务端;而服务端app/controller/print.js会把这条回显当成一次服务调用去路由,services.printer里没有camera.*服务 → 刷一堆服务路径 camera 不存在的错误。 客户端日志里若出现该报错,说明有人给这些方法加了return。 -
持续型动作必须由 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 |
八、已知限制(按当前口径接受)
- 无回执、无状态:设备写失败、超时,WMS 一律看不到,只能靠客户端本地日志排查。
- 无自动停止:WMS 侧异常 / 断网 / 忘了发 stop,云台会持续转动。
- 无幂等/防重:重复下发即重复执行;预置点类幂等,方向类会叠加。
- 可攻击面:
/camera/ptzControl、/camera/ptzStop、/camera/ptzPresetGoto、/camera/setOSD、/sendToRoom、/record/force均未挂鉴权中间件,端口可达即可调用(app/middleware/jwtAuth.js已存在但未启用)。 - 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 同时改为复用,输出不变) |