Skip to content

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换型时批量订阅低
设备 IDdev-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 IntervalCONNECT / CONNACK / DISCONNECT0,连接断开会话即结束上限 session_expiry_interval = 2h,客户端不写仍是 0断线期间的 QoS1 消息全丢,重连后订阅要重建
Message Expiry IntervalPUBLISH、Will Properties不过期message_expiry_interval = infinity离线队列里的旧数据会在重连时一次性倒给业务
Will Delay IntervalWill Properties0,立即发由客户端设,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报文往返可能结果适合不适合
01丢高频遥测,下一条马上就到计费、告警
12重复绝大多数上行不写幂等就直接入库
24一次极少数资金类场景高吞吐上行

重传这件事规范写得很硬。[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。

第一个是设备端上线并挂遗嘱。

python
# 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}

第二个是两个进程跑同一个共享订阅。

python
# 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 必须不同,
# 相同的话会互相踢掉,共享订阅看起来就像"偶发丢消息"。

第三个,把默认值写进配置,别靠记忆。

hcl
# 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 后清掉旧的保留值再重写"的逻辑。

bash
# 清掉某个设备的保留状态:发一条空 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 集群复盘。