# MQTT over QUIC 桥接配置参考

本页说明如何在 EMQX Edge 中配置 MQTT over QUIC 桥接。内容包括支持的配置方式、所有可用配置项（通用 MQTT 桥接参数和 QUIC 专用设置），并提供独立 MQTT over QUIC 桥接和 QUIC/TCP 混合桥接的配置示例。

## 基础配置

MQTT over QUIC 桥接可通过 EMQX Edge Dashboard 配置（推荐），也可以直接编辑配置文件。无论使用哪种方式，所有配置最终都会以 HOCON 格式持久化，并遵循相同的配置模型。

### 通过 Dashboard 配置（推荐）

EMQX Edge Dashboard 提供基于 UI 的引导式流程，用于创建和管理 MQTT over QUIC 桥接。建议在初始设置和验证时使用该方式。

有关通过 Dashboard 创建 MQTT over QUIC 桥接的分步说明，请参见[快速上手：创建 MQTT over QUIC 桥接](./quic-bridge-quick-start)。

Dashboard 字段会直接映射到本参考中描述的配置项，因此后续如需从 UI 配置切换到基于文件的管理，也很容易对应。

### 通过配置文件配置

MQTT over QUIC 桥接使用 HOCON 语法在 `nanomq.conf` 文件中配置。基于 QUIC 的桥接与其他 MQTT 桥接的定义方式相同，主要区别在于使用 QUIC 专用 server URL，并可选配置 QUIC 相关参数。

要配置 MQTT over QUIC 桥接：

1. 定义 `bridges.mqtt.<name>` 配置段以创建桥接实例。
2. 将 `server` 参数设置为 `mqtt-quic://host:port` URL。
3. 配置标准 MQTT 桥接参数，例如协议版本、认证和主题转发规则。
4. 可选配置 QUIC 专用选项，以调优连接行为和性能。

以下各节详细说明所有可用配置项。

## 配置项

以下各节说明 MQTT over QUIC 桥接可用的配置项，包括通用 MQTT 桥接参数和 QUIC 专用设置。

### 基础 MQTT 桥接参数

这些参数适用于 TCP、TLS 和 QUIC 桥接。以下仅列出最相关的选项。

| Parameter | Description | Notes / Values |
| --- | --- | --- |
| `bridges.mqtt.<name>.server` | 桥接连接的目标 MQTT Broker URL。 | 示例：<br />`mqtt-tcp://127.0.0.1:1883`（MQTT over TCP）<br />`tls+mqtt-tcp://127.0.0.1:8883`（MQTT over TLS）<br />`mqtt-quic://54.75.171.11:14567`（MQTT over QUIC） |
| `bridges.mqtt.<name>.proto_ver` | 桥接客户端使用的 MQTT 协议版本。 | `5` = MQTT v5<br />`4` = MQTT v3.1.1 |
| `bridges.mqtt.<name>.clientid` | 桥接连接使用的 Client ID。 | 如果未指定，会自动生成随机 Client ID。 |
| `bridges.mqtt.<name>.keepalive` | MQTT 协议级 Keepalive 间隔。 | 该参数不同于 QUIC 级别的 `quic_keepalive`。 |
| `bridges.mqtt.<name>.username` | 连接远端 Broker 时用于认证的用户名。 | 与 `password` 一起使用。 |
| `bridges.mqtt.<name>.password` | 连接远端 Broker 时用于认证的密码。 | - |
| `bridges.mqtt.<name>.forwards` | 定义哪些本地主题会转发到远端 Broker 的规则。 | 每条规则可包含：<br />`local_topic`：本地主题过滤器（支持通配符）<br />`remote_topic`：转发时使用的远端主题<br />可选 `qos`、`retain`、`prefix`、`suffix` 等。 |
| `bridges.mqtt.<name>.subscription` | 定义订阅哪些远端主题并在本地重新发布的规则。 | 每条规则可包含：<br />`remote_topic`：在远端 Broker 上订阅的主题<br />`local_topic`：本地重新发布使用的主题<br />`qos`：该主题的 QoS<br />可选：`retain_as_published`、`retain_handling` |

当 `server` 参数使用 `mqtt-quic://` scheme 时，上述所有 MQTT 桥接语义都会运行在 QUIC 之上。

### QUIC 专用选项

以下选项定义在 `bridges.mqtt.<name>` 下，并且仅在 `server` 参数使用 `mqtt-quic://` scheme 时生效。

#### 超时和 Keepalive

| Parameter | Type | Description | Default / Notes |
| --- | --- | --- | --- |
| `quic_keepalive` | Duration | 发送 QUIC 级 Keepalive 探测的间隔。 | 默认值：`120s` |
| `quic_idle_timeout` | Duration | QUIC 连接关闭前允许的最大空闲时间。 | 默认值：`120s`<br />设置为 `0` 可禁用 idle timeout。 |
| `quic_discon_timeout` | Duration | 在判定路径失效并断开连接前，等待 ACK 的最长时间。 | 默认值：`20s` |
| `quic_handshake_timeout` | Duration | 完成 QUIC 握手允许的最长时间。 | 默认值：`20s` |

#### 拥塞和 RTT 相关选项

| Parameter | Type | Description | Default |
| --- | --- | --- | --- |
| `quic_send_idle_timeout` | Duration | 连接空闲达到指定时间后重置拥塞控制，以便重新估算网络状况。 | `2s` |
| `quic_initial_rtt_ms` | Duration (ms) | 获得真实 RTT 测量值前使用的初始 RTT 估计值。 | `800ms` |
| `quic_max_ack_delay_ms` | Duration (ms) | 接收数据后发送 ACK 的最大延迟。 | `100ms` |

#### 多路复用和 QoS 优先级

| Parameter | Type | Description | Default |
| --- | --- | --- | --- |
| `quic_multi_stream` | Boolean | 启用 QUIC multi-stream 模式。<br />`true`：将不同主题或订阅映射到不同 stream。<br />`false`：所有流量使用单个 stream。 | `false` |
| `quic_qos_priority` | Boolean | 当链路或缓冲区拥塞时，优先处理 QoS 1/2 消息，而不是 QoS 0 流量。 | `true` |

#### 0-RTT 快速重连

| Parameter | Type | Description | Default |
| --- | --- | --- | --- |
| `quic_0rtt` | Boolean | 启用 QUIC 0-RTT，允许重连时无需等待完整握手即可发送应用数据。 | `true` |

## 混合桥接（QUIC + TCP）

混合桥接允许 EMQX Edge 结合 QUIC 的性能优势和传统 TLS/TCP 连接的稳健性。在该模式下，可以配置多个候选远端服务器，使 EMQX Edge 优先使用 QUIC，并在 QUIC 不可用或不稳定时自动回退到 TLS/TCP。

### 混合桥接选项

| Parameter | Type | Description |
| --- | --- | --- |
| `hybrid_bridging` | Boolean | 启用或禁用混合桥接模式。启用后，EMQX Edge 会从配置的候选列表中选择可用服务器。 |
| `hybrid_servers` | Array of strings | 定义候选远端 Broker URL 列表。列表顺序决定优先级。通常将 QUIC URL 放在前面，后面跟 TCP 或 TLS URL 作为回退。 |

在生产环境中，建议采用“QUIC 优先，TLS/TCP 回退”的策略。该方式允许运维人员逐步采用 QUIC，同时在 QUIC 不受支持或出现暂时故障时保持连接性和可靠性。

## 配置示例

以下示例展示 EMQX Edge 中常见的 MQTT over QUIC 桥接配置。

### MQTT over QUIC 桥接

该示例展示如何配置一个独立 MQTT 桥接，使用 QUIC 作为传输协议，将 EMQX Edge 连接到远端 Broker。

```hcl
bridges.mqtt.emqx_quic {
  server    = "mqtt-quic://your_server_address:14567"
  proto_ver = 4
  clientid  = "bridge_client"
  username  = "username"
  password  = "password"
  keepalive = "60s"

  # QUIC-specific options
  quic_keepalive         = "120s"
  quic_idle_timeout      = "120s"
  quic_discon_timeout    = "20s"
  quic_handshake_timeout = "20s"
  quic_send_idle_timeout = "2s"
  quic_initial_rtt_ms    = "800ms"
  quic_max_ack_delay_ms  = "100ms"
  quic_multi_stream      = false
  quic_qos_priority      = true
  quic_0rtt              = true
  hybrid_bridging        = false

  forwards = [
    { remote_topic = "fwd/topic1", local_topic = "topic1", qos = 1 },
    { remote_topic = "fwd/topic2", local_topic = "topic2", qos = 2 }
  ]

  subscription = [
    { remote_topic = "cmd/topic1", local_topic = "topic3", qos = 1 },
    { remote_topic = "cmd/topic2", local_topic = "topic4", qos = 2 }
  ]

  max_parallel_processes = 2
  max_send_queue_len     = 32
  max_recv_queue_len     = 128
}
```

### QUIC/TCP 混合桥接

该示例展示一个混合桥接配置：远端连接优先使用 QUIC，当 QUIC 不可用时自动回退到 MQTT over TCP。

```hcl
bridges.mqtt.emqx_hybrid {
  server    = "mqtt-quic://your_server_address:14567"

  # Hybrid bridging: prefer QUIC, fall back to TCP
  hybrid_bridging = true
  hybrid_servers  = [
    "mqtt-tcp://your_server_address:1883"
  ]

  quic_keepalive      = "120s"
  quic_idle_timeout   = "120s"
  quic_discon_timeout = "20s"
  quic_0rtt           = true
  quic_qos_priority   = true
}
```