# MQTT 数据桥接

MQTT 数据桥接是 EMQX Edge 的核心能力之一，用于在边缘部署和上游 MQTT Broker 之间转发 MQTT 消息。它提供了一种灵活、可靠的方式，将边缘侧设备流量连接到云端，同时将设备连接与上游网络状况解耦。

通过 MQTT 数据桥接，设备使用标准 MQTT 协议连接到 EMQX Edge，由 EMQX Edge 负责向上游 Broker 进行消息转发、订阅和传输方式选择。

## EMQX Edge 中的 MQTT 数据桥接是什么

在 EMQX Edge 中，MQTT 数据桥接相当于一个运行在 Broker 内部的 MQTT 客户端。它会连接到上游 MQTT Broker，并执行以下功能：

- 将选定的本地主题从边缘端转发到上游 Broker
- 订阅上游主题，并在本地重新发布
- 保留 QoS 等级、Retain 标志和主题映射等 MQTT 语义

从设备视角来看，桥接是透明的。设备仍然只与 EMQX Edge 通信，由 EMQX Edge 负责云边数据交换。

## 支持的桥接传输协议

EMQX Edge 的 MQTT 数据桥接支持多种传输协议，用户可以根据网络状况和部署要求选择最合适的方式。

### MQTT over TCP 桥接

MQTT over TCP 桥接使用传统 TCP 或 TLS/TCP 作为 EMQX Edge 与上游 Broker 之间 MQTT 连接的传输层。

该桥接类型支持广泛、部署简单，适用于大多数稳定网络环境。

了解更多：[MQTT over TCP 桥接](./tcp-bridge.md)

### MQTT over QUIC 桥接

MQTT over QUIC 桥接使用 QUIC 作为边缘到云端 MQTT 连接的传输层。QUIC 运行在 UDP 之上，旨在提供更快的连接建立速度，并改善弱网或高延迟网络中的连接表现。

该桥接类型适用于移动网络、跨地域部署，或存在丢包和频繁重连的环境。

了解更多：[MQTT over QUIC 桥接](./quic-bridge.md)

## 何时使用 MQTT 数据桥接

MQTT 数据桥接常用于以下场景：

- 在边缘端汇聚设备数据并转发到云端
- 在不修改设备固件的情况下改善云边连接
- 适应不稳定、高延迟或易丢包的网络环境
- 在保持可靠性的同时逐步引入新的传输技术

## 在 Dashboard 中使用 MQTT over TCP 桥接

EMQX Edge Dashboard 提供了易用的 Web 界面，可用于配置和管理桥接，无需手动编辑配置文件。

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

你可以在 EMQX Edge Dashboard 的两个位置监控桥接性能：

#### Monitor 页面

进入 **Monitor > Overview**，在 **Bridges** 区域查看基础桥接指标。

<img src="./assets/bridge-overview.png" alt="bridge-overview" style="zoom:67%;" />

这里会显示每个桥接的摘要信息，包括：

- **Name**：桥接自定义名称
- **Sent Messages Number**：发送到远端 Broker 的消息数
- **Received Messages Number**：从远端 Broker 接收的消息数
- **Sent Bytes**：发送的数据总量
- **Received Bytes**：接收的数据总量

这些信息可用于快速确认消息流量是否正常。

#### Bridges 页面

进入 **Bridges** 查看所有已配置的 MQTT 桥接。桥接列表以表格形式展示每个桥接，帮助你详细查看其状态和性能。

![Bridge List](./assets/dashboard-bridge-volums.png)

每个桥接都会在表格中显示关键指标，便于你快速评估性能和连接健康状况：

- **Message Counts**

  - **Dropped / Sent messages number**：本地 Broker 成功发送的消息数，以及被丢弃的消息数

  - **Dropped / Received messages number**：从远端 Broker 成功接收的消息数，以及被丢弃的消息数

- **Data Transfer**

  - **Sent bytes**：通过该桥接发送的数据总量，单位为字节

  - **Received bytes**：通过该桥接接收的数据总量，单位为字节

- **Connection Health**
  - **Reconnect times**：桥接连接重新建立的次数，可用于监控连接稳定性
  - **Cached message size**：桥接缓存中当前存储的消息数，即连接恢复后等待发送的消息

### 管理桥接

在 **Bridges** 页面中，每个桥接都提供以下操作按钮：

- **Enable / Disable**：临时启用或禁用桥接，无需删除桥接。
- **Edit**：修改连接、转发或订阅设置。
- **Delete**：永久删除桥接。

### 添加新桥接

要创建新桥接，点击右上角的 **Add** 按钮。系统会打开引导式配置流程，你可以配置：

- 连接设置
- 转发规则
- 订阅规则

详细步骤请参见：

- [快速上手：创建 MQTT over TCP 桥接](./tcp-bridge-quick-start.md)
- [快速上手：创建 MQTT over QUIC 桥接](./quic-bridge-quick-start.md)

## 监控桥接和客户端连接状态

EMQX Edge 提供系统级 MQTT 主题（以 `$SYS/` 为前缀），用于发布客户端和桥接的实时状态更新。这些主题可帮助监控连接事件，例如客户端或桥接何时连接或断开。每条消息都包含桥接配置中由 `clientid` 定义的唯一客户端标识。

该机制便于构建 Dashboard、监控工具或告警系统，用于实时跟踪桥接和客户端的健康状态与连接情况。

### 通过系统主题查看连接事件

要观察桥接或客户端连接状态：

1. 使用任意 MQTT 客户端，例如 MQTTX。
2. 连接到 EMQX Edge。
3. 订阅相关系统主题，例如：

```
$SYS/brokers/client_status/#
```

这样即可实时接收连接和断开连接事件消息。

### 消息格式示例

以下示例展示 EMQX Edge 为客户端连接和断开连接事件发布的系统事件消息格式。不同 EMQX Edge 版本中的消息格式略有差异。

#### 在线事件（v1.2.0 之前）

```
Topic: $SYS/brokers/connected
Message: {"username":"hello", "ts":1691225605933,"proto_name":"MQTT","keepalive":60,"return_code":"0","proto_ver":4,"client_id":"nanomq-8a2a5c2e","clean_start":1, "IPv4":"127.0.0.1"}
```

#### 离线事件（v1.2.0 之前）

```
Topic: $SYS/brokers/disconnected
Message: {"username":"hello","ts":1691225608391,"reason_code":"8b","client_id":"nanomq-8a2a5c2e","IPv4":"127.0.0.1"}
```

#### 合并后的状态主题（自 v1.2.0 起）

从 v1.2.0 开始，在线/离线事件会发布到统一主题：

```
Topic: $SYS/brokers/client_status/${clientid}
```

**在线事件**

```
Topic: $SYS/brokers/client_status/${clientid}
Message: {"status":"online", "username":"hello", "ts":1691225605933,"proto_name":"MQTT","keepalive":60,"return_code":"0","proto_ver":4,"client_id":"nanomq-8a2a5c2e","clean_start":1, "IPv4":"127.0.0.1"}
```

**离线事件**

```
Topic: $SYS/brokers/client_status/${clientid}
Message: {"status":"offline", "username":"hello","ts":1691225608391,"reason_code":"8b","client_id":"nanomq-8a2a5c2e","IPv4":"127.0.0.1"}
```

### 使用 Retained 消息保存最新状态

这些系统事件支持 MQTT `retain` 标志，表示最新连接状态会被保存。当新的订阅者连接并订阅 `$SYS/brokers/client_status/#` 时，会立即收到每个客户端或桥接的最后已知状态。

## 桥接管理最佳实践

正确设置和管理桥接，是确保 EMQX Edge 与远端 MQTT Broker 之间数据流可靠、高效的关键。Dashboard 提供可视化界面，可简化这一过程，让你专注于应用逻辑，而不是复杂的配置语法。请遵循以下最佳实践来优化 MQTT over TCP 桥接。

### 监控建议

1. **定期检查桥接状态**
   确保每个桥接都保持连接。非预期断开可能表示认证或网络存在问题。
2. **监控重连次数**
   较高的重连次数可能表示网络不稳定、Keepalive 间隔配置不当，或远端 Broker 不可用。
3. **跟踪丢弃消息**
   频繁出现发送或接收消息丢弃，可能表示存在以下问题：
   - 队列溢出
   - QoS 设置不正确
   - 网络状况较差
4. **观察缓存消息数量**
   持续增长的缓存可能表示桥接已断开，或远端 Broker 处理消息速度不足。

### 配置建议

1. **使用描述性桥接名称**
   使用清晰的名称体现桥接用途或目标，例如 `cloud_bridge_ny`、`emqx_enterprise_main`。这有助于在存在多个桥接的环境中进行管理。
2. **优先从 QoS 1 开始**
   - 大多数应用可使用 **QoS 1**，在可靠性和性能之间取得较好平衡。
   - 仅在需要恰好一次投递时使用 **QoS 2**。它可避免消息重复，但开销更高。
   - 对非关键数据或可容忍丢失的场景使用 **QoS 0**，此时消息最多发送一次，不保证投递。
3. **生产部署前先测试**
   在生产环境使用前，先通过测试主题验证桥接设置。这有助于尽早发现配置错误。
4. **调优性能参数**
   监控吞吐量，并根据消息量和系统容量调整 `max_parallel_processes` 等配置。避免过度配置，以免造成资源竞争。

::: tip

对于长期运行或大规模部署，建议启用日志和监控工具，以便在桥接故障或性能下降时触发告警。

:::

## 桥接问题排查

如果桥接未按预期工作，可参考下表识别常见问题及处理方式。

| Issue | Possible Cause | Recommended Action |
| --- | --- | --- |
| **Connection Failures** | Broker 地址无效、凭据错误或网络问题 | 检查 Broker 地址、认证凭据和网络连通性。 |
| **Message Loss** | 使用 QoS 0、连接断开或网络不稳定 | 使用合适的 QoS 等级，验证网络状况，并检查消息缓存设置。 |
| **High Latency** | 网络性能问题或并行度不足 | 减少并行连接数，或评估网络性能。 |
| **Authentication Errors** | 用户名/密码错误或 TLS 证书问题 | 验证登录凭据和 TLS 证书配置。 |
| **High Reconnect Counts** | 网络不稳定或 Keepalive 配置不当 | 检查网络可靠性，并微调 Keepalive 间隔。 |