ThingsPanel 开源社区版已将默认 MQTT Broker 从 gmqtt 切换为 Eclipse Mosquitto。

本次调整主要涉及社区版的 MQTT 通信组件。对于用户来说，ThingsPanel 的设备接入方式、平台功能和业务使用方式没有变化，已有设备也可以继续使用。

需要说明的是，ThingsPanel 并不依赖某一种 MQTT Broker，系统支持多种 Broker 的适配与集成，包括 Mosquitto、gmqtt、EMQX、VerneMQ 等。 本次调整只是将 Mosquitto 作为社区版的默认方案。

一、为什么选择 Mosquitto？

此前，ThingsPanel 社区版使用基于 Go 语言开发的 gmqtt，实现设备 MQTT 连接和消息通信。

此次调整主要基于以下考虑：

1. 成熟的 MQTT 开源生态

Mosquitto 是 Eclipse 基金会旗下的开源 MQTT Broker，支持 MQTT 3.1、3.1.1 和 5.0，拥有广泛的应用基础和成熟的技术文档。

开发者可以直接使用 Mosquitto 的标准配置、命令行工具及相关生态资源，设备接入、调试和问题排查更加方便。

2. 更加方便的部署与维护

Mosquitto 体积小、资源占用低，支持 Linux、Windows、Docker 等多种部署环境。

其配置体系包含持久化、TLS 加密、用户认证、ACL 访问控制等常用功能，方便用户根据实际项目需求进行调整。

3. 减少基础组件的维护成本

MQTT Broker 的核心职责是处理设备连接和消息传输，而 ThingsPanel 更关注设备管理、数据处理、规则引擎、可视化和物联网应用。

使用成熟、独立的 Broker，可以减少社区版在 MQTT 基础组件上的维护工作，将开发资源投入到平台自身功能的完善上。

本次调整并不是因为 gmqtt 无法满足 MQTT 通信需求，也不代表 Mosquitto 在所有场景下都比 gmqtt 性能更好，而是综合考虑社区版的部署、维护和生态支持后作出的选择。

二、用户常见问题

Q1：已经使用 gmqtt 的用户，需要立即切换吗？

不需要。

已经部署的 ThingsPanel 可以继续使用原有 gmqtt，不受此次默认方案调整的影响。对于用户而言，平台功能和使用方式没有变化。

如果后续升级到采用 Mosquitto 的社区版本，再按照对应版本的升级说明进行操作即可。

Q2：原来通过 gmqtt 接入的设备，还能继续使用吗？

可以。

gmqtt 和 Mosquitto 都支持标准 MQTT 协议。原有 MQTT 设备不需要因为更换 Broker 而重新开发接入程序。

如果切换后 MQTT 服务地址、端口及认证信息保持不变，设备通常无需修改配置；如果这些参数发生变化，则需要相应调整。

Q3：切换 Mosquitto 后，原来的设备数据会丢失吗？

不会因为更换 Broker 而丢失已经存储在 ThingsPanel 数据库中的历史数据。

设备信息、历史遥测数据等仍由 ThingsPanel 管理，不依赖 gmqtt 保存。

需要注意的是，Broker 内部的持久会话、离线消息和 Retained 消息不一定能自动迁移。如果项目使用了这些功能，切换前应单独检查和处理。

Q4：切换后，设备连接和数据上报会受影响吗？

正常运行时不受影响。

Mosquitto 同样负责 MQTT 设备连接、消息订阅和发布。设备数据上报、平台指令下发等功能可以继续使用。

切换过程中可能出现短暂断连，设备重新连接后即可恢复通信。建议设备启用自动重连机制。

Q5：ThingsPanel 以后只能使用 Mosquitto 吗？

不是。

ThingsPanel 在架构上支持多种 MQTT Broker，包括：

• Mosquitto：轻量级、成熟的开源 MQTT Broker，作为当前社区版默认方案。
• gmqtt：基于 Go 语言开发的 MQTT Broker，此前社区版使用的方案。
• EMQX：面向大规模 MQTT 连接和消息处理场景的 MQTT 平台。
• VerneMQ：支持分布式部署的 MQTT Broker。

需要区分的是，平台架构具备多 Broker 适配能力，并不等于社区版默认安装包对上述 Broker 全部提供开箱即用的配置。

社区版主要围绕 Mosquitto 提供默认部署和维护支持。

Q6：Mosquitto 比 gmqtt 性能更好吗？

不能一概而论。

两者的性能与连接数量、消息频率、QoS、持久化配置和硬件资源有关。

此次切换的主要原因是 Mosquitto 的成熟生态、标准化配置和维护便利性，而不是单纯的性能比较。

对于设备连接规模较大、消息吞吐要求较高的项目，仍建议根据实际负载进行测试。

Q7：自己开发的 MQTT 设备或网关程序需要修改吗？

使用标准 MQTT 协议的设备或网关，通常不需要修改业务代码。

只需确认 Broker 地址、端口、用户名、密码、TLS 配置及 Topic 权限等保持兼容。

如果原先使用了 gmqtt 特有的插件、接口或扩展功能，则需要针对 Mosquitto 进行适配。

三、现有用户升级时需要注意什么？

对于新部署 ThingsPanel 社区版的用户，按照当前版本的官方部署说明安装即可。

对于从 gmqtt 版本升级的用户，建议重点检查以下内容：

1. 备份数据与配置：包括 ThingsPanel 数据库及现有 Broker 配置。
2. 核对 MQTT 接入参数：包括监听端口、设备认证、Topic、TLS 和 ACL 权限。
3. 检查消息持久化需求：确认是否需要迁移保留消息、持久会话或离线消息。
4. 验证设备通信：升级后检查设备在线状态、数据上报和指令下发是否正常。

具体升级步骤以相应版本的官方文档为准。

四、后续社区版的发展方向

本次调整是 ThingsPanel 社区版对默认 MQTT 通信组件的一次优化。

ThingsPanel 将继续保持组件化、开放式的架构设计，支持根据不同业务需求适配 MQTT Broker，而社区版的默认部署、文档和维护工作将主要围绕 Mosquitto 展开。

后续我们将继续完善设备接入、数据处理、规则引擎、可视化等核心功能，并持续优化社区版的安装部署和使用体验。

欢迎开发者通过 ThingsPanel GitHub Issues 反馈升级过程中遇到的问题，也欢迎参与 Broker 适配与社区建设。

ThingsPanel 团队