消息队列 MQTT 版 客户端事件实践教程

一、获取客户端事件

建议你通过以下两种方式之一获取客户端事件，客户端事件的详细字段定义及完整内容请查看查询客户端事件。

方式一：控制台查询

1. 登录 MQTT 控制台。

2. 在左侧导航栏单击资源管理 > 集群管理，选择好地域后，单击目标集群的“ID”，进入集群基本信息页面。

3. 在左侧页签栏选择客户端管理，进入具体客户端详情页，下拉即可查看客户端事件。

方式二：订阅系统主题

订阅系统事件 Topic，如$event/client_connected(上线)、$events/session_subscribed (订阅）或者订阅所有事件$events/#，即可接收到包含详细事件内容的事件消息，详情见查询客户端事件文档中的事件主题。

二、场景一 客户端连接失败排查

设备端日志显示连接失败或断开，或者控制台客户端列表状态为“离线”。

三、排查步骤

·登录 MQTT 控制台 > 客户端管理 > 根据Client ID搜索客户端，点击查看详情。

·筛选该客户端的事件记录。

·重点关注 client_disconnected 事件中的 reason字段，具体断连原因定义及解决建议，请参照下方常见断连原因对照表。

四、典型表现

网络环境正常时，设备持续、高频发生重连。日志中密集出现 Connected 和 Disconnected，设备无法稳定在线。

注意：说明：

五、排查步骤

·在控制台查看事件时间轴。

·如果发现密集的 client_connected 和 client_disconnected 交替出现。

·检查 client_disconnected 事件的 reason 字段。如果reason为 takeovered，这是最典型的客户端连接抖动的原因之一，说明当前客户端被相同客户端 ID 设备挤下线。

六、解决方案

·确保每个设备的 Client ID 全局唯一

·检查是否有旧的测试脚本未停止运行

注意：在排查 Takeover 问题时，并非所有 reason: takeovered 都代表故障。如果是偶发状况，且通常发生在设备网络波动恢复后的Takeover断连，可能是 MQTT 在弱网环境下的 Self-Repair 行为，无需额外干预。

七、场景三 消息未收到问题排查

客户端事件主要用于诊断连接性的问题。如果你遇到设备在线但无法收发消息的情况，通常需要结合消息轨迹进行联合排查。

·利用事件判断在线状态：通过消息轨迹获取消息下发的时间点，检查在此时间是否有 client_disconnected 事件，确认设备是否发生闪断。

·利用事件确定订阅行为：检查是否有 session_subscribed 事件，确认设备是否成功订阅了目标 Topic。

关于“消息丢失、ACK未确认”等消费进程问题的详细排查步骤，请参阅消息轨迹。

八、常见断连原因对照表