稳定性，始终是 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 开始：

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，几个版本的修复具有关联性：

这些问题在开发环境中不一定容易复现，却可能在网络不稳定、设备规模扩大、连接频繁切换或代理链路复杂时暴露出来。

因此，不建议只选择其中某个中间版本，推荐直接升级至最新正式版 2.6.8。

十、升级方式

以 Spring Boot 客户端为例：

<dependency>
    <groupId>org.dromara.mica-mqtt</groupId>
    <artifactId>mica-mqtt-client-spring-boot-starter</artifactId>
    <version>2.6.8</version>
</dependency>

Spring Boot 服务端：

<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 及更早版本的用户

生产环境升级前，请结合自身业务完成必要的回归测试。