内置 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 + 设备密钥认证
架构设计
模块结构
| 模块 | 说明 |
|---|---|
| mqtt-broker | MQTT Broker 核心实现 |
| MqttConnect | CONNECT 消息处理与认证 |
| MqttPublish | PUBLISH 消息处理 |
| MqttSubscribe | SUBSCRIBE 订阅管理 |
| MqttUnsubscribe | UNSUBSCRIBE 取消订阅 |
| MqttPubAck/PubRec/PubRel | QoS 确认流程 |
| ClientManager | 客户端连接管理 |
| SessionManager | 会话状态管理 |
| RetainMsgManager | 保留消息管理 |
| ResponseManager | 响应消息管理 |
连接认证流程
- 客户端发送 CONNECT 消息(ClientID=设备编号, Username=产品ID, Password=设备密钥)
- Broker 调用 AuthService 验证凭据
- 验证通过后创建会话,注册到 ClientManager
- 发送 CONNACK 确认
连接参数(clientId 格式、简单认证与加密认证、主题列表与报文格式)的完整说明见 MQTT 接入。
消息流转
- 设备 PUBLISH → MqttPublish 处理 → 主题匹配 → 路由到业务层
- 业务层下发 → ResponseManager → 找到目标 Session → PUBLISH 到设备
- 订阅/取消订阅 → 更新 Session 的订阅列表
能力边界
- 协议版本为 MQTT 3.1.1,不支持 MQTT 5.0 的扩展特性。
- QoS 支持 0 和 1,不支持 QoS 2 的精确一次语义。
- 内置 Broker 面向单机部署;集群接入、负载均衡与大规模连接能力见集群版文档。
- 设备与平台交互的主题与报文格式为 FastBee 约定格式,自定义数据格式可通过规则脚本转换。
性能调优
- 连接池:单机支持数千并发连接
- Netty 参数:通过
NettyConfig调整 IO 线程数、Boss/Worker 比例 - 内存:合理设置 Netty 缓冲区大小
- 消息队列:使用 Redis 作为消息中间件,解耦 Broker 与业务层
关联文档
常见问题
还需要单独部署 EMQX 吗?
不需要。开源版内置基于 Netty 的 MQTT Broker,随后端服务一起启动;只有在使用集群版的 FMQ 或外部 Broker 集成等场景才需要额外的 MQTT 服务端。
网页端设备模拟器或 Web 客户端应该连哪个端口?
TCP 客户端连接 1883 端口;浏览器等只能走 WebSocket 的客户端连接 8083 端口(路径 /mqtt,经 Nginx 代理时见系统部署 的配置示例)。
设备连接被拒绝如何排查?
依次检查:服务器 1883 端口是否放行、后端服务是否正常运行、clientId 格式(S&设备编号&产品ID&用户ID)是否正确、产品是否启用了设备授权码、设备是否被禁用。详细排查清单见 MQTT 接入 的常见错误一节。


