Table of Contents

直连挂载总章(TierXxxReplicaBuilder ×9 + TierReplicaSet——一个底座挂 N 产品)

直连模式 = 能力轴:一个 Builder 起一个 raft 组(单选民组 = 共识持久化;N 选民 = 高可用), 产品全参数直配、注入面全开。与 hub 入口(AddRaftXxxAsync)同一份装配代码——hub spec 是 Builder 的两行薄委托,双入口产出门面行为一致(契约测试互证,裁定③)。 多组本地编排(一个底座挂 N 产品)走下文 §4 TierReplicaSet 装载器—— 声明即目录、批量装配、动态装卸;要跨域保证(全局目录/事务/治理)才升 hub。

模式模型(三承载 × 两使用)与选型判据见 tierhub.md(§3C:要跨域保证 → hub;只要单域能力 → 直连)。

1. 统一装配形态(九件同一形态——W1 Kv/VarKv 判例,W2 五件同构,W3 Blob/Queue 收口)

var host = await new TierRaftHost(transport, new TierRaftHostOptions { … }).StartAsync();

// 定长键 KV(TierKvReplicaBuilder<TKey>)
var kv = await new TierKvReplicaBuilder<long>(engineFs, new TierKvOptions { … })
    .WithRaft(new TierReplicaRaftOptions
    {
        GroupId = groupId,
        Config = config,          // 单选民组 = 共识持久化;三成员 = HA
        StateFs = stateFs,        // null = host GroupFileSystemFactory 派生
        ReadPolicy = ReadPolicy.Leased,
    })
    .StartAsync(host);

// 变长键 KV / 集合族三件(TierVarKv/TierHash/TierSet/TierZSetReplicaBuilder)——同一形态;
// Collections 的 DomainTtl 为辖权循环配置(有效配置才装配——leader 收集到期域,经提案全组一致)
var varKv = await new TierVarKvReplicaBuilder(engineFs, new TierVarKvOptions { … })
    .WithRaft(raftOptions).StartAsync(host);
var hash  = await new TierHashReplicaBuilder(engineFs, new HashOptions { … })
    .WithRaft(raftOptions).StartAsync(host);

// 时序/日志(TierSeries/TierLogReplicaBuilder)——自管业务快照档:压缩完成钩子接导出任务组,
// warmup 门先显式导入快照再等 applied 追平;Series 的 RetentionTime/MaxBytes 为辖权循环配置
var series = await new TierSeriesReplicaBuilder(engineFs, new TimeSeriesOptions { … })
    .WithRaft(raftOptions).StartAsync(host);
var log    = await new TierLogReplicaBuilder(engineFs, new TierLogOptions { … })
    .WithRaft(raftOptions).StartAsync(host);

// 队列(TierQueueReplicaBuilder——统一档:ctor(fs, opts, logger);副本行为面走 WithReplicaOptions;
// 保留 QueueBuilder 全注入面透传 WithRingFactory/WithWorkerScheduler/…)
var queue = await new TierQueueReplicaBuilder(engineFs, new TierQueueOptions { … }, logger)
    .WithReplicaOptions(new TierQueueReplicaOptions().WithHomeSweepInterval(…))
    .WithRaft(raftOptions).StartAsync(host);

// Blob(TierBlobReplicaBuilder)——元数据/内容分离:apply 通道驮元数据(≤ ~50B 全组对称),
// 内容经 swarm 反熵(holder 块源 + 导入泵;副本行为面走 WithReplicaOptions)
var blob = await new TierBlobReplicaBuilder(engineFs, new TierBlobOptions { … }, logger)
    .WithReplicaOptions(new BlobReplicaOptions().WithSwarmBlockSize(…))
    .WithRaft(raftOptions).StartAsync(host);
Builder(九件) 引擎选项 副本行为面 辖权循环 备注
TierKvReplicaBuilder<TKey> TierKvOptions —(ReadPolicy 在 raft 档) ExpiryScanInterval→到期键提案回收 读档三档消费面(W1 判例)
TierVarKvReplicaBuilder TierVarKvOptions — 同上(ForceSweep 主动面)
TierHashReplicaBuilder HashOptions — DomainTtl→TruncateDomain 提案
TierSetReplicaBuilder SetOptions — DomainTtl
TierZSetReplicaBuilder ZSetOptions — DomainTtl
TierQueueReplicaBuilder TierQueueOptions WithReplicaOptions HomeSweepInterval 内建 全注入面透传保留
TierSeriesReplicaBuilder TimeSeriesOptions — RetentionTime/MaxBytes→Truncate 提案 自管业务快照档
TierLogReplicaBuilder TierLogOptions — 无(零策略性后台发散轴) 自管业务快照档
TierBlobReplicaBuilder TierBlobOptions WithReplicaOptions 无(内容缺失≠删除——导入泵补齐) 元数据 raft+内容 swarm 双面

TierReplicaRaftOptions(九产品统一,裁定⑪——TierQueueReplicaRaftOptions 改名收编):

字段 语义
GroupId / Config 组身份 + 初始集群配置(成员事实源)
StateFs 组持久真相域(wal+meta+快照);null → host factory 派生(直连缺省单域自包含目录树,拷贝即迁移)
NodeOptions 节点装配(null = 产品默认)
WarmupTimeout 复制恢复追平等待上限(缺省 30s,超时抛)
ReadPolicy 共识读装配档(见 §2)
LeaseClockDriftBound 租约读时钟漂移界(null = 选举窗下界 1/4)
MaxStagedBytes 事务 staged 字节预算护栏(缺省 64MiB;超限确定性拒绝;0 = 测试形态不限)

2. 共识读三档(ReadPolicy——装配档 + per-call 覆盖,按需付费)

档 语义 代价
Local(缺省) 本地单调前缀读,apply 追平即一致 零 RTT
Leased leader 租约窗内零往返,窗外自动降级 Linearizable 需时钟界;装配档自动启用 raft 租约读快路径
Linearizable ReadIndex 多数派确认 → 等本地 apply → 读;follower 可用 每读一轮确认(有界,见下)
// per-call 覆盖(ct 显式传——裸 default 与接口形状二义)
var v = await replica.TryGetBytesAsync(key, ReadPolicy.Linearizable, ct);

★ fail-closed 有界(check-quorum 根机制——论文 §6.4):分区内 leader 选举窗内未获多数派 续约即退役,在途线性读与写提案随降级 NotLeaderException fail-fast(调用方重路由——缺省 取消令牌也不会无限挂起);follower 转发路径自带 4 选举窗总时限。过期判定只对观测时间计数 (双观测确认——调度饥饿/假钟大步进不误判)。租约窗语义(选举窗下界 − 漂移界)与墙钟跳变 单调守卫由 Core.Net 读基座承载(RaftLeaseReadTests/RaftFakeClockTests)。

3. 装配七步(Builder 内部——失败逆序清理零残留)

①引擎 StartAsync → ②状态机构造 → ③host.CreateGroupAsync → ④Router 挂载注册 → ⑤防发散闸门(副本零本地判定——引擎本地 sweep 强制关)→ ⑥辖权循环(有效配置才装配)→ ⑦门面构造返回 + warmup 追平门(applied ≥ CommitIndex 后 ops 开放)。

★ 引擎介质由调用方给定(缺省建议 memory——副本引擎为易失物化,raft 日志 = 持久真相; 重启经快照导入 + 增量重放重建)。

4. TierReplicaSet 本地组集装载器(拍板⑭/方案⑶——直连×group 编排)

一个底座按声明批量挂载 N 个 raft 组成员:批量装配+注入派发+组句柄字典+动态装卸+统一逆序释放。

var set = host.Replicas()
    .AddKv<long>("orders", gid1, config1, new TierKvOptions { … })
    .AddQueue("jobs", gid2, config2, new TierQueueOptions { … })
    .AddLog("audit", gid3, config3)
    .WithEngineFs(businessFs)              // set 级缺省引擎域派发(§4.4 一个域全部业务数据一个域)
    .WithWorkerScheduler(IsolatedTaskScheduler.Shared)   // 共享调度器派发到各成员 Options 轴
    .StartAllAsync(ct);                    // 声明序批量装配;失败逆序就地收口零残留

var kv = set.Get<TierKvReplica<long>>("orders");   // 组句柄字典(按名取类型化门面)
await set.RemoveMemberAsync("audit");              // 动态卸载(组下线+门面收口+句柄摘除)
await set.StartMemberAsync("audit");               // 动态装载(同声明再装载——装卸往返)
await set.DisposeAsync();                          // 统一逆序释放

契约边界(拍板⑭):

  • 声明即目录:声明集是成员事实源,不持久化——恢复 = 重新执行声明(「直连目录不持久」裁定一致)。 动态装卸不删声明(RemoveMemberAsync 后可 StartMemberAsync 再装载);新增成员须改声明重建。
  • 注入派发:set 级 WithEngineFs/WithWorkerScheduler/WithLogger 在启动时派发到各成员—— 声明链在 Add 之后仍可续;成员 Options 显式自带调度器 = 逃生口(派发跳过非 null 轴)。 介质是配置:成员与 set 级都未供给引擎域 = 启动期 fail-fast,绝不静默选介质。
  • 不做:全局放置决策(放置=消费方静态配置)/跨组事务/目录持久化(◇ 继承登记—— 重开条件=真实「要编排不要治理」需求出现再升 hub 治理件)。
  • 零热路径开销:纯装配期糖——成员即直连 Builder 产物(TierXxxReplica 全功能门面)。

5. 相关