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

本指南演示如何使用免费公共 MQTT Broker 创建 MQTT over TCP 桥接。该桥接用于在 EMQX Edge 与远端 Broker 之间转发 MQTT 消息。你可以通过 Dashboard 或配置文件进行配置。

通过 Dashboard 创建 MQTT 桥接

按照以下步骤使用 EMQX Edge Dashboard 配置 MQTT over TCP 桥接。

第 1 步：打开桥接创建向导

1. 在 Dashboard 中，进入 Bridges。
2. 在 Bridges 页面右上角点击 Add。
3. 桥接配置表单会显示以下标签页：
   • Connector
   • Forwards
   • Subscriptions
   • Security
   • Advanced

第 2 步：设置 Connector

Connector 标签页定义 EMQX Edge 如何连接到远端 MQTT Broker。

配置桥接连接设置：

• Name：为桥接指定唯一名称，例如 emqx1。

• Server：远端 Broker 地址。EMQX Edge 支持协议和传输解耦的设计，URL 前缀用于定义 MQTT 的传输层。你可以使用不同前缀表示通过 TCP、TLS over TCP 或 QUIC 连接。支持的协议包括：

  • mqtt-tcp
  • tls+mqtt-tcp
  • mqtt-quic

  本示例中，将地址设置为 mqtt-tcp://broker.emqx.io:1883。

• Protocol version：MQTT 协议版本：

  • 5 表示 MQTT 5.0
  • 4 表示 MQTT 3.1.1

  示例：4

• Client ID：该桥接连接的唯一标识，例如 bridge_client。如果省略，会生成随机 ID。

• Clean start：布尔标志，部分平台需要该设置。启用后，桥接每次连接都会启动新会话；禁用后，会尝试恢复之前的会话。

• Username/Password：用于向远端 Broker 认证的凭据。本示例设置为 username/password。

• Keepalive：可选的 Keepalive 间隔，单位为秒，用于保持连接。

第 3 步：定义转发规则

Forwards 标签页定义如何将 EMQX Edge 中的消息转发到远端 MQTT Broker。

创建消息转发规则：

1. 点击 Add。
2. 配置以下字段：
   • Local Topic：本地 EMQX Edge 实例上的主题
   • Remote Topic：远端 Broker 上的目标主题
   • QoS：选择 0、1 或 2

转发规则示例：

Local Topic	Remote Topic	QoS
topic1	fwd/topic1	1

之后可以使用操作按钮编辑或删除每条规则。

第 4 步：定义订阅规则

Subscriptions 标签页定义 EMQX Edge 如何从远端 Broker 订阅主题，并将收到的消息在本地重新发布。

创建订阅规则：

1. 点击 Add。

2. 配置以下字段：

   • Remote topic：远端 Broker 上的主题

   • Local topic：EMQX Edge 上对应的主题

   • QoS：选择 0、1 或 2

订阅规则示例：

Remote Topic	Local Topic	QoS
cmd/topic3	topic3	1

之后可以使用操作按钮编辑或删除每条规则。

第 5 步：安全和高级设置（可选）

Security 标签页允许启用 TLS，以便与远端 Broker 建立安全的加密连接，例如 tls+mqtt-tcp://broker.emqx.io:8883。启用后，你可以配置以下字段：

• Key Password：用于解锁私钥文件的密码。
• Key：私钥文件路径，例如 /etc/certs/key.pem。
• Cert：证书文件路径，例如 /etc/certs/cert.pem。
• Cacert：CA 证书文件路径，例如 /etc/certs/cacert.pem。
• Verify Peer：启用后，客户端会验证服务端证书的真实性。
• Fail if No Peer Cert：启用后，如果服务端未提供证书，连接将失败。

Advanced 标签页允许定义以下选项：

• Max parallel processes：桥接使用的并发连接数。默认值为 2。如需提升吞吐量，可按需增大。

第 6 步：保存并应用桥接配置

1. 点击 Save 应用桥接设置。
2. 点击 Save 后，系统会提示桥接配置将在重启 EMQX Edge 后生效。点击 Confirm 关闭提示。

EMQX Edge 重启后，新桥接会显示在 Bridges 列表中。你可以通过 Action 列中的开关启用或禁用桥接。禁用后，桥接不会连接或交换数据，Bridges 页面也不会显示相关指标。

通过配置文件创建 MQTT 桥接

本节演示如何通过配置文件在 EMQX Edge 与免费公共 MQTT Broker 之间建立 MQTT over TCP 数据桥接，用于转发和接收消息。

方式 1：通过 Dashboard 添加配置（All configurations）

如果你更偏好在 EMQX Edge Dashboard 中操作，可以直接将桥接配置粘贴到 Settings -> All configurations 页面：

1. 在左侧菜单中进入 Settings。

2. 点击 All configurations 标签页。

3. 将以下配置片段添加到编辑器中，以定义桥接配置：

   bridges.mqtt.emqx1 {
     server = "mqtt-tcp://broker.emqx.io:1883"
     proto_ver = 5
     clientid = "bridge_client"
     keepalive = 60s
     clean_start = false
     username = username
     password = passwd
   
     forwards = [
       {
         remote_topic = "fwd/topic1"
         local_topic = "topic1"
         qos = 1
       }
     ]
   
     subscription = [
       {
         remote_topic = "cmd/topic3"
         local_topic = "topic3"
         qos = 1
       }
     ]
   
     max_parallel_processes = 2
     max_send_queue_len = 32
     max_recv_queue_len = 128
   }

4. 点击 Save，然后重启 EMQX Edge 使变更生效。

方式 2：编辑 nanomq.conf 文件

1. 打开 /etc 目录下的配置文件 nanomq.conf。
2. 将以下 HOCON 配置片段添加到配置文件中，以定义桥接配置：

bridges.mqtt.emqx1 {
  server = "mqtt-tcp://broker.emqx.io:1883"
  proto_ver = 5
  clientid = "bridge_client"
  keepalive = 60s
  clean_start = false
  username = username
  password = passwd

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

  subscription = [
    {
      remote_topic = "cmd/topic3"
      local_topic = "topic3"
      qos = 1
    }
  ]

  max_parallel_processes = 2
  max_send_queue_len = 32
  max_recv_queue_len = 128
}

使用桥接配置启动 EMQX Edge

运行以下命令，使用本地配置文件启动 EMQX Edge：

emqx-edge start --conf /path/to/your/nanomq.conf --license /path/to/your/nanomq.lic

将 /path/to/your/nanomq.conf 替换为本地机器上 nanomq.conf 文件的实际路径。

完整配置项列表请参见数据桥接配置。配置会在 EMQX Edge 重启后生效。

TIP

如果你使用 HOCON 格式配置项并且 EMQX Edge 版本为 0.19 或更高版本，可以将桥接相关配置直接写入 nanomq.conf，也可以放入独立文件（例如 nanomq_bridge.conf），再通过 HOCON 的 include 指令在 nanomq.conf 中引用：

示例：

include "path/to/nanomq_bridge.conf"

如需在运行时查看更多日志数据，可以在配置文件中设置日志等级 log.level。

测试 MQTT 数据桥接

本节演示如何使用 MQTTX 模拟客户端，测试 EMQX Edge 与公共 MQTT Broker 之间的数据桥接。你将创建两个连接，一个连接到 EMQX Edge，另一个连接到远端 MQTT Broker，以验证双向消息转发。

连接客户端到 EMQX Edge

在 MQTTX 中创建名为 NanoMQTest 的客户端，连接到 localhost:1883。

连接客户端到远端 MQTT Broker

在 MQTTX 中创建另一个名为 MQTTbridge 的客户端，连接到 broker.emqx.io:1883。

测试从 EMQX Edge 到远端 Broker 的消息转发

1. 在 MQTTbridge 客户端中订阅主题 fwd/#。
2. 在 NanoMQTest 客户端中向 topic1 发布消息，例如 Hello from NanoMQ。
3. 确认消息出现在 MQTTbridge 客户端中，表示转发成功。

测试从远端 Broker 到 EMQX Edge 的消息订阅

1. 在 NanoMQTest 客户端中订阅主题 topic3。
2. 在 MQTTbridge 客户端中向 cmd/topic3 发布消息，例如 Hello from broker.emqx.io。
3. 验证 NanoMQTest 客户端是否收到消息，以确认订阅成功。

查看桥接指标和状态

完成消息转发和接收测试后，你可以在 Dashboard 的 Bridges 页面查看桥接状态和指标。