配置 MQTT 桥接高级功能

本指南介绍 EMQX Edge 中 MQTT over TCP 桥接可用的高级功能配置。这些功能可对边缘与云端之间的数据桥接方式进行细粒度控制，帮助在真实部署中优化性能、路由和可靠性。

如果你是第一次使用桥接，请先阅读快速上手指南。

完整配置项列表请参见数据桥接配置。

主题映射和重映射

EMQX Edge 支持在本地 Broker 与远端 Broker 之间动态转换主题，包括：

• 移除或修改主题前缀
• 替换主题层级中的部分内容
• 保留或重塑主题中的特定片段

在本地和远端 Broker 使用不同主题结构的桥接部署中，这项能力尤其有用。它有助于在无需手动重新配置的情况下保持一致的路由逻辑，并支持构建统一命名空间（UNS）。

基于通配符的主题转换

EMQX Edge 使用 MQTT 通配符作为主题重映射模式：

• +：精确匹配主题层级中的一级，例如一个单独片段。
• #：匹配零级或多级主题层级，且必须出现在主题模式末尾。

这些通配符可作为动态片段的占位符，使 EMQX Edge 能够根据匹配结果处理传入或传出的主题。

你可以在 remote_topic 和 local_topic 字段中使用这些通配符，并可选应用 prefix 和 suffix，用于在匹配后修改生成的主题。

示例：订阅时进行主题重映射

假设你希望在订阅时移除前缀 system/nano，并添加自定义前缀 cmd/ 和后缀 /remote。

如果远端 Broker 上的消息主题为：

system/nano/start

使用以下配置：

bridges.mqtt.mybridge {
  ...
  subscription = [
    {
      remote_topic = "+/nano/#"   # Matches topics like system/nano/start
      local_topic  = "#"          # Preserves only the matched suffix (start)
      prefix       = "cmd"
      suffix       = "remote"
    }
  ]
}

生成的本地主题为：

cmd/start/remote

前缀和后缀会在通配符过滤后应用。

该模式也可用于转发规则，从而在两个方向上实现一致的主题转换。

透明桥接

透明桥接是一种自动转发模式，会将本地客户端的所有订阅和取消订阅请求自动转发到远端 Broker。该模式无需预定义主题配置，适用于希望远端 Broker 镜像所有本地客户端订阅的场景。

要启用透明桥接，请在配置中将 transparent 字段设置为 true：

bridges.mqtt.mybridge {
  transparent = true
}

启用后，EMQX Edge 会动态转发本地客户端的所有订阅活动到远端桥接目标。

混合桥接

混合桥接允许为单个桥接定义多个目标服务器。如果某个服务器不可用，EMQX Edge 会自动尝试连接列表中的下一个服务器。

这种方式可提升连接韧性，也支持从 QUIC 等现代协议回退到 TLS/TCP 等传统协议。

配置示例

bridges.mqtt.mybridge {
  hybrid_bridging = true
  hybrid_servers = [
    "mqtt-quic://127.0.0.1:14567",
    "mqtt-tcp://127.0.0.1:1883",
    "tls+mqtt-tcp://127.0.0.1:8883",
    "mqtt-tcp://127.0.0.1:1884"
  ]
}

在重连尝试中，EMQX Edge 会按顺序尝试每个 URL，直到成功建立连接。

绑定网络接口

在具有多个网络接口的生产环境中，通常需要将 MQTT 桥接流量绑定到指定接口，以满足性能、安全或路由需求。

你可以使用 tcp 配置段中的 bind_interface 设置控制使用哪个接口。

配置示例

bridges.mqtt.mybridge {
  tcp {
    bind_interface = wlan0
    nodelay = false
  }
}

• bind_interface：指定桥接流量应绑定到的网络接口名称，例如 wlan0。这可确保数据包通过指定接口发送。
• nodelay：
  • 设置为 true 时，如果初次接口绑定失败，EMQX Edge 会持续重试。该设置适用于严格网络场景，在这些场景中不允许回退到系统默认路由。
  • 设置为 false 时，会忽略绑定失败，并在当前周期跳过该连接尝试。

当接口绑定是强制要求，且必须阻止回退行为时，请设置 nodelay = true。

消息缓存和重试

在真实部署中，尤其是边缘场景下，不稳定或较慢的网络条件可能导致消息重传、拥塞以及最终数据丢失。EMQX Edge 提供可配置的缓存和重试机制，以提升此类环境中的消息投递可靠性。

这些设置可细粒度控制桥接如何处理飞行消息、重试时机和取消策略。

配置示例

bridges.mqtt.emqx1 {
  keepalive            = 30s
  max_send_queue_len   = 512
  resend_interval      = 5000
  resend_wait          = 3000
  cancel_timeout       = 10000
}

• keepalive：桥接连接的心跳间隔，也作为重试逻辑的时间参考。
• max_send_queue_len：可缓存（排队）等待重传的最大消息数，可视为 QoS 消息的飞行窗口。
• resend_interval（ms）：QoS 消息重试尝试之间的间隔。为获得较好性能，通常设置为 keepalive 值的 1/2 或 1/4。
• resend_wait（ms）：失败消息首次重试前的等待时间。如果希望避免重复 QoS 消息，请将该值设置为大于 keepalive。
• cancel_timeout（ms）：在未收到确认时等待多久后丢弃消息。它定义了每条消息的总重试窗口。

提示：要确保消息至少重试一次，可使用以下公式：

(cancel_timeout - resend_wait) / resend_wait > 1

合理调优这些值对于在较差网络条件下保障消息可靠投递十分关键，同时也可避免过度重试或缓冲区溢出。

更多配置选项请参见数据桥接配置。