WuKongIM 多节点 ISR 写入数据平面设计:commit-before-ack 的通道消息持久化架构解析
WuKongIM 多节点 ISR 写入数据平面设计:commit-before-ack 的通道消息持久化架构解析
本文基于仓库设计文档 2026-04-03-complete-isr-multi-node-write-design.md 展开,围绕 WuKongIM 通道消息写入路径的一次关键架构升级:让消息发送真正走
channellog数据平面,获得真实多节点 ISR 复制、commit-before-ack(先提交后应答)语义、follower 重启后的已提交消息恢复能力。读完本文,你将掌握两平面(控制平面 + 数据平面)的职责划分、权威ChannelRuntimeMeta元数据模型、Snowflake 消息 ID 策略、写入与提交的完整调用链、失败语义,以及三层测试策略与 9 步实施顺序,可以直接据此评估或复现这一阶段的设计。
1. 设计目标:把消息发送搬到真实数据平面
1.1 目标与解决的问题
本设计的核心目标非常明确:让 channel 消息发送使用真实的 pkg/storage/channellog 数据平面,并同时满足四个硬性要求:
- 真实多节点 ISR 复制:消息不是只在 leader 本地落盘,而是通过 ISR(In-Sync Replicas)集合在多个节点间复制;
- durable commit-before-ack 语义:客户端收到发送成功应答(ack)之前,消息必须已经在 ISR 集合中达到提交(commit)条件并持久化;
- committed message recovery after follower restart:follower 重启之后,已经提交的消息仍然可恢复、可读取;
- no dependency on cross-node online delivery:消息的持久化写入与已提交可见性,不依赖任何跨节点的在线投递(在线投递是另一个阶段的主题)。
也就是说,这一阶段只覆盖两件事:消息的持久化写入与已提交读取的可见性。
1.2 非目标(Non-Goals)
设计文档明确划出了边界,以下内容不属于本阶段:
- 跨节点在线 fanout(在线扇出投递);
- 自动副本放置(replica placement);
- 在现有控制平面之上的自动 leader 选举策略;
- 完整 channel 生命周期编排。
这份边界划分非常关键:它把"复制正确性"从"规模管理""选举策略""投递语义"中剥离开,让每一层都可以独立验证。
2. 双平面架构:控制平面与数据平面
本设计的核心决策(Decision)是:系统由 internal/app 组合而成的两个平面构成。
| 平面 | 组成 | 职责 |
|---|---|---|
| 控制平面(Control Plane) | pkg/cluster/raftcluster + pkg/storage/metastore |
拥有权威的 channel 复制元数据 |
| 数据平面(Data Plane) | pkg/replication/isrnode + pkg/storage/channellog |
消息追加、复制、提交、本地持久化、拉取 |
其中:控制平面拥有权威的 channel 复制元数据;数据平面拥有消息追加、复制、提交、本地持久化与 fetch。internal/usecase/message 必须通过真实的 channellog.Cluster 发送消息,而不是直接依赖 *raftcluster.Cluster。
2.1 控制平面的职责与权威读模型
控制平面继续负责:
- channel 复制元数据存储;
- leader 身份视图(leader identity view);
- ISR 成员视图;
- epoch 与 feature 变更;
- leader lease 签发(lease issuance)。
控制平面必须暴露一个权威的 ChannelRuntimeMeta 读模型,至少包含以下字段:
| 字段 | 含义 |
|---|---|
ChannelID |
通道 ID |
ChannelType |
通道类型 |
ChannelEpoch |
通道复制元数据的结构版本,涉及 Status/Replicas/ISR/MinISR/Features 变更时递增 |
LeaderEpoch |
leader 身份版本,可独立于 ChannelEpoch 推进 |
Replicas |
目标副本集 |
ISR |
当前同步副本集 |
Leader |
当前唯一可写 leader |
MinISR |
提交所需的最小同步副本数 |
Status |
通道状态 |
Features |
通道能力特性位 |
LeaseUntil |
leader lease 截止时间 |
设计文档特别强调:metadb.Channel 不能满足此用途,因为它只存储基本业务 channel 字段,不包含复制状态(replication state)。
从当前仓库结构看,这个权威模型已经落地在 pkg/db/meta/table_runtime_meta.go 的
ChannelRuntimeMeta结构体中,字段包含ChannelID、ChannelType、ChannelEpoch、LeaderEpoch、Replicas、ISR、Leader、MinISR、Status、Features、LeaseUntilMS,并在后续演进中扩展了RouteGeneration(路由记录权威版本)、RetentionThroughSeq(权威保留边界)、WriteFenceToken/Version/Reason/UntilMS(写入 fence)与DirectoryGeneration等字段。同文件中的UpsertChannelRuntimeMeta采用单调冲突消解(MonotonicApplied/MonotonicIgnoredStale/MonotonicConflict),并配套批量CreateChannelRuntimeMeta;对应测试见 pkg/db/meta/channel_runtime_meta_test.go。这说明设计中的"权威读模型"已成为仓库中可查证的真实持久化表。
2.2 数据平面的组成与规则
数据平面由每个节点本地的一组组件构建:
- 一个本地
isrnode.Runtime(组生命周期与复制调度); - 一个本地
channellog.DB(本地持久化存储); - 一个本地
channellog.Cluster(channel 面向的 facade)。
三条关键规则:
- 一个 channel 映射一个
isr.GroupKey:即"one channel = one ISR",每个业务 channel 对应一个独立的 ISR 复制组; channellog是唯一允许做ChannelKey -> GroupKey翻译的包:业务通道身份与复制运行时身份之间的翻译边界被严格锁定;- 职责分离:
channellog.Cluster只缓存 channel 元数据并执行 channel 面向的 send/fetch/status;isrnode.Runtime拥有组生命周期和复制调度。
关于
GroupKey的具体形态,配套设计 2026-04-03-channel-keyed-isr-design.md 给出了更细的约束:GroupKey是pkg/replication/isr定义的强类型字符串(type GroupKey string),空字符串非法、对 ISR 核心而言是不透明标识符;推荐编码为channel/<channelType>/<base64.RawURLEncoding(channelID)>,跨节点确定性一致、对分隔符与特殊字符安全、单向映射(ISR 层无需反向解析)。channellog是唯一同时知道业务 channel 身份与本地消息日志存储布局的包。
2.3 与 ISR 核心库的分层关系
数据平面并非凭空而来,它建立在单组 ISR 核心库之上。配套文档 2026-04-02-isr-design.md 将其定位为:
一个由外部 control-plane 驱动的单组 ISR 数据复制引擎,只解决单组数据面问题(角色切换、append/fetch/ack、
LEO/HW、leader lease fencing、divergence truncate、snapshot/restore),不解决 leader 选举策略、副本放置与业务语义。
而 isrnode(对应多组 ISR 库设计中的节点级 runtime)则负责在单节点内管理大量 ISR 组、统一调度复制/fetch/lease 检查/snapshot 等后台任务、复用节点间连接与批量 IO——即"单组正确性"与"多组规模管理"的分层,详见 2026-04-02-multiisr-design.md。
3. App 组合根:唯一组合点与元数据应用顺序
3.1 组合根职责
internal/app 是唯一的组合根(composition root)。它必须构造以下对象:
channelLogDB *channellog.DBisrRuntime isrnode.RuntimechannelLog channellog.ClusterchannelMetaRefresherchannelMetaApplier
3.2 固定的元数据应用顺序
控制平面元数据到数据平面的应用序列是固定的:
1. load authoritative control-plane metadata // 加载权威控制平面元数据
2. project it into isr.GroupMeta // 投影为 isr.GroupMeta
3. EnsureGroup or ApplyMeta on isrnode.Runtime // 在 isrnode.Runtime 上确保组存在或应用元数据
4. project it into channellog.ChannelMeta // 投影为 channellog.ChannelMeta
5. ApplyMeta on channellog.Cluster // 在 channellog.Cluster 上应用元数据
一个容易踩坑的要点:channellog.ApplyMeta(...) 本身不会创建或更新 ISR 组,也不应被当作运行时生命周期钩子(lifecycle hook)。组的创建/更新只能通过 isrnode.Runtime 的 EnsureGroup/ApplyMeta 完成;channellog.Cluster 只是消费已经就绪的组。
从实现计划 2026-04-03-complete-isr-multi-node-write-implementation.md 看,
internal/app层的channelMetaSync结构体会持有metastore.Store、isrnode.Runtime、channellog.Cluster与本地节点 ID,先向isrnode应用、再向channellog应用,并且"先启动 cluster,再启动元数据同步,最后启动 gateway/API;停止时先停 gateway/API 再关闭数据平面资源"——这正是本节固定顺序在生命周期中的体现。
4. 消息 ID 策略:Snowflake 与 Node.ID 直接映射
4.1 决策
MessageID 使用 github.com/bwmarrin/snowflake。每个节点进程在启动时创建一个本地 snowflake 生成器,channellog.Config.MessageIDs 由该生成器提供支撑。
4.2 V1 约束:Node.ID 直映射与 fail-fast 校验
V1 采用直接的 node-id 映射,而不是哈希或截断:
- app 的
Node.ID直接映射为 snowflake node id; - 启动时必须校验
Node.ID落在 snowflake node-id 支持范围 0..1023 内; - 如果配置的 node id 超出该范围,app 启动必须快速失败(fail fast)。
设计文档特别说明了为什么这是刻意的 V1 约束:静默的哈希或截断会带来 ID 碰撞风险(collision)。如果两个不同节点因为截断映射到同一个 snowflake node id,即使时钟不同步,也可能生成重复 ID,破坏幂等与去重语义。
4.3 保证:集群内唯一而非全局有序
设计文档澄清了一个常见误解:MessageID 的目标是 cluster-wide uniqueness(集群内唯一性),不是跨所有节点的全局总排序。客户端看到的有序值仍然是 messageSeq——它是 per-channel(通道内)的单调有序值。
这一约束在当前仓库中已有对应实现:在 internal/app/app.go 中,
nodeMessageIDs用snowflake.NewNode(int64(nodeID))创建节点级分配器,Next()通过原子floor保证进程内单调不回退,SetFloor(floor)用于激活恢复/导入场景:先证明自然时钟分配器已高于所有恢复出的持久化消息 ID 之上,再抬高 floor——"它永远不会合成重启后(在墙钟追上之前)可能被复用的未来 ID"。这正好呼应了设计中"直接映射 + 校验"的动机:让分配器足够简单可靠,避免任何形式的静默换算。
5. 元数据契约:投影规则与节点本地同步
5.1 MetaRefresher 与投影规则
internal/usecase/message.MetaRefresher 必须读取权威控制平面元数据,并返回一个完整的 channel 复制视图。投影规则固定为两条:
ChannelRuntimeMeta -> channellog.ChannelMeta:复制业务面向的复制字段;ChannelRuntimeMeta -> isr.GroupMeta:复制复制字段,并把LeaseUntil映射进 ISR leader lease 状态。
LeaseUntil 必须来自控制平面。发送路径(send path)不得在本地自行发明或延长 leader lease——这是防止旧 leader 在网络分区期间继续接受写入、造成脑裂的关键约束。
5.2 元数据分发:请求级刷新不够
设计文档明确指出:request-scoped metadata refresh(请求级元数据刷新)不足以支撑多节点 ISR 就绪。原因是:
每个出现在
ChannelRuntimeMeta.Replicas中的副本节点,都必须先有本地元数据、先应用本地 ISR 组生命周期,之后才能参与复制。
因此 V1 必须在 internal/app 中提供一条 node-local metadata sync path(节点本地元数据同步路径):
- 启动时预加载所有"副本集包含本地节点"的 channel 运行时元数据;
- 当控制平面元数据变化时,或按有界周期刷新(bounded periodic refresh),**调和(reconcile)**本地已应用的元数据;
- 确保 follower 组在 leader 依赖它们完成 commit 之前,已经被创建并更新。
同时明确:message.MetaRefresher 只是请求路径上修复过期本地元数据的补救机制(repair mechanism),不是数据平面元数据分发的主要机制。
6. 写入路径:九步调用链与 commit-before-ack
6.1 请求路径(Request Path)
durable send 的完整路径如下:
1. access layer 构建 message.SendCommand
2. message.App.Send(...) 携带请求上下文与有界超时调用 durable send
3. channellog.Send(...) 校验元数据、状态、协议能力与幂等性
4. leader 本地 ISR 副本追加编码后的消息记录
5. ISR 复制推进 follower 进度
6. 一旦 ISR 进度达到提交条件,leader 的 HW 推进
7. 释放 append waiter
8. channellog.Send(...) 返回 MessageID 与已提交的 MessageSeq
9. access layer 写入发送 ack
6.2 提交语义:ack 只能在 commit 之后
设计文档用一条极简的规则锁定语义:
messageSeq = committed HW
也就是说:leader 本地追加完成,不等于可以 ack 成功。只有当 ISR 集合中的同步副本进度达到提交条件、HW(High Watermark,提交水位)推进之后,messageSeq 才被确定,客户端才收到成功应答。
6.3 提交推进的具体规则
配套的 ISR 核心库设计(2026-04-02-isr-design.md)对 HW 的推进给出了精确定义:
HW采用 exclusive 语义:HW = next uncommitted offset,即已提交记录满足offset < HW,未提交记录满足offset >= HW,空日志时HW = 0, LEO = 0;- leader 为 ISR 内每个 follower 维护
MatchOffsetExclusive(该副本下一条未复制 offset),leader 自己的MatchOffsetExclusive = LEO; - 提交规则:
HW = ISR 中第 MinISR 大的 MatchOffsetExclusive;当MinISR == len(ISR)时,等价于 ISR 内最小的MatchOffsetExclusive。
这套规则直接支撑了"只有多数同步副本都落盘,leader 才能提交并应答"的 commit-before-ack 语义。
6.4 上下文与超时:拒绝无限期等待
设计文档对 internal/usecase/message 提出了一条硬性要求:必须停止在 durable send 中使用 context.Background(),改用:
- access layer 传入的 request-scoped context,或
- 从请求上下文派生的有界超时(bounded timeout)。
原因非常直接:如果 quorum 不满足,ISR append 可能会等待复制进度,而这个等待必须是可取消的。因此需要把上下文从 access 入口一直穿透到 durable send 路径。V1 明确禁止在 usecase 内部重新创建无界 background context。
从当前仓库看,
internal/usecase/message/send.go中的App.Send(ctx, cmd)已经接受上下文(send.go),并在SendBatch系列批量路径中按 item 携带上下文、合并 deadline 进行权限分组处理——这正是设计文档所要求的"请求上下文穿透"在现网代码中的形态。
7. 复制传输:isrnode 入站 fetch 扩展与生产适配器
7.1 为什么传输适配器还不够
设计文档指出:仅靠传输适配器(transport adapter)不足以支撑多节点复制,因为当前 pkg/replication/isrnode 的对外表面存在缺口:
目前 runtime 可以发起复制工作并消费 fetch 响应,但没有暴露生产环境可用的入站 fetch 请求服务路径。
7.2 isrnode 核心扩展:入站 fetch 服务
V1 必须在 pkg/replication/isrnode 中增加一个窄范围的核心扩展,用于服务入站复制 fetch 请求:
- 接受一个按 group key、generation、epoch、follower identity 寻址的 fetch 请求;
- 校验本地归属与 generation fencing(防止 tombstone 之后旧实例的迟到包污染新实例);
- 执行本地 replica fetch 路径;
- 返回 fetch 结果 payload,交给传输适配器编码并发送。
边界规则(rule)必须固定:
- fetch 语义、group/generation 校验留在
pkg/replication/isrnode; - wire framing 与网络传输留在适配器包。
实现计划给出的入站信封形状与此一致:
type FetchRequestEnvelope struct {
GroupKey isr.GroupKey
Epoch uint64
Generation uint64
ReplicaID isr.NodeID
FetchOffset uint64
OffsetEpoch uint64
MaxBytes int
}
type FetchResponseEnvelope struct {
GroupKey isr.GroupKey
Epoch uint64
Generation uint64
TruncateTo *uint64
LeaderHW uint64
Records []isr.Record
}
其中 TruncateTo 用于告知落后/分叉的 follower 先截断再继续 fetch(divergence truncate),LeaderHW 用于推进 follower 本地可见水位。
7.3 生产适配器:isrnodetransport
仓库需要一个构建在 pkg/transport/nodetransport 之上的具体生产适配器(专用适配器包,实现计划中命名为 pkg/replication/isrnodetransport),职责包括:
- 实现
isrnode.Transport; - 实现
isrnode.PeerSessionManager; - 定义 ISR 复制信封与响应的具体 wire codec;
- 使用上述窄范围
isrnodefetch-serving 扩展处理入站复制请求; - 将数据平面流量与既有 raft 流量隔离。
该适配器必须位于 pkg/replication/isrnode 之外,以保持核心 runtime 的通用性(generic)。
7.4 传输规则:不假设第二个 HandleRPC 槽
传输设计有几条硬性规则:
- 数据平面传输在共享节点传输上使用自己的消息类型或 RPC payload;
- 复制流量不得复用控制平面 raft payload 语义;
- per-peer session 复用与背压(backpressure)是传输适配器的职责;
- V1 不得假设共享服务器上还存在第二个独立的
nodetransport.Server.HandleRPC(...)注册槽——现有控制平面 runtime 已经占用该槽; - 如果采用共享 RPC,实现必须引入显式 RPC multiplexer;否则优先在共享服务器上使用专用的数据平面消息类型。
实现计划中的
RPCMux正是为此设计:在 RPC payload 内增加一个字节的服务选择(service selection),raftcluster 转发注册到固定 service ID 下,ISR 服务使用自己的 service ID,从而在不改变 wire 级 RPC framing 的前提下共享同一个HandleRPC槽。
7.5 配套的复制协议细节
ISR 复制协议(来自 2026-04-02-isr-design.md)采用 follower 主动拉取(pull) 模型:follower 自带背压,重启恢复可以从本地 LEO 继续,leader 不需要维护复杂的 push 队列。fetch 返回契约包含 Epoch、HW、Records、TruncateTo:正常追赶时 TruncateTo == nil;发生分叉时 follower 必须先截断到 TruncateTo 再继续;如果 follower 的 FetchOffset < LogStartOffset(落后到需要装 snapshot),则返回 ErrSnapshotRequired,follower 通过 snapshot 路径恢复到 LogStartOffset 附近再继续增量 fetch。
8. 通道状态存储:真实幂等索引与快照恢复
8.1 V1 需要真实的 ChannelStateStore
pkg/storage/channellog 已经具备真实的消息日志持久化与 checkpoint/snapshot 桥接能力,但 V1 仍需要一个真实的 ChannelStateStore 与 StateStoreFactory,用于:
- 幂等索引读取(idempotency index reads);
- 已提交应用时的幂等索引更新(idempotency index updates on committed apply);
- 快照恢复(snapshot restore)。
设计文档强调:app 不得依赖测试 fake 来做通道状态存储。
实现计划给出的状态存储形状为:
type stateStore struct {
store *Store
}
func (s *stateStore) PutIdempotency(key IdempotencyKey, entry IdempotencyEntry) error
func (s *stateStore) GetIdempotency(key IdempotencyKey) (IdempotencyEntry, bool, error)
func (s *stateStore) Snapshot(offset uint64) ([]byte, error)
func (s *stateStore) Restore(snapshot []byte) error
规则:幂等状态与 channel log 放在同一个 Pebble DB;已提交应用继续由 checkpoint 推进驱动;snapshot payload 必须完整往返全部幂等状态。channellog.DB 通过 StateStoreFactory() 暴露真实工厂。
8.2 与 channellog 本地存储设计的衔接
配套文档 2026-04-03-channellog-local-storage-design.md 给出了本地存储的对象模型与真值来源,二者必须衔接一致:
- 对象模型:
DB.Open(path)/db.ForChannel(key) *Store,Store是 channel 作用域的,绑定ChannelKey、派生GroupKey与底层*pebble.DB; - 存储层真值是
groupKey + offset,而不是channel + messageSeq; messageSeq被解释为offset + 1;- 已提交可见性由 checkpoint
HW派生:最后一条已提交可见消息的 seq 是checkpoint.HW,下一条可读 seq 是checkpoint.HW + 1,空通道即HW == 0; - checkpoint 至少包含
Epoch、LogStartOffset、HW三个字段; - 同一个 channel 作用域的
Store实例既可以服务channellog本地读路径,也可以派生出 ISR 副本所需的 log/checkpoint/history/snapshot 适配器。
这样,"幂等索引 + checkpoint HW + messageSeq 派生"三者共同构成 commit-before-ack 在存储层的落地点:ack 的消息必然能按 seq 读到,且重启后依然可读。
9. 失败语义:ErrStaleMeta / ErrNotLeader / 配额与超时
9.1 ErrStaleMeta
在以下任一情况返回:
- 本地 channel 元数据缺失;
- 已知 channel 元数据对应的本地 runtime group 缺失;
- 请求预期 epoch 与本地已应用元数据不匹配。
处理方式:
1. 刷新权威元数据
2. 将投影应用到 isrnode 与 channellog
3. 重试一次
9.2 ErrNotLeader
在以下任一情况返回:
- 本地 group 角色不是 leader;
- 本地 leader lease 已过期;
- 本地 leader fencing 被 ISR 观察到。
处理方式:
1. 刷新元数据
2. 仅当刷新后的元数据使本地节点重新成为 leader 时,重试一次
9.3 Quorum / Timeout:两类失败必须保持区分
设计文档强调,两种失败类别必须严格区分,不能混为一谈:
| 类别 | 触发条件 | 结果 |
|---|---|---|
| 立即 ISR 不足(insufficient ISR) | 元数据视图已经显示 len(ISR) < MinISR |
立即失败,无需等待 |
| 复制超时(replication timeout) | 元数据看起来有效,但 commit 无法在请求 deadline 前完成 | 按请求超时失败 |
第二条是关键底线:第二类必须因请求超时而失败,绝不能虚假成功(false success)——宁可让客户端重试,也不能在消息尚未提交时向客户端返回成功。
10. 三层测试策略
设计文档为这一阶段规划了从底层契约到端到端的三层测试,每一层锁定一组明确行为。
10.1 Layer 1:ISR / 数据平面契约测试
锁定以下行为:
- leader append 在 commit 之前不 ack;
- follower 复制推进 leader 的 commit;
- lease 过期 fence 掉 leader 写入;
- divergence 与 truncate 恢复正常工作;
- 幂等重放返回原始的
MessageID与MessageSeq(这是幂等索引的核心价值:客户端重试同样的ClientMsgNo不会产生第二条消息)。
10.2 Layer 2:三节点 channellog 集成
运行真实的三节点 ISR harness:
- node 1 为 leader,node 2 与 node 3 为 follower;
- 所有节点应用同一份 channel 元数据视图。
锁定以下行为:
- leader
Send只在 commit 后返回; - 已提交消息可以从
channellog.Fetch读取; - follower 重启后,已提交消息依然可恢复;
- quorum 丢失导致超时或 insufficient-ISR 失败,而不是成功。
10.3 Layer 3:三节点 internal/app 集成
运行三个真实的 app 实例,锁定:
- gateway 对 leader 发送,只在 durable commit 之后返回成功;
- 已 ack 的消息存在于
channellog存储中; - 过期元数据或旧 leader 路径返回预期的重试/not-leader 语义。
设计文档再次重申:跨节点在线 fanout 明确不在此阶段范围内。
实现计划为各层提供了 TDD 形态的测试骨架与验证命令,例如:
go test ./pkg/storage/channellog -run 'TestThreeNodeClusterSendCommitsBeforeAckAndSurvivesFollowerRestart' -v
go test ./internal/app -run 'TestThreeNodeAppGatewaySendUsesDurableCommit' -v
go test ./pkg/storage/channellog ./pkg/replication/isrnode ./pkg/replication/isrnodetransport \
./pkg/transport/nodetransport ./pkg/storage/metadb ./pkg/storage/metafsm ./pkg/storage/metastore \
./internal/usecase/message ./internal/access/gateway ./internal/access/api ./internal/app -count=1
计划还记录了执行期间发现并修复的三个稳定性问题,可作为落地参考:
channelMetaSync现在会先跟踪本地已应用的组,再调用cluster.ApplyMeta,这样即使 cluster 元数据应用中途失败,Stop()也能清理 runtime 状态;isrnode在发送失败后改为调度延迟的 follower 复制重试,而不是单次自动重试后停止;- 三 app 集成测试先刷新当选 leader 的 channel 元数据、再刷新 follower,以关闭测试 harness 中的 leader-not-ready 启动窗口。
11. 实施顺序与完成标准
11.1 九步实施顺序
设计文档给出了明确的实现顺序(Implementation Order):
1. 在 pkg/storage/channellog 中增加真实 ChannelStateStore 与 StateStoreFactory
2. 增加 snowflake 支撑的 MessageIDGenerator
3. 增加权威控制平面 ChannelRuntimeMeta
4. 增加窄范围 isrnode 入站 fetch-serving 扩展
5. 在 nodetransport 之上增加生产 isrnode 传输/会话适配器
6. 在 internal/app 中增加节点本地元数据预加载与调和
7. 将 isrnode.Runtime + channellog.Cluster 接入 internal/app
8. 将 message.App durable 路径切换到请求作用域上下文与真实 channellog.Cluster
9. 增加三节点集成覆盖
11.2 完成标准(Completion Criteria)
本阶段完成当且仅当以下全部成立:
- 三节点集群对消息发送执行真实 ISR 复制;
- 发送 ack 仅在 commit 之后返回;
- 已 ack 消息可从
pkg/storage/channellog读取; - follower 重启保留已提交消息;
ErrStaleMeta、ErrNotLeader、lease 过期与 quorum 超时语义是确定性的。
12. 关联文档导航
以下仓库文档与本文主题直接相关,可进一步深入:
- 设计原文:docs/superpowers/specs/2026-04-03-complete-isr-multi-node-write-design.md
- 实施计划(含任务拆分、TDD 测试骨架与验证命令):docs/superpowers/plans/2026-04-03-complete-isr-multi-node-write-implementation.md
- 单组 ISR 核心库设计(HW 语义、恢复顺序、角色状态机、lease/fencing):docs/superpowers/specs/2026-04-02-isr-design.md
- 节点级多组 ISR 管理库设计(EnsureGroup/RemoveGroup、tombstone generation、传输抽象):docs/superpowers/specs/2026-04-02-multiisr-design.md
- Channel-Keyed ISR 设计(GroupKey 强类型与 channel->GroupKey 翻译边界):docs/superpowers/specs/2026-04-03-channel-keyed-isr-design.md
- channellog 本地存储设计(DB/Store 对象模型、groupKey+offset 真值、messageSeq 派生):docs/superpowers/specs/2026-04-03-channellog-local-storage-design.md