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

本指南演示如何使用[免费公共 MQTT Broker](https://www.emqx.com/zh/mqtt/public-mqtt5-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 间隔，单位为秒，用于保持连接。

![bridge-connector](./assets/bridge-connector.png)

### 第 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](https://www.emqx.com/zh/mqtt/public-mqtt5-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 配置片段添加到配置文件中，以定义桥接配置：

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

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

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

完整配置项列表请参见[数据桥接配置](../config-description/bridges.md)。配置会在 EMQX Edge 重启后生效。

::: tip

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

示例：

```bash
include "path/to/nanomq_bridge.conf"
```

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

:::

## 测试 MQTT 数据桥接

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

### 连接客户端到 EMQX Edge

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

![Connect to NanoMQ](./assets/connect-nanomq.png)

### 连接客户端到远端 MQTT Broker

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

![Connect to Public Broker](./assets/connect-public-broker.png)

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

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

<img src="./assets/hellofromnano.png" alt="message from nanomq"  />

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

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

![message from broker](./assets/hellofrombroker.png)

### 查看桥接指标和状态

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

![bridge-view-status](./assets/bridge-view-status.png)