MQTT 数据桥接

MQTT 数据桥接是 EMQX Edge 的核心能力之一，用于在边缘部署和上游 MQTT Broker 之间转发 MQTT 消息。它提供了一种灵活、可靠的方式，将边缘侧设备流量连接到云端，同时将设备连接与上游网络状况解耦。

通过 MQTT 数据桥接，设备使用标准 MQTT 协议连接到 EMQX Edge，由 EMQX Edge 负责向上游 Broker 进行消息转发、订阅和传输方式选择。

EMQX Edge 中的 MQTT 数据桥接是什么

在 EMQX Edge 中，MQTT 数据桥接相当于一个运行在 Broker 内部的 MQTT 客户端。它会连接到上游 MQTT Broker，并执行以下功能：

• 将选定的本地主题从边缘端转发到上游 Broker
• 订阅上游主题，并在本地重新发布
• 保留 QoS 等级、Retain 标志和主题映射等 MQTT 语义

从设备视角来看，桥接是透明的。设备仍然只与 EMQX Edge 通信，由 EMQX Edge 负责云边数据交换。

支持的桥接传输协议

EMQX Edge 的 MQTT 数据桥接支持多种传输协议，用户可以根据网络状况和部署要求选择最合适的方式。

MQTT over TCP 桥接

MQTT over TCP 桥接使用传统 TCP 或 TLS/TCP 作为 EMQX Edge 与上游 Broker 之间 MQTT 连接的传输层。

该桥接类型支持广泛、部署简单，适用于大多数稳定网络环境。

了解更多：MQTT over TCP 桥接

MQTT over QUIC 桥接

MQTT over QUIC 桥接使用 QUIC 作为边缘到云端 MQTT 连接的传输层。QUIC 运行在 UDP 之上，旨在提供更快的连接建立速度，并改善弱网或高延迟网络中的连接表现。

该桥接类型适用于移动网络、跨地域部署，或存在丢包和频繁重连的环境。

了解更多：MQTT over QUIC 桥接

何时使用 MQTT 数据桥接

MQTT 数据桥接常用于以下场景：

• 在边缘端汇聚设备数据并转发到云端
• 在不修改设备固件的情况下改善云边连接
• 适应不稳定、高延迟或易丢包的网络环境
• 在保持可靠性的同时逐步引入新的传输技术

在 Dashboard 中使用 MQTT over TCP 桥接

EMQX Edge Dashboard 提供了易用的 Web 界面，可用于配置和管理桥接，无需手动编辑配置文件。

查看桥接状态和指标

你可以在 EMQX Edge Dashboard 的两个位置监控桥接性能：

Monitor 页面

进入 Monitor > Overview，在 Bridges 区域查看基础桥接指标。

这里会显示每个桥接的摘要信息，包括：

• Name：桥接自定义名称
• Sent Messages Number：发送到远端 Broker 的消息数
• Received Messages Number：从远端 Broker 接收的消息数
• Sent Bytes：发送的数据总量
• Received Bytes：接收的数据总量

这些信息可用于快速确认消息流量是否正常。

Bridges 页面

进入 Bridges 查看所有已配置的 MQTT 桥接。桥接列表以表格形式展示每个桥接，帮助你详细查看其状态和性能。

每个桥接都会在表格中显示关键指标，便于你快速评估性能和连接健康状况：

• Message Counts

  • Dropped / Sent messages number：本地 Broker 成功发送的消息数，以及被丢弃的消息数

  • Dropped / Received messages number：从远端 Broker 成功接收的消息数，以及被丢弃的消息数

• Data Transfer

  • Sent bytes：通过该桥接发送的数据总量，单位为字节

  • Received bytes：通过该桥接接收的数据总量，单位为字节

• Connection Health

  • Reconnect times：桥接连接重新建立的次数，可用于监控连接稳定性
  • Cached message size：桥接缓存中当前存储的消息数，即连接恢复后等待发送的消息

管理桥接

在 Bridges 页面中，每个桥接都提供以下操作按钮：

• Enable / Disable：临时启用或禁用桥接，无需删除桥接。
• Edit：修改连接、转发或订阅设置。
• Delete：永久删除桥接。

添加新桥接

要创建新桥接，点击右上角的 Add 按钮。系统会打开引导式配置流程，你可以配置：

• 连接设置
• 转发规则
• 订阅规则

详细步骤请参见：

• 快速上手：创建 MQTT over TCP 桥接
• 快速上手：创建 MQTT over QUIC 桥接

监控桥接和客户端连接状态

EMQX Edge 提供系统级 MQTT 主题（以 $SYS/ 为前缀），用于发布客户端和桥接的实时状态更新。这些主题可帮助监控连接事件，例如客户端或桥接何时连接或断开。每条消息都包含桥接配置中由 clientid 定义的唯一客户端标识。

该机制便于构建 Dashboard、监控工具或告警系统，用于实时跟踪桥接和客户端的健康状态与连接情况。

通过系统主题查看连接事件

要观察桥接或客户端连接状态：

1. 使用任意 MQTT 客户端，例如 MQTTX。
2. 连接到 EMQX Edge。
3. 订阅相关系统主题，例如：

$SYS/brokers/client_status/#

这样即可实时接收连接和断开连接事件消息。

消息格式示例

以下示例展示 EMQX Edge 为客户端连接和断开连接事件发布的系统事件消息格式。不同 EMQX Edge 版本中的消息格式略有差异。

在线事件（v1.2.0 之前）

Topic: $SYS/brokers/connected
Message: {"username":"hello", "ts":1691225605933,"proto_name":"MQTT","keepalive":60,"return_code":"0","proto_ver":4,"client_id":"nanomq-8a2a5c2e","clean_start":1, "IPv4":"127.0.0.1"}

离线事件（v1.2.0 之前）

Topic: $SYS/brokers/disconnected
Message: {"username":"hello","ts":1691225608391,"reason_code":"8b","client_id":"nanomq-8a2a5c2e","IPv4":"127.0.0.1"}

合并后的状态主题（自 v1.2.0 起）

从 v1.2.0 开始，在线/离线事件会发布到统一主题：

Topic: $SYS/brokers/client_status/${clientid}

在线事件

Topic: $SYS/brokers/client_status/${clientid}
Message: {"status":"online", "username":"hello", "ts":1691225605933,"proto_name":"MQTT","keepalive":60,"return_code":"0","proto_ver":4,"client_id":"nanomq-8a2a5c2e","clean_start":1, "IPv4":"127.0.0.1"}

离线事件

Topic: $SYS/brokers/client_status/${clientid}
Message: {"status":"offline", "username":"hello","ts":1691225608391,"reason_code":"8b","client_id":"nanomq-8a2a5c2e","IPv4":"127.0.0.1"}

使用 Retained 消息保存最新状态

这些系统事件支持 MQTT retain 标志，表示最新连接状态会被保存。当新的订阅者连接并订阅 $SYS/brokers/client_status/# 时，会立即收到每个客户端或桥接的最后已知状态。

桥接管理最佳实践

正确设置和管理桥接，是确保 EMQX Edge 与远端 MQTT Broker 之间数据流可靠、高效的关键。Dashboard 提供可视化界面，可简化这一过程，让你专注于应用逻辑，而不是复杂的配置语法。请遵循以下最佳实践来优化 MQTT over TCP 桥接。

监控建议

1. 定期检查桥接状态 确保每个桥接都保持连接。非预期断开可能表示认证或网络存在问题。
2. 监控重连次数 较高的重连次数可能表示网络不稳定、Keepalive 间隔配置不当，或远端 Broker 不可用。
3. 跟踪丢弃消息 频繁出现发送或接收消息丢弃，可能表示存在以下问题：
   • 队列溢出
   • QoS 设置不正确
   • 网络状况较差
4. 观察缓存消息数量 持续增长的缓存可能表示桥接已断开，或远端 Broker 处理消息速度不足。

配置建议

1. 使用描述性桥接名称 使用清晰的名称体现桥接用途或目标，例如 cloud_bridge_ny、emqx_enterprise_main。这有助于在存在多个桥接的环境中进行管理。
2. 优先从 QoS 1 开始
   • 大多数应用可使用 QoS 1，在可靠性和性能之间取得较好平衡。
   • 仅在需要恰好一次投递时使用 QoS 2。它可避免消息重复，但开销更高。
   • 对非关键数据或可容忍丢失的场景使用 QoS 0，此时消息最多发送一次，不保证投递。
3. 生产部署前先测试 在生产环境使用前，先通过测试主题验证桥接设置。这有助于尽早发现配置错误。
4. 调优性能参数 监控吞吐量，并根据消息量和系统容量调整 max_parallel_processes 等配置。避免过度配置，以免造成资源竞争。

TIP

对于长期运行或大规模部署，建议启用日志和监控工具，以便在桥接故障或性能下降时触发告警。

桥接问题排查

如果桥接未按预期工作，可参考下表识别常见问题及处理方式。

Issue	Possible Cause	Recommended Action
Connection Failures	Broker 地址无效、凭据错误或网络问题	检查 Broker 地址、认证凭据和网络连通性。
Message Loss	使用 QoS 0、连接断开或网络不稳定	使用合适的 QoS 等级，验证网络状况，并检查消息缓存设置。
High Latency	网络性能问题或并行度不足	减少并行连接数，或评估网络性能。
Authentication Errors	用户名/密码错误或 TLS 证书问题	验证登录凭据和 TLS 证书配置。
High Reconnect Counts	网络不稳定或 Keepalive 配置不当	检查网络可靠性，并微调 Keepalive 间隔。