跳到主要内容

MQTT 服务端转发

插件用途​

启动内置 MQTT Server，向已连接客户端发布变量、设备、报警和插件事件，并按权限处理变量 RPC 写入和历史读取请求。

转发组范围、触发、分批、缓存和启停见数据转发。本页只说明监听、TLS、客户端限制、Topic、RPC、模板和服务端调试。

功能入口​

进入“开发配置 → 数据转发”，按以下顺序配置：

  1. 保存转发组范围、触发、定时间隔、在线过滤和批处理策略。
  2. 新增目标，选择“MQTT 服务端转发”，填写目标基本信息。
  3. 打开“目标属性”，配置监听、安全认证、消息主题、脚本、模板和缓存。
  4. 保存并启用目标，用测试 MQTT 客户端连接后再打开“目标调试”。

目标基本信息​

参数默认值如何配置
所属转发组-必须选择已保存的转发组。
目标名称-必填，同组唯一。
启用开启关闭时不会监听端口。
日志级别Info排查监听、认证或发布问题时临时使用 Debug。
启动超时60 秒页面可填 1～3600 秒。

目标属性​

监听与安全​

参数默认值如何配置
连接类型TcpTcp 监听 MQTT TCP；WebSocket 通过 HTTP 服务监听 WebSocket。
端口1883TCP 明文常用 1883，TLS 或 WebSocket 端口按部署填写。
WebSocket路径/mqtt仅 WebSocket 生效，必须以 / 开头。
启用SSL关闭开启后 Listener 使用 TLS。必须选择服务器证书。
服务器证书名称空从“证书管理”选择带私钥的服务端证书；TLS 开启且证书不存在会启动失败。
CA名称空双向 TLS 时选择用于验证客户端证书的 CA。
允许不受信任证书关闭仅临时自签名证书测试；生产环境保持关闭。
SSL协议版本None（系统默认）按客户端兼容性或安全策略选择 TLS 版本。
检查证书吊销关闭按安全策略开启。
允许连接ID前缀空非空时只接受 Client ID 以该文本开头的客户端；空值允许所有 ID。
用户名空非空时要求客户端用户名完全匹配。
密码空与用户名配套，认证失败的客户端会被拒绝。

消息与 RPC​

参数默认值如何配置
QoS等级0服务端发布消息使用的 QoS。
保留消息关闭开启后发布 Retained Message；停用时在 Broker 客户端清理旧保留消息。
RPC写入TopicRpcWrite填主题前缀，不含 +/#；服务端订阅 {前缀}/+，响应为 {前缀}/{请求编号}/Response。
历史读取RPC TopicRpcHistory填不含通配符的主题前缀；请求和分块响应使用请求编号。
数据请求Topic空收到消息后发布变量、设备和报警快照；不需要时留空。
设备Topic模板空留空不发布设备模型；可使用 ${Name} 等字段。
变量Topic模板ThingsGateway/Variable可使用 ${DeviceName}、${Name} 等字段。
报警Topic模板空留空不发布报警模型。
插件事件Topic模板空留空不发布插件事件模型。
RPC脚本空选择 MQTT 动态 RPC 脚本处理请求和响应；无需自定义处理时留空。

目标变量属性​

参数默认值说明
允许RPC写入开启允许外部 MQTT 客户端通过当前目标写入该变量。监控点应关闭。

变量必须已在转发组范围内；新增目标变量属性不会把变量加入转发组。

该插件还继承通用 数据1～数据10 预留文本字段，默认为空，不会自动进入消息；需要发送时在脚本或模板中显式引用。

数据与脚本​

继承属性包括“详细日志”“JSON缩进格式化”“JSON忽略Null”、设备/变量/报警/插件事件列表和字典上传、四类实体脚本，以及“上传模板配置”。这些开关的配置方式见MQTT 客户端转发；服务端与客户端使用相同的消息实体和 ${字段名} 占位符。

上传模板字段​

在“上传模板配置”中选择 Text 或 JSON 模式并插入 ${字段名}，保存前先执行预览。

数据类型可用字段
变量Id、Name、DeviceName、Value、RawValue、LastSetValue、CollectGroup、CollectTime、CreateTime、ChangeTime、IsOnline、DataType、Unit、RegisterAddress、OtherMethod、Description、ProtectType、RpcWriteEnable、Remark1～Remark5、ValueInited、IsMemory
设备Id、Name、ActiveTime、DeviceStatus、PluginName、Description、LastErrorMessage、Remark1～Remark5
报警AlarmId、VariableId、Name、DeviceName、AlarmCode、AlarmLevel、AlarmLimit、AlarmText、RecoveryCode、AlarmTime、EventTime、FinishTime、ConfirmTime、ConfirmText、AlarmType、EventType、Remark1～Remark5
插件事件DeviceName、ObjectValue

缓存与容量​

参数默认值如何配置
启用失败重试缓存开启发送失败时保留待发数据，恢复后自动补发。
缓存文件最大行数262144CacheDB 出站上限，超过后删除最旧数据。
上传分片大小2000每次补发的最大记录数。
内存队列上限100000内存缓冲上限，持续超限仍可能丢弃旧数据。
过滤离线数据关闭开启后过滤离线变量，转发组在线过滤也会生效。
并发上传数量1服务端共享连接向多个客户端发布，先保持 1，确认负载后再调整。

目标调试​

进入“开发配置 → 数据转发”，选择 MQTT 服务端目标，打开“调试 → 协议调试 · MqttServer”。

功能作用
服务端状态查看监听状态、已连接客户端、订阅和消息活动。
发布消息填写测试 Topic 和正文，验证服务端发布。
客户端管理查看或断开指定客户端连接。

服务端调试​

MQTT 服务端转发专用调试面板

发布消息​

MQTT 服务端转发发布测试消息

状态监控​

MQTT 服务端转发状态监控

断开客户端会立即中断其连接，执行前必须确认客户端身份和影响范围。

验证方法​

  1. 启用目标，确认 Listener 已启动。
  2. 使用允许的 Client ID 和凭据连接测试 MQTT 客户端。
  3. 订阅变量 Topic，让一个转发范围内的测试变量产生新值。
  4. 核对 Topic、正文、QoS、Retain 和消息条数。
  5. 需要 RPC 时，再单独核对请求 Topic、响应 Topic 和变量权限。

常见问题​

现象检查方法
客户端无法连接端口、连接类型、防火墙、TLS 证书、凭据和 Client ID 前缀。
订阅端没有消息转发组范围、目标状态、Topic 模板、QoS、客户端订阅和目标日志。
出现意外保留消息关闭“保留消息”，并清理旧保留消息。
RPC 写入失败RPC Topic、目标变量权限、请求正文、响应 Topic 和源变量写权限。
模板正文无效模板预览、占位符、JSON 语法和 ${字段名} 对应实体。

相关操作​

  • 数据转发：配置转发组、触发、缓存和公共目标操作。
  • 证书管理：维护 MQTT 服务端证书和 CA。
  • 插件索引：查找其它采集或数据转发插件。