消息队列 MQTT 版查询客户端事件

什么是客户端事件?
客户端事件是指在 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. 在左侧页签栏选择客户端管理，进入具体客户端详情页，下拉即可查看客户端事件。
﻿
方式二：
订阅系统事件 Topic（如$events/client_connected），即可接收到包含详细事件内容的事件消息，详情见下文事件主题。
事件主题
MQTT 系统将触发的事件以 QoS=0 消息发布到以下系统主题，业务系统可根据业务需要订阅。
主题名称
备注
$events/client_connected
客户端已连接。
$events/client_disconnected
客户端已断开连接。
$events/session_subscribed
客户端会话新增了订阅。
$events/session_unsubscribed
客户端会话取消了订阅。
$events/certificate_registered
客户端注册了设备证书。
$events/certificate_rejected
客户端设备证书被拒绝, 证书状态为非激活状态，例如 PENDING_ACTIVATION。
连接类事件
客户端连接完成或者断开网络连接后，MQTT Broker 会触发客户端连接或者客户端断开连接事件。
事件消息体是 UTF-8编码的，包含以下字段的 JSON 字符串。
客户端连接事件
客户端成功连接后，MQTT Broker 会触发客户端连接事件，发送消息至主题 $events/client_connected。
事件消息体是 UTF-8 编码的 JSON 字符串，并包含以下字段：
字段
语义
示例值
clientid
客户端 ID，经常为产品序列号，车架号等唯一编码。
306520284186458
clean_start
会话是否为 clean-start。
true
connected_at
会话连接时间，自1970/01/01 00:00:00以来的毫秒数。
1717651184811
event
事件类型，固定值 "client.connected"。
client.connected
keepalive
客户端 "keep-alive" 周期， 单位：秒。
60
node
MQTT Broker 节点信息（IP 地址：端口）。
10.0.0.1:1883
proto_ver
协议版本 3/4/5。
4
timestamp
事件产生时间，自1970/01/01 00:00:00以来的毫秒数。
1717651184811
username
用户名。
sample_user
客户端断开事件
客户端断开连接后，MQTT Broker 会触发客户端断开事件，发送消息至主题 $events/client_disconnected。订阅者可以检视 clientid、reason 等字段，以做出适当的响应。
事件消息体是 UTF-8 编码的 JSON 字符串，并包含以下字段：
字段
语义
示例值
clientid
客户端 ID，经常为产品序列号，车架号等唯一编码。
306520284186458
event
事件类型，固定值: "client.disconnected"。
client.disconnected
disconnected_at
断开事件产生时间，自1970/01/01 00:00:00以来的毫秒数。
1717651184811
node
MQTT Broker 节点。
10.0.0.1:1883
reason
客户端断开的原因，枚举值，详细参见下表的客户端断开原因。
normal
username
用户名。
sample_user
peername
客户端网络地址。
IP:Port
sockname
MQTT Broker 网络地址。
IP:Port
客户端断开原因
断开连接原因
语义
处理建议
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 包含非法字符，详细参见 Spec 3.1.3.1。
客户端ID不合规。客户端ID只能包含 [0-9a-zA-Z] 这些字符。请修改客户端ID生成逻辑，移除或替换非法字符。
bad_will_message
非法遗嘱消息。
遗嘱消息配置错误。检查客户端设置的遗嘱消息（Will Message），确认其主题（Topic）、内容（Payload）格式正确，且客户端有权限向该遗嘱主题发布消息。
server_internal_error
服务端内部错误。
服务端问题。请联系我们并提供相关信息（如时间点、实例ID、客户端ID）以排查服务端问题。
订阅类事件
客户端订阅事件
客户端会话新增订阅后，MQTT Broker 会触发客户端订阅事件，发送消息至主题$events/session_subscribed
事件消息体是 UTF-8 编码的 JSON 字符串，并包含以下字段：
字段
语义
示例值
clientid
客户端 ID，经常为产品序列号，车架号等唯一编码。
306520284186458
event
事件类型，固定值："client.subscribed"。
client.subscribed
node
MQTT Broker 节点。
10.0.0.1:1883
peerhost
客户端地址。
10.0.0.1:1234
qos
订阅 QoS。
0/1/2
timestamp
订阅事件产生时间，自1970/01/01 00:00:00以来的毫秒数。
1717651184811
topic
订阅的 Topic Filter。
home/#
客户端取消订阅事件
客户端会话取消订阅后，MQTT Broker 会触发客户端订阅事件，发送消息至主题$events/session_unsubscribed
事件消息体是 UTF-8 编码的 JSON 字符串，并包含以下字段：
字段
语义
示例值
clientid
客户端 ID，经常为产品序列号，车架号等唯一编码。
306520284186458
event
事件类型，固定值："client.unsubscribed"。
client.unsubscribed
node
MQTT Broker 节点。
10.0.0.1:1883
peerhost
客户端地址。
10.0.0.1:1234
qos
订阅 QoS。
0/1/2
timestamp
取消订阅事件产生时间，自1970/01/01 00:00:00以来的毫秒数。
1717651184811
topic
订阅的Topic Filter。
home/#
证书生命周期事件
如果 X.509配置使用"一机一证"模式，以下事件类型可能会产生。
客户端证书注册事件
在自动注册模式下, 客户端证书在客户端首次连接时自动注册到云服务。为了标识新的设备加入集群，MQTT 服务会触发客户端注册事件，并发送消息到主题：$events/certificate_registered。
事件消息体是 UTF-8 编码的 JSON 字符串，并包含以下字段：
字段
语义
示例值
event
事件类型，固定值 "certificate.registered"
certificate.registered
timestamp
断开事件产生时间，自1970/01/01 00:00:00以来的毫秒数。
1717651184811
node
MQTT Broker 节点。
10.0.0.1:1234
peerName
客户端地址 IP:port。
10.0.0.2:1234
caSn
CA 证书序列号。
7439e17052ff2edbeda4f5db379a69fd8c5f48a5
sn
设备证书序列号。
1bf2f708389ad1397628ab3c6c33b1636b7e49f5
commonName
设备证书常用名。
VIN-1234-5678
status
设备证书状态。
pending_activation/active/inactive/revoked
certificateChainSn
设备证书链序列号。
1bf2f708389ad1397628ab3c6c33b1636b7e49f5,7439e17052ff2edbeda4f5db379a69fd8c5f48a5
客户端证书拒绝事件
如果客户端证书的状态是: 待激活（PENDING_ACTIVATION），客户端尝试连接时，将触发客户端拒绝事件，并发送事件消息到主题：$events/certificate_rejected
消息体是 UTF-8编码的 JSON 字符串, 并包含以下字段：
字段
语义
示例值
event
事件类型，固定值："certificate.rejected"。
certificate.rejected
timestamp
事件产生时间，自1970/01/01 00:00:00以来的毫秒数。
1717651184811
node
MQTT Broker 节点。
10.0.0.1:1234
peerName
客户端地址 IP:port。
10.0.0.2:1234
caSn
CA 证书序列号。
7439e17052ff2edbeda4f5db379a69fd8c5f48a5
sn
设备证书序列号。
1bf2f708389ad1397628ab3c6c33b1636b7e49f5
commonName
设备证书常用名。
VIN-1234-5678
status
设备证书状态。
inactive/revoked/pending_activation/active
certificateChainSn
设备证书链序列号。
1bf2f708389ad1397628ab3c6c33b1636b7e49f5,7439e17052ff2edbeda4f5db379a69fd8c5f48a5
客户端证书拒绝原因
拒绝原因
语义
处理建议
inactive
证书未注册
注册证书。请在 MQTT 控制台注册该客户端证书。
revoked
证书吊销
更换证书。该证书已被列入吊销列表（CRL），通常是出于安全原因（如密钥泄露）。请确认吊销原因。如需恢复设备连接，应为其颁发并配置新的证书
pending_activation
证书未激活
激活证书。证书已在平台注册但尚未激活。请前往控制台，找到该证书并完成激活操作，以允许其建立连接。
﻿
﻿
﻿
﻿
﻿
﻿
﻿
﻿

主题名称	备注
$events/client_connected	客户端已连接。
$events/client_disconnected	客户端已断开连接。
$events/session_subscribed	客户端会话新增了订阅。
$events/session_unsubscribed	客户端会话取消了订阅。
$events/certificate_registered	客户端注册了设备证书。
$events/certificate_rejected	客户端设备证书被拒绝, 证书状态为非激活状态，例如 PENDING_ACTIVATION。

字段	语义	示例值
clientid	客户端 ID，经常为产品序列号，车架号等唯一编码。	306520284186458
clean_start	会话是否为 clean-start。	true
connected_at	会话连接时间，自1970/01/01 00:00:00以来的毫秒数。	1717651184811
event	事件类型，固定值 "client.connected"。	client.connected
keepalive	客户端 "keep-alive" 周期，单位：秒。	60
node	MQTT Broker 节点信息（IP 地址：端口）。	10.0.0.1:1883
proto_ver	协议版本 3/4/5。	4
timestamp	事件产生时间，自1970/01/01 00:00:00以来的毫秒数。	1717651184811
username	用户名。	sample_user

断开连接原因	语义	处理建议
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 包含非法字符，详细参见 Spec 3.1.3.1。	客户端ID不合规。客户端ID只能包含 [0-9a-zA-Z] 这些字符。请修改客户端ID生成逻辑，移除或替换非法字符。
bad_will_message	非法遗嘱消息。	遗嘱消息配置错误。检查客户端设置的遗嘱消息（Will Message），确认其主题（Topic）、内容（Payload）格式正确，且客户端有权限向该遗嘱主题发布消息。
server_internal_error	服务端内部错误。	服务端问题。请联系我们并提供相关信息（如时间点、实例ID、客户端ID）以排查服务端问题。

拒绝原因	语义	处理建议
inactive	证书未注册	注册证书。请在 MQTT 控制台注册该客户端证书。
revoked	证书吊销	更换证书。该证书已被列入吊销列表（CRL），通常是出于安全原因（如密钥泄露）。请确认吊销原因。如需恢复设备连接，应为其颁发并配置新的证书
pending_activation	证书未激活	激活证书。证书已在平台注册但尚未激活。请前往控制台，找到该证书并完成激活操作，以允许其建立连接。

查询客户端事件

本页目录：

什么是客户端事件?

事件举例说明

查看客户端事件

事件主题

连接类事件

客户端连接事件

客户端断开事件

客户端断开原因

订阅类事件

客户端订阅事件

客户端取消订阅事件

证书生命周期事件

客户端证书注册事件

客户端证书拒绝事件

客户端证书拒绝原因