diff --git a/app/controller/hikvision.js b/app/controller/hikvision.js index d889d42..2ba9267 100644 --- a/app/controller/hikvision.js +++ b/app/controller/hikvision.js @@ -26,13 +26,54 @@ class HikvisionController extends Controller { } } + /** + * 找仓库内在线的录制电脑(is_recording === 1) + * @param {string|number} warehouseId 仓库 ID + * @returns {Promise} Redis 中的 print_computer_info(含 uniqueId / computerId) + */ + async _findRecordingClient(warehouseId) { + const { app } = this; + const warehousePattern = `warehouse:${warehouseId}:printer:*`; + let cursor = '0'; + do { + const [nextCursor, keys] = await app.redis.scan(cursor, 'MATCH', warehousePattern, 'COUNT', 100); + cursor = nextCursor; + for (const key of keys) { + const raw = await app.redis.get(key); + if (!raw) continue; + const info = JSON.parse(raw); + if (info.is_recording === 1) return info; + } + } while (cursor !== '0'); + return null; + } + + /** + * 按仓库选录制电脑并下发 WS 指令(method / data 原样透传给客户端) + * 客户端不在线或发送失败时返回 status:'fail' + * @returns {Promise<{status:string, message:string, result?:object}>} + */ + async _pushToRecordingClient(warehouseId, method, data) { + const { app } = this; + const client = await this._findRecordingClient(warehouseId); + if (!client || !client.uniqueId) { + return { status: 'fail', message: `仓库 ${warehouseId} 中没有在线的录制电脑` }; + } + console.log(`[hikvision] 下发 ${method} → 房间 ${client.uniqueId}(电脑 ${client.computerId})`); + const res = await app.ws.sendTo(client.uniqueId, JSON.stringify({ method, data })); + if (res !== 1) { + return { status: 'fail', message: '录制电脑不在线,消息发送失败' }; + } + return { status: 'success', result: { computer_id: client.computerId, method } }; + } + /** * POST /camera/setOSD * 主程序调用,下发 OSD 叠加信息到仓库中开启录制服务的客户端 * 入参: warehouse_id, rtspUrl, text, x?, y? */ async setCameraOSD() { - const { ctx, app } = this; + const { ctx } = this; const { warehouse_id, rtspUrl, text } = ctx.request.body; const x = ctx.request.body.x !== undefined ? ctx.request.body.x : -0.9; const y = ctx.request.body.y !== undefined ? ctx.request.body.y : 0.8; @@ -51,58 +92,21 @@ class HikvisionController extends Controller { } try { - // 1. 扫描仓库下所有在线电脑,找到录制中的那台 - const warehousePattern = `warehouse:${warehouse_id}:printer:*`; - let recordingClient = null; - let cursor = '0'; - - do { - const [nextCursor, keys] = await app.redis.scan(cursor, 'MATCH', warehousePattern, 'COUNT', 100); - cursor = nextCursor; - for (const key of keys) { - const raw = await app.redis.get(key); - if (!raw) continue; - const info = JSON.parse(raw); - if (info.is_recording === 1) { - recordingClient = info; - break; - } - } - if (recordingClient) break; - } while (cursor !== '0'); - - if (!recordingClient || !recordingClient.uniqueId) { - ctx.body = { - status: 'fail', - message: `仓库 ${warehouse_id} 中没有在线的录制电脑`, - }; + console.log(`[setCameraOSD] 下发 OSD, rtspUrl=${rtspUrl}, text=${text}`); + const pushed = await this._pushToRecordingClient(warehouse_id, 'setting.setCameraOSD', { + rtspUrl, text, x, y, + }); + if (pushed.status !== 'success') { + ctx.body = { status: 'fail', message: pushed.message }; return; } - - const roomId = recordingClient.uniqueId; - console.log(`[setCameraOSD] 发送 OSD 到房间 ${roomId}, rtspUrl=${rtspUrl}, text=${text}`); - - // 2. 下发 setting.setCameraOSD 消息 - const res = await app.ws.sendTo(roomId, JSON.stringify({ - method: 'setting.setCameraOSD', - data: { rtspUrl, text, x, y }, - })); - - if (res !== 1) { - ctx.body = { - status: 'fail', - message: '录制电脑不在线,消息发送失败', - }; - return; - } - console.log('[setCameraOSD] 消息发送成功'); ctx.body = { status: 'success', message: 'OSD 设置指令已下发', result: { warehouse_id, - computer_id: recordingClient.computerId, + computer_id: pushed.result.computer_id, rtspUrl, text, x, @@ -114,6 +118,97 @@ class HikvisionController extends Controller { ctx.body = { status: 'fail', message: error.message }; } } + + /** + * POST /camera/ptzControl + * 主程序调用,下发云台开始运动(方向 / 变倍 / 聚焦 / 光圈) + * 入参: warehouse_id, rtspUrl, action, speed?, channel?, port? + * ⚠️ 方向/变倍/聚焦/光圈是持续型动作,调用方必须另行下发 /camera/ptzStop,否则云台会一直转 + * ⚠️ 下发到客户端的 method 是 camera.ptz.control(与内部 API 名 camera.ptzControl 不同名) + */ + async ptzControl() { + const { ctx } = this; + const { warehouse_id, rtspUrl, action, speed, channel, port } = ctx.request.body; + + const missing = [ 'warehouse_id', 'rtspUrl', 'action' ] + .find(field => ctx.request.body[field] === undefined || ctx.request.body[field] === null || ctx.request.body[field] === ''); + if (missing) { + ctx.body = { status: 'fail', message: `缺少必要参数: ${missing}` }; + return; + } + + try { + const pushed = await this._pushToRecordingClient(warehouse_id, 'camera.ptz.control', { + rtspUrl, action, speed, channel, port, + }); + ctx.body = pushed.status === 'success' + ? { status: 'success', message: '云台指令已下发', result: pushed.result } + : pushed; + } catch (error) { + console.error('[ptzControl] 错误:', error); + ctx.body = { status: 'fail', message: error.message }; + } + } + + /** + * POST /camera/ptzStop + * 主程序调用,停止云台持续运动 + * 入参: warehouse_id, rtspUrl, action(必须与开始时的 action 一致), channel?, port? + * 下发到客户端的 method: camera.ptz.stop + */ + async ptzStop() { + const { ctx } = this; + const { warehouse_id, rtspUrl, action, channel, port } = ctx.request.body; + + const missing = [ 'warehouse_id', 'rtspUrl', 'action' ] + .find(field => ctx.request.body[field] === undefined || ctx.request.body[field] === null || ctx.request.body[field] === ''); + if (missing) { + ctx.body = { status: 'fail', message: `缺少必要参数: ${missing}` }; + return; + } + + try { + const pushed = await this._pushToRecordingClient(warehouse_id, 'camera.ptz.stop', { + rtspUrl, action, channel, port, + }); + ctx.body = pushed.status === 'success' + ? { status: 'success', message: '云台停止指令已下发', result: pushed.result } + : pushed; + } catch (error) { + console.error('[ptzStop] 错误:', error); + ctx.body = { status: 'fail', message: error.message }; + } + } + + /** + * POST /camera/ptzPresetGoto + * 主程序调用,云台转到指定预置点(一次性动作,无需再发 stop) + * 入参: warehouse_id, rtspUrl, presetId, channel?, port? + * 下发到客户端的 method: camera.ptz.presetGoto + */ + async ptzPresetGoto() { + const { ctx } = this; + const { warehouse_id, rtspUrl, presetId, channel, port } = ctx.request.body; + + const missing = [ 'warehouse_id', 'rtspUrl', 'presetId' ] + .find(field => ctx.request.body[field] === undefined || ctx.request.body[field] === null || ctx.request.body[field] === ''); + if (missing) { + ctx.body = { status: 'fail', message: `缺少必要参数: ${missing}` }; + return; + } + + try { + const pushed = await this._pushToRecordingClient(warehouse_id, 'camera.ptz.presetGoto', { + rtspUrl, presetId, channel, port, + }); + ctx.body = pushed.status === 'success' + ? { status: 'success', message: '预置点调用指令已下发', result: pushed.result } + : pushed; + } catch (error) { + console.error('[ptzPresetGoto] 错误:', error); + ctx.body = { status: 'fail', message: error.message }; + } + } } module.exports = HikvisionController; diff --git a/app/router.js b/app/router.js index bb10032..19d4c71 100644 --- a/app/router.js +++ b/app/router.js @@ -11,6 +11,9 @@ module.exports = app => { router.post('/hikvision/forceRecord', controller.hikvision.forceRecord); router.post('/record/force', controller.hikvision.forceRecord); router.post('/camera/setOSD', controller.hikvision.setCameraOSD); + router.post('/camera/ptzControl', controller.hikvision.ptzControl); + router.post('/camera/ptzStop', controller.hikvision.ptzStop); + router.post('/camera/ptzPresetGoto', controller.hikvision.ptzPresetGoto); router.post('/sendToRoom', controller.home.sendToRoom); app.ws.route('/ws', controller.print.ws); }; \ No newline at end of file diff --git a/云台对接说明.md b/云台对接说明.md index 1af7593..24f6442 100644 --- a/云台对接说明.md +++ b/云台对接说明.md @@ -2,7 +2,7 @@ > 适用版本:`services.printer`(服务端中转)+ `printServer`(打印/录制电脑客户端) > 最后更新:2026-09-15 -> 定位:**service.printer 只是中转**,外部(WMS)传入什么就原样推给客户端,不校验执行结果、不做回执、不记状态。 +> 定位:**services.printer 只是中转**(method 换名 + data 透传),不校验执行结果、不做回执、不记状态。 --- @@ -10,11 +10,12 @@ ``` WMS 主服务 - │ ①HTTP POST /sendToRoom { warehouse, computerId, method, data } + │ ①HTTP POST /camera/ptzControl | /camera/ptzStop | /camera/ptzPresetGoto + │ body: { warehouse_id, rtspUrl, action, speed? } / + presetId ▼ -services.printer :4052 ← 本仓库,仅做中转,零改动 - │ ②查 Redis 路由表 warehouse:{warehouse}:printer:{computerId} - │ ③WS sendTo(uniqueId, { method, data }) 原样透传 +services.printer :4052 ← 本仓库,仅做中转 + │ ②SCAN warehouse:{warehouse_id}:printer:* → 取 is_recording === 1 的那台 + │ ③WS sendTo(uniqueId, { method, data }) method 换名,data 透传 ▼ printServer(仓库录制电脑) │ ④按 method 点分路由 → services/camera.ptz.* @@ -22,29 +23,33 @@ printServer(仓库录制电脑) 摄像头 / NVR(仓库内网,ISAPI) ``` +**入参风格与 OSD 完全一致**:`warehouse_id` + `rtspUrl` + 业务参数,**不需要 computerId**(由打印服务自己按仓库挑录制电脑)。 + **关键语义**:HTTP 返回 `status: success` 只代表「消息已写进 WS 房间」,**不代表云台动了**。执行结果只落客户端本地日志,不回传。 --- -## 二、WMS → services.printer(HTTP) +## 二、WMS → services.printer(HTTP,与 OSD 同风格) -复用已有端点(`app/router.js` → `app/controller/home.js#sendToRoom`),**无需新增路由**: +三个独立端点,入参口径与 `/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/sendToRoom +POST http://{services.printer 地址}:4052/camera/ptzControl 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 - } + "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 } ``` @@ -52,18 +57,18 @@ Content-Type: application/json | 返回 | 含义 | |---|---| -| `{ status:'success', message:'消息发送成功', result: 1 }` | 已推送到该电脑的 WS 房间(`result` = 命中房间数) | -| `{ status:'fail', message:'缺少必要参数: warehouse, computerId, method, 或 data' }` | 入参不全 | -| `{ status:'fail', message:'未找到打印机信息,无法发送消息' }` | 该电脑不在线(Redis 无记录,TTL 300s) | -| `{ status:'fail', message:'打印电脑不在线,消息发送失败...' }` | `sendTo` 未命中房间 | +| `{ status:'success', message:'云台指令已下发', result:{ computer_id, method } }` | 已推送到该电脑的 WS 房间 | +| `{ status:'fail', message:'缺少必要参数: warehouse_id' }` | 入参不全(字段名会原样回显) | +| `{ status:'fail', message:'仓库 9 中没有在线的录制电脑' }` | 该仓库没有 `is_recording = 1` 的在线电脑 | +| `{ status:'fail', message:'录制电脑不在线,消息发送失败' }` | `sendTo` 未命中房间(连接刚断) | -> 目标电脑怎么定:`wms_print_computer` 里 `warehouse_id = warehouse AND is_recording = 1` 的那台。WMS 侧本来就能查这张表,直接带上 `computerId` 即可。 +> 目标电脑怎么定:`SCAN warehouse:{warehouse_id}:printer:*` → 取 `is_recording === 1` 的那台。与 `/camera/setOSD` **同一个公用方法**(`app/controller/hikvision.js#_pushToRecordingClient`),所以两边行为天然一致。 --- ## 三、services.printer → 客户端(WS 下发契约) -服务端把 `method` / `data` **原样** 透传,所以下表就是客户端必须实现的入口。 +服务端会把 **method 换名**再下发(HTTP 侧 `camera.ptzControl` → WS 侧 `camera.ptz.control`),`data` 原样透传。下表就是客户端必须实现的入口。 | method | 用途 | 是否持续型 | |---|---|---| @@ -107,6 +112,8 @@ Content-Type: application/json > 索引 9(自动巡航)不在 `control` 里支持,请用 `camera.ptz.auto`。 +> HTTP 侧目前只暴露前 3 个方法(`control` / `stop` / `presetGoto`)。`presetSet` / `auto` **客户端已实现**,但打印服务侧暂无 HTTP 入口 —— 需要时按同一模式加一个端点即可。 + ### 通道号来源 客户端从 `rtspUrl` 路径解析,规则: @@ -145,8 +152,11 @@ Content-Type: application/json | 日志 | 位置 | |---|---| -| 云台 | `%ProgramData%\printServer\cameraPtz.log`(同时输出到控制台,前缀 `[CameraPTZ]`) | -| OSD | `%ProgramData%\printServer\cameraOsd.log` | +| 云台 | `{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/...`。 --- @@ -200,22 +210,19 @@ const SIGNS = { pan: 1, tilt: 1, zoom: 1, focus: 1, iris: 1 }; ```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 } } +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 /sendToRoom -{ "warehouse": 9, "computerId": 12, "method": "camera.ptz.stop", - "data": { "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601", - "action": "left" } } +POST /camera/ptzStop +{ "warehouse_id": 9, "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 } } +POST /camera/ptzPresetGoto +{ "warehouse_id": 9, "rtspUrl": "rtsp://admin:xxx@192.168.9.200:554/Streaming/Channels/601", + "presetId": 3 } ``` --- @@ -224,6 +231,7 @@ POST /sendToRoom | 现象 | 原因 / 处理 | |---|---| +| 三个端点返回 **404** | 打印服务版本过旧,未包含 `/camera/ptzControl` 等路由 → 部署新版本 | | 云台完全不动,服务端返回 success | 客户端 method 路由未命中。看客户端日志 `[WSClient] 方法路由: camera.ptz.control MISSING` → 客户端版本过旧,未包含 `services/camera.js` 的 `ptz` | | 客户端日志 `ISAPI 认证失败` | 设备账号密码不对(来自 `rtspUrl`)或设备不是海康系 | | `全部候选接口失败(最后 HTTP 400/404)` | 路径不匹配:NVR 的 IP 通道、非 80 端口(用 `port`)、或非海康设备 | @@ -239,7 +247,7 @@ POST /sendToRoom 1. **无回执、无状态**:设备写失败、超时,WMS 一律看不到,只能靠客户端本地日志排查。 2. **无自动停止**:WMS 侧异常 / 断网 / 忘了发 stop,云台会持续转动。 3. **无幂等/防重**:重复下发即重复执行;预置点类幂等,方向类会叠加。 -4. **可攻击面**:`POST /sendToRoom`、`/camera/setOSD`、`/record/force` 均**未挂鉴权中间件**,端口可达即可调用(`app/middleware/jwtAuth.js` 已存在但未启用)。 +4. **可攻击面**:`/camera/ptzControl`、`/camera/ptzStop`、`/camera/ptzPresetGoto`、`/camera/setOSD`、`/sendToRoom`、`/record/force` 均**未挂鉴权中间件**,端口可达即可调用(`app/middleware/jwtAuth.js` 已存在但未启用)。 5. ISAPI 端口默认 80,非 80 设备需显式传 `port`。 --- @@ -249,3 +257,4 @@ POST /sendToRoom | 日期 | 内容 | |---|---| | 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` 同时改为复用,输出不变) |