Table of Contents

TierRaftNode 使用指南（raft × TierWAL 产品节点）

TierRaftNode 是 raft × TierWAL 的完整产品节点装配入口：TierWAL 存储（持久化）+ raft 共识（RaftStateMachine）+ 提交应用管道（ApplyPipeline）+ 多源快照分发与反熵 （Swarm，可选）+ 宿主调度循环（快照压缩/发布/反熵周期）——一个装配器成节点， 节点成集群只差传输。

与 Core.Net 的关系：RaftStateMachine 是共识引擎（引擎与存储互不泄露布局）， 本产品层把它与 TierWAL 接成开箱节点；共识引擎语义（复制完成档/读面/成员变更） 见 net.md §6。

快速上手

嵌入式·同进程（测试 / 单机进程内）

await using var hub = new InProcessTransportHub();
var id = NodeId.NewRandom();
var config = new ClusterConfig([new ClusterMember(id, "node-1")]);

var node = await TierRaftNodeBuilder.Create(id, TierFs.New("memory:"), config, myMachine)
    .WithTransport(hub.Register(id))                       // 注入现成传输
    .StartAsync();

// 写入（复制完成档三选一——见 net.md §6.1）
await node.Raft.ReplicateAsync(command);

TCP 集群（真部署形态）

// 每节点各自执行：peers 表 = 全体成员（含自己）的监听地址
var node = await TierRaftNodeBuilder.Create(id, TierFs.New("local:///data/raft"), config, myMachine)
    .WithClusterTransport(
        listen: new IPEndPoint(IPAddress.Any, 7001),
        peers: new Dictionary<NodeId, IPEndPoint>
        {
            [idA] = new(IPAddress.Parse("10.0.0.1"), 7001),
            [idB] = new(IPAddress.Parse("10.0.0.2"), 7001),
            [idC] = new(IPAddress.Parse("10.0.0.3"), 7001),
        },
        tune: o => o.WithReconnect(TimeSpan.FromMilliseconds(100), 2.0, TimeSpan.FromSeconds(1)))
    .StartAsync();

内建形态经 Core.Net 装配器（ClusterBuilder）组装传输——传输配置全旋钮可调 （tune 管道：握手超时/重连退避/保活/请求回调/背压深度等），传输生命周期随节点。

传输形态怎么选

形态 方法 场景
注入现成传输 WithTransport 嵌入式同进程（InProcessTransportHub）、调用方自组装传输
内建 TCP 组装 WithClusterTransport 真网络部署——listen + peers 表 + 配置管道一行组装

二选一，双供给/零供给均 fail-fast（不偷偷选形态）。多节点同进程测试拓扑： 每节点一个 hub.Register(id) 注入即可。

配置链（TierRaftNodeOptions）

With 默认 说明
WithWal TierWalOptions.Default 存储参数（提交间隔/载体写穿档等——TierWAL 文档）
WithRaft RaftOptions.Default 选举窗/复制并发等（raft 引擎参数）
WithApply ApplyPipelineOptions.Default 应用管道参数
WithSwarm null（不装配） SwarmOptions——多源快照分发；不装配 = 快照安装禁用
WithAntiEntropyInterval TimeSpan.Zero（关） 反熵对账周期（仅 leader 发起）
WithSnapshotGrowthThresholdEntries 0（关） 日志增长达阈值触发一体快照压缩（宿主调度）
WithSnapshotBlockSize 64KB 快照内容块化粒度（Swarm 拉取/对账单元）
WithHostLoopInterval 30s 宿主调度循环节拍
WithHighResolutionTimer true Windows 提升定时器分辨率至 1ms（时序敏感路径）

观测面

  • node.Raft.IsLeader / node.Raft.LeaderId / node.Raft.CommitIndex——角色与进度；
  • node.Wal——TierWal 读面/水位（AllocatedIndex/PersistedIndex/SnapshotIndex）；
  • node.Swarm——多源组件（装配时非空）。

生命周期

StartAsync 返回即完整可用（存储恢复 → 适配 → raft 循环 → 宿主调度全就绪）； DisposeAsync 有界分段收尾：宿主循环 → raft → apply → 多源 → TierWal →（内建 形态）传输。每段超时告警不挂死。

反模式

  • 双供给/零供给：WithTransport 与 WithClusterTransport 只能给一个；都不给直接抛。
  • peers 表缺自己：内建 TCP 形态的 peers 表应含全体成员（含本节点）——成员制 拨号按表直连，缺表项 = 该成员不可达。
  • 同步等待启动：StartAsync() 返回 Task——用 await，禁止 GetAwaiter().GetResult()（线程池耗尽死锁风险）。
  • Swarm 未装配却期待快照追赶：WithSwarm 缺省 = 快照安装传输面禁用，落后 follower 越过快照边界后无法追平——生产集群装配 Swarm。

故障注入本地验证（VALIDATIONS V 项的本地形态）

云上验证（真网络/kill -9/真时序）之外的本地确定性形态——V 项复跑与对抗场景族在任一介质等价驱动的抓手：

  • 时钟缝：nodeOptions.WithRaft(nodeOptions.Raft.WithClock(fake))——选举/心跳/复制计时由假钟快进 驱动（FakeTimeProvider.Advance，零真实睡等）；墙钟跳变不误触发选举（单调钟守卫）。 注入假钟时节点自动新建同钟节拍注册表，无需手动配对。
  • 传输缝：传输面 ITransportFaultInjector（延迟/分区/丢包/乱序，节点对级定向）——TCP/QUIC/InProcess 三介质等价（spec-12 §9.2）。
  • 引擎缝/IO 缝：见 storage-engine.md §5.5 与 fault-injection.md。
  • 本地形态与云上形态的落账边界（哪个 V 项用哪种、判定口径）：scripts/cloud/VALIDATIONS.md 各 V 项 "本地注入形态 / 云上形态"行。

想深入

Edit this page