MQTT 订阅
用 MQTTX 建立订阅，在 FMQ 查询运行时关系，并通过真实发布和实收判断消息是否送达。
页面导读
适用场景适合需要查询 MQTT 运行时订阅关系，并用真实发布和实收判断消息是否送达的运维人员。
前置条件具备 MQTT 运行监控查看权限，准备一个 MQTTX 客户端用于建立订阅和接收消息，预计 20 分钟。
验收点平台能查到订阅关系且 MQTTX 实收新消息，断开后刷新可看到订阅状态变化，重连并重订阅后平台能再次查到同一订阅关系。
阅读方法
先确认入口、权限和目标对象，再按编号完成操作。每一步都包含预期结果；详细字段和选项收在可展开的参考表中。
截图说明
截图来自原始操作手册。公开版会隐藏真实节点地址、连接地址和凭据；示例中的状态、时间和数据不代表当前生产环境。
开始前准备
| 项目 | 说明 |
|---|---|
| 能做什么 | 查询订阅关系并验证 MQTTX 真实收发。 |
| 从哪里进入 | MQTT → 订阅 |
| 需要权限 | MQTT 运行监控查看权限 |
| 预计时间 | 20 分钟 |
MQTT 订阅页是做什么的
这张页面只查询已经存在的运行时订阅关系。订阅由 MQTTX 或设备发送 SUBSCRIBE 建立，不能在 FMQ 页面里新建。查到记录也不等于消息已送达，必须再用 MQTTX 真实收一条新消息。
看懂页面统计和结果
1. 先看懂订阅页面
操作位置： MQTT→订阅
确认这是一张运行时查询页，先看四项统计、筛选区和结果列表。
图：这是一张运行时查询页，不在平台内新建订阅。
2. 按 Client ID 查询
操作位置： MQTT→订阅→筛选范围
输入 MQTTX 的完整 Client ID；不确定节点时保持全部，点击查询。
图：输入完整 Client ID 并点击查询。
字段说明
| 字段 / 控件 | 说明 |
|---|---|
| 客户端 ID | 优先从 MQTTX 连接配置复制完整值；用于定位是谁建立了订阅；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。选填 · 来源：MQTTX 连接配置或客户端中心。选择：优先从 MQTTX 连接配置复制完整值；用于定位是谁建立了订阅。推荐：按对接资料填写 · 示例：FastBee_mqtt_sub_demo |
| 节点 | 不知道客户端连到哪台节点时选全部；排查单节点差异时再指定；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。选填 · 来源：订阅结果或客户端中心。选择：不知道客户端连到哪台节点时选全部；排查单节点差异时再指定。推荐：按对接资料填写 · 示例：按实际环境填写 |
3. 核对订阅结果行
操作位置： MQTT→订阅→订阅列表
逐列核对 Client ID、Topic、QoS 和节点；查到只证明订阅关系存在。
图：Client ID、Topic、QoS 和节点四列共同确认订阅关系。
订阅页面字段与操作
| 配置项 | 用途与使用建议 | 生效与恢复 |
|---|---|---|
| 订阅总数 | 当前筛选条件下命中的订阅关系数量；怎么看：当前筛选条件下命中的订阅关系数量。 | 数据来源：来自 MQTTX 连接信息或 FMQ 当前运行状态；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。 |
| 覆盖节点 | 当前返回页实际出现的 FMQ 节点数量，不是集群节点总数；怎么看：当前返回页实际出现的 FMQ 节点数量，不是集群节点总数。 | 数据来源：来自 MQTTX 连接信息或 FMQ 当前运行状态；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。 |
| 已用筛选 | 客户端 ID、Topic、节点三类条件中当前填写了几项，不是命中数量；怎么看：客户端 ID、Topic、节点三类条件中当前填写了几项，不是命中数量。 | 数据来源：来自 MQTTX 连接信息或 FMQ 当前运行状态；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。 |
| QoS 层级 | 当前返回页中出现了几种 QoS 值，不是成功率；怎么看：当前返回页中出现了几种 QoS 值，不是成功率。 | 数据来源：来自 MQTTX 连接信息或 FMQ 当前运行状态；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。 |
| 客户端 ID | 优先从 MQTTX 连接配置复制完整值；用于定位是谁建立了订阅；怎么选：优先从 MQTTX 连接配置复制完整值；用于定位是谁建立了订阅；值从哪里来：MQTTX 连接配置或客户端中心；建议：以部署或对接资料为准；示例：FastBee_mqtt_sub_demo。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；影响范围：当前查询或测试会话；生效要求：保存后按字段说明确认；填错时：筛选过窄或 Topic 不一致会造成看似无数据；恢复：放宽筛选并用新消息重新验证。 |
| Topic | 用于缩小主题范围。先用完整 Topic；查不到时清空它排除筛选过窄；怎么选：用于缩小主题范围。先用完整 Topic；查不到时清空它排除筛选过窄；值从哪里来：MQTTX 订阅配置；建议：以部署或对接资料为准；示例：FastBee/manual/subscription/demo。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；影响范围：当前查询或测试会话；生效要求：保存后按字段说明确认；填错时：筛选过窄或 Topic 不一致会造成看似无数据；恢复：放宽筛选并用新消息重新验证。 |
| 节点 | 不知道客户端连到哪台节点时选全部；排查单节点差异时再指定；怎么选：不知道客户端连到哪台节点时选全部；排查单节点差异时再指定；值从哪里来：订阅结果或客户端中心；建议：以部署或对接资料为准。全部节点：不限制运行节点；查询所有节点返回的关系。指定节点：只查选中的运行节点；用于定位单节点差异。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；影响范围：当前查询或测试会话；生效要求：保存后按字段说明确认；填错时：筛选过窄或 Topic 不一致会造成看似无数据；恢复：放宽筛选并用新消息重新验证。 |
| 查询 | 修改筛选条件后点击，才按当前输入重新请求订阅关系；什么时候用：修改筛选条件后点击，才按当前输入重新请求订阅关系。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；失败时：放宽筛选并用新消息重新验证。 |
| 刷新列表 | MQTTX 新订阅、取消订阅、断开或重连后重新读取当前运行状态；什么时候用：MQTTX 新订阅、取消订阅、断开或重连后重新读取当前运行状态。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；失败时：放宽筛选并用新消息重新验证。 |
| 全部订阅 / 清空筛选 | 无结果时先放宽条件，排除筛选造成的空结果；什么时候用：无结果时先放宽条件，排除筛选造成的空结果。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；失败时：放宽筛选并用新消息重新验证。 |
| 打开客户端中心 | 仍无结果时检查客户端是否在线以及是否真的发送 SUBSCRIBE；什么时候用：仍无结果时检查客户端是否在线以及是否真的发送 SUBSCRIBE。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；失败时：放宽筛选并用新消息重新验证。 |
| 客户端 ID 列 | 发起订阅的 MQTT 客户端身份；怎么看：发起订阅的 MQTT 客户端身份。 | 数据来源：来自 MQTTX 连接信息或 FMQ 当前运行状态；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。 |
| Topic 列 | 客户端订阅的主题或带 +/# 的主题过滤器；怎么看：客户端订阅的主题或带 +/# 的主题过滤器。 | 数据来源：来自 MQTTX 连接信息或 FMQ 当前运行状态；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。 |
| QoS 列 | 该订阅请求使用的服务质量等级；怎么看：该订阅请求使用的服务质量等级。 | 数据来源：来自 MQTTX 连接信息或 FMQ 当前运行状态；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。 |
| 节点列 | 持有这条运行时订阅关系的 FMQ 节点；怎么看：持有这条运行时订阅关系的 FMQ 节点。 | 数据来源：来自 MQTTX 连接信息或 FMQ 当前运行状态；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。 |
| 每页数量 | 记录较多时在 20 或 50 条间切换；怎么选：记录较多时在 20 或 50 条间切换；值从哪里来：来自 MQTTX 连接信息或 FMQ 当前运行状态；建议：保持当前值。20 条：默认密度；每页最多 20 条。50 条：集中查看更多结果；每页最多 50 条。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；影响范围：当前查询或测试会话；生效要求：保存后按字段说明确认；填错时：筛选过窄或 Topic 不一致会造成看似无数据；恢复：放宽筛选并用新消息重新验证。 |
| 上一页 / 下一页 | 总数超过一页时翻页；页面显示从 1 开始，前端请求使用从 0 开始的页号；什么时候用：总数超过一页时翻页；页面显示从 1 开始，前端请求使用从 0 开始的页号。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；失败时：放宽筛选并用新消息重新验证。 |
MQTTX 订阅与消息实收
4. 用 MQTTX 建立测试连接
操作位置： MQTTX→新建连接
填写 FMQ MQTT 地址、端口和唯一 Client ID，连接后只确认会话已建立。
公开版截图说明
截图包含原测试 Broker 地址，公开版以示例域名代替。操作方法和字段说明完整保留。
字段说明
| 字段 / 控件 | 说明 |
|---|---|
| Broker 地址 | 填写 FMQ MQTT 数据入口，不是管理页面地址；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。必填 · 来源：FMQ 服务管理或部署清单。选择：填写 FMQ MQTT 数据入口，不是管理页面地址。推荐：按对接资料填写 · 示例：mqtt.example.com |
| 端口 | 当前普通 MQTT TCP 入口为 1883；实际以部署为准；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。必填 · 来源：FMQ 服务管理或部署清单。选择：当前普通 MQTT TCP 入口为 1883；实际以部署为准。推荐：按对接资料填写 · 示例：1883 |
| Client ID | 本次演示使用唯一 FastBee_ 前缀身份，并与平台查询条件保持一致；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。必填 · 来源：实施人员按资源命名规范创建。选择：本次演示使用唯一 FastBee_ 前缀身份，并与平台查询条件保持一致。推荐：按对接资料填写 · 示例：FastBee_mqtt_sub_demo |
5. 在 MQTTX 订阅测试 Topic
操作位置： MQTTX→订阅
订阅测试 Topic，QoS 选择 1；这一步会向 FMQ 发送 SUBSCRIBE。
图：订阅 Topic 与 QoS 1清楚可见。
字段说明
| 字段 / 控件 | 说明 |
|---|---|
| 订阅 Topic | 订阅、平台查询、发布必须指向同一主题；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。必填 · 来源：业务 Topic 约定。选择：订阅、平台查询、发布必须指向同一主题。推荐：按对接资料填写 · 示例：FastBee/manual/subscription/demo |
| QoS | 演示使用 QoS 1，至少一次到达；页面列表应显示同一值；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。必填 · 来源：来自 MQTTX 连接信息或 FMQ 当前运行状态。选择：演示使用 QoS 1，至少一次到达；页面列表应显示同一值。推荐：1 · 示例：按实际环境填写 |
6. 发布并确认 MQTTX 实收
操作位置： MQTTX→发布与消息列表
向同一 Topic 发布新的 JSON，核对接收区 Topic、Payload 和接收时间。
图：同一 Topic 的新 Payload 和接收时间证明消息送达。
字段说明
| 字段 / 控件 | 说明 |
|---|---|
| 订阅 Topic | 订阅、平台查询、发布必须指向同一主题；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。必填 · 来源：业务 Topic 约定。选择：订阅、平台查询、发布必须指向同一主题。推荐：按对接资料填写 · 示例：FastBee/manual/subscription/demo |
| Payload | 发布一条容易识别的新 JSON，并在 MQTTX 接收区核对内容和时间；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。必填 · 来源：本次演示数据。选择：发布一条容易识别的新 JSON，并在 MQTTX 接收区核对内容和时间。推荐：按对接资料填写 · 示例： |
MQTTX 订阅与收发参数
| 配置项 | 用途与使用建议 | 生效与恢复 |
|---|---|---|
| 必填 Broker 地址 | 填写 FMQ MQTT 数据入口，不是管理页面地址；怎么选：填写 FMQ MQTT 数据入口，不是管理页面地址；值从哪里来：FMQ 服务管理或部署清单；建议：以部署或对接资料为准；示例：mqtt.example.com。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；影响范围：当前查询或测试会话；生效要求：保存后按字段说明确认；填错时：筛选过窄或 Topic 不一致会造成看似无数据；恢复：放宽筛选并用新消息重新验证。 |
| 必填 端口 | 当前普通 MQTT TCP 入口为 1883；实际以部署为准；怎么选：当前普通 MQTT TCP 入口为 1883；实际以部署为准；值从哪里来：FMQ 服务管理或部署清单；建议：以部署或对接资料为准；示例：1883。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；影响范围：当前查询或测试会话；生效要求：保存后按字段说明确认；填错时：筛选过窄或 Topic 不一致会造成看似无数据；恢复：放宽筛选并用新消息重新验证。 |
| 必填 Client ID | 本次演示使用唯一 FastBee_ 前缀身份，并与平台查询条件保持一致；怎么选：本次演示使用唯一 FastBee_ 前缀身份，并与平台查询条件保持一致；值从哪里来：实施人员按资源命名规范创建；建议：以部署或对接资料为准；示例：FastBee_mqtt_sub_demo。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；影响范围：当前查询或测试会话；生效要求：保存后按字段说明确认；填错时：筛选过窄或 Topic 不一致会造成看似无数据；恢复：放宽筛选并用新消息重新验证。 |
| 必填 订阅 Topic | 订阅、平台查询、发布必须指向同一主题；怎么选：订阅、平台查询、发布必须指向同一主题；值从哪里来：业务 Topic 约定；建议：以部署或对接资料为准；示例：FastBee/manual/subscription/demo。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；影响范围：当前查询或测试会话；生效要求：保存后按字段说明确认；填错时：筛选过窄或 Topic 不一致会造成看似无数据；恢复：放宽筛选并用新消息重新验证。 |
| 必填 QoS | 演示使用 QoS 1，至少一次到达；页面列表应显示同一值；怎么选：演示使用 QoS 1，至少一次到达；页面列表应显示同一值；值从哪里来：来自 MQTTX 连接信息或 FMQ 当前运行状态；建议：1。QoS 0：最多一次；不重传。QoS 1：至少一次；可能重复，业务需幂等。QoS 2：仅一次；握手更多。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；影响范围：当前查询或测试会话；生效要求：保存后按字段说明确认；填错时：筛选过窄或 Topic 不一致会造成看似无数据；恢复：放宽筛选并用新消息重新验证。 |
| 必填 Payload | 发布一条容易识别的新 JSON，并在 MQTTX 接收区核对内容和时间；怎么选：发布一条容易识别的新 JSON，并在 MQTTX 接收区核对内容和时间；值从哪里来：本次演示数据；建议：以部署或对接资料为准；示例：{ temperature: 31.5, source: MQTTX }。 | 只改变查询范围或 MQTTX 当前连接，不修改产品主数据；影响范围：当前查询或测试会话；生效要求：保存后按字段说明确认；填错时：筛选过窄或 Topic 不一致会造成看似无数据；恢复：放宽筛选并用新消息重新验证。 |
| 连接状态 | 已连接只证明 MQTT 会话存在，不证明已订阅；怎么看：已连接只证明 MQTT 会话存在，不证明已订阅。 | 数据来源：来自 MQTTX 连接信息或 FMQ 当前运行状态；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。 |
| 接收记录 | Topic、Payload 和接收时间同时一致，才证明匹配消息已送达 MQTTX；怎么看：Topic、Payload 和接收时间同时一致，才证明匹配消息已送达 MQTTX。 | 数据来源：来自 MQTTX 连接信息或 FMQ 当前运行状态；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。 |
断开与重连后怎么判断
7. 主动断开 MQTTX
操作位置： MQTTX→当前连接
主动断开连接，记录断开时间；不要把平台历史行当在线状态。
图：记录断开状态，不把平台历史行当在线证据。
8. 刷新查看断开后的订阅状态
操作位置： MQTT→订阅
点击刷新并重新查询同一 Client ID，结合会话配置判断记录是否仍存在。
图：刷新后结合会话配置解释订阅记录是否仍存在。
字段说明
| 字段 / 控件 | 说明 |
|---|---|
| 客户端 ID | 优先从 MQTTX 连接配置复制完整值；用于定位是谁建立了订阅；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。选填 · 来源：MQTTX 连接配置或客户端中心。选择：优先从 MQTTX 连接配置复制完整值；用于定位是谁建立了订阅。推荐：按对接资料填写 · 示例：FastBee_mqtt_sub_demo |
9. 重连、重订阅并发送新消息
操作位置： MQTTX→当前连接
重新连接并确认订阅，再发布一条不同时间的新消息，避免把旧记录当恢复证据。
图：重连、重订阅并收到不同时间的新消息。
字段说明
| 字段 / 控件 | 说明 |
|---|---|
| 订阅 Topic | 订阅、平台查询、发布必须指向同一主题；只改变查询范围或 MQTTX 当前连接，不修改产品主数据。必填 · 来源：业务 Topic 约定。选择：订阅、平台查询、发布必须指向同一主题。推荐：按对接资料填写 · 示例：FastBee/manual/subscription/demo |
10. 平台再次确认订阅关系
操作位置： MQTT→订阅
刷新后再次查到同一 Client ID、Topic、QoS 和节点，和 MQTTX 新实收一起完成恢复判断。
图：平台再次查到同一订阅关系。
查询、刷新和分页什么时候用
修改筛选项后要点击查询；刷新用于重新读取当前状态。第一次定位优先只填完整 Client ID，节点保持全部。查不到时先清空 Topic 和节点，再到客户端中心确认客户端在线。
- 查询：应用当前筛选条件。
- 刷新：重新读取运行时状态。
- 分页：总数超过一页时使用，不能把当前页统计当全局统计。
常见问题
参考表
| 看到什么现象 | 可能原因 | 先检查哪里 | 如何恢复 |
|---|---|---|---|
| MQTTX 已连接，页面无订阅 | 客户端只连接但没有发送 SUBSCRIBE。 | 查看 MQTTX 是否存在目标订阅。 | 重新订阅后回到 FMQ 刷新。 |
| 页面有订阅，MQTTX 收不到 | 发布 Topic 不匹配、客户端已断开或只看了旧消息。 | 核对 Topic、连接状态和接收时间。 | 向完全匹配的 Topic 发布一条新消息。 |
| 查询结果为空 | 筛选条件过窄。 | 清空 Topic 和节点，只保留 Client ID。 | 重新查询；仍为空时去客户端中心检查在线状态。 |
| 重连后仍看到旧记录 | 列表不能单独证明客户端在线。 | 刷新并检查当前 MQTTX 连接。 | 重新订阅并发送新消息，以新接收时间作为恢复证据。 |
生产操作提示
截图和示例用于说明操作位置与判断方法，不代表当前生产状态。涉及发布、启停、重绑、重试或删除时，应先确认目标环境、影响范围和恢复方案，并由授权人员执行。
蜂信物联（FastBee） · FMQ 操作手册