什么是客户端事件
客户端事件是指在 MQTT 协议通信过程中，针对客户端会触发的一系列状态变化和交互行为的通知。通过追踪系统事件，用户可以及时排查定位分析问题，保障系统稳定性。
一个管理大量 IoT 设备的挑战，就是在设备离线时如何及时应对。设计良好的业务系统通常需要检视并归类设备离线原因，然后激活对应的预案措施。
为了实现这样的业务目标，业务应用可以订阅
$events/client/disconnect 主题。一旦设备离线，MQTT 系统将触发客户端事件消息。业务系统将会及时收到类似下面事件内容：{ "clientid": "V622-XXX-XXX","username": "sample-user","event": "client.disconnected","reason": "authentication_expired","node": "sz-h-125xm","peername": "10.0.0.1:5768","disconnected_at": 1724136603064}
查看客户端事件
方式一：
1. 登录 MQTT 控制台。
2. 在左侧导航栏单击资源管理 > 集群管理，选择好地域后，单击目标集群的“ID”，进入集群基本信息页面。
3. 在左侧页签栏选择客户端管理，进入具体客户端详情页，下拉即可查看客户端事件。
方式二：
事件方言
事件方言指系统事件的主题格式与消息结构标准，消息队列 MQTT 版支持多种版本的事件主题（v1、v2、v3，默认版本为v3），可根据业务需求在控制台进行事件的格式切换。
事件方言设置
1. 登录 MQTT 控制台。
2. 在左侧导航栏单击资源管理 > 集群管理，选择好地域后，单击目标集群的“ID”，进入集群基本信息页面，右下角可进行系统事件的方言修改。
系统事件 Topic
MQTT 系统将触发的事件以 QoS=0 消息发布到以下 Topic，业务系统可根据业务需要订阅。
事件类型 | 系统事件 Topic（v1/v2） | 系统事件 Topic（v3，默认版本） | 备注 |
$events/client_connected | $events/client/connected | 客户端连接事件 | |
$events/client_disconnected | $events/client/disconnected | ||
$events/session_subscribed | $events/session/subscribed | 客户端会话新增了订阅。 | |
$events/session_unsubscribed | $events/session/unsubscribed | 客户端会话取消了订阅。 | |
$events/certificate_registered | $events/certificate/registered | 客户端注册了设备证书。 | |
$events/certificate_rejected | $events/certificate/rejected |
订阅后的返回字段会根据系统事件选择的方言版本不同而有所差别，各类事件返回的字具体字段及详细说明见下文。
连接类事件
客户端连接事件
客户端成功连接后，MQTT Broker 会触发客户端连接事件，发送消息至主题
$events/client/connected（默认v3版本）。事件消息体是 UTF-8 编码的 JSON 字符串，并包含以下字段：
系统事件版本 | 字段 | 语义 | 示例值 |
v1/v3 | event | 事件类型，固定值 "client.connected"。 | client.connected |
| clientid | 客户端 ID，经常为产品序列号，车架号等唯一编码。 | 306520284186458 |
| username | 用户名 | user |
| clean_start | 会话是否为 clean-start。 | true |
| connected_at | 会话连接时间，自1970/01/01 00:00:00以来的毫秒数。 | 1717651184811 |
| keepalive | 客户端 "keep-alive" 周期， 单位：秒。 | 60 |
| expiry_interval | 会话过期时间 | 60 |
| proto_ver | 协议版本号 3/4/5。 | 4 |
| peername | 客户端地址 | 192.168.1.100:54321 |
| sockname | 服务端监听地址 | 0.0.0.0:1883 |
| node | MQTT Broker 节点信息（IP 地址：端口）。 | 10.0.0.1:1883 |
| instance | 实例 ID | mqtt-3wmngqam |
| timestamp | 事件产生时间，自1970/01/01 00:00:00以来的毫秒数。 | 1717651184811 |
| dialect | 系统事件版本 | v3 |
| certificateChainSn | 证书链序列号（未提供证书进行认证时不会出现） | 1bf2f708389ad1397628ab3c6c33b1636b7e49f5,7439e17052ff2edbeda4f5db379a69fd8c5f48a5 |
v2 | eventType | 事件类型，固定值 "connect"。 | connect |
| eventIndex | 事件唯一序号/ID，用于区分每一次事件上报。 | 00661A3F01000001 |
| clientId | 客户端 ID | device-sensor-001 |
| time | 事件时间戳（毫秒） | 1738123456789 |
| channelId | 通道 ID，用于标识当前会话的底层通信通道。 | 7f000001fffe0001 |
| clientIp | 客户端 IP 和端口，格式为“ip:port”。 | 192.168.1.10:50234 |
客户端断开事件
客户端断开连接后，MQTT Broker 会触发客户端断开事件，发送消息至主题
$events/client/disconnected（默认v3版本）。订阅者可以检视 clientid、reason 等字段，以做出适当的响应。事件消息体是 UTF-8 编码的 JSON 字符串，并包含以下字段：系统事件版本 | 字段 | 语义 | 示例值 |
v1/v3 | event | 事件类型，固定值: "client.disconnected"。 | client.disconnected |
| clientid | 客户端 ID，经常为产品序列号，车架号等唯一编码。 | 306520284186458 |
| username | 用户名。 | sample_user |
| reason_code | normal_disconnect | |
| reason | normal | |
| disconnected_at | 断开事件产生时间，自1970/01/01 00:00:00以来的毫秒数。 | 1717651184811 |
| expiry_interval | 会话过期时间 | 60 |
| peername | 客户端网络地址。 | 192.168.1.100:54321 |
| sockname | MQTT Broker 网络地址。 | 0.0.0.0:1883 |
| node | MQTT Broker 节点。 | 10.0.0.1:1883 |
| instance | 实例 ID | mqtt-3wmngqam |
| timestamp | 事件产生时间，自1970/01/01 00:00:00以来的毫秒数。 | 1717651184811 |
| certificateChainSn | 证书链序列号（未提供证书进行认证时不会出现） | 1bf2f708389ad1397628ab3c6c33b1636b7e49f5,7439e17052ff2edbeda4f5db379a69fd8c5f48a5 |
| dialect | 系统事件版本 | v3 |
v2 | eventType | 事件类型，固定值 "connect"。 | disconnect |
| eventIndex | 事件唯一序号/ID，用于区分每一次事件上报。 | 00661A3F01000001 |
| clientId | 客户端 ID | 306520284186458 |
| time | 事件时间戳（毫秒） | 1738123456789 |
| channelId | 通道 ID，用于标识当前会话的底层通信通道。 | 7f000001fffe0001 |
| clientIp | 客户端 IP 和端口，格式为“ip:port”。 | 192.168.1.10:50234 |
| reason_code | normal_disconnect | |
| reason | normal | |
客户端断开原因
断开连接原因（reason） | 语义 | 处理建议 |
normal | 服务端收到 DISCONNECT 报文后正常断开。 | 正常事件。客户端主动发起的断连，确认是否为业务逻辑预期（如客户端任务完成主动退出）。 |
takeovered | 客户端被相同客户端 ID 设备挤下线。 | 客户端 ID 冲突。检查客户端 ID 生成策略，确保每个在线的设备都有唯一的客户端 ID。 （若为偶发单次，可能是网络波动后的自动修复，无需处理。） |
kicked | 客户端被管控踢下线。 | 管理员操作。请检查 MQTT 服务的管控后台或 API 调用日志，确认是哪位管理员或哪个自动化策略执行了踢出操作及其原因。 |
keepalive_timeout | MQTT Broker 节点未在1.5倍 keep-alive 周期内收到客户端交互报文，服务端主动关闭连接。此时底层 TCP 连接仍然存活，问题发生在 MQTT 应用层。 | 网络或客户端问题。 1. 检查设备网络连接是否稳定。 2. 检查设备 CPU/内存负载是否过高，导致无法及时发送心跳包。 3. 如果是弱网环境，可适当调大 keep-alive 值 |
not_authenticated | 未认证，类似 HTTP 状态码401。 | 认证信息错误。检查客户端配置的用户名、密码、证书或 Token 等认证信息是否正确、是否与服务端配置一致。 |
not_authorized | 未授权，类似 HTTP 状态码403 | 权限不足。客户端认证成功，但无权连接或操作（如发布/订阅特定主题）。请检查 ACL 策略配置，为该客户端授予必要权限。 |
tcp_closed | TCP 连接已关闭，但客户端未按协议发送 MQTT DISCONNECT 报文。 | 网络层断开。原因如设备网络中断、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 | 服务端内部错误。 | |
connection_reset | 底层的 TCP 连接被重置 | 网络异常，通常由于客户端重启或中间网络设备主动发送 RST 包导致，客户端应实现自动重连机制，以便后续自动恢复连接。 |
network_error | 网络传输层异常。服务端通过 tcp-keep-alive-probe 在传输层主动探测，感知到底层 TCP 连接已断开。 | 常见的网络链路故障（如丢包严重、网络抖动或防火墙拦截）。建议检查客户端网络连通性，并确保开启 Keep Alive 心跳监测。客户端应实现自动重连机制，以便网络回复后自动恢复连接。 |
订阅类事件
客户端订阅事件
客户端会话新增订阅后，MQTT Broker 会触发客户端订阅事件，发送消息至主题
$events/session/subscribed事件消息体是 UTF-8 编码的 JSON 字符串，并包含以下字段：
系统事件版本 | 字段 | 语义 | 示例值 |
v1/v2/v3 | event | 事件类型，固定值："client.subscribed"。 | client.subscribed |
| clientid | 客户端 ID，经常为产品序列号，车架号等唯一编码。 | 306520284186458 |
| username | 用户名。 | sample_user |
| topic | 订阅的 Topic Filter。 | home/# |
| qos | 订阅 QoS。 | 0/1/2 |
| result | 订阅结果。 | at_least_once |
| reason_code | granted_qos_1 | |
| peerhost | 客户端地址。 | 10.0.0.1:1234 |
| node | MQTT Broker 节点。 | 10.0.0.1:1883 |
| instance | 实例 ID | mqtt-3wmngqam |
| timestamp | 订阅事件产生时间，自1970/01/01 00:00:00以来的毫秒数。 | 1717651184811 |
| certificateChainSn | 证书链序列号（未提供证书进行认证时不会出现） | 1bf2f708389ad1397628ab3c6c33b1636b7e49f5,7439e17052ff2edbeda4f5db379a69fd8c5f48a5 |
客户端取消订阅事件
客户端会话取消订阅后，MQTT Broker 会触发客户端订阅事件，发送消息至主题
$events/session/unsubscribed（默认v3版本）。事件消息体是 UTF-8 编码的 JSON 字符串，并包含以下字段：
系统事件版本 | 字段 | 语义 | 示例值 |
v1/v2/v3 | event | 事件类型，固定值："client.unsubscribed"。 | client.unsubscribed |
| clientid | 客户端 ID，经常为产品序列号，车架号等唯一编码。 | 306520284186458 |
| username | 用户名。 | sample_user |
| topic | 订阅的 Topic Filter。 | home/# |
| qos | 订阅 QoS。 | 0/1/2 |
| peerhost | 客户端地址。 | 10.0.0.1:1234 |
| node | MQTT Broker 节点。 | 10.0.0.1:1883 |
| instance | 实例 ID | mqtt-3wmngqam |
| timestamp | 订阅事件产生时间，自1970/01/01 00:00:00以来的毫秒数。 | 1717651184811 |
| certificateChainSn | 证书链序列号（未提供证书进行认证时不会出现） | 1bf2f708389ad1397628ab3c6c33b1636b7e49f5,7439e17052ff2edbeda4f5db379a69fd8c5f48a5 |
证书生命周期事件
如果 X.509配置使用"一机一证"模式，以下事件类型可能会产生。
客户端证书注册事件
在自动注册模式下, 客户端证书在客户端首次连接时自动注册到云服务。为了标识新的设备加入集群，MQTT 服务会触发客户端注册事件，并发送消息到主题：
$events/certificate/registered（默认v3版本）。事件消息体是 UTF-8 编码的 JSON 字符串，并包含以下字段：系统事件版本 | 字段 | 语义 | 示例值 |
v1/v2/v3 | event | 事件类型，固定值 "certificate.registered" | certificate.registered |
| sn | 设备证书序列号。 | 1bf2f708389ad1397628ab3c6c33b1636b7e49f5 |
| caSn | CA 证书序列号。 | 7439e17052ff2edbeda4f5db379a69fd8c5f48a5 |
| commonName | 设备证书常用名。 | VIN-1234-5678 |
| status | 设备证书状态。 | pending_activation/active/inactive/revoked |
| certificateChainSn | 设备证书链序列号。 | 1bf2f708389ad1397628ab3c6c33b1636b7e49f5,7439e17052ff2edbeda4f5db379a69fd8c5f48a5 |
| peerName | 客户端地址 IP:port。 | 10.0.0.2:1234 |
| node | MQTT Broker 节点。 | 10.0.0.1:1234 |
| instance | 实例 ID | mqtt-3wmngqam |
| timestamp | 断开事件产生时间，自1970/01/01 00:00:00以来的毫秒数。 | 1717651184811 |
客户端证书拒绝事件
如果客户端证书的状态是: 待激活（PENDING_ACTIVATION），客户端尝试连接时，将触发客户端拒绝事件，并发送事件消息到主题：
$events/certificate/rejected（默认v3版本）。消息体是 UTF-8编码的 JSON 字符串, 并包含以下字段：
系统事件版本 | 字段 | 语义 | 示例值 |
v1/v2/v3 | event | 事件类型，固定值："certificate.rejected"。 | certificate.rejected |
| reason | 拒绝的详细原因 | Client certificate is inactive |
| sn | 设备证书序列号。 | 1bf2f708389ad1397628ab3c6c33b1636b7e49f5 |
| caSn | CA 证书序列号。 | 7439e17052ff2edbeda4f5db379a69fd8c5f48a5 |
| commonName | 设备证书常用名。 | VIN-1234-5678 |
| status | 设备证书状态。 | inactive/revoked/pending_activation/active |
| certificateChainSn | 设备证书链序列号。 | 1bf2f708389ad1397628ab3c6c33b1636b7e49f5,7439e17052ff2edbeda4f5db379a69fd8c5f48a5 |
| peerName | 客户端地址 IP:port。 | 10.0.0.2:1234 |
| node | MQTT Broker 节点。 | 10.0.0.1:1234 |
| instance | 实例 ID | mqtt-3wmngqam |
| timestamp | 事件产生时间，自1970/01/01 00:00:00以来的毫秒数。 | 1717651184811 |
客户端证书拒绝原因
拒绝原因（reason） | 语义 | 处理建议 |
Client certificate is inactive | 证书未注册 | |
Client certificate is revoked | 证书被吊销 | 更换证书。该证书已被列入吊销列表（CRL），通常是出于安全原因（如密钥泄露）。请确认吊销原因。如需恢复设备连接，应为其颁发并配置新的证书 |
Client certificate is pending_activation | 证书未激活 | 激活证书。证书已在平台注册但尚未激活。请前往控制台，找到该证书并完成激活操作，以允许其建立连接。 |
