MQTT 采集服务端
插件用途
作为 MQTT Server 接收客户端上报数据
选择入口
进入“开发配置 → 采集配置”，创建设备并在“采集插件”中选择“MQTT 采集服务端”。
支持的通道和数据类型
| 通道类型 | 配置前检查 |
|---|---|
| 插件内置连接 | 连接参数在设备动态属性中配置，不使用公共 TCP、UDP 或串口通道参数。 |
可选数据类型： 对象（由协议节点或载荷决定）
插件参数
该插件在设备属性中维护 MQTT 监听器，不使用普通 TCP、UDP 或串口通道字段。失败重试、写优先等采集公共运行属性仍按采集配置配置。
连接配置
| 参数 | 说明 |
|---|---|
| 连接类型 | 默认：Tcp；填写：下拉选择。设置建立连接时使用的连接类型。 |
| 端口 | 默认：1883；填写：数字输入。设置建立连接时使用的端口。 |
| WebSocket路径 | 默认：/mqtt；填写：文本输入。设置建立连接时使用的WebSocket路径。 |
“连接类型”只有 Tcp 和 WebSocket；WebSocket 客户端连接路径由“端口”和“WebSocket路径”共同决定，启用 SSL 时使用 wss://。
安全认证
| 参数 | 说明 |
|---|---|
| 启用SSL | 默认：否；填写：开关。控制“启用SSL”功能是否启用。 |
| 服务器证书名称 | 填写：证书选择。设置身份校验或安全连接使用的服务器证书名称。 |
| CA名称 | 填写：证书选择。设置身份校验或安全连接使用的CA名称。 |
| 允许不受信任证书 | 默认：是；填写：开关。控制“允许不受信任证书”功能是否启用。 |
| SSL协议版本 | 默认：0；填写：下拉选择。设置身份校验或安全连接使用的SSL协议版本。 |
| 检查证书吊销 | 默认：否；填写：开关。控制“检查证书吊销”功能是否启用。 |
| 允许连接ID前缀 | 填写：文本输入。设置身份校验或安全连接使用的允许连接ID前缀。 |
| 用户名 | 填写：文本输入。设置身份校验或安全连接使用的用户名。 |
| 密码 | 填写：文本输入。设置身份校验或安全连接使用的密码。 |
启用 SSL 时必须选择“服务器证书名称”；“允许不受信任证书”默认开启，仅适合受控测试。填写“用户名”后，客户端用户名和密码必须完全匹配；“允许连接ID前缀”非空时，Client ID 也必须以前缀开头。
消息配置
| 参数 | 说明 |
|---|---|
| QoS等级 | 默认：0；填写：下拉选择。设置消息发布或订阅使用的QoS等级。 |
QoS 选项为 0（最多一次）、1（至少一次）和 2（恰好一次），用于服务端发布和 RPC 回执。
日志诊断
| 参数 | 说明 |
|---|---|
| 详细日志 | 默认：否；填写：开关。开启后记录更详细的连接、模板或收发日志，排障完成后可关闭以减少日志量。 |
缓存与可靠性
| 参数 | 说明 |
|---|---|
| 检查清除时间 | 默认：60000；填写：数字输入。设置缓存、重试或连接恢复使用的检查清除时间。 |
地址规则
- 变量地址：${订阅主题};${JSONPath1||JSONPath2};${Condition};${发布主题};${Json|RawString};${Retain};${RPC响应主题};${RPC超时毫秒}
- 只读示例：vendor/device;$.data.temperature;TelemetryCondition
- 只写示例：;;;factory/a/reboot;RawString;false
- RPC 示例：;;;factory/a/command/{RequestId};Json;false;factory/a/response/{RequestId};5000
- 负载示例：
- {
- "data": {
- "items": [ { "value": 12.5 } ],
- "temperature": 31
- },
- "a.b": "special",
- "devs": [{ "d": [{ "m": "ZP_AA01_01_VC", "v": 233.4 }] }]
- }
- 示例：vendor/device;$.data.items[0].value，结果是 12.5
- 示例：vendor/device;$['a.b']，结果是 "special"
- 示例：vendor/device;$.devs[0].d[?(@.m == 'ZP_AA01_01_VC')].v，结果是 233.4
- 示例：devices/+/up;$.data.temperature||$.payload.temperature;ConditionName
- 路径支持省略根符号 $，数组也可使用 items.0.value；候选路径按从左到右的顺序取第一个存在字段。
- 支持过滤器 [?()]、通配符 [] 与 .、递归下降 $..name；匹配多个节点时按文档顺序取第一个。
- 括号外的 || 分隔候选路径，过滤器 [?()] 内的 || 表示逻辑或。
- 属性先精确匹配大小写；仅当不存在精确名称时，才使用唯一的忽略大小写匹配。
- 条件是 DataTrans 脚本名称，raw 为完整 Payload JSON；可声明 Topic 或 MqttTopic 输入参数读取实际发布主题。
- 服务端条件脚本还可声明 ClientId 或 MqttClientId 输入参数读取实际发布客户端 ID。
- 通配主题匹配的所有消息会更新同一变量；需要按设备隔离时请配置精确主题，或在条件脚本中按 Topic 或 ClientId 过滤。
- 发布主题不能使用 + 或 #；RPC 请求和响应主题的 {RequestId} 必须独占最后一个 Topic 层级。
- 地址最多 8 段；订阅主题与 JSONPath 必须同时填写，发布选项必须依附发布主题。RPC 响应主题和超时必须同时填写，超时范围为
100～60000毫秒。 - 变量为“只读”时不能填写发布字段；变量为“只写”时不能填写订阅和 JSONPath 字段；至少配置一条读取或写入路由。
设备调试
进入“开发配置 → 采集配置”，选择当前设备后点击“更多功能”并打开“调试”。
协议调试 · MqttServer
| 功能 | 作用 |
|---|---|
| 发布消息 | 由内置 MQTT Server 向指定 Topic 发布测试消息。 |
| Topic 统计 | 查看 Topic 名称和当前订阅数量。 |
| 客户端列表 | 查看客户端 ID、用户名、远端地址和连接时间。 |
| 踢出客户端 | 主动断开指定客户端，属于连接控制操作。 |
发布消息
填写主题和消息内容，验证服务端发布能力。
状态监控
查看客户端连接、订阅和消息状态。
调试要点
先查看客户端列表和订阅，再向测试 Topic 发布消息；ClientId 过滤和 RPC 主题必须按页面规则验证。
验证重点
- 使用测试 MQTT 客户端连接网关端口，确认客户端列表出现对应客户端 ID 和远端地址。
- 让测试客户端订阅一个测试 Topic，确认 Topic 统计中的订阅数量增加。
- 从测试客户端发布一条已知 JSON，确认对应变量值和采集时间更新。
- 在调试页向测试 Topic 发布消息，确认客户端收到的 Payload、QoS 和 Retain 与填写内容一致。
- 踢出客户端只在确认不会影响生产连接时执行；操作后客户端列表应移除该连接。
排障差异
- 客户端无法连接：检查监听端口、连接类型、防火墙、用户名密码、允许连接 ID 前缀及 TLS 证书配置。
- 客户端在线但变量不更新：核对变量 Topic、JSONPath、条件脚本和数据类型，并在 Topic 统计中确认消息使用的 Topic。
- 同一通配 Topic 的数据互相覆盖：改用精确 Topic，或在条件脚本中按
Topic或ClientId过滤来源。 - 调试页发布成功但客户端收不到：确认客户端订阅条件、QoS、Retain 和 Topic 大小写完全一致。
- 踢出后客户端立即重连：这是客户端自动重连行为；需要阻止连接时应调整认证或允许的客户端 ID 配置。
- 保存失败：按错误提示检查段数、JSONPath、主题通配符、读写权限组合以及 RPC 超时范围。