Gateway MQTT 采集客户端
插件用途
在中心 Gateway 上通过一个共享 MQTT Broker 连接，采集多个边缘 Gateway 的变量目录、实时值、设备状态和快照。每个边缘节点由唯一 RemoteKey 区分。
该插件不是通用 MQTT JSON 采集器。普通自定义 Topic 和载荷请使用MQTT 采集客户端。
选择运行模式
| 模式 | 适用网络 | 中心端行为 | 边缘端行为 |
|---|---|---|---|
GatewayMqttCollectClient | 已有统一 Broker，或各网关都只能主动出站 | 以一个固定 ClientId 连接 Broker，并订阅全部已配置来源 | 多个 MqttClientProducer 连接同一 Broker，并按各自 RemoteKey 发布 |
GatewayMqttCollectServer | 中心 Gateway 可以开放 MQTT 入站端口 | 在一个端口监听多个边缘客户端，并按 ClientId、账号和可选证书指纹绑定来源 | 多个 MqttClientProducer 直接连接中心 Gateway |
配置前准备
- 为每台边缘 Gateway 分配不会变化的
RemoteKey，仅使用英文字母、数字、连字符或下划线。 - 确认中心端和边缘端使用相同的 Topic 根，默认是
ThingsGateway/Gateway。 - 在每台边缘 Gateway 的数据转发页面创建
MqttClientProducer，关闭 Retain，并按下文配置变量、数据请求和 RPC Topic。 - 需要远程写入时，先确认边缘 Producer、中心采集设备和目标变量三处权限都允许写入。
- 生产环境使用 TLS；Server 模式应为每个来源配置独立账号，启用客户端证书时再绑定独立 SHA-256 指纹。
完整数据链路
GatewayMqttCollectClient 和 GatewayMqttCollectServer 只安装在中心 Gateway，负责接收和采集；边缘 Gateway 的 MQTT 上传继续使用现有数据转发插件 MqttClientProducer，不需要创建第二套 Gateway 专用上传插件。
边缘 Gateway 的采集变量
→ 数据转发组（决定上传范围和触发方式）
→ MqttClientProducer（上传实时值并响应快照、写入请求）
→ 共享 Broker 或中心 Gateway 的 MQTT 监听端口
→ GatewayMqttCollectClient / GatewayMqttCollectServer
→ 中心 Gateway 镜像变量
插件名称中的 Client 和 Server 表示中心采集端的 MQTT 角色，不是数据方向：Client 模式由中心端连接共享 Broker；Server 模式由中心端监听，边缘 MqttClientProducer 主动连接中心端。
配置边缘端 MQTT 上传
在每台边缘 Gateway 上执行以下操作：
- 登录 GatewayRuntime Web，进入“开发配置 → 数据转发”。
- 新建并启用数据转发组，在组变量范围中加入需要汇聚的变量；组范围未包含的变量不会上传。
- 在该组中新建转发目标，插件选择
MqttClientProducer，并启用目标。 - 按所选模式配置连接地址，再按当前边缘 Gateway 的
RemoteKey配置固定 Topic。 - 保存后确认目标在线且没有 CacheDB 积压，再到中心采集设备的调试页请求快照和同步变量。
连接地址对应关系
| 中心采集模式 | 边缘 MqttClientProducer 连接地址 | 身份配置 |
|---|---|---|
GatewayMqttCollectClient | 填写共享 Broker 的地址和端口；中心采集端也连接这个 Broker | 边缘 ClientId 必须唯一，用户名和密码使用 Broker 分配的边缘账号；Broker ACL 应只允许该边缘访问自己的 {TopicRoot}/{RemoteKey}/# |
GatewayMqttCollectServer | 填写中心 Gateway 的地址，以及 GatewayMqttCollectServer 配置的监听端口 | ClientId 必须等于中心来源配置的 AllowedClientId，用户名和密码也必须与该来源完全一致 |
不要在边缘端使用 MqttServerProducer：Client 汇聚模式需要双方连接同一个 Broker，Server 汇聚模式需要边缘端作为客户端连接中心监听端口，这两种拓扑都由 MqttClientProducer 发起连接。
固定 Topic 与上传结构
假设中心采集设备的 Topic 根为 ThingsGateway/Gateway，当前边缘的 RemoteKey 为 edge-01，边缘 MqttClientProducer 应使用以下配置：
| 边缘端配置项 | 配置值或要求 |
|---|---|
| 变量 Topic 模板 | ThingsGateway/Gateway/edge-01/Variable |
| 数据请求 Topic | ThingsGateway/Gateway/edge-01/RpcQuest |
| RPC 写入 Topic | ThingsGateway/Gateway/edge-01/RpcWrite |
| 变量列表上传 | 开启 |
| 变量字典上传 | 关闭 |
| 变量实体脚本 / 上传模板配置 | 保持为空，不改变当前固定 Payload |
| JSON 忽略 Null | 关闭 |
| 保留消息 | 关闭；专用采集会拒绝 Retain 消息 |
| 过滤离线数据 | 关闭，使全量快照包含离线变量及其元数据 |
| QoS 等级 | 边缘端与中心来源配置保持一致；推荐 AtLeastOnce 时允许重复投递，由中心采集端幂等处理 |
| 上传分片大小 | 必须大于 0，并保证单批 JSON 不超过中心采集设备的“入站载荷字节上限” |
RemoteKey 不是 MqttClientProducer 的独立属性，而是固定写入上述三个 Topic 中。每台边缘 Gateway 必须使用不同的 RemoteKey；不要在 Topic 中使用 ${...} 占位符，也不要配置变量实体脚本或上传模板改变 Payload。历史读取 RPC Topic 不由 Gateway MQTT 专用采集使用。
选择入口
进入“开发配置 → 采集配置”，创建一个采集设备，在“采集插件”中选择“Gateway MQTT 采集客户端”。
这是共享连接插件：在一个设备的“远端来源”中配置多个边缘节点。不要为每个边缘节点创建一个普通 MQTT 通道或 Gateway MQTT 设备。
每个边缘 Gateway 需要配置对应的 MQTT 客户端转发目标，完整拓扑和固定 Topic 见本页“配置边缘端 MQTT 上传”。
连接与安全
| 参数 | 默认值 | 说明 |
|---|---|---|
| 连接类型 | Tcp | 根据共享 Broker 选择 TCP 或 WebSocket。 |
| IP地址 | localhost | 共享 MQTT Broker 的主机名或 IP。 |
| 端口 | 1883 | Broker 端口。 |
| WebSocket路径 | /mqtt | 仅 WebSocket 模式使用。 |
| 客户端ID | - | 中心采集器的持久 Client ID，在 Broker 上必须唯一。 |
| 清除会话 | 开启 | 控制共享 MQTT 会话状态是否保留。 |
| MQTT协议版本 | 4（MQTT 3.1.1） | 必须与 Broker 一致。 |
| 启用SSL | 关闭 | 开启共享 MQTT TLS 连接。 |
| SSL目标主机名 | - | 用于校验 Broker 证书的主机名。 |
| 客户端证书 / CA | - | 从证书管理中选择客户端证书和 CA。 |
| 允许不受信任证书 | 关闭 | 只用于临时调试，生产环境保持关闭。 |
| SSL协议 / 吊销检查 | - | 按 Broker 和项目安全策略配置。 |
| 用户名 / 密码 | - | 中心采集器的 Broker 凭据。不要在截图或日志中公开。 |
| 保活时间 | 60 秒 | MQTT Keep Alive 周期。 |
| 连接超时 | 3000 毫秒 | 建立共享连接的等待上限。 |
远端来源与协议
| 参数 | 说明 |
|---|---|
| Topic根 | 默认 ThingsGateway/Gateway。中心采集器和全部边缘转发目标必须一致。 |
| 远端来源 | 打开来源列表，每个边缘 Gateway 新增一条。 |
| RemoteKey | 稳定来源键，只能使用 ASCII 字母、数字、短横线或下划线，且必须唯一。 |
| 显示名称 | 调试页中显示的边缘节点名称。 |
| 启用 | 控制当前来源是否参与订阅、快照、目录和 RPC。 |
| QoS | 当前来源固定协议消息使用的 QoS。 |
| 允许远程写入 | 允许中心向边缘变量发起 RPC 写入，默认关闭。 |
| 快照间隔 | 默认 60 秒，范围 10～3600。 |
| 请求超时 | 默认 30 秒，范围 1～600。 |
| 离线超时 | 默认 180 秒，必须大于快照间隔。 |
共享 MQTT 会话只负责传输；每个来源的身份由 Topic 命名空间中的 RemoteKey 区分。
容量限制
| 参数 | 默认值 | 说明 |
|---|---|---|
| 远端来源上限 | 32 | 当前设备允许配置的边缘来源数。 |
| 快照并发上限 | 4 | 同时执行的快照或同步任务数。 |
| 入站载荷字节上限 | 1048576 | 单条 MQTT 入站载荷上限。 |
| 每秒消息上限 | 200 | 全部来源进入解析器的消息速率上限。 |
| 入站处理并发上限 | 4 | 并发 JSON 处理任务数。 |
| JSON深度上限 | 64 | 协议 JSON 最大嵌套深度。 |
| 单来源目录上限 | 100000 | 一个来源的最大变量数。 |
| 目录总上限 | 300000 | 全部来源变量总数，不能小于单来源上限。 |
| RPC等待上限 | 256 | 同时等待的远程 RPC 批次数。 |
| 详细日志 | 关闭 | 记录脱敏协议摘要；排障后关闭。 |
只有在确认内存、Broker 流量和来源规模后才提高限制。
地址规则
{RemoteKey}/{RemoteVariableId}
示例：factory-a/828746157506629。
远端变量 ID 来自边缘 Gateway，不能替换为本地镜像变量 ID。
设备调试
进入“开发配置 → 采集配置”，选择 Gateway MQTT 客户端设备，打开“调试 → 协议调试 · GatewayMqttCollectClient”。
| 功能 | 作用 |
|---|---|
| 远端网关 | 查看来源连接、目录、消息计数和错误，并请求快照或测试 RPC。 |
| 远端变量 | 查询来源变量目录和在线状态。 |
| 诊断日志 | 查看按来源过滤的协议诊断事件。 |
| 变量同步 | 预览并确认远端目录同步到本地变量的差异。 |
“概览”和“运行状态”是公共工作台页，本专题不重复截图。
验证方法
- 新增一个具有唯一 RemoteKey 的远端来源。
- 确认边缘 MQTT 目标使用相同 Topic 根和 RemoteKey。
- 确认共享连接在线，远端来源状态变为在线。
- 请求快照并等待远端目录完成。
- 读取一个镜像变量并与边缘值比较。
- 仅在中心、边缘、目标和变量权限都允许时测试远程写入。
常见问题
| 现象 | 检查方法 |
|---|---|
| 共享连接无法启动 | Broker 地址、端口、客户端ID、凭据、TLS、CA 和 ACL。 |
| 来源一直离线 | RemoteKey、Topic 根、边缘目标状态、快照间隔和协议消息。 |
| 目录为空 | 边缘转发范围、变量目录上传、快照响应、载荷上限和目录限制。 |
| 多个来源数据混淆 | 每个来源必须使用唯一 RemoteKey，每个镜像地址必须使用匹配的来源键。 |
| 快照超时 | 边缘连接、请求超时、消息速率、载荷大小和 Broker 流量。 |
| 远程写入失败 | 两端远程写入开关、变量权限和 RPC 响应日志。 |
| 来源变为降级 | 离线超时、快照完成情况、边缘重连状态和诊断日志。 |
相关操作
- Gateway MQTT 采集服务端：中心监听模式的服务端专用参数。
- 采集配置：公共设备、变量、导入和调试操作。
- 证书管理：维护 MQTT 客户端证书和 CA。
- 插件索引：查找其它采集或数据转发插件。