跳到主要内容

MQTT 采集服务端

作为 MQTT Server 接收客户端上报数据

选择入口​

进入“开发配置 → 采集配置”，创建设备并在“采集插件”中选择“MQTT 采集服务端”。

支持的通道和数据类型​

通道类型配置前检查
插件内置连接连接参数在设备动态属性中配置，不使用公共 TCP、UDP 或串口通道参数。

变量类型按当前编辑器选择；使用 Object 时保留载荷字段的对象值，数值、布尔和字符串则按实际字段类型核对。类型设置不会把非 JSON 文本自动变成 JSON。

插件参数​

该插件在设备属性中维护 MQTT 监听器，不使用普通 TCP、UDP 或串口通道字段。失败重试、写优先等采集公共运行属性仍按采集配置配置。

连接配置​

参数说明
连接类型默认：Tcp；填写：下拉选择。设置建立连接时使用的连接类型。
端口默认：1883；填写：数字输入。设置建立连接时使用的端口。
WebSocket路径默认：/mqtt；填写：文本输入。设置建立连接时使用的WebSocket路径。

“连接类型”只有 Tcp 和 WebSocket；WebSocket 客户端连接路径由“端口”和“WebSocket路径”共同决定，启用 SSL 时使用 wss://。

安全认证​

参数说明
启用SSL默认：否；填写：开关。控制“启用SSL”功能是否启用。
服务器证书名称填写：证书选择。设置身份校验或安全连接使用的服务器证书名称。
CA名称填写：证书选择。设置身份校验或安全连接使用的CA名称。
允许不受信任证书默认：是；填写：开关。控制“允许不受信任证书”功能是否启用。
SSL协议版本默认：0；填写：下拉选择。设置身份校验或安全连接使用的SSL协议版本。
检查证书吊销默认：否；填写：开关。控制“检查证书吊销”功能是否启用。
允许连接ID前缀填写：文本输入。设置身份校验或安全连接使用的允许连接ID前缀。
用户名填写：文本输入。设置身份校验或安全连接使用的用户名。
密码填写：文本输入。设置身份校验或安全连接使用的密码。

启用 SSL 时必须选择带私钥的“服务器证书名称”。“允许不受信任证书”默认开启；关闭后，服务端还会要求终端提供有效客户端证书，应同时配置用于验证终端的 CA，并在终端配置客户端身份。终端也需要信任网关的服务端证书。

填写“用户名”后，客户端用户名和密码必须完全匹配；“允许连接ID前缀”非空时，Client ID 也必须以前缀开头。证书通过与账号通过分别检查。

消息配置​

参数说明
QoS等级默认：0；填写：下拉选择。设置消息发布或订阅使用的QoS等级。

QoS 选项为 0（最多一次）、1（至少一次）和 2（恰好一次），用于服务端发布和 RPC 回执。

日志诊断​

参数说明
详细日志默认：否；填写：开关。开启后记录更详细的连接、模板或收发日志，排障完成后可关闭以减少日志量。

缓存与可靠性​

参数说明
检查清除时间默认 60000，单位秒。可读变量超过该缺样窗口后转为离线；收到新的有效消息后恢复，不是磁盘缓存清理时间。

地址规则​

地址使用 属性名称=值;，属性顺序不限，名称不区分大小写，未使用的属性直接省略：

SubscribeTopic=vendor/device;Path=$.data.temperature;Condition=TelemetryCondition;ConditionParameters={"Minimum":"12.5"};

SubscribeTopic、Path、Condition、ConditionParameters、PublishTopic、PayloadMode、Retain、ResponseTopic、Timeout 的填写方法与 MQTT 采集客户端的命名地址相同。本插件在网关上监听，终端连接后向网关发布数据，条件脚本还可以读取发布者 ClientId。

在“变量地址”右侧点击“字段编辑”，选择条件脚本后按参数名称填写，点击“确认并回填”后保存变量。参数输入与特殊字符规则见条件参数配置。未填写的参数沿用脚本默认值，Topic、MqttTopic、ClientId、MqttClientId 未显式填写时自动注入实际消息上下文。

原八段位置地址继续支持；修改后通过编辑器应用时生成命名格式，现有地址无需修改。位置顺序与原八段地址一致。

用途地址示例
读取一个字段SubscribeTopic=vendor/device;Path=$.data.temperature;
读取并判断条件SubscribeTopic=vendor/device;Path=$.data.temperature;Condition=TelemetryCondition;
条件参数SubscribeTopic=vendor/device;Path=$.data.temperature;Condition=TelemetryCondition;ConditionParameters={"Minimum":"12.5"};
发布字符串原文PublishTopic=factory/a/reboot;PayloadMode=RawString;Retain=false;
RPC 请求与响应PublishTopic=factory/a/command/{RequestId};PayloadMode=Json;Retain=false;ResponseTopic=factory/a/response/{RequestId};Timeout=5000;

先新增只读变量，使用第一个地址，让独立客户端连接后发布以下 JSON，应读到 31；再发布不同值并检查新的采集时间。脚本必须先创建并编译，才能使用含脚本名的示例。

{
  "data": {
    "items": [{ "value": 12.5 }],
    "temperature": 31
  },
  "a.b": "special",
  "devs": [{ "d": [{ "m": "ZP_AA01_01_VC", "v": 233.4 }] }]
}

采集映射要求有效 JSON；RawString 只控制发布的字符串原文格式。使用上面的消息时：

  • SubscribeTopic=vendor/device;Path=$.data.items[0].value; 得到 12.5。
  • SubscribeTopic=vendor/device;Path=$['a.b']; 得到字符串 special。
  • SubscribeTopic=vendor/device;Path=$.devs[0].d[?(@.m == 'ZP_AA01_01_VC')].v; 得到 233.4。
  • SubscribeTopic=devices/+/up;Path=$.data.temperature||$.payload.temperature;Condition=ConditionName; 可匹配多个来源；每个匹配消息仍更新同一变量。
  • 路径支持省略根符号 $，数组也可使用 items.0.value；候选路径按从左到右的顺序取第一个存在字段。
  • 支持过滤器 [?()]、通配符 [] 与 .、递归下降 $..name；匹配多个节点时按文档顺序取第一个。
  • 括号外的 || 分隔候选路径，过滤器 [?()] 内的 || 表示逻辑或。
  • 属性先精确匹配大小写；仅当不存在精确名称时，才使用唯一的忽略大小写匹配。
  • 条件是 DataTrans 脚本名称，raw 为完整 Payload JSON；可声明 Topic 或 MqttTopic 输入参数读取实际发布主题。
  • 服务端条件脚本还可声明 ClientId 或 MqttClientId 输入参数读取实际发布客户端 ID。
  • 通配主题匹配的所有消息会更新同一变量；需要按设备隔离时请配置精确主题，或在条件脚本中按 Topic 或 ClientId 过滤。
  • 发布主题不能使用 + 或 #；RPC 请求和响应主题的 {RequestId} 必须独占最后一个 Topic 层级。
  • 订阅主题与 JSONPath 必须同时填写，发布选项必须依附发布主题。RPC 响应主题和超时必须同时填写，超时范围为 100～60000 毫秒。
  • 变量为“只读”时不能填写发布字段；变量为“只写”时不能填写订阅和 JSONPath 字段；至少配置一条读取或写入路由。

设备调试​

进入“开发配置 → 采集配置”，选择当前设备后点击“更多功能”并打开“调试”。

协议调试 · MqttServer​

MQTT 采集服务端 协议调试 · MqttServer

功能作用
发布消息由内置 MQTT Server 向指定 Topic 发布测试消息。
Topic 统计查看 Topic 名称和当前订阅数量。
客户端列表查看客户端 ID、用户名、远端地址和连接时间。
踢出客户端主动断开指定客户端，属于连接控制操作。

发布消息​

MQTT 采集服务端发布消息

填写主题和消息内容，验证服务端发布能力。

状态监控​

MQTT 采集服务端状态监控

查看客户端连接、订阅和消息状态。

调试要点

先查看客户端列表和订阅，再向测试 Topic 发布消息；ClientId 过滤和 RPC 主题必须按页面规则验证。

验证重点​

  1. 使用测试 MQTT 客户端连接网关端口，确认客户端列表出现对应客户端 ID 和远端地址。
  2. 让测试客户端订阅一个测试 Topic，确认 Topic 统计中的订阅数量增加。
  3. 从测试客户端发布一条已知 JSON，确认对应变量值和采集时间更新。
  4. 在调试页向测试 Topic 发布消息，确认客户端收到的 Payload、QoS 和 Retain 与填写内容一致。
  5. 踢出客户端只在确认不会影响生产连接时执行；操作后客户端列表应移除该连接。

排障差异​

  • 客户端无法连接：检查监听端口、连接类型、防火墙、用户名密码、允许连接 ID 前缀及 TLS 证书配置。
  • 客户端在线但变量不更新：核对变量 Topic、JSONPath、条件脚本和数据类型，并在 Topic 统计中确认消息使用的 Topic。
  • 同一通配 Topic 的数据互相覆盖：改用精确 Topic，或在条件脚本中按 Topic 或 ClientId 过滤来源。
  • 调试页发布成功但客户端收不到：确认客户端订阅条件、QoS、Retain 和 Topic 大小写完全一致。
  • 踢出后客户端立即重连：这是客户端自动重连行为；需要阻止连接时应调整认证或允许的客户端 ID 配置。
  • 保存失败：按错误提示检查属性名称是否拼写正确或重复、参数类型、JSONPath、主题通配符、读写权限组合以及 RPC 超时范围。

相关操作​

  • 采集配置：查看通道、设备和公共变量配置。
  • 插件索引：查找其它采集或数据转发插件。