ES Documentation
手册
API
手册
API
简体中文

设备（业务）

设备模块讲两件事：采集设备与采集服务器的服务间支撑面（按编号查档、换取认证令牌密钥、内网 IP 自报同步），以及它背后真正的设备域重心——MQTT 设备消息链（上行遥测/检索、下行送达、janus 转发）。本模块 7 个 REST 端点全部是面向采集服务器 / 采集设备的服务间调用（普遍要求 token 查询参数，见接口规范）；Web/App 侧的设备资产 CRUD 不在这里，在 data-service 的设备（业务）。

本页是 device-service device 模块接口的业务说明，非业务说明不在本页复述：

  • OpenAPI JSON（可直接导入 Postman 等工具）：https://zxs.netbodycamera.com/device-service/v3/api-docs/device
  • 在线 Swagger 视图：device-service · 设备
  • 端点全量清单（含中文说明）：清单层 · device

参数、请求/响应字段、错误码等契约事实一律见上述 Swagger 与清单层；本页只讲业务语义与动线。

data-acquisition-device 采集设备

采集设备（执法记录仪等）在 device-service 侧的主档读取与信息推送面，4 个端点按「编号」而非 ID 寻址——服务间调用方（采集服务器）只持有设备编号。

identity-and-token 身份与令牌密钥

  • getByDataAcquisitionDeviceNo：按采集设备编号查询设备信息——采集侧装配本地视图时的主档读取。
  • getGenerationTokenKeyByDataAcquisitionDeviceNo：按编号生成认证令牌密钥。与 token 查询参数的服务间鉴权配套：密钥由服务端缓存供给（时效天级，见运行时关联），是「设备侧向中心 REST 面」的信任凭据供给侧。
  • pushInfoByDataAcquisitionDeviceNo：按编号推送采集设备信息——设备侧重回中心侧的档案回流端点（设备实际信息以推送时点为准）。

binding-lifecycle 绑定生命周期读取

  • listByDataAcquisitionServerNo：按采集服务器编号查询其关联采集设备的绑定生命周期列表——采集服务器启动/同步时拉取「我名下有哪些设备、绑定处于什么周期」的服务侧视角读取。管理侧的绑定维护（关联表 CRUD）在 data-service（见采集服务器与采集设备关联），本端点只读。

场景页对本资源族无直接引用；设备消息行为的场景正本见下节。契约见清单层 · data-acquisition-device。

data-acquisition-server 采集服务器

采集服务器自身在 device-service 侧的支撑面：listByDataAcquisitionServerNo（按编号查信息列表）、getGenerationTokenKeyByDataAcquisitionServerNo（认证令牌密钥，与设备侧同款信任链，服务端缓存时效天级）。

internal-ip-and-dms-sync 内网 IP 自报与 DMS 推送

updateInternalIpByDataAcquisitionServerNo 是本模块唯一的写端点：采集服务器向中心自报内网 IP。内网 IP 更新后中心会触发采集服务器信息同步链——中心按该服务器遍历关联采集设备、比对在线状态，并按需向设备推送 DMS 载荷（下行 topic device/{deviceNo}/iot/deliver/v1，全表见MQTT 消费者与主题清单 · 动态下行）。

采集服务器的管理侧（导入/缓存/CRUD）在 data-service；场景领域页：设备与资产域 · data-acquisition-server（含异步导入、缓存读取两个子流程小节）。契约见清单层 · data-acquisition-server。

mqtt-bridge 设备消息链（MQTT 面）

设备域的实时行为不在本模块 REST，走 MQTT。device-service 是中心侧唯一的 MQTT 网关与消费方（MQTT v5 订阅、QoS 全局 2），设备消息的业务动线分四条：

Web 侧发布约定：Web 直发的下行报文（data/{id}/v1/*、configs/webrtc/janus 信令族）统一 QoS 1、retain false——与中心侧网关的 QoS 2 语义不同（中心物理出口默认 QoS 2），两侧 QoS 勿混用。

  • 上行遥测与检索（iot 谓词族）：设备/采集服务器/用户以 {identity}/{id}/iot/telemetry/v1、{identity}/{id}/iot/retrieve/v1 发布（谓词族命中后与静态主题同名汇入）；遥测由中心消费入库（历史检索面的供给侧），检索按 params.items 词汇表检索（ice / firmware / dms / ptt / upload/*，未知项静默忽略）、应答经 reply 回包（data 以检索项为键）。Web 侧的固件/文件上报触发（items:["firmware"] / ["upload/<category>"]）走同一 retrieve 通道，应答发往设备 deliver topic、Web 不可见：场景正本触发设备固件与文件上报（retrieve），yaml 详解retrieve。
  • 下行送达：device/{deviceNo}/iot/deliver/v1 是设备侧应答/推送的落点——retrieve 应答（固件包信息、上传目标 URL/ts/混淆码）与采集服务器 IP 同步后的 DMS 载荷都从这里下行。零售侧据此确认设备固件无需硬编码上传路径（见兼容候选）。
  • ptt / webrtc 通道：对讲与视频通话各有同构的 telemetry/retrieve 谓词族与 janus 信令转发（server/center-server/{iot,webrtc,ptt}/v1/forward/janus/to 直通 topic，原文透传到对应 Janus 服务器、回包按 transaction 路由，janus 回包按会话路由——服务端分钟级缓存；字段级见MQTT 详解）。ICE 服务器分配走 server/center-server/iot/v1/list-ice-server（请求响应）与设备侧 deliver（场景正本下发 ICE 服务器到设备——该命令中心网关不消费）。
  • 在线状态：keep-alive-online-status 保活（刷新服务端在线缓存）与 list-online-status 批量查询；每次 iot 族命令的 id 解析也会顺带刷新在线状态（触发固件查询即刷新在线是已核验副作用）。每日凌晨另有在线状态对账兜底（见运行时关联）。

设备直连命令（device/{deviceNo}/iot/configs/v1 上 sub:"get"/"set"/"bcplus"）中心网关不消费（不在订阅清单与路由表），不在 MQTT 主题清单内；webrtc 设备直连族同口径：device/{deviceNo}/webrtc/v1 上的直播探测（ping/media）、P2P 信令（call/sdp/candidate/bye）、SFU 起播控制（play/idr）与 ICE 下发 device/{deviceNo}/webrtc/deliver/v1（无应答单向、Web 按内容去重）都不经中心消费（场景正本在实时监看与设备遥控章节）；直播域 janus 转发复用 iot 通道的 server/center-server/iot/v1/forward/janus/*，但 transaction 第 2 段为 deviceNo（对讲域为 talkGroupId），中心以该段解析目标 Janus 节点。场景正本在设备遥控章节：读取设备配置、修改设备配置、发送设备 BC+ 原始指令。

topic 维度全量（18 静态 + 7 谓词族 + 2 $SYS + 5 动态下行）见MQTT 主题清单，重点 yaml 详解见MQTT 详解；消费者业务语义（IotV1 信封解包、Janus 转发、谓词族汇入）逐类见MQTT 消费者。

runtime-links 运行时关联

本模块相关的定时任务 / 消费者 / 缓存（全量表见 device-service 消费者与 data-service 定时任务、缓存的 device-service 节，此处只点名不复述）：

  • 在线/状态/会话路由等有服务端缓存（时效分钟~天级：在线状态与客户端映射、设备状态、janus 会话路由等；认证令牌密钥见上文各端点）。
  • 定时任务两类：每日凌晨对账在线状态（保活动线之外的兜底口径）；遥测数据异步入历史索引（上行遥测的索引落地侧）。
  • 消费链两条业务动词级口径：内网 IP 同步 → DMS 载荷下行（见 data-acquisition-server）；设备变更 → 向相关用户 App 推送设备列表刷新（topic user/{username}/app/ponycam/message）。设备消息消费面全量（含监听器）见MQTT 消费者。
目录