什么是客户端事件?
客户端事件是指在 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}
事件主题
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 字符串。
客户端连接事件
字段 | 语义 | 示例值 |
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 等字段，以做出适当的响应。
字段 | 语义 | 示例值 |
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 设备挤下线。 |
kicked | 客户端被管控踢下线。 |
keepalive_timeout | MQTT Broker 节点未在1.5倍 keep-alive 周期内收到客户端交互报文。 |
not_authenticated | 未认证，类似 HTTP 状态码401。 |
not_authorized | 未授权，类似 HTTP 状态码403 |
tcp_closed | TCP 连接已关闭。 |
ping_without_connect | 协议错误，客户端在 CONNECT 完成之前发送了 PING 报文。 |
authentication_expired | 认证失败，JWT/SAS 等 Token 已过期。 |
too_many_connection | 超过集群/节点最大连接数。 |
go_away | MQTT Broker 节点重启，优雅下线。 |
client_id_too_long | 客户端 ID 超过最大限制。 |
client_id_required | 持久会话连接时，缺少必要的客户端 ID 字段。 |
client_id_invalid | |
bad_will_message | 非法遗嘱消息。 |
server_internal_error | 服务端内部错误。 |
订阅类事件
客户端订阅事件
字段 | 语义 | 示例值 |
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/# |
客户端取消订阅事件
字段 | 语义 | 示例值 |
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 | 设备证书状态。 | pending_activation/active/inactive/revoked |
certificateChainSn | 设备证书链序列号。 | 1bf2f708389ad1397628ab3c6c33b1636b7e49f5,7439e17052ff2edbeda4f5db379a69fd8c5f48a5 |
