MQTT 5 主题设计与 QoS 选型:把共享订阅、会话过期、遗嘱消息放进同一张设计图
先把基线钉死:MQTT 5.0 是 OASIS 在 2019 年 3 月 7 日发布的 Standard,到 2026 年 11 月还没有 5.1。下面每一条行为都能在规范的对应条款里查到。
broker 侧我按 EMQX 6.3.x 这条 LTS 线说,最新补丁号与 EOL 日期以 EMQX 版本发布说明 为准。它家 mqtt 配置的默认值我用 6.x 的 schema 核过。换别的 broker,默认值一定不一样,看到数字请自己再核一遍。
1. 这节课的交付物
读完你应该能:
- 画出一条从设备到业务库的 topic 链路,并对每一级分层给出理由
- 判断共享订阅在你这个场景里该不该上,上哪种分发策略
- 说出会话过期、消息过期、遗嘱延迟三个属性的缺省值,以及缺省值会把系统带到哪里
- 按业务后果而不是"这条数据重不重要"来选 QoS
预期输出有三样:一张 5 行的 topic 表、一张 QoS 决策表、三个能跑起来的脚本。
2. 这张图是本篇的坐标
四道设计里,前三道是协议层,最后一道是架构层。本文按这个顺序走,每一段都给反例。
3. 四千台设备挤在三分钟里重连,账算在谁头上
一个园区能耗项目,约 4000 台表计,QoS 1 上行,网关侧做 5 秒轮询重连。某次园区交换机重启,4000 台设备挤在 3 分钟里重连,broker 端积压了近 40 万条待投消息。两个小时后业务侧才发现,有一半的电量数据没入库。
运维第一反应是"broker 在重传风暴"。我翻日志看到的不是这样:broker 没有主动重发任何一条,问题在订阅侧,清洗服务只部署了一个实例,而且是普通订阅。
那 40 万条排队的消息最后去哪了?这就是第 6 节要讲的默认值。
4. 主题分层:路由键和过滤条件不是一回事
topic 是一串用 / 分隔的层级,broker 只做层级匹配,不解析语义。所以分层的第一原则是:每一层都必须是稳定维度。
| 层级 | 示例 | 作用 | 变更成本 |
|---|---|---|---|
| 租户 | factory-a | 多租户隔离、ACL 前缀 | 高 |
| 位置 | line1 | 现场排障定位 | 中 |
| 设备类型 | th200 | 换型时批量订阅 | 低 |
| 设备 ID | dev-0001 | 点对点指令下行 | 极低 |
| 数据类别 | telemetry / status | 区分冷热与 QoS | 低 |
反例一:把业务属性塞进 topic,比如 factory-a/line1/th200/temp-high-21.4。听起来聪明,实际上阈值一调就长出一批新前缀,订阅端要么改代码,要么退化成 # 全收。
反例二:层级过深。EMQX 6.3.x 的 mqtt.max_topic_levels 默认 128,机器不嫌多,人脑维护不了 8 层以上。
变量放 payload,或者放 MQTT 5 的 User Property。topic 只留不变量。顺带提一句,6.3.x 起 CONNECT 和 Will 里的 User Property 有对数上限(mqtt.max_connect_user_properties,具体值随补丁版本可能调整,以 EMQX 配置手册 为准),把大对象塞进属性这条路也有上限。
5. 共享订阅:扩容单位是组名,不是订阅数
规范里共享订阅的格式是 $share/{ShareName}/{filter},ShareName 不能含 /、+、#。同一条消息会投给每个组各一次,组内只有一个会话收到。
EMQX 6.3.x 的 mqtt.shared_subscription_strategy 有七种,选错的代价不在吞吐,在顺序:
| 策略 | 组内怎么选 | 适合 | 会踩到什么 |
|---|---|---|---|
random | 随机挑一个在线成员 | 成员同质、任务无状态 | 同一设备的消息乱序,基本不推荐 |
round_robin(默认) | 轮转 | 无状态清洗、ETL | 有状态计算被打散 |
round_robin_per_group | 按组轮转 | 多租户各自均摊 | 组间流量不均时单组过载 |
sticky | 粘住一个成员直到它断开 | 会话内状态最重 | 滚动发布时整组状态迁移一次 |
local | 优先本节点订阅者 | 多机房就近投递 | 节点故障时该批消息要重投 |
hash_clientid | 按 publisher 的 ClientID 取模 | 按设备串行处理 | 扩缩容时部分键重新映射 |
hash_topic | 按主题取模 | 按主题分片、跨设备聚合 | 热点主题仍会集中到一个成员 |
无状态清洗选 round_robin;要按设备串行处理选 hash_clientid;多机房部署想少跨节点流量选 local。扩缩容那两行是有代价的:hash_* 策略下 worker 数量一变,被重新映射的键会短暂落到另一个成员上,那段时间的状态缓存是冷的。所以这类策略要么固定 worker 数,要么接受一次冷启动窗口。
这里有一处只有被队列打满过才会记住的细节:共享订阅如果配了长会话,客户端断线期间那个会话仍然在收消息,发布速率一高,队列就溢出丢消息。EMQX 文档给的结论是共享订阅用 clean session、v5 用短 SessionExpiryInterval。我的经验值是 30 到 120 秒,够扛一次重连,不够扛一场交换机重启。
6. 三个属性的默认值
| 属性 | 出现位置 | 规范缺省 | EMQX 6.3.x 侧 | 默认值下的后果 |
|---|---|---|---|---|
| Session Expiry Interval | CONNECT / CONNACK / DISCONNECT | 0,连接断开会话即结束 | 上限 session_expiry_interval = 2h,客户端不写仍是 0 | 断线期间的 QoS1 消息全丢,重连后订阅要重建 |
| Message Expiry Interval | PUBLISH、Will Properties | 不过期 | message_expiry_interval = infinity | 离线队列里的旧数据会在重连时一次性倒给业务 |
| Will Delay Interval | Will Properties | 0,立即发 | 由客户端设,broker 不替你兜底 | 一次 1 秒抖动就被判成掉线 |
从 v3 迁到 v5 最容易踩的就是第一个。v3.1.1 里 clean_session=false 本身就代表持久会话;v5 把这件事拆成 Clean Start 和 Session Expiry Interval 两个独立字段。很多脚本把 clean_session=False 改成 clean_start=False 就以为迁完了,没写 SEI,于是断线后会话立刻销毁,订阅全没。症状是"连上了但收不到消息",日志里一切正常。
规范里还有一句容易被跳过:如果 Will Delay Interval 比 Session Expiry Interval 长,规范建议客户端用 DISCONNECT 的原因码 0x04(Disconnect with Will Message)显式要求发布遗嘱,否则会话先结束,遗嘱的时序跟你想的不一样。
7. QoS 与重传:规范只允许在一个时刻重发
| QoS | 报文往返 | 可能结果 | 适合 | 不适合 |
|---|---|---|---|---|
| 0 | 1 | 丢 | 高频遥测,下一条马上就到 | 计费、告警 |
| 1 | 2 | 重复 | 绝大多数上行 | 不写幂等就直接入库 |
| 2 | 4 | 一次 | 极少数资金类场景 | 高吞吐上行 |
重传这件事规范写得很硬。[MQTT-4.4.0-1]:客户端和服务端重发未确认的 PUBLISH 与 PUBREL,只在"以 Clean Start=0 重连且会话存在"时才是 MUST,"MUST NOT resend messages at any other time"。连接活着的时候因为超时重发,是不允许的。
所以你在抓包里看到的大片 DUP=1,多半来自设备端自己在重连,或者两个客户端用了同一个 ClientID 互相踢。EMQX 侧对应的是 mqtt.retry_interval,默认 infinity,也就是不主动重发。很多人以为它是 30 秒。
更值得盯住的是 6.3.x 升级说明里的一条:MQTT connector 和 cluster link 早先把 retry_interval 的秒数又乘了 1000,后来改成按配置的秒数执行(生效补丁与 issue 号见 EMQX 发布说明)。老集群升上来,QoS1 的重发间隔会突然变短,下游 bridge 没做幂等的话,升级窗口能看到一批重复写入。
不建议这样用:把 QoS 2 当默认。四个报文的往返换来的"业务不需要去重",吞吐和延迟都要付代价。资金类场景真正的解法是业务主键幂等加 QoS 1。我在两个项目里把默认 QoS 从 2 降到 1,重复率没有变化,因为重复本来就是业务侧重试造成的。
8. 动手:三个脚本看见三个默认值
前置:EMQX 6.3.x(Docker 或二进制都行);Python 3.11 加 pip install paho-mqtt==2.2.0。选 2.x 是因为 1.x 里 CallbackAPIVersion 的用法不同,版本与 Python 版本要求见 paho-mqtt releases。
第一个是设备端上线并挂遗嘱。
# device.py —— paho-mqtt 2.2.0 / Python 3.11 / EMQX 6.3.x
import paho.mqtt.client as mqtt
from paho.mqtt.packettypes import PacketTypes
from paho.mqtt.properties import Properties
will = Properties(PacketTypes.WILLMESSAGE)
will.WillDelayInterval = 30 # 秒:断线 30s 后才发遗嘱,避开抖动
will.MessageExpiryInterval = 300 # 遗嘱本身也带生命周期
conn = Properties(PacketTypes.CONNECT)
conn.SessionExpiryInterval = 3600 # v3 的 clean_session=False 在 v5 里必须显式写
cli = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
client_id="dev-0001", protocol=mqtt.MQTTv5)
cli.will_set("factory/a/line1/dev-0001/status", b'{"online":false}',
qos=1, retain=True, properties=will)
cli.connect("127.0.0.1", 1883, keepalive=60, clean_start=False, properties=conn)
cli.loop_start()
# 预期输出(Dashboard → 连接 → dev-0001 详情):
# clean_start = false, session_expiry_interval = 3600, will_delay_interval = 30
# kill -9 之后约 30 秒,status 上出现 {"online":false}第二个是两个进程跑同一个共享订阅。
# worker.py —— 用 client_id worker-1 / worker-2 各跑一次
import paho.mqtt.client as mqtt
def on_message(cli, ud, msg):
print(msg.topic, msg.payload.decode())
c = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
client_id="worker-1", protocol=mqtt.MQTTv5)
c.on_message = on_message
c.connect("127.0.0.1", 1883, keepalive=30, clean_start=True)
c.subscribe("$share/etl/factory/+/+/+/telemetry", qos=1)
c.loop_forever()
# 预期输出:只有 worker-1 打印
# factory/a/line1/th-200/telemetry {"t":21.4,"h":48}
# 再发一条,这次是 worker-2 打印。两个进程的 client_id 必须不同,
# 相同的话会互相踢掉,共享订阅看起来就像"偶发丢消息"。第三个,把默认值写进配置,别靠记忆。
# emqx.conf 片段(EMQX 6.3.x)
mqtt {
max_inflight = 32 # 每会话在途 QoS1/2 上限,默认就是 32
max_mqueue_len = 1000 # 离线队列上限,默认 1000,超了丢最旧的
retry_interval = infinity # 不主动重发,只有重连才发
session_expiry_interval = 2h # 服务端允许的上限,不是客户端默认值
mqueue_default_priority = lowest # 队列满了先丢优先级最低的
}emqx ctl conf show mqtt 应该输出与上面一致的几项。改完执行 emqx ctl conf reload,不用重启节点。
9. 保留消息与遗嘱:离线状态到底谁写
前八节的例子都假设"status 主题只是发一条消息"。一旦开了 retain=true,这个主题就变成了一个有状态的槽位,而槽位只有最后一个写入者。
保留消息的规则很硬:broker 为每个 topic 只存一条,新订阅者订阅时立刻收到;发布一条空 payload 的保留消息,等于把该 topic 的保留值删掉。没有超时,没有 TTL,除空 payload 之外没有任何东西能清它。
由此产生一个必须提前设计的冲突。设备上线发 {"online":true} 带 retain,遗嘱是 {"online":false} 带 retain。三个场景的结果完全不同:
| 场景 | 遗嘱发不发 | status 主题里的最终值 |
|---|---|---|
设备 DISCONNECT 正常下线(0x00) | 不发 | 停在 online:true,永远 |
| 设备断电、TCP 半开 | 等 Keep Alive 超时才发 | 1.5 倍 Keep Alive 之后变 false |
| 设备断电后 3 秒又重连(Will Delay = 0) | 照发,且可能后于新连接的 online:true 到达 | false 盖住 true,看板显示离线而设备在线 |
第三行是最难查的。遗嘱不是"连接断开时立即执行"的动作,它要等 broker 判定连接异常关闭、再走投递流程,而新连接可能已经先建立并发了 online:true。两个写入的先后由链路时序决定,不由你的代码决定。
规范里还有一条可以利用:Will Delay Interval 大于 0 时,如果在这段时间内同一个会话被重新接管,服务端不得发送遗嘱。也就是说给遗嘱加 10–30 秒延迟,既避开了网络抖动,也自动消除了上面那次覆盖。代价是真正的掉线要多等这么久才被标记。
可以接受的解法有两个,选一个,别两个都不做。
第一个是把状态写进 payload 的时间戳,前端以时间戳新者为准,遗嘱里的 ts 天然比新连接上报的旧。第二个是让设备上线时用一条普通消息(非保留)主动更正,并在服务端加一条"收到 online:true 后清掉旧的保留值再重写"的逻辑。
# 清掉某个设备的保留状态:发一条空 payload 的保留消息
mosquitto_pub -h 127.0.0.1 -p 1883 -t 'factory/a/line1/dev-0001/status' \
-m '' -q 1 -r
# 预期现象:之后新订阅者订阅该主题,不会再收到任何历史值这里也有一个反直觉的取舍:如果你把 status 设成 retain,就等于承认"这个主题只有最新值,不要指望历史"。要历史就得自己落库,而落库之后前端到底读哪一份,得在接口层定死,否则看板和数据库会长期打架。
10. 出口选型:规则引擎还是自建消费者
| 维度 | EMQX Rule Engine + Sink | 自建消费者 |
|---|---|---|
| 上线速度 | 控制台配 SQL,几十分钟 | 一个服务加一条流水线 |
| 适用形态 | 过滤、改名、单流简单聚合 | 多流 join、窗口计算、跨库事务 |
| 失败处理 | Sink 侧缓冲重试,可观测性在 broker 里 | 重试、死信、背压全自己实现 |
| 成本 | 企业版功能,随 License 走 | 只花机器钱 |
| 换 broker | 规则要重写 | 消费者不动 |
判断标准:数据只需要"过滤加落库",用规则引擎;一旦出现跨 topic 的状态计算,尽早把消费者拉到应用侧,别在 broker 里堆 SQL。
这条线在实践中还有两个补充判据,都在压测里显形。
一是下游写入的失败率。规则引擎的 Sink 有缓冲与重试,但重试是有限的,且失败计数埋在 broker 的指标里,业务侧看不到。当目标库的写入失败率超过 0.5% 时,Sink 的重试会把消息堆在 broker 内存里,最终表现为连接层的延迟上升——故障点从数据库跑到了 broker,排障方向完全错。这种情况要换成自建消费者,把背压做在应用侧。
二是改动频率。规则 SQL 写在控制台里,改一次要审核一次,而且没有单元测试。我们统计过一个月里的规则变更次数:超过 15 次以后,规则本身就该进版本库,用 MR 流程管理;到了这一步,自建消费者的成本已经低于维护控制台里的十几条 SQL。
一个具体数字供参考:4 万条/秒的上行、单条 128 字节,规则引擎直接写 MySQL 时的秒级落点在上万行,而换成 Kafka 之后吞吐翻了约三倍。这条链路的瓶颈从来不在 broker 的路由能力上。
顺带记一个版本事实:EMQX 5.4.0 起原来的 data bridge 按方向拆成了 Sink 和 Source,网上的 5.0 时代教程直接抄会找不到地方配。
11. 三个最容易想反的地方
很多人以为 QoS 1 保证不丢,实际上它只保证"到达下一个节点"。设备到 broker、broker 到 Kafka、Kafka 到库,每一跳都要自己兜。
很多人以为共享订阅等于自动扩容。订阅组里没有在线成员,消息就不投;扩容靠 worker 数量,而且组内不保证顺序。
很多人以为遗嘱消息就是掉线告警。设备主动发 DISCONNECT(0x00) 是不发遗嘱的;TCP 半开那种情况,要等 Keep Alive 超时才判定。规范给的口径是 1.5 倍 Keep Alive 内没收到任何控制报文,服务端必须断开连接——这段时间就是你告警的真实延迟下限。
12. 本篇出现的术语
| 中文 | 英文 | 一句话 |
|---|---|---|
| 会话过期间隔 | Session Expiry Interval | 断线后会话(订阅加队列)保留多久,0 表示立即销毁 |
| 消息过期间隔 | Message Expiry Interval | 单条消息在 broker 里的最长存活秒数 |
| 遗嘱延迟 | Will Delay Interval | 非正常断开后延迟多久才发遗嘱 |
| 共享订阅 | Shared Subscription | $share/组名/主题,组间广播、组内负载均衡 |
| 保留消息 | Retained Message | 每个 topic 只留一条,新订阅者立刻收到 |
| 在途窗口 | Inflight Window | 已发未确认的 QoS1/2 上限,EMQX 默认 32 |
| 会话接管 | Session Takeover | 同 ClientID 新连接踢掉旧连接 |
13. 三道还没标准答案的题
一,会话过期设成 0,但业务要求"设备断线 10 分钟内的下行指令不能丢",你要改哪两个参数?只改一个会出什么症状?
二,共享订阅组里 8 个 worker,其中一个卡在 GC 上 20 秒,这段时间的消息去哪了?七种分发策略里哪种能减轻这件事,代价是什么?
三,遗嘱消息设成 retain=true。设备正常下线时,你怎么让 Dashboard 从"在线"变成"离线",而不是一直停在最后一次遗嘱的值上?
前两题在这篇里有线索。第三题第 9 节给了两个解法,但选哪个要先回答一个前置问题:你能不能改设备固件。改不了,就只能在服务端做兜底,那套逻辑比协议本身更容易出错。
规范原文在 OASIS MQTT 5.0 Standard,3.1.2.5 到 3.1.2.7 讲的是遗嘱消息的三个属性,值得原样读一遍。设备身份那一套单独写在 设备身份与证书体系;集群侧的横向扩展在 百万连接 Broker 集群复盘。