# 内置 MQTT Broker

FastBee 社区版内置了基于 Netty 开发的 MQTT Broker，无需额外部署 EMQX 或其他 MQTT 服务端。Broker 与后端服务运行在同一进程中，随平台启动自动就绪，设备完成认证后即可上报数据与接收指令。

## 核心特性

* **协议支持**：MQTT 3.1.1
* **连接方式**：TCP (1883) + WebSocket (8083)
* **QoS 等级**：QoS 0、QoS 1
* **消息保留**：支持 Retain 消息
* **遗嘱消息**：支持 Last Will and Testament
* **会话管理**：支持持久会话与清理会话
* **认证机制**：产品 ID + 设备密钥认证

## 架构设计

```mermaid
%%{init: {"flowchart": {"htmlLabels": false}}}%%
flowchart TB
  Client["MQTT 客户端"]
  TCP["TCP 通道 :1883"]
  WS["WebSocket 通道 :8083"]
  Codec["协议编解码<br/>MqttCodec"]
  Handler["消息处理器<br/>MqttHandler"]
  Auth["认证服务<br/>AuthService"]
  Session["会话管理<br/>SessionManager"]
  Route["消息路由"]
  Biz["业务处理层"]

  Client --> TCP
  Client --> WS
  TCP --> Codec
  WS --> Codec
  Codec --> Handler
  Handler --> Auth
  Handler --> Session
  Handler --> Route
  Route --> Biz

  classDef endpoint fill:#eef4ff,stroke:#536dfe,color:#1f2937;
  classDef platform fill:#f4efff,stroke:#7c3aed,color:#1f2937;
  classDef service fill:#ecfeff,stroke:#0891b2,color:#1f2937;
  class Client endpoint;
  class TCP,WS,Codec,Handler,Route platform;
  class Auth,Session,Biz service;
```

## 模块结构

| 模块 | 说明 |
|------|------|
| mqtt-broker | MQTT Broker 核心实现 |
| MqttConnect | CONNECT 消息处理与认证 |
| MqttPublish | PUBLISH 消息处理 |
| MqttSubscribe | SUBSCRIBE 订阅管理 |
| MqttUnsubscribe | UNSUBSCRIBE 取消订阅 |
| MqttPubAck/PubRec/PubRel | QoS 确认流程 |
| ClientManager | 客户端连接管理 |
| SessionManager | 会话状态管理 |
| RetainMsgManager | 保留消息管理 |
| ResponseManager | 响应消息管理 |

## 连接认证流程

1. 客户端发送 CONNECT 消息（ClientID=设备编号, Username=产品ID, Password=设备密钥）
2. Broker 调用 AuthService 验证凭据
3. 验证通过后创建会话，注册到 ClientManager
4. 发送 CONNACK 确认

连接参数（clientId 格式、简单认证与加密认证、主题列表与报文格式）的完整说明见 [MQTT 接入](https://www.fastbee.cn/doc/open/v2/quickstart/mqtt.md)。

## 消息流转

1. 设备 PUBLISH → MqttPublish 处理 → 主题匹配 → 路由到业务层
2. 业务层下发 → ResponseManager → 找到目标 Session → PUBLISH 到设备
3. 订阅/取消订阅 → 更新 Session 的订阅列表

## 能力边界

* 协议版本为 MQTT 3.1.1，不支持 MQTT 5.0 的扩展特性。
* QoS 支持 0 和 1，不支持 QoS 2 的精确一次语义。
* 内置 Broker 面向单机部署；集群接入、负载均衡与大规模连接能力见[集群版文档](https://www.fastbee.cn/doc/cluster/v2.md)。
* 设备与平台交互的主题与报文格式为 FastBee 约定格式，自定义数据格式可通过[规则脚本](https://www.fastbee.cn/doc/open/v2/manual/script.md)转换。

## 性能调优

* **连接池**：单机支持数千并发连接
* **Netty 参数**：通过 `NettyConfig` 调整 IO 线程数、Boss/Worker 比例
* **内存**：合理设置 Netty 缓冲区大小
* **消息队列**：使用 Redis 作为消息中间件，解耦 Broker 与业务层

## 关联文档

* [架构概览](https://www.fastbee.cn/doc/open/v2/architecture/overview.md)
* [MQTT 接入](https://www.fastbee.cn/doc/open/v2/quickstart/mqtt.md)
* [设备管理](https://www.fastbee.cn/doc/open/v2/manual/device.md)

## 常见问题

### 还需要单独部署 EMQX 吗？

不需要。社区版内置基于 Netty 的 MQTT Broker，随后端服务一起启动；只有在使用集群版的 FMQ 或外部 Broker 集成等场景才需要额外的 MQTT 服务端。

### 网页端设备模拟器或 Web 客户端应该连哪个端口？

TCP 客户端连接 `1883` 端口；浏览器等只能走 WebSocket 的客户端连接 `8083` 端口（路径 `/mqtt`，经 Nginx 代理时见[系统部署](https://www.fastbee.cn/doc/open/v2/install/system.md) 的配置示例）。

### 设备连接被拒绝如何排查？

依次检查：服务器 1883 端口是否放行、后端服务是否正常运行、clientId 格式（`S&设备编号&产品ID&用户ID`）是否正确、产品是否启用了设备授权码、设备是否被禁用。详细排查清单见 [MQTT 接入](https://www.fastbee.cn/doc/open/v2/quickstart/mqtt.md) 的常见错误一节。
