WuKongIM MQTT 聚合存储容量准入机制:节点与集群共享存储的预订、退款与重启恢复全解析

原创2026-10-15 19:25:341,437 阅读
文章标签:即时通讯后端

WuKongIM MQTT 聚合存储容量准入机制:节点与集群共享存储的预订、退款与重启恢复全解析

本指南围绕 WuKongIM 为 MQTT 会话引入的聚合存储容量(aggregate storage capacity)功能展开,讲解其如何在节点与集群两级预算下,对「一份源消息体被多个 Session 共享」的受保护发布做统一准入控制,并保证容量耗尽时已接受内容的复制、锚定、ACK 与退休仍可完成。读完本文你将掌握:mqtt.storage_node_bytes / mqtt.storage_cluster_bytes 的配置语义、Placement Prebooking(放置预订)协议的设计动机、容量票据(ticket)与节点托管(escrow)的底层实现,以及完整的过程级验收测试如何复现与验证这套机制。

功能定位:为什么需要聚合存储容量

在 MQTT 场景下,一条发布消息的正文可能被同一个频道上的多个订阅者(Session)共享。WuKongIM 需要一种**跨节点、跨 Session 的共享存储准入(shared-storage admission)**能力,让"节点 + 集群"两级聚合预算能够约束受保护发布(protected publication)的落盘。其核心语义是:

  • 新发布的原始正文与其未来的规范重放(canonical replay)表示,必须在任何原始变更(original mutation)下发之前,先在每一个投票者(voter)和学习者(learner)副本上完成保留(reservation);
  • 原始正文与重放表示之间的转移不得再消耗额外未保留容量;
  • 一份源正文被多个 Session 共享时,在每个副本上只消耗一份保留,而不是按订阅者数重复计费;
  • 物理 WAL、压缩(compaction)、普通历史与元数据放大需要单独的磁盘余量,逻辑保留不覆盖它们。

该功能已实现并通过限定范围内的记录验收(status: implemented and qualified),对应验收证据见 mqtt-storage-capacity 验收报告,关联源码修订为 1aff256b2bd9bc71a69cf5e365553357a69c3bc9,规格文档即本文依据的 mqtt-storage-capacity.md。

授权范围与测试缝(test seams)

运营方批准了以下范围:节点与集群聚合共享存储准入、已接受责任的保留、安全释放与重启恢复。测试复用已批准的进程级缝:Paho MQTT 客户端、WKProto、公开 HTTP、固定公开指标与进程重启缝;任何存储内部检查都不属于 E2E 验收。验收从两个分别合规的离线 Session、不同数据源开始。

实现前的失败清单:13 类必须被消灭的错误

文档以失败优先(failure-first)方式列出了实现前必须覆盖的 13 类故障,它们是整个设计的主要驱动力:

  1. 跨源超额:分别合规的 Session 在不同源上共同超出节点或集群预算,此时新持久发送绝不能成功;
  2. 并发观测竞态:并发源或节点同时观测到空闲空间,聚合保留必须在权威持久边界(authoritative durable boundary)处串行化;
  3. 多协议共享准入:MQTT、WKProto、Product HTTP、遗嘱(Will)与转发发送必须共享同一准入;仅在做异步重放复制时检查是不够的;
  4. 幂等语义:重复发布/提案/复制不得重复计费,不同内容的重试不得再占用另一份责任,必须保持精确幂等;
  5. 不确定性退款:调用方取消、丢失的分配回复或未知物理提交不得错误地返还空间,不确定的保留必须保持计费;
  6. 耗尽时维护:容量耗尽不能阻止已接受内容的复制、锚定、ACK 或退休;在接受前就为其重放表示预留资金,并让有界维护准入独立于新业务发布;
  7. 过早释放:ACK、Session 过期或退订不得释放仍被其他消费者需要的共享内容,只有已被证明的退休(retirement)才能触发释放;
  8. 副本满而法定人数接受:不得虚构该副本容量或抹除已接受的债务,准入与修复必须对照完整存储放置进行;
  9. 重启一致性:重启不得重置节点用量、重复集群授予或退还未知分配,必须重建用量并恢复精确持久授予;
  10. 绕行路径:备份/恢复、副本转移、后缀替换或保留策略变更不得绕过记账,重开前必须保留或重建规范记账;
  11. 既有保护数据:早于计数器的既有数据、超过降低后限额的数据、或证据损坏/缺失的数据,必须保留数据并关闭新准入,直到有界恢复证明其计费;
  12. 陈旧放置与配置失配:陈旧放置、不可用的 Slot 权威、失配的预算配置、算术溢出或畸形回复不得授予空间,全部 fail closed;
  13. 分配爆炸:全局分配不得退化为每条消息一次同步复制命令,也不得让内存随 Session/消息增长;必须使用有界节点授予与持久源记账,配合低基数容量观测。

放置预订协议(Placement Prebooking Protocol)

三节点 RED(复现缺陷)测试显示:逐存储(per-store)检查会在集群预算无法覆盖全部副本时留下部分写入的原始正文(partly written original)。而简单地要求"返回 HW 前所有副本都通过"又会保留该业务提案,阻塞同源锚定/退休,导致既有债务无法释放空间。

为此设计了一个独立的存储资金准备/取消(prepare/cancel)操作,运行在既有有界对等交换路径上,在任何原始变更下发之前执行:

  • 它携带精确密封的清单与内容(exact sealed manifest/content),覆盖全部投票者与非投票学习者;
  • 资金确认(funding acknowledgement)与持久性投票(durability vote)分离;
  • 每个 Channel 只保留一个有界持久票据(bounded durable ticket),带单调 nonce 与精确清单;收费收据与准备(preparation)原子写入;
  • 取消在返还任何额度(credit)之前持久化 nonce 下限(nonce floor),使延迟到达的准备无法复活它;
  • 原始写入只消耗唯一的活动票据,绝不重复计费;
  • 失败/未知的准备不占用原始定序器的待定提案,既有维护可继续推进;未知取消保留债务;
  • 新资金不能在未经精确取消、或无法提供"其原始范围已被另一提案占用"的规范证明时,替换未决票据;
  • 重启保留并校验活动票据,与原始/重放一起重建其收费;
  • 节点托管(node escrow)保持分块(chunked),而不是每条发布发放一次集群分配。

对应实现可见 mqtt_storage.go(预算串行化、reserve/release/register/rebuild)与 mqtt_storage_preparation.go(票据三态 mqttStoragePrepared/mqttStorageCanceled/mqttStorageConsumed、PrepareMQTTStorage、compareMQTTStorageAuthority 完整写栅栏排序)。

容量票据与三态生命周期

mqttStorageTicket 是每个 Channel 唯一的资金证据,字段包括单调 Nonce、Phase 三态、精确 DurableProposalManifest 与收费明细 Charges。其状态迁移是:

  • Prepared(已准备):资金已按精确清单保留,原始尚未落盘;
  • Consumed(已消费):原始已提交,Charges 清空,转为长期收费行;
  • Canceled(已取消):nonce floor 已持久化,收费行已删除,额度可被退还。

PrepareMQTTStorage(见 mqtt_storage_preparation.go)在持有 Channel 的 append/checkpoint 锁与预算互斥下工作:先校验清单与记录、加载旧票据做权威排序(compareMQTTStorageAuthority 按 ChannelEpoch → LeaderTerm → FenceVersion 依次比较),再 prepareMQTTStorageBooking 预检收费、把收费与票据同批原子提交,最后 commitMQTTStoragePreparation 把未知副作用转移给节点。收费收据只证明资金,永远不充当持久性投票——这是它与 durability vote 严格分离的体现。

Definite Will 资金拒绝(Definite Will Funding Refusal)

容量满时,遗嘱(Will)发送会在原始派发前被拒绝,但遗嘱起源日志(origin journal)可能已经颁发了提交许可。文档要求:

  • 只在全新密封提案(fresh sealed proposal)的资金失败处返回一个封闭的"未提交"(non-submission)错误,绝不在保留/待定重试或任何原始持久性结果上返回;
  • 该类型化证据必须穿透本地集群适配器与封闭的节点 RPC 错误码;传输丢失与畸形回复不构成证据;
  • 当同步发布调用返回该证明后,同一启动(same-boot)的起源日志即可持久密封其已颁发尝试;既有"收据优先"恢复、许可重读与后继 CAS 接管重试;
  • 泛化压力、截止时间、缺失收据与错误文本永远不得授予密封;
  • 起源路由器在整个调用期间单调保持不确定性,包括路由刷新重试与存储兄弟重试,任何较早未决提交之后都抑制后续负能力(negative capability)。

该错误类型即 ErrAppendNotSubmitted("internal/message: original append not submitted"),定义于 channelappend/errors.go,消费点包括 mqtt_will_execution.go、channel_append_codec.go 与 publisher.go。

重复与取消完成证据

  • 一次派发前的资金拒绝仍必须进入既有的正向已提交幂等查找;负能力只作用于本次调用的新原始派发,不能使更早的已提交重复失效。因此两条批量恢复路径对正向查找都接受 ErrAppendNotSubmitted,在未命中时保留该拒绝;
  • 物理取消故障即使持久化取消下限已写入,仍可能复现"挥发性借方泄漏"。该不确定性被移入每节点一个的待定退款所有者(pending refund owner):在其互斥锁下,一个精确取消票据 + 该提案范围内不存在任何收费,才能证明原子取消;超时、单独原始缺失、更新票据或进程驱逐都不能退款;
  • 未知准备债务同样归属节点:存储句柄可能在资金所有者打开另一句柄取消前关闭。短物理准备在同一有界证明所有者下串行化;
  • 封闭 escrow 行最多支持 1,024 个历史节点,其对称 256 KiB 编码行上限覆盖最大宽度 uint64 授予/成员字段与信封,编码在提交前检查上限(旧的 128 KiB 只读上限会拒绝合法写入输出);
  • 三节点拒绝最初在严格 RPC 解码时丢失证据——空错误结果的零 reason 等于 Success。因此空负结果必须以 system-error reason 编码且不带身份,并拒绝任何实际矛盾的成功身份;封闭负码还区分有界压力与可重试依赖就绪,使恢复后跟随者缺口仍为 HTTP 503 重试必需;
  • 公开同 ClientID 重连在明确容量拒绝后会失败(MQTT 把每个 Send 错误都视为未决所有者工作)。只消费类型化全调用能力且不带消息身份,避免额外不确定性;保留既有关闭/错误映射与所有泛化/歧义错误。

重启维护分类:原生格式 7 恢复屏障

历史 E2E 显示:legacy-over-limit 场景重启后成功 ACK 已接受正文,但连接随即以 EOF 关闭——重放记账已推进到 4,完成仍停留在 2。有界探针表明恢复屏障被当作消费者内容准入,其确定性时间戳可能超过在线出站时钟,关闭投递并搁浅退休。

修复方案是给新写入的权威屏障一个显式的单记录原生格式 7(RecoveryBarrierProposalManifestVersion = 7),独立于业务标志/负载拼写验证(见 recovery_barrier.go:InternalProposalVersion 只把明确的本地维护格式归类为内部维护)。消费端读取只把该已提交格式分类为内部维护:

  • 普通 SyncOnce 业务记录仍是普通记录,必须计费;
  • 明确的源/锚/退休/屏障控制不获取正文容量;
  • 既有无类型的格式 1 历史屏障不能仅凭负载拼写重新贴标签,其证据保持 fail-closed。

周期取消锁故障清单与修复

一个未决 prepare/cancel 可能让节点健康所有者获取一个前台 append 或 checkpoint 变更仍在运行的 Channel;上下文过期不能打断 Mutex.Lock,等待会拖延后续健康报告并持有恢复所有权。另一个竞争节点预算物理提交也可能在 Channel 准入后造成同类等待。修复要点:

  • 周期重试跳过每个繁忙锁,保留精确已计费证明,保持 append → checkpoint → 预算锁顺序;
  • 取消身份/原始检查与明确原子退款不变;
  • 慢 fsync 同样不被调用方上下文打断:把有界精确取消转移给既有受管提交协调器,其 finalizer 保留规范 Channel 引脚/锁;健康调用方可以超时,但债务保持到取消下限与收费删除被证明;
  • 队列/构建拒绝与未知物理完成保留原始证明;该周期路径不允许直接同步提交回退。

实现见 mqtt_storage_refund.go 的 retryMQTTStorageCancellation:使用 TryLock 跳过繁忙锁,通过 newCommitOwnership 构造所有权并交给 committer.Submit,绝不同步回退。

配置参数与语义

容量通过两对 TOML/环境变量配置(解析见 internal/config/mqtt.go,schema 定义见 internal/config/schema.go):

TOML 路径 环境变量 类型 默认/建议 语义
mqtt.storage_node_bytes WK_MQTT_STORAGE_NODE_BYTES uint64 8 GiB/节点 单节点副本保留上限
mqtt.storage_cluster_bytes WK_MQTT_STORAGE_CLUSTER_BYTES uint64 64 GiB/集群 跨副本保留的聚合上限

必须将 mqtt.storage_cluster_bytes 在每个存储节点上设置为相同值,包括 MQTT 被禁用的存储节点。 这些是逻辑保留(logical reservations);普通历史、元数据、WAL、压缩及其他物理放大需要单独的磁盘余量。Escrow 分块在空闲额度被证明返还前,可保守地拒绝发送。

ConfigureMQTTStorage(mqtt_storage.go)在 Channel 运行时准入之前执行;即使既有受保护数据已超过新限额,也会被保留并计费。mqttStorageBudget 的 reserve 在需要增长授予时按不超过 8 MiB 的分块(quantum = min(8<<20, ClusterBytes/64, NodeBytes))摊销一次权威 Slot 命令,而不是每条消息分配一次授予;adjust 永不花费不确定分配,收缩先关闭本地复用再发 RPC,丢失释放回复也不能消费已退额度。所有观测均为聚合低基数仪表(ObserveMQTTStorage(used, granted, nodeLimit, clusterLimit) 与封闭事件名),不携带 Channel/UID 身份。

重启、恢复与既有债务重建

rebuildMQTTStorage(mqtt_storage.go)以 64 频道一批的页式扫描重建收费:从源激活的 StartAfter 与已退休 deletedThrough 的下界起,为每个剩余位置计算 mqttStorageRowCharge(内部维护格式豁免、业务格式按 mqttStorageRowBytes 计费),每 256 条批提交,最后结算 Prepared 票据(原始存在→Consumed,否则→Canceled)。

每个存储节点在集群授予可花之前,必须先注册其重建的启动债务(register 用 InitialDebt 做 CAS 注册)。MaintainMQTTStorage 复用节点周期所有者:空闲退款保留分块摊销,不新增 Channel 定时器;成员表变化会先关闭缓存花费再走 RPC。这正是"重启重置节点用量、重复集群授予、退款未知分配"三类故障的防线。

过程级验收测试与复现

E2E 用例位于 test/e2e/mqtt/storage_capacity/,全部使用独立 Paho MQTT 5 客户端、公开供给/发送收据与固定公开指标,256 个 hash Slot;无 MQTT 行检查或直接 usecase 调用参与过程验收。验收矩阵覆盖:

  • 满入口/共享正文、两个独立 ACK、Will 恢复与精确生产者重连(1/3 节点);
  • 聚合 tracer 与加入式重启/重放/退休/重开准入;
  • 独立节点与集群上限(3 节点);
  • 超限既有数据全三节点停止/加入候选;
  • 并发不同源/入口节点与被拒源健康静默(1/3 节点);
  • 未知物理 prepare/cancel/retirement(gofail 矩阵);
  • 普通产品 MQTT/WK 互操作与 Will 延迟/正常取消;
  • 在线恢复两次、竞态 CONNECT、保留 PacketID/DUP/正文身份、仅投递一次;
  • Will 预追加、已发布未知、已提交重放与超授予接受追加;
  • 繁忙 append/checkpoint/预算准入与慢受管物理提交(含竞态隔离集成用例)。

例如 ingress_test.go 的 TestIngressAndSharedConsumersUseOneStorageBudget 在 1/3 节点上分别运行:alice 作为生产者向 bob/carol 发布 2048 字节 QoS 1 正文,断言 wukongim_mqtt_storage_bytes{state="reserved"} 大于 0 且不超过 8192,随后重复发布(同一 client_msg_no)在容量满时仍成功且保留不变,验证"共享正文只占一份保留 + 幂等重试不重复计费"。

最终容量矩阵在记录报告(README.md)中为 9/9 与 3/3 全过,Will 中断 8/8 全过,周期集成修复 1.840s 通过、竞态运行 2.970s 通过。

复现命令(Go 1.25.11,GOWORK=off,验证模块缓存):

go build -buildvcs=false -tags=e2e -o /tmp/wk-capacity ./cmd/wukongim
WK_E2E_BINARY=/tmp/wk-capacity \
WK_E2E_MQTT_REPORT_DIR=/tmp/wk-capacity-reports \
go test -p 1 -tags=e2e ./test/e2e/mqtt/storage_capacity \
  -run '^(TestIngress|TestAggregate|TestThreeNodeStorageLimits|TestConcurrentSources)' \
  -count=1 -timeout=8m -v

gofail 故障注入构建与周期取消竞态用例:

GOFLAGS=-buildvcs=false GOWORK=off scripts/build-gofail-binary.sh \
  --out /tmp/wk-capacity-gofail --package pkg/db/message \
  --package internal/usecase/mqttsession --package internal/app \
  --package internal/infra/mqttwill --package internal/runtime/channelappend
WK_E2E_GOFAIL_MQTT=1 WK_E2E_BINARY=/tmp/wk-capacity-gofail \
WK_E2E_MQTT_REPORT_DIR=/tmp/wk-capacity-faults \
go test -p 1 -tags=e2e ./test/e2e/mqtt/storage_capacity \
  -run '^TestUnknown' -count=1 -timeout=3m -v
go test -p 1 -race -tags=integration ./pkg/db/message \
  -run '^TestMQTTStoragePeriodicCancellation' -count=1 -timeout=90s -v

既有债务回归需在独立临时检出中构建基础修订 1aff256b2bd9bc71a69cf5e365553357a69c3bc9 并应用 red/config-shim.patch.gz 配置覆盖,设置 WK_E2E_MQTT_STORAGE_LEGACY_BINARY 后运行 TestThreeNodeRegistersLegacyDebtBeforeAdmission(三节点全部停止再加入,不限定混版本运行)。

操作限制与发布前提

  • 新账本/命令/系统记录、exchange 版本 7、封闭 RPC 能力与原生格式 7 要求全集群二进制/工具匹配并冷滚动(cold rollout);旧的无类型格式 1 屏障不能靠负载拼写重贴标签,歧义/损坏证据保持准入或完成关闭;
  • 该验收不限定滚动降级、分区、任意存储损坏、全部原生转移/成员排列、10 万成员负载、Linux 执行、完整 MQTT 限定或发布物发布;
  • 报告明确:未创建任何云资源或外部 PR/推送/发布,容量行为在 12 用例矩阵后未改变(后续仅调整了配置帮助文案与示例,差异补丁见 post-validation-help.patch.gz)。

这套机制把"多副本、多协议、多 Session 共享"的持久发布统一到两级的逻辑容量预算之下,用独立资金通道、精确票据与节点托管三件套,同时解决了超额准入、部分写入、幂等重试与重启恢复四类经典难题,为 MQTT 生产级容量治理提供了完整的参考实现。

登录后查看全文
WuKongIM