Gateway MQTT 专用采集

Gateway MQTT 专用采集用于把多台边缘 Gateway 的变量汇聚到一台中心 Gateway。中心端只创建一个采集设备：使用 GatewayMqttCollectClient 时只建立一条到共享 Broker 的连接；使用 GatewayMqttCollectServer 时只开放一个 MQTT 监听端口。每台边缘 Gateway 通过稳定的 RemoteKey 隔离目录、实时值、快照、在线状态和远程写入。

与普通 MQTT 采集的区别

普通 MqttCollectClient、MqttCollectServer 面向任意 Topic 和 JSON 字段映射；Gateway MQTT 专用采集只接收 ThingsGateway 当前固定协议。不要把普通 MQTT 变量地址、JSONPath 或任意发布调试配置复制到专用采集设备中。

选择运行模式

模式	适用网络	中心端行为	边缘端行为
GatewayMqttCollectClient	已有统一 Broker，或各网关都只能主动出站	以一个固定 ClientId 连接 Broker，并订阅全部已配置来源	多个 MqttClientProducer 连接同一 Broker，并按各自 RemoteKey 发布
GatewayMqttCollectServer	中心 Gateway 可以开放 MQTT 入站端口	在一个端口监听多个边缘客户端，并按 ClientId、账号和可选证书指纹绑定来源	多个 MqttClientProducer 直接连接中心 Gateway

配置前准备

1. 为每台边缘 Gateway 分配不会变化的 RemoteKey，仅使用英文字母、数字、连字符或下划线。
2. 确认中心端和边缘端使用相同的 Topic 根，默认是 ThingsGateway/Gateway。
3. 在每台边缘 Gateway 的数据转发页面创建 MqttClientProducer，关闭 Retain，并按下文配置变量、数据请求和 RPC Topic。
4. 需要远程写入时，先确认边缘 Producer、中心采集设备和目标变量三处权限都允许写入。
5. 生产环境使用 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 上执行以下操作：

1. 登录 GatewayRuntime Web，进入“开发配置 → 数据转发”。
2. 新建并启用数据转发组，在组变量范围中加入需要汇聚的变量；组范围未包含的变量不会上传。
3. 在该组中新建转发目标，插件选择 MqttClientProducer，并启用目标。
4. 按所选模式配置连接地址，再按当前边缘 Gateway 的 RemoteKey 配置固定 Topic。
5. 保存后确认目标在线且没有 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 专用采集使用。

新建采集设备

登录 GatewayRuntime Web，进入“开发配置 → 采集配置”，切换到“设备显示”，新建采集设备并选择 GatewayMqttCollectClient 或 GatewayMqttCollectServer。

公共参数

参数	说明
Topic根	全部来源共用的固定 Topic 根。中心端和所有边缘 Producer 必须完全一致。
允许远程写入	中心端远程写入总开关。关闭时仍可采集，但不会向边缘端发起变量写入。
快照间隔（秒）	周期请求完整快照的间隔，范围 10 至 3600。
请求超时（秒）	快照和 RPC 请求的等待时间，范围 1 至 600。
离线超时（秒）	来源长时间没有合法协议消息后转为离线；必须大于快照间隔。
远端来源上限	单个采集设备允许配置的来源数量。
快照并发上限	多来源同时执行快照或变量同步时的并发数。
入站载荷字节上限	单条 MQTT 消息允许的最大字节数。
每秒消息上限	全部来源进入解析器的总速率上限。
入站处理并发上限	JSON 消息并发处理数量。
JSON深度上限	固定协议 JSON 的最大嵌套深度。
单来源目录上限 / 目录总上限	限制单个来源和全部来源的变量目录规模。
RPC等待上限	同时等待远端响应的 RPC 批次数量。
详细日志	记录脱敏协议摘要。联调时开启，稳定运行后关闭。

Client 模式参数

参数	说明
连接类型、IP地址、端口	共享 Broker 的连接方式和地址。
WebSocket路径	仅 WebSocket/WSS 模式使用，必须与 Broker 一致。
启用SSL、SSL目标主机名	控制 TLS/WSS，并校验 Broker 证书中的主机名。
客户端证书名称、CA名称	双向 TLS 使用的客户端证书和校验 Broker 的 CA。
允许不受信任证书	生产环境保持关闭。
SSL协议版本、检查证书吊销	按现场安全策略设置。
客户端ID	中心 Collector 在 Broker 上使用的稳定 ClientId，不能与其它客户端重复。
用户名、密码	中心 Collector 的 Broker 账号。
保活时间、清除会话、MQTT协议版本	共享连接的会话参数。
连接超时	建立共享连接的等待时间，单位毫秒。
远端来源	维护多个 RemoteKey、显示名称、启用状态和 QoS。Client 模式不在这里配置边缘账号。

Server 模式参数

参数	说明
连接类型、端口	中心 Gateway 的 MQTT 监听方式和端口。
WebSocket路径	仅 WebSocket/WSS 监听使用。
启用SSL、服务端证书名称、CA名称	启用 TLS/WSS 后提供服务端证书，并使用 CA 校验边缘客户端证书。
允许不受信任证书	生产环境保持关闭。
SSL协议版本、检查证书吊销	按现场安全策略设置。
远端来源	每个来源配置 RemoteKey、显示名称、启用状态、QoS、唯一 AllowedClientId、独立用户名和密码。
ClientCertificateSha256	可选的客户端证书 SHA-256 小写十六进制指纹。启用一个来源的指纹绑定时，全部启用来源都必须配置。

Server 的 TCP 监听允许已授权边缘端使用相同 AllowedClientId 正常重连。新连接会先完成 ClientId、账号和可选证书指纹校验，再自动关闭仍占用该 ClientId 的旧连接并接管会话，因此采集通道重启或网络恢复时不需要手工清理旧客户端。这个接管规则只用于同一来源的连接替换，不允许两个边缘 Gateway 共用一个 ClientId；WebSocket/WSS 模式仍应确保旧连接已经关闭后再重连。

配置变量

中心采集变量的地址固定为：

RemoteKey/RemoteVariableId

例如 edge-01/828746157506629。RemoteKey 必须已经存在于当前采集设备的“远端来源”中，RemoteVariableId 使用边缘变量的稳定 ID。推荐先在专用调试页获取远端变量目录，再使用“同步当前远端”或“同步全部远端”创建和更新本地镜像变量，不要手工猜测变量 ID。

同步只新增镜像变量，并只更新数据类型、单位和描述；本地变量名称、表达式、报警、历史和写权限由中心 Gateway 维护。边缘变量删除或移出范围后，本地镜像不会被自动删除，而是在调试页标记来源缺失。

专用调试页

进入“采集配置 → 设备显示”，选择 Gateway MQTT 专用采集设备，再打开“调试”标签。专用页面显示共享传输、聚合状态、远端网关、远端变量、诊断日志和变量同步，不提供任意 Topic 或任意 Payload 发布入口。

移动端会把远端来源表转换为纵向记录，状态、身份绑定和 ClientId 不会挤压在同一行。

页面区域	用途
共享传输	判断中心端是否已经连接 Broker，或 MQTT Server 是否正在监听。
聚合状态	Online 表示全部启用来源在线；Degraded 表示至少一个来源仍可用但不是全部在线；Offline 表示共享传输不可用或没有可用来源。
远端网关	查看每个 RemoteKey 的状态、身份绑定、目录数量、最近消息、最近快照和错误。
远端变量	按来源查看远端目录、映射和在线状态。
诊断日志	查看脱敏的协议拒绝、限流、快照和 RPC 结果。
变量同步	同步当前来源或全部来源，并按 OperationId 查看逐来源结果。

采集设备显示在线需要同时满足：共享传输可用、至少一个来源为 Online 或 Degraded，并且至少一个镜像变量在线。共享传输断开后，即使页面短暂保留上一轮来源快照，设备也会立即转为离线。

常见问题

现象	处理方法
共享传输未就绪	Client 模式检查 Broker 地址、账号、ClientId、TLS 和 Topic ACL；Server 模式检查监听端口、证书和端口占用。
来源一直 Offline	检查边缘 Producer 是否使用相同 Topic 根和 RemoteKey，Server 模式还要精确核对 ClientId、用户名和密码。
TCP 重连后提示 ClientId 已存在	当前版本会自动接管同一来源的旧 TCP 会话。先确认中心端和边缘端都已更新并重启，再检查是否有两个边缘 Gateway 误用了同一个 ClientId；WebSocket/WSS 模式需先关闭旧连接。
目录有变量但设备离线	查看镜像变量是否在线，并确认边缘端仍在发送合法实时值或快照。
变量地址无效	地址只能使用 RemoteKey/RemoteVariableId；不要填写普通 MQTT Topic 或 JSONPath。
同步后本地名称没有变化	这是预期行为。本地名称、表达式、报警、历史和写权限由中心端维护。
远程写入被拒绝	同时检查中心设备“允许远程写入”、边缘 Producer 的 RPC 配置、变量写权限和用户权限。
单个来源异常影响其它来源	检查是否发生共享 Broker/监听故障。普通来源协议错误只会隔离当前 RemoteKey；共享传输故障才会影响全部来源。

相关说明：采集配置、设备调试、插件属性、证书管理。