raft 共识接入
分册导航:net.md | net-topology.md | net-transport.md | [net-raft.md](raft 接入) | net-identity-security.md | net-p2p.md | net-observability.md | 运行拓扑与一致性 | 传输配置与调参 | raft 共识接入 | 身份与安全档 | P2P 会员与 gossip 广播 | 可观测与故障注入
6. raft 共识
RaftStateMachine(共识引擎)+ ApplyPipeline(提交→应用管道)+ 你的 IRaftStore(持久化)
IStateMachine(业务状态机)成套装配:
var store = new MyRaftStore(); // 实现 IRaftStore(持久化归你——内存/文件/任意)
await store.InitializeAsync(ct);
var machine = new MyStateMachine(); // 实现 IStateMachine.ApplyAsync
var pipeline = new ApplyPipeline(store, machine, ApplyPipelineOptions.Default);
var raft = new RaftStateMachine(nodeId, store, transport, pipeline, RaftOptions.Default);
pipeline.SetConfigCallback(raft.PostConfigChanged);
pipeline.StartAsync();
await raft.StartAsync(new ClusterConfig(members));
本节是使用面(怎么调用)。要判断这套 raft 是否满足论文核心性质(稳定性/活性/有序性) 以及高性能怎么来——见 raft-architecture.md(论文五性质逐条实现 映射 + 线程/泵模型 + 有序性与高性能设计)。
引擎直拼是自由组合面(持久化归你)。要完整产品节点(TierWAL 存储 + 快照压缩 调度 + 多源反熵 + 传输组装收口),用产品装配器一步到位: TierRaftNodeBuilder——嵌入式同进程与 TCP 集群两种传输形态,本节引擎语义在其上原样适用。
6.1 复制(完成档三选一)
// 默认档:返回 = committed 且 applied(read-your-writes——拿到返回值即可从业务存储读到效果)
long index = await raft.ReplicateAsync(command, ct);
// committed 档:多数派提交即返(不等 apply——吞吐优先;apply 可能滞后,读效果不保证)
long index2 = await raft.ReplicateCommittedAsync(command, ct);
// LeaderLocal 档:leader 本地持久化即返(不等多数派——异步一致,延迟最低)
// ★ 返回的 index 不保证最终在多数派日志中(leader 宕机丢未复制尾部写)
long index3 = await raft.ReplicateLeaderLocalAsync(command, ct);
// 批量:一批一次追加,批尾 applied
long lastIndex = await raft.ReplicateBatchAsync(commands, ct);
- 非 Leader 立即抛
NotLeaderException——重路由新 Leader 重试:
for (; ; )
{
var leader = FindLeader(); // raft.LeaderId / 集群发现
try { return await leader.ReplicateAsync(cmd, ct); }
catch (NotLeaderException) { await Task.Delay(25, ct); }
}
- 换届在途等待者以
NotLeaderException取消——重试即可,不是错误。
怎么选档:读自己的写 → 默认档;吞吐优先且接受 apply 滞后 → committed 档;
高吞吐低延迟且业务可容忍换届丢尾部(Redis 类异步一致形态)→ LeaderLocal 档。
三档是 per-call 语义(同一集群不同调用方各选各档);RaftOptions.WithReplicationAck(ReplicationAck.LeaderLocal)
可把默认入口整体切到 LeaderLocal(部署态弱档开关——committed/applied 档调用不受影响)。
强一致读配合 ReadIndexAsync(多数派身份确认后返回 commitIndex)。
6.2 读与观测
long readIndex = await raft.ReadIndexAsync(ct); // 线性读(多数派身份确认后;N=1 立即返回)
long commit = raft.CommitIndex; // 跨线程观测
bool isLeader = raft.IsLeader;
bool isVoter = raft.IsVoter; // false = learner(引导/观察副本的就绪信号)
raft.LeaderChanged += became => { /* 换届通知 */ };
CancellationToken leadership = raft.LeadershipToken; // 换届感知令牌——丢失 leadership 即取消
- 租约读(opt-in):
RaftOptions.WithLeaseReads(时钟漂移界)——多数派确认后 (选举窗下界 − 漂移界) 窗口内的线性读零往返返回,窗外自动回落心跳确认。 时钟同步纪律(NTP)由运维承担;要求不满足则保持缺省关。
6.3 主动让位与成员变更
await raft.ResignAsync()——主动让位(运维:节点下线/维护前先让位):leader 立即 降级,集群经选举窗立刻重选,不等心跳超时窗;非 leader 调用抛NotLeaderException。Membership——单成员变更提案(两步提交,在线加减成员)。- follower 落后超过快照覆盖点时自动走快照安装(单源流式 ∥ 多源 swarm——块清单 + K 并行 + 换源重试,使用方无感)。
- 多源成立:安装完成的节点自动向 leader 上报持有(
SourceAnnounce),leader 端持有表 按代累积(快照换代自动清表、换届自动重报)——后续冷节点安装时 holders 含全体持有者, 基线带宽分散到多源,不再全压 leader。SwarmOptions.WithServeBlocks(false)= 纯消费者 (不服务块、不上报);WithAnnounceOnStart(false)= 退出广播面(静态 holders 仍可指名拉取)。 - 反熵对账(漂移收敛):
SwarmAntiEntropy.RunOnceAsync按内容与对端逐层比对 (Merkle 根相等 = 零传输;不等 = 只传差异块修复)——把分发升级为持续收敛。 周期与对端轮转由使用方驱动(SwarmOptions.WithAntiEntropyInterval供配置承载; Majority 档无需开启,LeaderLocal/Swarm-only 档建议开启)。 - learner 副本:
ClusterMember角色位ClusterMemberRole.Learner——日志照常复制/追平可读, 但不参与选举投票、不计入多数派(读扩容/容灾副本不占写入可用性)。
6.3.1 raft 的存储需求面
IRaftStore 是 raft 对持久化的全部需求(term/votedFor/日志追加/截尾/双水位/快照点)——
实现它即可接入任意存储。fsync 时机由协议层控制(WaitForPersistedAsync 同步点)。
6.3.2 Standby 引导加入(新节点上线)
新节点以 learner 身份启动并向集群宣告,追平自动晋级 voter——追赶期不占多数派席位, 不扰动既有写入可用性:
// 产品装配形态(TierRaftNodeBuilder)——JoinAsync 已随启动编排
var node = await TierRaftNodeBuilder.Create(id, fs, config, machine)
.WithTransport(transport) // 或 WithClusterTransport(listen, peers)
.WithJoin(idA, idB) // 引导同伴(至少一个当前集群成员)
.StartAsync(ct);
// 就绪信号:node.Raft.IsVoter 翻真
// 引擎形态:raft.JoinAsync(bootstrapPeers 或 bootstrapEndpoints, timeout, ct)
引导档位三态(JoinAsync 尾参,进程内/已互联传输与 TCP 端点拨号两形态同语义):
| 档位 | 参数 | 完成信号 | 语义 |
|---|---|---|---|
| Standby(缺省) | autoPromote: true |
IsVoter 翻真 |
learner 入组,追平自动晋级 voter |
| 永久观察者 | autoPromote: false |
活动配置收敛含自身 | learner 永久只读,不投票不计多数派 |
| 见证者 | asWitness: true |
leader 受理(即配置已提交) | 投票计多数派、不存日志体、永不晋级 |
TCP 形态的成员表拨号加入:JoinAsync 尾参 listenEndPoint 通告本端监听地址
(leader 受理后登记进配置条目并动态注册拨号表回连复制——不通告则 leader 无法回连,
配置不收敛、Join 超时)。join 完成前引导循环对全部 bootstrap 对端补建链路
(换届免疫——新 leader 与本端互发选举/复制请求不依赖单链)。
便捷成员操作(leader 侧):Membership.AddLearnerAsync / Membership.AddWitnessAsync
(witness 角色单操作登记,投票计多数派、不存数据、永不晋级)。