Gateway MQTT 专用采集
Gateway MQTT 专用采集用于把多台边缘 Gateway 的变量汇聚到一台中心 Gateway。中心端只创建一个采集设备：使用 GatewayMqttCollectClient 时只建立一条到共享 Broker 的连接；使用 GatewayMqttCollectServer 时只开放一个 MQTT 监听端口。每台边缘 Gateway 通过稳定的 RemoteKey 隔离目录、实时值、快照、在线状态和远程写入。
普通 MqttCollectClient、MqttCollectServer 面向任意 Topic 和 JSON 字段映射；Gateway MQTT 专用采集只接收 ThingsGateway 当前固定协议。不要把普通 MQTT 变量地址、JSONPath 或任意发布调试配置复制到专用采集设备中。
选择运行模式
| 模式 | 适用网络 | 中心端行为 | 边缘端行为 |
|---|---|---|---|
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 专用采集使用。
新建采集设备
登录 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 发布入口。
| 页面区域 | 用途 |
|---|---|
| 共享传输 | 判断中心端是否已经连接 Broker，或 MQTT Server 是否正在监听。 |
| 聚合状态 | Online 表示全部启用来源在线；Degraded 表示至少一个来源仍可用但不是全部在线；Offline 表示共享传输不可用或没有可用来源。 |
| 远端网关 | 查看每个 RemoteKey 的状态、身份绑定、目录数量、最近消息、最近快照和错误。 |
| 远端变量 | 按来源查看远端目录、映射和在线状态。 |
| 诊断日志 | 查看脱敏的协议拒绝、限流、快照和 RPC 结果。 |
| 变量同步 | 同步当前来源或全部来源，并按 OperationId 查看逐来源结果。 |
采集设备显示在线需要同时满足：共享传输可用、至少一个来源为 Online 或 Degraded，并且至少一个镜像变量在线。共享传输断开后，即使页面短暂保留上一轮来源快照，设备也会立即转为离线。
保存、启用与验证
- 先保存并启用边缘端数据转发组和 MQTT 上传目标，确认目标在线且持续发送。
- 在中心端保存采集设备和远端来源，再启用设备。
- 打开专用调试页，确认共享传输可用、目标
RemoteKey已认证且目录数量大于 0。 - 执行“同步当前远端”，确认创建或更新的镜像变量没有失败项。
- 改变一个安全测试变量，确认中心镜像值、采集时间和在线状态更新。
- 需要远程写入时，另行验证中心写入、边缘 RPC 权限和现场反馈。
通过标准：共享传输可用，预期来源在线，目录和镜像变量一致，实时值能够持续更新；启用反向写入的项目还要完成一次安全写入和回读。
常见问题
| 现象 | 处理方法 |
|---|---|
| 共享传输未就绪 | 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；共享传输故障才会影响全部来源。 |