新功能发布记录
客户端事件
引言
在 IoT 业务中，设备处于复杂的网络环境（弱网、断电、移动网络切换），设备“掉线”或“连不上”是最高频的问题。客户端事件是指在 MQTT 协议通信过程中，客户端会触发的一系列状态变化和交互通知。通过追踪系统事件，可以帮助用户及时排查定位分析问题，快速修复业务问题，从而保障系统稳定性。
获取客户端事件
方式一：控制台查询
1. 登录 MQTT 控制台。
2. 在左侧导航栏单击资源管理 > 集群管理，选择好地域后，单击目标集群的“ID”，进入集群基本信息页面。
3. 在左侧页签栏选择客户端管理，进入具体客户端详情页，下拉即可查看客户端事件。
方式二：订阅系统主题
订阅系统事件 Topic，如
$event/client_connected(上线)、$events/session_subscribed (订阅）或者订阅所有事件$events/#，即可接收到包含详细事件内容的事件消息，详情见查询客户端事件文档中的事件主题。最佳实践
场景一 客户端连接失败排查
设备端日志显示连接失败或断开，或者控制台客户端列表状态为“离线”。
排查步骤
登录 MQTT 控制台 > 客户端管理 > 根据Client ID搜索客户端，点击查看详情。
筛选该客户端的事件记录。
重点关注
client_disconnected 事件中的 reason字段，具体断连原因定义及解决建议，请参照下方常见断连原因对照表。
场景二 客户端 Takeover
典型表现
网络环境正常时，设备持续、高频发生重连。日志中密集出现 Connected 和 Disconnected，设备无法稳定在线。
说明：
Takeover（接管/互踢） 是指当一个客户端使用已被占用的 Client ID 发起连接时，Broker 会强制断开旧连接，让新连接上线的行为。MQTT 协议规定，同一个 Client ID 在同一时刻只能有一个连接。
排查步骤
在控制台查看事件时间轴。
如果发现密集的
client_connected 和 client_disconnected 交替出现。检查
client_disconnected 事件的 reason 字段。如果reason为 takeovered，这是最典型的客户端连接抖动的原因之一，说明当前客户端被相同客户端 ID 设备挤下线。解决方案
确保每个设备的 Client ID 全局唯一
检查是否有旧的测试脚本未停止运行
注意：
在排查 Takeover 问题时，并非所有
reason: takeovered 都代表故障。如果是偶发状况，且通常发生在设备网络波动恢复后的Takeover断连，可能是 MQTT 在弱网环境下的 Self-Repair 行为，无需额外干预。场景三 消息未收到问题排查
利用事件判断在线状态：通过消息轨迹获取消息下发的时间点，检查在此时间是否有
client_disconnected 事件，确认设备是否发生闪断。利用事件确定订阅行为：检查是否有
session_subscribed 事件，确认设备是否成功订阅了目标 Topic。常见断连原因对照表
断开连接原因 | 语义 | 处理建议 |
normal | 服务端收到 DISCONNECT 报文后正常断开。 | 正常事件。客户端主动发起的断连，确认是否为业务逻辑预期（如客户端任务完成主动退出）。 |
takeovered | 客户端被相同客户端 ID 设备挤下线。 | 客户端ID冲突。检查客户端ID生成策略，确保每个在线的设备都有唯一的客户端ID。 （若为偶发单次，可能是网络波动后的自动修复，无需处理。） |
kicked | 客户端被管控踢下线。 | 管理员操作。请检查MQTT服务的管控后台或API调用日志，确认是哪位管理员或哪个自动化策略执行了踢出操作及其原因。 |
keepalive_timeout | MQTT Broker 节点未在1.5倍 keep-alive 周期内收到客户端交互报文。 | 网络或客户端问题。 1. 检查设备网络连接是否稳定。 2. 检查设备CPU/内存负载是否过高，导致无法及时发送心跳包。 3. 如果是弱网环境，可适当调大 keep-alive 值 |
not_authenticated | 未认证，类似 HTTP 状态码401。 | 认证信息错误。检查客户端配置的用户名、密码、证书或Token等认证信息是否正确、是否与服务端配置一致。 |
not_authorized | 未授权，类似 HTTP 状态码403 | 权限不足。客户端认证成功，但无权连接或操作（如发布/订阅特定主题）。请检查ACL策略配置，为该客户端授予必要权限。 |
tcp_closed | TCP 连接已关闭。 | 网络层断开。原因如设备网络中断、NAT网关超时、防火墙策略等。 |
ping_without_connect | 客户端在发送 CONNECT 报文之前发送了 PING | 客户端SDK/固件Bug。检查并修复客户端 MQTT 协议实现代码，确保严格遵守 CONNECT -> 其他报文的连接建立顺序。 |
authentication_expired | 认证失败，JWT/SAS 等 Token 已过期。 | 凭证过期。客户端程序应具备刷新Token的能力。 |
too_many_connection | 超过集群/节点最大连接数。 | 服务端容量问题。 1. 联系我们，提升服务规格或最大连接数限制。 2. 排查是否有客户端异常（如代码Bug）导致创建了大量无效连接。 |
go_away | MQTT Broker 节点重启，优雅下线。 | 通常为服务器端升级或维护所致。客户端应实现自动重连机制，以便在服务端恢复后能自动连接回来。 |
client_id_too_long | 客户端 ID 超过最大限制。 | 客户端ID超长。检查ID长度（MQTT协议本身上限为23个字符）并修改客户端ID生成逻辑。 |
client_id_required | 持久会话连接时，缺少必要的客户端 ID 字段。 | 客户端协议错误。当 CleanSession=false 时，客户端ID不能为空。请修复客户端逻辑，要么提供一个ID，要么将 CleanSession 设为true。 |
client_id_invalid | 客户端ID不合规。客户端ID只能包含 [0-9a-zA-Z] 这些字符。请修改客户端ID生成逻辑，移除或替换非法字符。 | |
bad_will_message | 非法遗嘱消息。 | 遗嘱消息配置错误。检查客户端设置的遗嘱消息（Will Message），确认其主题（Topic）、内容（Payload）格式正确，且客户端有权限向该遗嘱主题发布消息。 |
server_internal_error | 服务端内部错误。 |
文档反馈