直连挂载总章(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. 相关
- 副本门面语义(写经提案/辖权回收/参与面置空):raft-consistency.md
- hub 治理轴(跨结构事务/统一路由/目录自持久):tierhub.md
- 读基座机制(ReadIndex/租约/转发):raft-architecture.md