WuKongIM MQTT 回放修复(Replay Repair):有界跨节点恢复协议的设计与实现
WuKongIM MQTT 回放修复(Replay Repair):有界跨节点恢复协议的设计与实现
导读
本篇基于仓库中的设计文档 mqtt-replay-repair-routing.md,深入剖析 WuKongIM 在 MQTT 通道数据恢复场景下的核心构建块——有界跨节点 MQTT 回放修复(Bounded Cross-node MQTT Replay Repair)。它解决的核心问题是:当某副本的 MQTT 回放日志区间内容缺失时,如何用一个前台操作、一个捐赠节点(donor),把**一个显式选定的已接受锚点区间(accepted anchor interval)**精确地修复到目标副本上。读完本篇,你将掌握该修复操作从请求建模、路由流程、准入控制到 RPC 线协议(RPC 98)的完整设计,以及仓库源码中对每一条防护约束的实际落地方式。
本文以 docs/specs/mqtt-replay-repair-routing.md 为骨架主体,源码证据来自
pkg/channel、pkg/cluster、pkg/db/message等模块,用于佐证设计与实现的一致性。
一、定位:这是"网络恢复"的构建块,不是完整恢复方案
文档开篇就明确了该模块的边界声明:
一个前台操作修复一个显式选定的、已接受的锚点区间,目标是某个副本(target replica),数据来源是另一个副本(donor replica)。
换言之,本次设计只解决"怎么把一段已确认合法的内容搬运过去",它不承担以下职责:
- 自动锚点选择(automatic anchor selection):修复哪个区间、从哪个锚点开始,由调用方显式指定;
- 捐赠节点轮转(donor rotation):donor 的选择与故障切换;
- 复制源释放(replicated source release):修复完成后源内容的释放决策;
- 迁移就绪(migration readiness):修复本身不构成迁移就绪信号。
文档明确写道:"This is the network recovery building block; automatic anchor selection, donor rotation, replicated source release and migration readiness remain required."(这是网络恢复的构建块;自动锚点选择、捐赠节点轮转、复制源释放与迁移就绪仍然需要另行实现。)
从源码看,锚点选择与修复规划确实由独立的模块承担。仓库中的 mqtt_repair_plan.go 定义了 MQTTReplayRepairScan 与 MQTTReplayRepairPlan——前者只做"副本本地日志选择"的有界扫描(TargetAnchor > 0、Limit <= 64),后者唯一的产出是"下一个区间 / 完成本地覆盖 / 推进扫描游标",注释明确写着 "It confers no cluster readiness"(它不赋予任何集群就绪状态)。这与规格文档的边界声明完全吻合。
二、请求模型:一次修复绑定什么
2.1 请求绑定的字段
一次修复请求 MQTTReplayRepairRequest 需要同时绑定以下信息(见 pkg/channel/mqtt_repair.go):
| 字段 | 含义 |
|---|---|
Target |
目标副本节点 ID(接收修复的一方) |
Donor |
捐赠节点 ID(导出内容的一方) |
AnchorPosition |
锚点位置,即目标锚点在日志中的 LastOffset |
Request.ChannelID |
通道身份(Channel identity),包含 ID 与 Type |
Request.Range.Generation |
源代次(source generation),格式为 mqtt-log-v1:<hex command> |
Request.ExpectedChannelEpoch / ExpectedLeaderEpoch / ExpectedRouteGeneration |
Channel / leader / route 三道栅栏(fence) |
Request.Range |
行数预算 Limit 与字节预算 MaxBytes |
其中"预期栅栏"来自调用方选择的某一次权威快照,修复操作不会刷新这些栅栏,只负责验证它们仍然成立。
2.2 关键约束:没有内容摘要、没有调用方提供的 checkpoint
规格文档特别强调:请求中不包含内容摘要(content digest),也不包含调用方提供的 checkpoint。源码注释给出了原因(pkg/channel/mqtt_repair.go):
Neither caller nor donor supplies the receiver's expected digest.(调用方和捐赠方都不提供接收方期望的摘要。)
这是本设计最核心的安全属性:接收方期望的摘要只能由接收方自己本地已提交的锚点推导出来。在 mqtt_anchor_repair.go 中,committedMQTTReplayPrefix 函数注释明确写道:
A donor page is never an input to this proof.(捐赠方页面永远不是该证明的输入。)
这意味着 donor 无法自证内容——它导出的页面必须与 target 本地锚点推导出的期望值逐字节一致才能被导入,从根本上杜绝了"用捐赠方的自我认证内容覆盖本地证据"的攻击面。
2.3 请求合法性校验
MQTTReplayRepairRequest.Valid()(pkg/channel/mqtt_repair.go)拒绝以下情形:
- 隐式身份:
Target == 0或Donor == 0; - 递归自我捐赠:
Target == Donor; - 锚点位置不合理:
AnchorPosition <= Range.Through; - 区间不合法或通道 ID 超长 / 非 UTF-8 / 含空字符。
这些校验在服务端、客户端编解码两处都会重复执行(encodeMQTTRepairRequest 与 decodeMQTTRepairRequest 都会调用 Valid())。
三、端到端流程:单跳路由、自证锚点、原子导入
规格文档描述的完整流程如下,源码 pkg/cluster/channels/mqtt_repair.go 中的 Service.RepairMQTTReplay 逐一落实:
- 起源节点只路由一次到精确目标:
RepairMQTTReplay只在本地节点恰好是q.Target时才执行导入(importMQTTReplayRepair),否则通过ForwardMQTTReplayRepair转发一次。注释明确 "routes once to the exact receiver"。测试文件TestMQTTRepairReceiverFencesProofsAndCleanup中甚至有panic("local repair recursively forwarded"),防止本地修复被再次递归转发(mqtt_repair_test.go)。 - 目标先读自己的已提交锚点,再请求内容:
importMQTTReplayRepair首先通过LoadMQTTReplayAnchor(ctx, q.AnchorPosition)加载本地锚点证明(proof);若!found返回ErrNotReady;随后用q.AcceptsAnchor(proof)验证该证明与请求区间、当前权威顺序匹配。 - 目标通过原子锚点绑定存储端口导入:
transfer.ImportMQTTReplayAnchor(ctx, q.AnchorPosition, page),存储层在 append/checkpoint 所有权下重新加载自身锚点,消除预检与实际落盘之间的间隙。 - 捐赠者独立验证自己的日志,导出完整锚点区间:
exportMQTTReplayRepair中,donor 侧调用transfer.ExportMQTTReplayAnchor,在本地 snapshot 上推导committedMQTTReplayPrefix后导出(from, through]完整区间;短页面(short pages)会被拒绝,因为其端点无法被该锚点认证。 - 操作前后都做 Fresh Slot 读取,导入前目标再次重检:
mqttRepairAuthority每次调用都通过ResolveChannelMetaFresh读取新鲜元数据;导入前后各执行一次recheckMQTTRepairAuthority,比较成员集合(mqttCopyAuthority)与写栅栏(sameWriteFence),任何变化都返回ErrStaleMeta。
3.1 不变式:成员、状态、仲裁、写栅栏全程不变
规格文档要求:有序成员集合、状态、仲裁和写栅栏在操作期间必须保持不变。这与 mqttRepairAuthority 的实现一致——它校验 replicas 全部属于当前 m.Replicas,否则返回 ErrNotReplica,并拒绝超过 256 个副本或 ISR 成员的元数据(ErrNotReady)。
3.2 学习者(learner)可以接收内容
规格文档规定:"Both nodes must be current replicas; a learner may receive content."(两个节点都必须是当前副本;学习者可以接收内容。)也就是说 target 和 donor 必须是成员集合中的当前副本,但 learner 可以作为内容接收方。仓库中 pkg/channel/replication/learner_repair_integration_test.go 与 learner_integration_test.go 专门验证了 learner 场景下的修复行为,其中 learner_integration_test.go 第 84 行断言"结构合法但尾部不匹配的内容不得推进修复"。
3.3 迁移写栅栏下允许的不可变恢复
规格文档强调:既有的迁移写栅栏(migration write fences)允许这次不可变恢复操作,而不允许源激活或普通写入。源码中 mqttRepairMeta 的注释与此对应:
mqttRepairMeta permits immutable recovery while a migration blocks new writes. It still requires fresh authority, strict-majority configuration and placement.(mqttRepairMeta 在迁移阻塞新写入期间允许不可变恢复;它仍要求新鲜权威、严格多数配置与正确放置。)
mqttRepairAuthority 在验证元数据时会先清空写栅栏再比对(unfenced.WriteFence = ch.WriteFence{}),确保修复请求携带的栅栏本身不参与放置校验,而实际权威校验则要求当前写栅栏与请求前的栅栏一致。
四、有界性与并发控制:防死锁的四槽无队列准入
4.1 独立的接收/协调与捐赠准入池
规格文档规定:接收/协调方与捐赠方使用相互独立的四槽(four-slot)无队列准入(admission),以此限制跨节点嵌套而不产生死锁。源码落地在 pkg/cluster/channels/mqtt_repair.go:
mqttRepairConcurrent = 4;- 接收侧信号量
s.mqttRepairReceivers(RepairMQTTReplay使用,满则返回ErrBackpressured); - 捐赠侧信号量
s.mqttRepairDonors(exportMQTTReplayRepair使用,满则返回ErrBackpressured)。
两者都用非阻塞 select + default 实现,绝不排队等待。exportMQTTReplayRepair 的注释解释了为何要分离池:
It performs no I/O on a reactor and creates no per-Channel goroutine or waiting queue.(它在 reactor 上不做 I/O,不创建任何每通道 goroutine 或等待队列。)
因为目标节点在导入时还要作为协调方向 donor 发起嵌套读取(FetchMQTTReplayRepair),如果接收与捐赠共用同一个槽位池,跨节点嵌套调用就可能互相占满槽位而死锁——独立四槽正是文档所述"bounds cross-node nesting without deadlock"的实现。
4.2 五秒 deadline 与 256 行 / 16 MiB 上限
规格文档规定:调用有五秒 deadline,单次最多传输 256 行 / 16 MiB。源码中有三处对应:
- pkg/cluster/channels/mqtt_repair.go:
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)(RepairMQTTReplay与exportMQTTReplayRepair均有); - pkg/db/message/mqtt_replay_codec.go:
mqttReplayMaxBytes = 16 << 20、mqttReplayMaxRows = 256; - RPC 帧级别还有请求字节上限
mqttRepairRPCMaxRequestBytes = 4096与回复上限mqttRepairRPCMaxReplyBytes = mqttReplayRPCMaxReplyBytes + 4096(mqtt_repair_rpc.go)。
区间校验器 MQTTReplayRange.Valid()(pkg/channel/mqtt_replay.go)同样约束 Limit <= 256、MaxBytes <= 16<<20,在服务端和客户端双重执行。
4.3 导入后栅栏失败的语义
规格文档规定:导入后栅栏检查失败会抑制回执(suppresses the receipt),但无法撤销已提交的相同内容。对应源码中 RepairMQTTReplay 的收尾逻辑:导入成功后执行 recheckMQTTRepairMeta,失败则返回错误、调用方拿不到成功回执;但由于 ImportMQTTReplayAnchor 已经把经过本地锚点验证的完全相同的内容原子落盘,这部分已提交内容不可撤销。这与"前缀证明只能来自本地已提交锚点"的约束共同保证:即便回执丢失,本地内容也必然与权威锚点一致。
五、RPC 98:封闭的版本化请求
5.1 RPC 编号与注册
规格文档称该 RPC 为 RPC 98。从 pkg/cluster/net/ids.go 的枚举顺序(RPCChannelMQTTSource → RPCChannelMQTTReplay → RPCChannelMQTTCopy → RPCChannelMQTTAnchor → RPCChannelMQTTPlan → RPCChannelMQTTRepair)以及 pkg/cluster/FLOW.md("MQTT source/replay RPCs 93/94"、"RPCs 95–101 bind copying, anchors/retirement, planning, selection and repair")可以推断:RPCChannelMQTTRepair 即文档所述的 RPC 98。它的注册在 mqtt_repair_rpc.go,通过 clusternet.RPCChannelMQTTRepair 通道号注册处理函数。
5.2 帧格式:两个 action、全量回显、既有错误目录
规格文档规定 RPC 98 是封闭的版本化请求(closed versioned request),包含:
- 两个 action(repair / export):请求帧中
action字节1表示修复(目标执行导入),2表示导出(donor 执行导出),见 mqtt_repair_rpc.go; - 全量请求回显(full request echo):回复帧携带完整重新编码的请求,解码端必须
bytes.Equal(echo, want)完全一致才接受(mqtt_repair_rpc.go),以此绑定 action、target 与独立选定的锚点; - 既有封闭错误目录(existing closed error catalog):状态字节从
mqttSourceStatuses中取,未知错误统一映射到目录末位,解码端拒绝任何越界状态。
帧头使用固定魔数:请求 WMDQ\x01、回复 WMDR\x01,随后是 action、Target/Donor/AnchorPosition 三个 BigEndian uint64,以及一个嵌套的 replay 请求字符串(mqtt_repair_rpc.go)。解码时要求 inner.Leader == fields[1](即嵌套请求中的 leader 必须等于显式 donor),防止字段被篡改。
5.3 导出复用回放页编码;修复只返回已验证前缀
规格文档规定:导出嵌入未改动的有界 replay-page 编码;修复只返回已验证前缀(verified prefix),不返回任何页面记录。源码对应:
- 导出回复把嵌套的
encodeMQTTReplayReply输出原样嵌入,注释强调 "Keep the established replay-page codec byte-for-byte"(mqtt_repair_rpc.go); - 修复回复只编码
MQTTReplayPrefix,并校验len(p.Page.Records) != 0 || p.Page.Before != ... || p.Page.After != ...时直接判错(mqtt_repair_rpc.go),即修复 action 的回复不允许携带页面。
5.4 无新 schema、无新日志格式
规格文档明确:不引入新的 schema 或日志格式。全链路复用的都是既有 MQTT 回放锚点与页面编解码(mqttReplayPrefix、mqttReplayPage),donor 的导出与 target 的导入都走 MQTTReplayAnchorTransfer 存储端口——这一点在 pkg/channel/FLOW.md 中也有印证:"the repair port exports/imports complete anchor intervals"。
六、实现前的故障清单(Failure Inventory)及其防护
规格文档在实现之前列了 6 类必须防护的故障,逐一对照源码可以确认每条都有对应防线:
| # | 故障描述 | 源码防护 |
|---|---|---|
| 1 | 陈旧/缺失/重复/替换的成员集合、错误服务节点、弱仲裁、外来源/区间或未来锚点权威被接受 | mqttRepairAuthority 每次走 Fresh 元数据读取并校验 slices.Contains(m.Replicas, replica);AcceptsAnchor 校验 Manifest.LastOffset == AnchorPosition 且通道纪元/Leader 任期/栅栏版本不超前 |
| 2 | 待定/缺失的接收锚点触发 donor 拉取,或导入 donor 自证内容;短页面、不匹配端点、伪造摘要到达存储或产生成功回执 | 导入前必须 LoadMQTTReplayAnchor 且 found;期望摘要只由本地已提交锚点推导(committedMQTTReplayPrefix);page.ValidFor + page.After == proof.Prefix();ImportMQTTReplayAnchor 再次 expected != page.After 即 ErrConflict |
| 3 | 导入前或提交后元数据变化仍发布回执;修复推进 follower HW、重置其前缀或充当迁移就绪 | 导入前后两次 recheckMQTTRepairAuthority(变化即 ErrStaleMeta 并抑制回执);存储层 ImportMQTTReplayAnchor 不改变 checkpoint / 源释放决策 / 普通历史;修复结果明确"不证明仲裁" |
| 4 | 饱和、递归路由、租约泄漏、取消或关闭导致无界工作或钉住存储;捐赠与接收准入死锁 | 独立四槽无队列准入(mqttRepairReceivers / mqttRepairDonors);请求校验拒绝递归自捐赠(Target != Donor);五秒 deadline;存储层 beginUse/endUse 兼容租约与 appendMu/checkpointMu 原子锁 |
| 5 | RPC 帧、action/状态/版本、精确回显、行/字节上限或 owned byte 生命周期导致畸形/超限/有损回复或不一致 action | 魔数 + 长度上限 + 精确回显比对 + r.Len() != 0 严格消费检查;action 仅接受 1/2;导出回复嵌套长度与字节数强校验;借用切片避免整页复制(nested := b[len(b)-r.Len():]) |
| 6 | 学习者无法修复、迁移写栅栏阻止必要恢复、变更的栅栏被静默忽略;重启丢失精确修复内容 | learner 可接收内容(见 3.2);既有迁移写栅栏允许不可变恢复;sameWriteFence 显式比对新旧栅栏,不一致即失败;内容经本地锚点认证后原子持久化,重启不丢失 |
规格文档还要求:"Tests precede implementation at approved Channel/cluster/RPC and Node integration seams. Real-process MQTT acceptance remains a separate mandatory final gate."(测试先于实现,在获准的 Channel/cluster/RPC 与 Node 集成接缝处进行;真实进程的 MQTT 验收仍是独立的强制最终门槛。)
七、测试证据:边界契约与集成验证
仓库中的测试与规格文档的 seam 划分一一对应:
- RPC/集群层单元测试:pkg/cluster/channels/mqtt_repair_test.go 包含
TestMQTTRepairReceiverFencesProofsAndCleanup(接收方栅栏、证明与清理)、TestMQTTRepairRPCStableGatewayAndDonorFences(网关与捐赠方栅栏稳定)、TestMQTTRepairRPCClosedFramingEchoAndOwnership(封闭帧、回显与所有权); - 存储层锚点修复测试:pkg/db/message/mqtt_anchor_repair_test.go 与 pkg/db/message/mqtt_repair_plan_test.go 验证导出/导入与规划边界的数值约束(如
prefix.Through-current.Through > mqttReplayMaxRows即拒绝); - 复制/集成测试:pkg/channel/replication/mqtt_anchor_integration_test.go 通过真实存储调用
ExportMQTTReplayAnchor/ImportMQTTReplayAnchor并断言page.After == repaired;pkg/cluster/node_mqtt_repair_integration_test.go 覆盖节点级修复集成。
八、冻结上下文(Frozen Context)
规格文档对实现基线做了冻结声明,源码提交为 7b0dcab92,并给出了三个关键文档的 SHA-256 摘要,用于保证评审与实现基于同一份上下文:
AGENTS.md:d1a79d1ca586c933ee11d984ff3c401e816fc09de13c635febb7fe4d57f50ade- pkg/channel/FLOW.md:
23d54a403cf241fa75f1d47ab4837764b21a4a9cf12040fb499fb17b2eb68cb7 - pkg/cluster/FLOW.md:
7ccfbeacecf121ec1cecb85c7a62db223d5e432e3675a1ba15ef9f9fb46ef619
九、总结
WuKongIM 的有界跨节点 MQTT 回放修复,是一套"小步、有界、自证"的网络恢复原语:
- 小步:单次修复只覆盖一个锚点区间,最多 256 行 / 16 MiB,五秒内完成;
- 有界:四槽无队列独立准入、封闭帧格式、严格数值上限,杜绝无界工作与跨节点嵌套死锁;
- 自证:期望摘要只由目标本地已提交锚点推导,donor 页面从不参与证明,导入前后双重栅栏重检。
它刻意把"选哪个区间、选哪个 donor、何时释放源、何时算迁移就绪"留给上层编排,自身只保证"一次精确的内容搬运"。这种边界清晰的构建块设计,配合"测试先于实现 + 真实进程 MQTT 验收兜底"的开发纪律,使得修复操作在集群成员变化、迁移栅栏与并发饱和等多重压力下依然可以保持可证明的一致性与可预测的资源占用——对需要深入理解 WuKongIM MQTT 恢复路径的读者,mqtt-replay-repair-routing.md 与上述源码共同构成完整的参考闭环。