Skip to content

内置 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-brokerMQTT Broker 核心实现
MqttConnectCONNECT 消息处理与认证
MqttPublishPUBLISH 消息处理
MqttSubscribeSUBSCRIBE 订阅管理
MqttUnsubscribeUNSUBSCRIBE 取消订阅
MqttPubAck/PubRec/PubRelQoS 确认流程
ClientManager客户端连接管理
SessionManager会话状态管理
RetainMsgManager保留消息管理
ResponseManager响应消息管理

连接认证流程 ​

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

连接参数(clientId 格式、简单认证与加密认证、主题列表与报文格式)的完整说明见 MQTT 接入。

消息流转 ​

  1. 设备 PUBLISH → MqttPublish 处理 → 主题匹配 → 路由到业务层
  2. 业务层下发 → ResponseManager → 找到目标 Session → PUBLISH 到设备
  3. 订阅/取消订阅 → 更新 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 接入 的常见错误一节。