diff --git a/云台对接说明.md b/云台对接说明.md new file mode 100644 index 0000000..1af7593 --- /dev/null +++ b/云台对接说明.md @@ -0,0 +1,251 @@ +# 云台(PTZ)通讯对接说明 + +> 适用版本:`services.printer`(服务端中转)+ `printServer`(打印/录制电脑客户端) +> 最后更新:2026-09-15 +> 定位:**service.printer 只是中转**,外部(WMS)传入什么就原样推给客户端,不校验执行结果、不做回执、不记状态。 + +--- + +## 一、整体链路 + +``` +WMS 主服务 + │ ①HTTP POST /sendToRoom { warehouse, computerId, method, data } + ▼ +services.printer :4052 ← 本仓库,仅做中转,零改动 + │ ②查 Redis 路由表 warehouse:{warehouse}:printer:{computerId} + │ ③WS sendTo(uniqueId, { method, data }) 原样透传 + ▼ +printServer(仓库录制电脑) + │ ④按 method 点分路由 → services/camera.ptz.* + ▼ +摄像头 / NVR(仓库内网,ISAPI) +``` + +**关键语义**:HTTP 返回 `status: success` 只代表「消息已写进 WS 房间」,**不代表云台动了**。执行结果只落客户端本地日志,不回传。 + +--- + +## 二、WMS → services.printer(HTTP) + +复用已有端点(`app/router.js` → `app/controller/home.js#sendToRoom`),**无需新增路由**: + +``` +POST http://{services.printer 地址}:4052/sendToRoom +Content-Type: application/json +``` + +```jsonc +{ + "warehouse": 9, // 必填,仓库 ID + "computerId": 12, // 必填,打印电脑 ID(须为录制电脑) + "method": "camera.ptz.control", // 必填,见第三节 + "data": { // 必填,且必须是非空对象 + "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601", + "action": "left", + "speed": 4 + } +} +``` + +### 返回 + +| 返回 | 含义 | +|---|---| +| `{ status:'success', message:'消息发送成功', result: 1 }` | 已推送到该电脑的 WS 房间(`result` = 命中房间数) | +| `{ status:'fail', message:'缺少必要参数: warehouse, computerId, method, 或 data' }` | 入参不全 | +| `{ status:'fail', message:'未找到打印机信息,无法发送消息' }` | 该电脑不在线(Redis 无记录,TTL 300s) | +| `{ status:'fail', message:'打印电脑不在线,消息发送失败...' }` | `sendTo` 未命中房间 | + +> 目标电脑怎么定:`wms_print_computer` 里 `warehouse_id = warehouse AND is_recording = 1` 的那台。WMS 侧本来就能查这张表,直接带上 `computerId` 即可。 + +--- + +## 三、services.printer → 客户端(WS 下发契约) + +服务端把 `method` / `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`。 + +### 通道号来源 + +客户端从 `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`)。 + +### 日志 + +| 日志 | 位置 | +|---|---| +| 云台 | `%ProgramData%\printServer\cameraPtz.log`(同时输出到控制台,前缀 `[CameraPTZ]`) | +| OSD | `%ProgramData%\printServer\cameraOsd.log` | + +--- + +## 五、动作 ↔ 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**。 + +```xml + +-600 + +00 + +30 + +-60 + +60 + +3A点 + +100 +``` + +**方向符号**:`pan` 正 = 右、`tilt` 正 = 上。若实机方向相反,改 `utils/cameraPtz.js` 顶部: + +```js +const SIGNS = { pan: 1, tilt: 1, zoom: 1, focus: 1, iris: 1 }; +``` + +> 预置点调用按 SDK 行为**不带请求体**。 + +--- + +## 六、WMS 需要发的完整调用序列 + +```jsonc +// 1) 按下:向左转 +POST /sendToRoom +{ "warehouse": 9, "computerId": 12, "method": "camera.ptz.control", + "data": { "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601", + "action": "left", "speed": 4 } } + +// 2) 松手:停止(action 必须与上面一致) +POST /sendToRoom +{ "warehouse": 9, "computerId": 12, "method": "camera.ptz.stop", + "data": { "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601", + "action": "left" } } + +// 3) 转到预置点(一次即可,不用 stop) +POST /sendToRoom +{ "warehouse": 9, "computerId": 12, "method": "camera.ptz.presetGoto", + "data": { "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601", + "presetId": 3 } } +``` + +--- + +## 七、排查手册 + +| 现象 | 原因 / 处理 | +|---|---| +| 云台完全不动,服务端返回 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. **可攻击面**:`POST /sendToRoom`、`/camera/setOSD`、`/record/force` 均**未挂鉴权中间件**,端口可达即可调用(`app/middleware/jwtAuth.js` 已存在但未启用)。 +5. ISAPI 端口默认 80,非 80 设备需显式传 `port`。 + +--- + +## 九、变更记录 + +| 日期 | 内容 | +|---|---| +| 2026-09-15 | 云台链路定稿:WMS 下发 start/stop,服务端只中转,无回执;客户端新增 `utils/cameraPtz.js` + `services/camera.js#ptz` |