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

QoS 与在线状态

验证状态：本页为接入视角新写（20 号票）。事实取材自 MQTT 清单层生成页与机构手册已核验场景正本，本页自身不做二次核验、未联调；QoS 数值一律链到清单层与业务页，不在本页内联。

用途与场景

设备「被判定在线」的机制与消息可靠性的全局约定。这是接入动线的第五步——上行 / 下行 / 媒体面就绪后，保活与在线口径决定设备在平台里的可见性；QoS 约定决定两侧（中心网关 vs Web 直发）的投递语义差异。

全局 QoS 约定

  • 中心网关侧：MQTT → JMS 路由有全局 QoS 约定（入站 / 出站统一、无 per-topic 差异）——口径见MQTT 主题清单页首路由说明（源码归纳），业务面叙事见设备业务 · mqtt-bridge。
  • Web 直发侧：Web 直发的下行报文（data/{id}/v1/*、configs / webrtc / janus 信令族）另有不同的发布约定（QoS / retain）——见设备业务 · mqtt-bridge的 Web 侧发布约定；ptt join/kick 的约定同样只在基础数据业务 · ptt-deliver-payload小节（两侧勿混用，数值以链接目标为准）。
  • 公共边界：QoS 不能推出业务必达、设备已执行或可安全重试——见机构手册MQTT 连接与消息边界。

保活（keep-alive-online-status）

静态 topic server/center-server/iot/v1/keep-alive-online-status（上行 · 保活）：客户端定时上报，服务端刷新在线状态与最后在线时间（双写 Redis 缓存），无业务回包（reply 留空）——契约行见静态 topic 表，字段级见 yaml 详解 · keep-alive-online-status。保活间隔的推荐值无文档约定（见已知缺口）。

在线查询（设备如何被查询）

  • server/center-server/iot/v1/list-online-status：按客户端 ID 前缀批量返回在线状态与最后在线时间——字段级见 yaml 详解 · list-online-status。
  • server/center-server/iot/v1/list-category-info：按前缀 + 类别返回在线状态与分类信息——字段级见 yaml 详解 · list-category-info。
  • 设备的查询键是客户端 ID 前缀：device,{deviceNo},iot 与 device,{deviceNo},webrtc（两式身份见设备身份与凭据；机构正本的请求示例即按此拼前缀）。

在线判定的全部口径

  1. 保活刷新：见上节。
  2. 命令驱动刷新（已核验副作用）：每次 iot 族命令的 id 解析都会顺带刷新在线状态与最后在线时间——Web 触发固件查询即刷新该设备在线——见机构手册触发设备固件与文件上报（retrieve）的动线表与MQTT 消费者。
  3. broker 事件：EMQX 系统事件（客户端连接 / 断开、订阅 / 退订）经 $SYS topic 被 broker 层监听（$SYS/brokers/+/clients/+/connected|disconnected 等）——契约行见MQTT 主题清单 · $SYS broker 系统事件。
  4. 每日对账兜底：每日 02:00 中心以 EMQX REST API 拉取在线客户端对账 Redis 缓存（DeviceOnlineStatusSyncScheduling）——见设备业务 · 运行时关联。

在线状态的读侧缓存（mqttClientIdCache，30 天）与消费链见设备业务 · 运行时关联。

设备侧要点

  • 两式客户端 ID（iot / webrtc）分别刷新各自的在线前缀——直播可用性判定走 webrtc 前缀（机构正本以 webrtcOnlineStatus 驱动 ICE 下发，见下发 ICE 服务器到设备）。
  • 断线重连后的重订阅与重新保活时序无平台约定（Web 侧为客户端库自动重连 + 会话无恢复语义，设备侧需自行设计，见MQTT 连接与用户会话订阅的 Web 侧口径与已知缺口）。

已知缺口

  1. 保活间隔、离线判定延迟（Redis 过期口径）无文档约定——mqttClientIdCache 的过期细节见设备业务 · 运行时关联，设备侧推荐值缺证。
  2. 设备侧断线重连 / 重订阅 / 重新保活的最佳实践无平台约定（平台无约定口径）。
目录