mica-mqtt 2.6.8 发布：集中修复重连、消息转发、会话清理与 MQTT 5.0 协议问题
稳定性，始终是 MQTT 系统最重要的基础能力之一。
从 mica-mqtt 2.6.3 发布以来，我们持续收集社区反馈，并陆续发布了 2.6.4～2.6.8。此次更新重点并不是简单增加功能，而是集中解决真实业务场景中的消息转发、断线重连、会话清理、代理接入以及 MQTT 5.0 协议兼容问题。
目前最新正式版为 **2.6.8**。如果你仍在使用 2.6.3 或更早版本，建议尽快升级。
---
## 一、消息转发更加可靠
在 2.6.5 中，我们修复了服务端消息转发问题。
该问题可能影响消息从发布端到订阅端的正常分发，尤其值得 Broker 使用者关注。本次修复同时补充了服务端与客户端集成测试，对消息发布、订阅和转发链路进行回归验证，降低类似问题再次出现的概率。
此外，2.6.8 还修复了高版本 QoS 消息发送逻辑，并进一步规范了 QoS 1、QoS 2 消息被拒绝后的 ACK 响应。
对于依赖可靠消息投递的生产系统，这部分修复是此次升级的重要理由。
---
## 二、断线重连问题持续加固
网络抖动、Broker 重启和连接异常是物联网系统中的常见情况。客户端能否正常恢复连接，直接影响设备在线率和消息连续性。
2.6.7 修复了底层发送状态在重连后没有正确复位的问题。该问题发生时，客户端虽然进入重连流程，但 MQTT CONNECT 报文可能无法正常发出，最终表现为客户端长时间无法恢复连接。
2.6.8 继续升级 mica-net 至 2.0.11，并围绕重连场景再次进行修复和验证。同时新增了基于 FakeBroker 的重连混沌测试，反复模拟：
- Broker 停止和重新启动
- 连接异常中断
- 重连期间并发发布消息
- 客户端资源释放和再次连接
这不是单点修补，而是对整个重连链路的一次系统性加固。
---
## 三、修复相同 clientId 互踢时误清理新会话的问题
按照 MQTT 的连接规则，当新的客户端使用相同 clientId 建立连接时，服务端会断开原有连接，由新连接接管会话。
由于连接关闭和会话清理存在异步过程，旧连接的清理逻辑可能在新连接建立后才执行。
如果没有准确区分新旧连接，就可能误将新连接对应的会话一并清理，进而造成：
- 新连接已经成功建立，但会话状态被意外删除
- 客户端订阅关系或在线状态出现异常
- 后续消息无法按照预期投递
- 客户端需要再次重连才能恢复
2.6.7 优化了客户端互踢场景下的会话解绑与清理逻辑，确保旧连接异步关闭时，不会误清理新连接已经接管的会话。
如果业务中存在设备重复登录、网络抖动后快速重连，或者多个实例使用相同 clientId 竞争连接的情况，建议尽快升级。
---
## 四、SSL、ProxyProtocol 与 WSS 接入问题修复
随着 MQTT 服务部署到负载均衡、网关和反向代理之后，连接链路通常会同时涉及 SSL、WebSocket 和 ProxyProtocol。
2.6.6 修复了 **SSL 与 ProxyProtocol 同时启用时的编解码异常**。该问题主要影响需要通过代理获取客户端真实 IP，同时又开启 TLS 加密的部署方式。
2.6.8 则修复了 **WSS 监听器启用条件判断错误**。此前 WSS 是否启用错误地受到了其他 SSL 监听器配置的影响，可能导致 WSS 配置正确但监听器未按预期启动。
涉及以下部署方式的用户建议更新：
- MQTT over TLS
- MQTT over WSS
- Nginx、HAProxy或四层负载均衡代理
- SSL 与 ProxyProtocol V1/V2 组合使用
---
## 五、MQTT 5.0 协议处理更加严格
2.6.8 对 MQTT 5.0 的协议处理进行了较大范围完善。
首先，解码器增加了更多协议合法性校验，包括：
- CONNECT 标志位
- 遗嘱相关标志
- 订阅选项保留位
- MQTT 5.0 属性取值
- 非法报文和边界报文处理
以前部分非法报文可能进入后续业务流程，现在可以在协议解码阶段更早发现并拒绝，避免异常数据影响连接状态。
其次，修复并补齐了多项 Reason Code 处理，包括：
- PUBACK
- PUBREC
- PUBREL
- PUBCOMP
- SUBACK
- UNSUBACK
- DISCONNECT
同时修正了 `MqttUnSubAckBuilder` 的原因码处理逻辑，以及 `MqttProperty` 的 `equals`、`hashCode` 实现，避免在属性为空或参与集合比较时出现空指针或行为不一致。
对于使用 MQTT 5.0、QoS 1/2 或需要与不同厂商客户端互联的用户，此次升级可以显著改善协议兼容性。
---
## 六、待发送消息队列恢复兼容行为
2.6.3 增加了连接前待发送消息队列：客户端尚未连接成功时发布的消息，可以先进入队列，连接成功后再发送。
但这项能力默认开启后，可能改变老用户原有的发布行为。为保证升级兼容性，从 2.6.4 开始：
```java
pendingPublishQueueEnabled=false
```
该功能调整为默认关闭，需要时再主动开启。
这可以避免应用在不知情的情况下缓存并延迟发送消息。如果业务确实需要离线等待队列，可以显式开启，并结合业务流量合理设置队列容量。
---
## 七、Solon 插件兼容性修复
2.6.4 修复了 Solon 客户端插件中 `mqttClientCreator` Bean 的初始化问题，同时将插件初始化调整为 `LifecycleBean` 机制。
这项调整改善了不同 Solon 版本之间的兼容性，避免插件使用较高版本 Solon 编译后，在较低版本环境运行时出现错误。
2.6.5 还为 `@MqttClientSubscribe` 增加了 `enabled` 属性，可以通过配置决定是否启用某个注解订阅，更适合多环境部署和功能开关场景。
---
## 八、订阅管理与消息匹配优化
除了 Bug 修复，2.6.8 还重构了服务端消息处理架构，并优化了 `TrieTopicManager`。
新的订阅管理方式：
- 区分精确订阅与通配符订阅
- 复用订阅数据，减少重复对象
- 优化主题匹配过程
- 降低大量连接和订阅场景中的内存占用
消息处理也按照 MQTT 报文类型拆分为独立 Handler，让连接、发布、订阅、确认和断开流程的职责更加清晰。
这部分重构为后续协议扩展和稳定性维护打下了更好的基础。
---
## 九、为什么建议直接升级到 2.6.8？
从 2.6.4 到 2.6.8，几个版本的修复具有关联性：
| 场景 | 修复内容 |
|------------|--------------------------------|
| 消息可靠性 | 修复消息转发及高版本 QoS 发送逻辑 |
| 断线恢复 | 修复 CONNECT 无法发送，持续加固重连流程 |
| 会话管理 | 修复相同 clientId 互踢后的会话清理 |
| 安全接入 | 修复 SSL + ProxyProtocol 编解码异常 |
| WebSocket | 修复 WSS 监听器启用判断 |
| MQTT 5.0 | 完善 Reason Code、ACK、属性和非法报文校验 |
| 框架集成 | 修复 Solon Bean 初始化与版本兼容问题 |
这些问题在开发环境中不一定容易复现，却可能在网络不稳定、设备规模扩大、连接频繁切换或代理链路复杂时暴露出来。
因此，不建议只选择其中某个中间版本，推荐直接升级至最新正式版 **2.6.8**。
---
## 十、升级方式
以 Spring Boot 客户端为例：
```xml
<dependency>
<groupId>org.dromara.mica-mqtt</groupId>
<artifactId>mica-mqtt-client-spring-boot-starter</artifactId>
<version>2.6.8</version>
</dependency>
```
Spring Boot 服务端：
```xml
<dependency>
<groupId>org.dromara.mica-mqtt</groupId>
<artifactId>mica-mqtt-server-spring-boot-starter</artifactId>
<version>2.6.8</version>
</dependency>
```
使用原生客户端或服务端时，同样将对应依赖版本更新为 `2.6.8` 即可。
升级后建议重点验证：
1. 客户端断线和 Broker 重启后的自动恢复；
2. QoS 1、QoS 2 消息发布及确认流程；
3. 相同 clientId 重复登录；
4. SSL、WSS 和 ProxyProtocol 代理接入；
5. MQTT 5.0 客户端的连接、订阅和断开流程；
6. 是否需要主动开启 `pendingPublishQueueEnabled`。
---
## 写在最后
感谢社区用户持续提交问题、复现信息和改进建议。很多稳定性问题只有进入真实网络环境、代理环境和大规模设备场景后才会显现，每一次反馈都在帮助 mica-mqtt 变得更加可靠。
如果你的项目仍在使用 2.6.3 或更早版本，建议尽快更新到 **mica-mqtt 2.6.8**。
这次升级不只是获得新功能，更重要的是让消息投递、断线重连、会话管理和 MQTT 5.0 协议处理更加稳定。
**最新版：mica-mqtt 2.6.8**
**建议范围：所有使用 2.6.3 及更早版本的用户**
**生产环境升级前，请结合自身业务完成必要的回归测试。**
---
原文链接：[点击查看](https://www.oschina.net/news/471700/mica-mqtt-2-6-8-released)
从 mica-mqtt 2.6.3 发布以来，我们持续收集社区反馈，并陆续发布了 2.6.4～2.6.8。此次更新重点并不是简单增加功能，而是集中解决真实业务场景中的消息转发、断线重连、会话清理、代理接入以及 MQTT 5.0 协议兼容问题。
目前最新正式版为 **2.6.8**。如果你仍在使用 2.6.3 或更早版本，建议尽快升级。
---
## 一、消息转发更加可靠
在 2.6.5 中，我们修复了服务端消息转发问题。
该问题可能影响消息从发布端到订阅端的正常分发，尤其值得 Broker 使用者关注。本次修复同时补充了服务端与客户端集成测试，对消息发布、订阅和转发链路进行回归验证，降低类似问题再次出现的概率。
此外，2.6.8 还修复了高版本 QoS 消息发送逻辑，并进一步规范了 QoS 1、QoS 2 消息被拒绝后的 ACK 响应。
对于依赖可靠消息投递的生产系统，这部分修复是此次升级的重要理由。
---
## 二、断线重连问题持续加固
网络抖动、Broker 重启和连接异常是物联网系统中的常见情况。客户端能否正常恢复连接，直接影响设备在线率和消息连续性。
2.6.7 修复了底层发送状态在重连后没有正确复位的问题。该问题发生时，客户端虽然进入重连流程，但 MQTT CONNECT 报文可能无法正常发出，最终表现为客户端长时间无法恢复连接。
2.6.8 继续升级 mica-net 至 2.0.11，并围绕重连场景再次进行修复和验证。同时新增了基于 FakeBroker 的重连混沌测试，反复模拟：
- Broker 停止和重新启动
- 连接异常中断
- 重连期间并发发布消息
- 客户端资源释放和再次连接
这不是单点修补，而是对整个重连链路的一次系统性加固。
---
## 三、修复相同 clientId 互踢时误清理新会话的问题
按照 MQTT 的连接规则，当新的客户端使用相同 clientId 建立连接时，服务端会断开原有连接，由新连接接管会话。
由于连接关闭和会话清理存在异步过程，旧连接的清理逻辑可能在新连接建立后才执行。
如果没有准确区分新旧连接，就可能误将新连接对应的会话一并清理，进而造成：
- 新连接已经成功建立，但会话状态被意外删除
- 客户端订阅关系或在线状态出现异常
- 后续消息无法按照预期投递
- 客户端需要再次重连才能恢复
2.6.7 优化了客户端互踢场景下的会话解绑与清理逻辑，确保旧连接异步关闭时，不会误清理新连接已经接管的会话。
如果业务中存在设备重复登录、网络抖动后快速重连，或者多个实例使用相同 clientId 竞争连接的情况，建议尽快升级。
---
## 四、SSL、ProxyProtocol 与 WSS 接入问题修复
随着 MQTT 服务部署到负载均衡、网关和反向代理之后，连接链路通常会同时涉及 SSL、WebSocket 和 ProxyProtocol。
2.6.6 修复了 **SSL 与 ProxyProtocol 同时启用时的编解码异常**。该问题主要影响需要通过代理获取客户端真实 IP，同时又开启 TLS 加密的部署方式。
2.6.8 则修复了 **WSS 监听器启用条件判断错误**。此前 WSS 是否启用错误地受到了其他 SSL 监听器配置的影响，可能导致 WSS 配置正确但监听器未按预期启动。
涉及以下部署方式的用户建议更新：
- MQTT over TLS
- MQTT over WSS
- Nginx、HAProxy或四层负载均衡代理
- SSL 与 ProxyProtocol V1/V2 组合使用
---
## 五、MQTT 5.0 协议处理更加严格
2.6.8 对 MQTT 5.0 的协议处理进行了较大范围完善。
首先，解码器增加了更多协议合法性校验，包括：
- CONNECT 标志位
- 遗嘱相关标志
- 订阅选项保留位
- MQTT 5.0 属性取值
- 非法报文和边界报文处理
以前部分非法报文可能进入后续业务流程，现在可以在协议解码阶段更早发现并拒绝，避免异常数据影响连接状态。
其次，修复并补齐了多项 Reason Code 处理，包括：
- PUBACK
- PUBREC
- PUBREL
- PUBCOMP
- SUBACK
- UNSUBACK
- DISCONNECT
同时修正了 `MqttUnSubAckBuilder` 的原因码处理逻辑，以及 `MqttProperty` 的 `equals`、`hashCode` 实现，避免在属性为空或参与集合比较时出现空指针或行为不一致。
对于使用 MQTT 5.0、QoS 1/2 或需要与不同厂商客户端互联的用户，此次升级可以显著改善协议兼容性。
---
## 六、待发送消息队列恢复兼容行为
2.6.3 增加了连接前待发送消息队列：客户端尚未连接成功时发布的消息，可以先进入队列，连接成功后再发送。
但这项能力默认开启后，可能改变老用户原有的发布行为。为保证升级兼容性，从 2.6.4 开始：
```java
pendingPublishQueueEnabled=false
```
该功能调整为默认关闭，需要时再主动开启。
这可以避免应用在不知情的情况下缓存并延迟发送消息。如果业务确实需要离线等待队列，可以显式开启，并结合业务流量合理设置队列容量。
---
## 七、Solon 插件兼容性修复
2.6.4 修复了 Solon 客户端插件中 `mqttClientCreator` Bean 的初始化问题，同时将插件初始化调整为 `LifecycleBean` 机制。
这项调整改善了不同 Solon 版本之间的兼容性，避免插件使用较高版本 Solon 编译后，在较低版本环境运行时出现错误。
2.6.5 还为 `@MqttClientSubscribe` 增加了 `enabled` 属性，可以通过配置决定是否启用某个注解订阅，更适合多环境部署和功能开关场景。
---
## 八、订阅管理与消息匹配优化
除了 Bug 修复，2.6.8 还重构了服务端消息处理架构，并优化了 `TrieTopicManager`。
新的订阅管理方式：
- 区分精确订阅与通配符订阅
- 复用订阅数据，减少重复对象
- 优化主题匹配过程
- 降低大量连接和订阅场景中的内存占用
消息处理也按照 MQTT 报文类型拆分为独立 Handler，让连接、发布、订阅、确认和断开流程的职责更加清晰。
这部分重构为后续协议扩展和稳定性维护打下了更好的基础。
---
## 九、为什么建议直接升级到 2.6.8？
从 2.6.4 到 2.6.8，几个版本的修复具有关联性：
| 场景 | 修复内容 |
|------------|--------------------------------|
| 消息可靠性 | 修复消息转发及高版本 QoS 发送逻辑 |
| 断线恢复 | 修复 CONNECT 无法发送，持续加固重连流程 |
| 会话管理 | 修复相同 clientId 互踢后的会话清理 |
| 安全接入 | 修复 SSL + ProxyProtocol 编解码异常 |
| WebSocket | 修复 WSS 监听器启用判断 |
| MQTT 5.0 | 完善 Reason Code、ACK、属性和非法报文校验 |
| 框架集成 | 修复 Solon Bean 初始化与版本兼容问题 |
这些问题在开发环境中不一定容易复现，却可能在网络不稳定、设备规模扩大、连接频繁切换或代理链路复杂时暴露出来。
因此，不建议只选择其中某个中间版本，推荐直接升级至最新正式版 **2.6.8**。
---
## 十、升级方式
以 Spring Boot 客户端为例：
```xml
<dependency>
<groupId>org.dromara.mica-mqtt</groupId>
<artifactId>mica-mqtt-client-spring-boot-starter</artifactId>
<version>2.6.8</version>
</dependency>
```
Spring Boot 服务端：
```xml
<dependency>
<groupId>org.dromara.mica-mqtt</groupId>
<artifactId>mica-mqtt-server-spring-boot-starter</artifactId>
<version>2.6.8</version>
</dependency>
```
使用原生客户端或服务端时，同样将对应依赖版本更新为 `2.6.8` 即可。
升级后建议重点验证：
1. 客户端断线和 Broker 重启后的自动恢复；
2. QoS 1、QoS 2 消息发布及确认流程；
3. 相同 clientId 重复登录；
4. SSL、WSS 和 ProxyProtocol 代理接入；
5. MQTT 5.0 客户端的连接、订阅和断开流程；
6. 是否需要主动开启 `pendingPublishQueueEnabled`。
---
## 写在最后
感谢社区用户持续提交问题、复现信息和改进建议。很多稳定性问题只有进入真实网络环境、代理环境和大规模设备场景后才会显现，每一次反馈都在帮助 mica-mqtt 变得更加可靠。
如果你的项目仍在使用 2.6.3 或更早版本，建议尽快更新到 **mica-mqtt 2.6.8**。
这次升级不只是获得新功能，更重要的是让消息投递、断线重连、会话管理和 MQTT 5.0 协议处理更加稳定。
**最新版：mica-mqtt 2.6.8**
**建议范围：所有使用 2.6.3 及更早版本的用户**
**生产环境升级前，请结合自身业务完成必要的回归测试。**
---
原文链接：[点击查看](https://www.oschina.net/news/471700/mica-mqtt-2-6-8-released)
评论
暂无评论。