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 桥接。

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。	示例： mqtt-tcp://127.0.0.1:1883（MQTT over TCP） tls+mqtt-tcp://127.0.0.1:8883（MQTT over TLS） mqtt-quic://54.75.171.11:14567（MQTT over QUIC）
bridges.mqtt.<name>.proto_ver	桥接客户端使用的 MQTT 协议版本。	5 = MQTT v5 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 的规则。	每条规则可包含： local_topic：本地主题过滤器（支持通配符） remote_topic：转发时使用的远端主题 可选 qos、retain、prefix、suffix 等。
bridges.mqtt.<name>.subscription	定义订阅哪些远端主题并在本地重新发布的规则。	每条规则可包含： remote_topic：在远端 Broker 上订阅的主题 local_topic：本地重新发布使用的主题 qos：该主题的 QoS 可选：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 设置为 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 模式。 true：将不同主题或订阅映射到不同 stream。 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。

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。

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
}