重点主题详解
返回 MQTT 主题清单。本页为 17 个重点主题的字段级详解（public yaml 的 Swagger 视图，逐主题一组 = 13 个静态 topic 契约 + 4 个谓词族通配形状契约）；全量主题形状（含 $SYS、动态下行与中心不消费的接入面）见清单页。
源码归纳 @ 2026-09-14（日期基线）。payload 字段级内容一律为「源码归纳 @ 2026-09-14，无 schema 真源」——后端无 DTO / OpenAPI schema 真源，演进后须以源码为准重新核对。
本页为生成物，不可手改，重摸底刷新（重跑生成器整体覆盖）。
iot-v1-retrieve
数据检索（retrieve） —— 请求主题 server/center-server/iot/v1/retrieve。按 params.items 检索（ice / firmware / dms / ptt / upload/*，未知项静默忽略），响应经 reply 主题回包（data 以检索项为键）；静态 topic 与 {identity}/{id}/iot/retrieve/v1 谓词族同名汇入。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-retrieve.yaml。
iot-v1-keep-alive-online-status
在线状态保活（keep-alive-online-status） —— 请求主题 server/center-server/iot/v1/keep-alive-online-status。客户端定时上报保活：服务端刷新在线状态与最后在线时间（双写 Redis），无业务回包（reply 留空）。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-keep-alive-online-status.yaml。
iot-v1-list-online-status
在线状态查询（list-online-status） —— 请求主题 server/center-server/iot/v1/list-online-status。按 params.mqttClientIdPrefixes 批量返回 mqttClientIdPrefix / onlineStatus / lastOnlineTime（三项键恒返回，源码归纳）。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-list-online-status.yaml。
iot-v1-report-category-info
分类信息上报（report-category-info） —— 请求主题 server/center-server/iot/v1/report-category-info。上报分类统计数据（键 = 信息类别，如 GPS_INFO / BATTERY_INFO）经 TelemetryReportFunction 入库；params 优先、data 兜底；无谓词族通配形状。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-report-category-info.yaml。
iot-v1-list-category-info
分类信息查询（list-category-info） —— 请求主题 server/center-server/iot/v1/list-category-info。按 params.mqttClientIdPrefixes + params.categories 返回各前缀的在线状态、最后在线时间与分类信息结果。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-list-category-info.yaml。
iot-v1-list-ice-server
ICE 服务器查询（list-ice-server） —— 请求主题 server/center-server/iot/v1/list-ice-server。按请求方设备编号返回 WebRTC 打洞用的 ICE 服务器配置（stun / turn），逐前缀附在线状态与最后在线时间。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-list-ice-server.yaml。
iot-v1-forward-janus-to
janus 信令转发（forward-janus-to） —— 请求主题 server/center-server/iot/v1/forward/janus/to。janus 请求原文透传（无 schema，载荷即 janus 协议原文）；回包 topic 由请求 transaction 前缀指定。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-forward-janus-to.yaml。
iot-v1-telemetry
遥测上报（telemetry） —— 请求主题 server/center-server/iot/v1/telemetry。iot 通道遥测上报主通道：按信息类别上报遥测数据（params 优先、data 兜底，sub 区分 status / data 入库模式），处理成功无业务回包；{identity}/{id}/iot/telemetry/v1 谓词族同名汇入，且常量串主题在直通白名单内可直接发布（iot 族差异）。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-telemetry.yaml。
iot-v1-forward-janus-admin-to
janus 管理转发（forward-janus-admin-to） —— 请求主题 server/center-server/iot/v1/forward/janus/admin/to。janus 管理请求转发（iot 通道）：载荷为 janus 管理报文，管理凭据由服务端侧处理（调用方无需携带）；回包 topic 由请求 transaction 字段解析（直连形 ≥3 段，旧设备形 device,{deviceNo} 回包落点 device/{deviceNo}/webrtc/janus-from）。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-forward-janus-admin-to.yaml。
webrtc-v1-forward-janus-to
janus 信令转发（webrtc 通道 forward-janus-to） —— 请求主题 server/center-server/webrtc/v1/forward/janus/to。janus 请求原文转发（webrtc 通道）：路由标识取设备号（解析目标 Janus 节点）；transaction 文法与 iot 通道一致（直连形 / 旧设备形 / 其他形状丢弃不转发）。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-webrtc-forward-janus-to.yaml。
webrtc-v1-forward-janus-admin-to
janus 管理转发（webrtc 通道 forward-janus-admin-to） —— 请求主题 server/center-server/webrtc/v1/forward/janus/admin/to。janus 管理请求转发（webrtc 通道）：管理凭据由服务端侧处理（调用方无需携带）；transaction 文法与 iot 通道一致。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-webrtc-forward-janus-admin-to.yaml。
ptt-v1-forward-janus-to
janus 信令转发（ptt 通道 forward-janus-to） —— 请求主题 server/center-server/ptt/v1/forward/janus/to。janus 请求原文转发（ptt 通道）：路由标识取对讲组 ID（解析该对讲组活跃音频房间所在的 Janus 节点；无活跃房间时请求被丢弃不转发）。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-ptt-forward-janus-to.yaml。
ptt-v1-forward-janus-admin-to
janus 管理转发（ptt 通道 forward-janus-admin-to） —— 请求主题 server/center-server/ptt/v1/forward/janus/admin/to。janus 管理请求转发（ptt 通道）：管理凭据由服务端侧处理（调用方无需携带）；路由标识取对讲组 ID，房间销毁类动作按该对讲组最近一次房间记录解析。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-ptt-forward-janus-admin-to.yaml。
webrtc-v1-telemetry
遥测上报（webrtc 通道 telemetry） —— 谓词族形状 {identity}/{id}/webrtc/telemetry/v1。谓词族形状 {identity}/{id}/webrtc/telemetry/v1（identity ∈ device / server / user）：常量串主题不在直通白名单内、直接发布会被网关丢弃，请使用该通配形状；载荷规则与 iot telemetry 一致（params 优先、data 兜底，sub 区分入库模式），处理成功无业务回包。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-webrtc-telemetry.yaml。
webrtc-v1-retrieve
数据检索（webrtc 通道 retrieve） —— 谓词族形状 {identity}/{id}/webrtc/retrieve/v1。谓词族形状 {identity}/{id}/webrtc/retrieve/v1（identity ∈ device / server / user）：常量串主题不可直发（会被网关丢弃），请使用该通配形状；检索词汇表与 iot retrieve 一致（ice / firmware / dms / ptt / upload/*，未知项静默忽略），响应经 reply 主题回包。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-webrtc-retrieve.yaml。
ptt-v1-telemetry
遥测上报（ptt 通道 telemetry） —— 谓词族形状 {identity}/{id}/ptt/telemetry/v1。谓词族形状 {identity}/{id}/ptt/telemetry/v1（identity ∈ device / server / user）：常量串主题不可直发（会被网关丢弃），请使用该通配形状；载荷规则与 iot telemetry 一致，用于上报 ptt 通道遥测（如设备 PTT 程序版本），处理成功无业务回包。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-ptt-telemetry.yaml。
ptt-v1-retrieve
数据检索（ptt 通道 retrieve） —— 谓词族形状 {identity}/{id}/ptt/retrieve/v1。谓词族形状 {identity}/{id}/ptt/retrieve/v1（identity ∈ device / server / user）：常量串主题不可直发（会被网关丢弃），请使用该通配形状；检索词汇表与 iot retrieve 一致，ptt 检索项返回默认对讲组与对讲组列表，响应经 reply 主题回包。
字段级契约 = 源码归纳 @ 2026-09-14（无 schema 真源）；下方 Swagger 视图渲染自
v1-ptt-retrieve.yaml。