MQTT 协议支持
TMQTT 完整支持 MQTT v3.1.1 和 MQTT v5.0 两个主流协议版本，兼容市面上绝大多数 MQTT 客户端（如 Eclipse Paho、MQTTX、EMQX 客户端等）。
协议版本
| 版本 | 支持状态 | 说明 |
|---|---|---|
| MQTT v3.1.1 | 全面支持 | 业界最广泛使用的版本，所有核心特性均已实现 |
| MQTT v5.0 | 全面支持 | 新一代协议，在 v3.1.1 基础上增加了属性系统、增强认证等高级特性 |
客户端连接时会自动协商协议版本，TMQTT 根据客户端请求自动适配。
消息服务质量（QoS）
MQTT 定义了三个等级的消息传递可靠性，TMQTT 全部支持：
| QoS | 名称 | 含义 | 适用场景 |
|---|---|---|---|
| 0 | 最多一次 | 消息发出即忘，不保证送达，不占用额外资源 | 传感器周期上报、心跳、日志等允许偶尔丢失的数据 |
| 1 | 至少一次 | 保证消息送达，但可能重复 | 告警通知、状态变更等不可丢失的数据 |
| 2 | 恰好一次 | 保证消息送达且不重复，开销最大 | 计费、订单等严格要求精确一次的数据 |
主题（Topic）与通配符
MQTT 使用层级化的主题来组织消息，TMQTT 完整支持标准通配符：
+（单层通配符）：匹配一个主题层级- 例如
sensor/+/temperature可匹配sensor/room1/temperature和sensor/room2/temperature
- 例如
#（多层通配符）：匹配当前位置及之后的所有层级- 例如
sensor/#可匹配sensor/room1/temperature、sensor/room1/humidity等
- 例如
通配符仅在订阅时使用，发布消息时必须使用具体的主题名称。
保留消息（Retain）
发布消息时设置 Retain 标志，TMQTT 会将该消息保存为对应主题的"最新值"。
使用场景：设备状态展示。比如温度传感器每次上报时都设置 Retain，新订阅者连接后会立即收到该主题的最新温度值，无需等待下一次上报。
清除方式：向同一主题发布一条空内容（payload 为空）的 Retain 消息即可清除。
遗嘱消息（Will Message）
客户端连接时可以指定一条遗嘱消息。如果客户端异常断开（未正常发送 DISCONNECT），TMQTT 会自动发布这条遗嘱消息。
使用场景：其他设备订阅该主题后，可以立即感知到设备离线。
MQTT v5.0 新特性
v5.0 在 v3.1.1 基础上增加了许多实用特性，以下是 TMQTT 已支持的全部 v5.0 特性：
主题别名（Topic Alias）
高频通信时，可以用一个短数字代替完整的主题名称，减少每条消息的带宽开销。客户端和 TMQTT 之间会自动建立别名映射，对使用者透明。
共享订阅（Shared Subscription）
多个客户端以 $share/组名/主题 的格式订阅同一主题时，TMQTT 会以轮询方式将消息分配给组内各客户端，实现负载均衡消费。
示例：三个 Worker 客户端订阅 $share/workers/sensor/#，每条消息只会被其中一个 Worker 收到。
用户属性（User Properties）
消息可以携带自定义的键值对元数据，TMQTT 在转发时会原样透传这些属性。
示例：在消息中添加 source: "building-A" 属性，接收方可以据此做来源区分。
请求/响应模式（Request/Response）
通过 Response Topic 和 Correlation Data 属性，可以实现类似 HTTP 的请求-应答通信模式。客户端 A 发布请求时附带响应主题，客户端 B 处理后向该主题回复结果。
消息过期间隔（Message Expiry Interval）
发布消息时可以指定过期时间（秒），超过该时间的消息将被自动丢弃，避免过时的数据被误用。
会话过期间隔（Session Expiry Interval）
客户端断开后，其会话（订阅关系、离线消息等）会保留指定时长。超时后自动清理，避免资源无限积累。最大支持 1 天（86400 秒）。
订阅选项
订阅时可以附加以下选项：
- NoLocal：不接收自己发布的消息
- RetainAsPublished：收到的消息保留原始 Retain 标志（默认情况下转发时会清除）
- RetainHandling：控制订阅时是否推送保留消息（每次订阅推送 / 仅首次推送 / 不推送）
增强认证（AUTH）
v5.0 支持在标准 CONNECT 认证之外进行多轮认证握手（如 SCRAM），为后续集成更复杂的认证协议预留了接口。
WebSocket 接入
TMQTT 支持通过 WebSocket 传输 MQTT 协议，方便浏览器和移动端直连。
- WS 端口：默认 8083（明文）
- WSS 端口：默认 8084（加密，需配置证书）
- 子协议：使用标准
mqtt子协议，兼容mqttv3.1/mqttv3.1.1
WebSocket 连接的使用方式和普通 TCP 连接完全一致，支持所有 MQTT 特性。
系统主题（$SYS/）
TMQTT 会定期在 $SYS/ 前缀的主题上发布 Broker 运行状态数据，客户端订阅即可实时获取：
| 主题 | 内容 |
|---|---|
$SYS/broker/clients/total | 总连接数 |
$SYS/broker/clients/connected | 活跃连接数 |
$SYS/broker/messages/received | 累计接收消息数 |
$SYS/broker/messages/sent | 累计发送消息数 |
$SYS/broker/uptime | 运行时间（秒） |
$SYS/broker/version | Broker 版本号 |
订阅 $SYS/# 可以获取所有系统主题的数据，便于实时监控和调试。
Copyright (c) 2026 桃子 TaoZi.Pub https://taozi.pub | MIT License