新功能发布记录
查询客户端事件
什么是客户端事件?
客户端事件是指在 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 系统将触发的事件以 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不合规。客户端ID只能包含 [0-9a-zA-Z] 这些字符。请修改客户端ID生成逻辑，移除或替换非法字符。 | |
bad_will_message | 非法遗嘱消息。 | 遗嘱消息配置错误。检查客户端设置的遗嘱消息（Will Message），确认其主题（Topic）、内容（Payload）格式正确，且客户端有权限向该遗嘱主题发布消息。 |
server_internal_error | 服务端内部错误。 |
订阅类事件
客户端订阅事件
客户端会话新增订阅后，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 | 证书未注册 | |
revoked | 证书吊销 | 更换证书。该证书已被列入吊销列表（CRL），通常是出于安全原因（如密钥泄露）。请确认吊销原因。如需恢复设备连接，应为其颁发并配置新的证书 |
pending_activation | 证书未激活 | 激活证书。证书已在平台注册但尚未激活。请前往控制台，找到该证书并完成激活操作，以允许其建立连接。 |
文档反馈