Gateway MQTT 采集服务端
插件用途
在中心 Gateway 上启动一个 MQTT 监听，通过 ThingsGateway Gateway MQTT 协议接收多个边缘 Gateway 的变量目录、实时值、设备状态和快照。每个边缘节点使用独立“远端来源”身份接入。
该插件不是通用 MQTT JSON 采集器。普通自定义 Topic 和载荷请使用MQTT 采集服务端。
选择入口
进入“开发配置 → 采集配置”，创建一个采集设备，在“采集插件”中选择“Gateway MQTT 采集服务端”。
这是共享监听插件：一个设备配置多个远端来源。不要为同一个监听端口创建多个 Gateway MQTT 服务端设备。
每个边缘 Gateway 需要配置对应的 MQTT 转发目标；中心与边缘的完整拓扑和固定 Topic 见Gateway MQTT 采集客户端中的“配置边缘端 MQTT 上传”。
通道和数据类型
| 项目 | 说明 |
|---|---|
| 通道 | 插件内置 MQTT Listener，不使用公共 TCP、UDP 或串口通道参数。 |
| 数据类型 | Object，变量类型和目录由远端 Gateway 协议数据提供。 |
监听与 TLS
| 参数 | 默认值 | 说明 |
|---|---|---|
| 连接类型 | Tcp | 选择 TCP 或 WebSocket 监听。 |
| 端口 | 1883 | 中心 Gateway 的 MQTT 监听端口，范围 1～65535。 |
| WebSocket路径 | /mqtt | 仅 WebSocket 模式使用。 |
| 启用SSL | 关闭 | 开启 MQTT TLS Listener。 |
| 服务端证书名称 | - | 开启 TLS 时必填，从证书管理中选择服务端证书。 |
| CA名称 | - | 开启 TLS 时必填，用于验证边缘客户端证书。 |
| 允许不受信任证书 | 关闭 | 只用于临时调试，生产环境保持关闭。 |
| SSL协议版本 / 检查证书吊销 | - | 按项目安全策略配置 TLS 协议和吊销检查。 |
远端来源
打开“远端来源”对话框，为每个允许接入的边缘 Gateway 新增一条记录。
| 参数 | 说明 |
|---|---|
| RemoteKey | 稳定技术标识，1～64 个 ASCII 字母、数字、短横线或下划线。它参与 Topic、变量地址、快照和 RPC，保存后不要随意修改。 |
| 显示名称 | 调试页中显示的边缘节点名称。 |
| 启用 | 控制该来源是否参与接入、快照、目录同步和 RPC。 |
| QoS | 当前来源固定协议消息使用的 QoS。 |
| 允许的客户端ID | 边缘 MQTT Client ID，必须精确匹配并在当前监听内唯一。 |
| 用户名 / 密码 | 当前来源连接 Listener 使用的独立凭据。不要在截图或日志中公开。 |
| 客户端证书 SHA-256 | 可选，小写 64 位十六进制指纹。用于把来源绑定到指定客户端证书。 |
每个来源的 RemoteKey、客户端ID和已填写的证书指纹都必须唯一。启用证书指纹绑定时必须开启 TLS；只要一个已启用来源使用指纹，所有已启用来源都必须配置指纹。
协议与可靠性
| 参数 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|
| Topic根 | ThingsGateway/Gateway | - | 中心监听与全部边缘转发目标必须完全一致。 |
| 允许远程写入 | 关闭 | - | 允许中心 Gateway 向边缘变量发起 RPC 写入。只在现场授权后开启。 |
| 快照间隔（秒） | 60 | 10～3600 | 周期请求完整变量目录和最新值。 |
| 请求超时（秒） | 30 | 1～600 | 快照和 RPC 请求的等待上限。 |
| 离线超时（秒） | 180 | 大于快照间隔，最大 86400 | 来源超过该时间没有合法协议消息后转为离线。 |
| 详细日志 | 关闭 | - | 记录不含完整敏感载荷的协议摘要；排障后关闭。 |
容量限制
| 参数 | 默认值 | 取值范围 | 说明 |
|---|---|---|---|
| 远端来源上限 | 32 | 1～128 | 当前设备允许配置的边缘来源数。 |
| 快照并发上限 | 4 | 1～32 | 同时执行的快照或同步任务数。 |
| 入站载荷字节上限 | 1048576 | 4096～16777216 | 单条 MQTT 入站载荷上限。 |
| 每秒消息上限 | 200 | 1～100000 | 全部来源进入解析器的消息速率上限。 |
| 入站处理并发上限 | 4 | 1～64 | 并发 JSON 处理任务数。 |
| JSON深度上限 | 64 | 8～256 | 协议 JSON 的最大嵌套深度。 |
| 单来源目录上限 | 100000 | 1～1000000 | 一个边缘来源允许保存的变量数。 |
| 目录总上限 | 300000 | 不小于单来源上限，最大 3000000 | 当前设备全部来源的变量总数。 |
| RPC等待上限 | 256 | 1～4096 | 同时等待的远程 RPC 批次数。 |
只有在确认内存、消息流量和边缘来源规模后才提高限制。
地址规则
变量地址由来源键和远端变量 ID 组成：
{RemoteKey}/{RemoteVariableId}
示例：factory-a/828746157506629。
远端变量 ID 是边缘 Gateway 上报的变量 ID，不能替换为中心 Gateway 的本地镜像变量 ID。公共变量字段、导入和采集周期见采集配置。
设备调试
进入“开发配置 → 采集配置”，选择 Gateway MQTT 服务端设备，打开“调试 → 协议调试 · GatewayMqttCollectServer”。
| 功能 | 作用 |
|---|---|
| 远端网关 | 查看来源身份、连接状态、客户端ID、目录数量、消息计数、快照时间和错误；可请求快照或测试 RPC。 |
| 远端变量 | 按来源、关键字和在线状态查询远端变量目录。 |
| 诊断日志 | 查看按来源过滤的有界协议诊断事件。 |
| 变量同步 | 预览远端目录与本地变量的新增、更新、缺失和冲突，确认后应用同步计划。 |
“请求快照”和“测试 RPC”只针对所选来源；“同步全部”或“应用计划”会改变本地变量配置，执行前必须核对差异和影响范围。
验证方法
- 新增一个具有唯一
RemoteKey、客户端ID和凭据的远端来源。 - 确认边缘 MQTT 目标使用相同 Topic 根和 RemoteKey，并连接到中心监听。
- 在调试页确认来源在线并请求一次完整快照。
- 在“远端变量”中找到一个变量，按地址规则创建或同步本地变量。
- 读取本地镜像值并与边缘 Gateway 比较。
- 仅在中心、边缘、目标和变量权限都允许时测试远程写入。
常见问题
| 现象 | 检查方法 |
|---|---|
| Listener 无法启动 | 端口占用、连接类型、TLS 服务端证书、CA 和防火墙。 |
| 来源无法连接 | 客户端ID、用户名、密码、证书指纹、TLS 和 Listener 状态。 |
| 来源一直离线 | RemoteKey、Topic 根、边缘目标状态、快照间隔和最后协议消息。 |
| 变量目录为空 | 边缘转发范围、快照响应、载荷上限和目录容量限制。 |
| 多个来源数据混淆 | 每个来源必须使用不同 RemoteKey、客户端ID和匹配的变量地址。 |
| 快照超时 | 边缘连接、请求超时、消息速率、载荷大小和 MQTT 流量。 |
| 远程写入失败 | 两端远程写入开关、变量权限、RPC 等待数量和响应日志。 |
相关操作
- Gateway MQTT 采集客户端：共享拓扑、边缘
MqttClientProducer和固定 Topic 配置。 - 采集配置：公共设备、变量、导入和调试操作。
- 证书管理：维护 MQTT 服务端证书和 CA。
- 插件索引：查找其它采集或数据转发插件。