# 配置 MQTT 桥接高级功能

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

> 如果你是第一次使用桥接，请先阅读[快速上手指南](./tcp-bridge-quick-start.md)。

完整配置项列表请参见[数据桥接配置](../config-description/bridges.md)。

## 主题映射和重映射

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
```

使用以下配置：

```hocon
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`：

```hocon
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
> ```

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

更多配置选项请参见[数据桥接配置](../config-description/bridges.md)。