TierWAL 使用指南
TierWAL = 协议中立 WAL 产品(raft/p2p 的存储中线):底层 EntryLog 封装 + 自定 opaque 容器 布局。全部持久化语义做齐、内容零知识——entry 与元数据均不解析(Opaque 槽), raft/p2p 是纯消费方,直接接线。核心面:批/单条追加 × 显式提交(组提交三维度自动触发) × 随机起点重放 × 头/尾截断 × 元数据 Opaque 槽 × 镜像快照(导出/导入)。 泛型产品类
TierWal,经TierWalBuilder装配(StartAsync 一步到位 = 构建 + 恢复 + 就绪)。
快速上手
using KernLab.Tier.Core.IO;
using KernLab.Tier.Products.Wal;
var fs = TierFs.New("memory:"); // 或 TierFs.New("local:///path/to/volume")
await using var wal = await TierWalOptions.Default
.WithWalName("raft-log")
.Builder(fs)
.StartAsync(); // 构建 + 恢复 + WaitForReady 一体
// 追加一批 entry(每条 = 一帧 payload——帧格式知识归调用方)
var entries = new List<ReadOnlyMemory<byte>> { new byte[] { 1, 2 }, new byte[] { 3 } };
var r = await wal.AppendBatchAsync(entries, default);
// r.StartIndex = 本批起始 index;r.Count = 条数
await wal.CommitAsync(default); // 显式提交(一次 fsync = 一批持久化)
Console.WriteLine(wal.PersistedIndex); // ≥ r.StartIndex + r.Count - 1
// 从任意 index 顺序重放
await foreach (var e in wal.ReadFromAsync(r.StartIndex, default))
Console.WriteLine($"{e.Index}: {e.Data.Length}B");
组件入口也可直接 new TierWalBuilder(fs, options)(Options.Builder(fs) 是糖)。
恢复 hints 通常无需提供(default 让底层自恢复);进程外已知水位时注入 WalRecoveryHints
(TailAddress/BeginAddress/CommittedOffset——地址直透 EntryLog)。
心智模型(三条铁律)
- index = 起点 + 顺序计数(设计 §8.7):raft 日志连续无空洞——帧内零 index,恢复按 「快照起点/重放起点 + 扫帧计数」推导;定位锚点 = 内存稀疏锚点(每 1024 条一个 [index→addr],不落盘),恢复随顺序重放重建。
- 双水位分离:
AllocatedIndex= 内存分配尾(含攒批窗口,未持久);PersistedIndex= 本地 fsync 水位(last persisted index,CommitAsync 后推进——自动提交 只提前落盘不推进)。raft 语义注意:PersistedIndex 不是集群 commitIndex(多数派确认 归协议层按复制进度计算),是应答/推进 matchIndex 的本地依据。 - 分配与持久化分离:Append 只写入不 fsync;持久化时机 = 组提交策略自动触发,或调用方
显式
CommitAsync——raft 攒批 → CommitAsync → 应答(一次 fsync = 一批持久化)。
追加与提交
| 路径 | 形态 | 适用 |
|---|---|---|
AppendBatchAsync(entries) |
批 → WalAppendResult(StartIndex, Count) |
raft 攒批主路径 |
AppendSingleAsync(entry) |
单条 → [index, 1] |
稀疏写;三维度全 0 配置 = 每写即提交 |
BeginAppendBatch() 租约 |
ref struct,逐条 Append/AppendAsync 返回 index |
适配器甜区:scratch 逐条帧化直写(集合形态的 N+1 次分配 → ~0) |
// 批追加租约:using 包裹,绝不跨 await 持有(持 WAL 写锁——ref struct 编译器强制不逃逸)
using (var lease = wal.BeginAppendBatch())
{
foreach (var frame in frames)
lease.Append(frame); // 页满 = 底层让渡零阻塞;双页在途才背压
// lease.StartIndex = 批起点;lease.Count = 已追加条数
}
持久化触发(TierWalOptions 组提交三维度,任一满足即提交):
| 维度 | 参数 | 默认 | 说明 |
|---|---|---|---|
| 时间 | CommitInterval |
10ms | 距上次提交;-1ms 禁用 |
| 数据量 | MaxUnflushedBytes |
64KB | 未提交字节 |
| 条数 | MaxUnflushedCount |
1000 | 未提交条数 |
- 单条提交形态 = 三维度全 0(每次 Append 即触发提交);显式
CommitAsync与自动提交并存。 WaitForPersistedAsync(index):阻塞等到 index 已持久化(raft 推进 commitIndex 的依据);IsPersisted(index)非阻塞查询。
重放(随机起点顺序读)
// 异步轨:冷启动/追赶主路径
await foreach (var e in wal.ReadFromAsync(SnapshotIndex + 1, ct)) { ... }
// 同步轨:专用 worker 线程(apply 管道)——零异步排队,页切片零拷贝
foreach (var e in wal.ReadFromSync(startIndex)) { ... } // e.Data 仅枚举存活期有效,跨枚举持有须拷贝
// 批读租约:复制读热路径零分配(页切片视图流)
using (var lease = wal.ReadBatchLeaseSync(startIndex, maxCount, ct))
await foreach (var e in lease.Entries) { ... } // Dispose 后视图失效(页归还池)
定位与总量无关:任意起点 = 内存稀疏锚点二分(O(log 锚点数))+ 自锚点顺序内扫 ≤1024 帧 (与起点无关,~5-11ms 量级,见性能契约②)。重放吞吐 ~3M 条/s (64B entry,mem/local 同量级)。
截断(冲突修正 / 日志压缩)
await wal.TruncateSuffixAsync(newTailIndex, ct); // 截尾 [newTail+1, ∞)——raft 冲突日志修正
await wal.TruncatePrefixAsync(newHeadIndex, ct); // 戴头 [0, newHead)——快照压缩回收,与写完全并行
元数据 Opaque 槽(term/vote/config)
await wal.WriteMetaAsync(opaqueBytes, ct); // 原子替换:搭 EntryLog 水位线落盘 + CRC 校验兜底
ReadOnlyMemory<byte> meta = wal.ReadMeta(); // 未写 = Empty
- 内容零知识:blob 由协议层定义(如 term/vote/集群配置序列化);TierWAL 只做原子替换。
- 容器布局(v1.1):
[WalOpaqueHeader 64B:Magic 4B|Version 2B|Flags 2B|TailIndex 8B|TailAddress 16B|HeadIndex 8B|HeadAddress 16B|ArchivedIndex 8B]+[编解码描述符扩展段 16B](Flags bit0 门控——压缩/加密卷的持久配置事实;bit0=0 时 容器字节与缺省卷逐字节一致)+[raft 元数据预留区]。容器内无段表/锚点表(定位锚为内存态)。 容量 =MetaOpaqueBytes − 64 − (扩展段在位 ? 16 : 0)(缺省 16KB,配置多大都可以)。ArchivedIndex= 归档持久水位(sink 已确认收讫的最大 index——留存/截断的水位闸依据)。 - meta 策略:默认
Managed(独立 .meta 引擎、恒单段、单槽覆盖原子语义、O(1) 恢复); 外部/远程托管走WithMetaPolicyKind(Transport)+WithMetaTransport(...)构建期一行注入。
镜像快照(日志压缩 / 冷节点追赶)
long n0 = await wal.SnapshotAsync(ct); // N₀ = 调用时 PersistedIndex;一体:镜像生成 → 本地存储 → 增量压缩截断
Console.WriteLine($"{wal.SnapshotHeadIndex}..{wal.SnapshotIndex}"); // 快照覆盖的 index 区间
// 冷启动:本地快照自动载入;重建状态机消费帧流(与导出格式同构)
await foreach (var frame in wal.ReadSnapshotEntriesAsync(ct)) { ... }
- 快照内容 = 主数据 [Head..N₀] 的原始条目帧流(WAL 自己生成,非 raft 状态机镜像);
快照后自动
TruncatePrefixAsync(N₀+1)压缩已镜像段(先快照后截断——被截区有覆盖)。 - 本地存储 = IncrementalSnapshot 段增量(每次只写增量段;raft 冷启动必须本地载入, 低频合并阈值内建)。
- 跨节点传输 = 注入
WithSnapshotPersistence(IAsyncTransferPersistence)(网络/对象存储/ 备份介质),随后ExportSnapshotAsync(Header(N₀) + 帧流 + Footer CRC)/ImportSnapshotAsync(读入校验 → 替换本地快照;导入后 SnapshotIndex = N₀,应用快照内容后向 leader 汇报 N₀)。 未注入传输面 = 单机形态:快照本地化开箱即用,Export/Import 抛InvalidOperationException。
装配与介质选型
TierWalBuilder 注入面(不注入回落默认;Meta 校验兜底不可绕过):
| 注入 | 用途 |
|---|---|
WithMetaPolicyFactory / WithMetaTransport |
自定义 meta 策略 / 元数据托管版本链(Transport 模式) |
WithCommitPolicy |
替换组提交策略(默认 = Options 三维度阈值) |
WithSnapshotPersistence |
快照跨节点传输面(Export/Import 前提) |
WithArchiveSink |
归档 sink(注入即启用归档管线——滚动/留存策略随 options 替换) |
WithLogger |
日志器 |
持久化质量地板(DurabilityValidation,默认 true——StartAsync 零 IO fail-fast):
| 介质 | 判定 |
|---|---|
| Network(network://) | 拒绝——远端对象存储无 fsync 语义、延迟无界,契约① 无保障 |
| Virtual(.tier) | 须挂载 CarrierWriteThrough(载体写穿档——四 IO 模式全达标;基线档 p99.9 ≥150ms 不达标) |
| Local / Memory | 通过(mem = 零 fsync 地板,稳定环境高吞吐首选;持久化取舍由部署方自权衡) |
IO hints(WithHints,默认 NoBuffering):TierWal 页模型 4MB 页 = 大块顺序写,落 DIO 甜区;
磁盘 raft 部署建议 NoBuffering | WriteThrough(DIO+WT 全介质最优)——机械盘上 buffered
与 DIO 单独在选举窗口口径不达标(DIO 单独是反模式,p99.9=178ms;DIO+WT p99.9=0.43ms),
实测矩阵见性能契约①。读侧不受影响(重放经游标自管页缓存吸收)。
线程模型(引擎 worker 调度器)
一个 TierWal 装配多个引擎(主日志 + Managed meta + 镜像快照 + 快照 meta),每个引擎的
后台 worker 跑在 IsolatedTaskScheduler 专用线程上:
- 缺省(自建形态):每引擎自建 2~4 条(
RecommendedThreadCount,随核数)—— 单实例最优并发;多实例(Multi-Raft 多组、测试多节点同进程)线程数与引擎数线性绑定。 - 共享注入形态:
WithWorkerScheduler(IsolatedTaskScheduler)一行注入——全部引擎共用 该实例(所有权 Referenced:TierWal 释放不回收,生命周期归注入方),多实例线程数恒定:
var scheduler = IsolatedTaskScheduler.Create(
new IsolatedSchedulerOptions { Name = "engine-shared", ThreadCount = 2 });
var wal = await TierWalOptions.Default.WithWorkerScheduler(scheduler).Builder(fs).StartAsync();
- 两形态词汇(全产品统一,#505):实例形态
WithWorkerScheduler(IsolatedTaskScheduler)——跨实例 共享一组线程;配置形态WithSchedulerThreads(n)/WithWorkerSchedulerOptions(...)——每引擎 自建 n 线程(单实例压缩线程数用;实例注入时被忽略)。meta/快照等派生引擎随主引擎继承配置形态。 - 其余引擎旋钮:
WithOptimization(worker 消费者数/段表自旋预算/CPU 限流族——限流默认关闭,SampleInterval设采样周期武装、ThrottleSpinMilliseconds调自旋预算/段表容量全族)、WithMetaTupleFlushInterval(meta 耐久化泵周期)、WithClock(引擎时钟)、WithLogPageSizeBits(页模型,默认 22=4MB)、WithSnapshotSegmentGrowthLimit(快照引擎段上限)。 - 选型:mem/低频写 2 线程即够;磁盘高频写慎用过小容量(worker 排队拖慢组提交,
2~4 起步按压测定)。产品节点档一行透传:
TierRaftNodeOptions.WithWorkerScheduler(scheduler); 或直接档位声明TierRaftNodeOptions.Default.WithResourceProfile(TierRaftResourceProfile.LowResource)——低资源档 = 引擎调度器收敛到进程级共享单例(只补缺省,显式注入恒优先);高性能档(缺省)= 每引擎自建,现网行为零变化。raft/apply/传输协议专用线程不受档位影响(共识活性地板)。
段滚动·留存与连续归档(W13/W14)
WAL 逻辑段 = 归档单元(index 连续区间,由滚动策略判定冻结点)——与底层引擎物理段无关 (引擎段命名/几何是引擎私有规则)。管线:段冻结 → sink 通知 → 成功回执推进 ArchiveIndex 持久水位(opaque 随水位提交原子落盘——恢复还原)→ 留存按窗口/容量回收本地前缀。
// 装配:注入 sink 即启用(本地目录 in-box 默认;外部 S3 走 Core.IO.S3 实现 IWalArchiveSink)
var sink = new LocalDirectoryWalArchiveSink(fs, "wal-archive");
await using var wal = await TierWalOptions.Default
.WithWalName("raft-log")
.Builder(fs)
.WithArchiveSink(sink, WalArchiveOptions.Default
.WithRotationPolicy(new WalRotationPolicy { MaxSegmentBytes = 128 << 20, MaxSegmentAge = TimeSpan.FromMinutes(10) })
.WithRetentionPolicy(new WalRetentionPolicy { RetentionWindow = TimeSpan.FromHours(24) }))
.StartAsync();
// 后台泵自动滚动/归档/留存(轮询周期 + 滚动阈值 = RPO 界);同步冲刷/编排/测试可手动驱动
await wal.RunArchivePipelineAsync(default);
Console.WriteLine(wal.ArchivedIndex); // sink 已收讫的持久水位
// 未归档不截断(不变式①):TruncatePrefix 允许边界 = max(SnapshotIndex, ArchivedIndex)
await wal.TruncatePrefixAsync(wal.ArchivedIndex + 1, ct); // 底座完整——允许
await wal.TruncatePrefixAsync(wal.ArchivedIndex + 2, ct); // 越顶——InvalidOperationException
| 注入面 | 内部默认 / 说明 |
|---|---|
IWalArchiveSink(Builder.WithArchiveSink) |
LocalDirectoryWalArchiveSink 本地目录(一单元一文件、临时名+原子改名回执、半写不可见);外部 S3 同契约接 Core.IO.S3 |
IWalRotationPolicy(WalArchiveOptions) |
WalRotationPolicy 按大小(默认 128MB)+按时间窗(默认 10min)——任一满足即冻结;空段不滚动 |
IWalRetentionPolicy(WalArchiveOptions) |
WalRetentionPolicy 保留窗口(默认 24h)+容量上限(默认关)——只截已归档前缀,越归档水位的返回值被闸夹回 |
- 归档旁路不阻塞写:管线全在后台泵(写入路径只在簿记锁内做字节/段龄记账,零 IO)——归档落后时
截断延迟,写入永不背压;
ArchivedIndex与PersistedIndex解耦(回执未到水位不动——安全方向)。 - RPO 契约:归档尾滞后有界 = 泵轮询周期(
PollInterval,默认 500ms)+ 滚动阈值(大小/时间窗先到者); sink 故障重试至成功(LastArchiveError可观测——零静默)。 - 单元流格式(
WalArchiveUnitFormat):Header(FirstIndex) +[len 4B][payload]帧流 + Footer(条数/总长/CRC) ——与快照传输格式同构复用;权威区间自描述(Header/Footer),sink 是内容零知识的持久字节容器。 - PITR 恢复(
WalArchiveRestore.RestoreAsync):快照(可选,经快照传输面)+ 归档帧顺序重放至目标 index——Footer CRC 逐单元校验、链断裂/RPO 缺口响亮失败;恢复产物 = 新集群冷启动(不变式②): 全新卷、opaque 清空(无 raft 元数据/无归档水位继承)、index 自恢复点连续续接——协议层以新 groupId/fencing 世代接入,不是原集群复活(防脑裂)。
帧压缩与落盘加密(W15/W16)
帧编解码管线 = TierWal 边界的逐条变换:写链 = 压缩 → 加密 → 底层帧 CRC(覆盖落盘字节);
读链反序 = 帧 CRC → AES-GCM 认证解密 → 解压(链序实现期定死,金样钉住——见
WalCodecGoldenTests)。缺省双 opt-in 关:不配 codec/keyProvider 的卷 payload 逐字节透传,
磁盘布局与既有卷逐字节零变化。
// 压缩(W15)——in-box Brotli;外部 zstd 实现 IWalFrameCodec 注入(id 自 2 起自登记)
var wal = await TierWalOptions.Default
.WithFrameCodec(new WalBrotliCodec())
.Builder(fs).StartAsync();
// 加密(W16)——in-box AES-256-GCM;密钥经 IKeyProvider 注入(轮换 = 多代 provider,历史代保留)
var wal = await TierWalOptions.Default
.WithKeyProvider(new WalStaticKeyProvider(keyId: 1, keyMaterial32B))
.Builder(fs).StartAsync();
| 注入面 | 内部默认 / 说明 |
|---|---|
IWalFrameCodec(Options.WithFrameCodec) |
null = 不压缩;in-box WalBrotliCodec(id=1,质量/窗口构造期可调);WalIdentityCodec(id=0)= 配置占位;外部(zstd 等)id ≥ 2 自登记 |
IKeyProvider(Options.WithKeyProvider) |
null = 不加密;注入即启用 AES-256-GCM(32B 密钥 + 12B 逐帧随机 nonce + 16B tag);in-box WalStaticKeyProvider 单代静态;外部 KMS/密钥文件(H 族 TierFsIdentityStore 材料面)适配注入 |
- 帧格式自描述:变换帧 = 28B 封套(
WCFH魔数 + 版本 + flags + OriginalLength + KeyId + nonce)- 变换字节。flags bits8-11 = 压缩 codecId、bits12-15 = 加密 schemeId(与底层 EntryLogHeader 的 codecId 预留位同族约定);封套自身不设 CRC——完整性由底层帧 CRC64(覆盖落盘字节)+ GCM tag (认证密文)两层各自兜底。压缩不小于原文时逐帧回落原样存储(codecId=None 落帧)。
- 配置 = 卷生命周期静态:编解码描述符(codecId/schemeId/写入代)随 opaque 容器原子落盘 (Flags bit0 门控 16B 扩展段——缺省卷无此段、字节不变)。重开配置漂移(关→开、开→关、 换 codec id)= StartAsync 响亮失败;存量缺省卷启用编解码走快照重建或 PITR 恢复到新卷。
- 密钥轮换:帧封套逐帧落 KeyId 代;读侧按代查 provider——轮换 = 新代入册 + 推进 CurrentKeyId,历史代保留可解析;缺代读密文 = 响亮失败(禁静默)。持久描述符的写入代 在恢复期做可解析性哨兵校验(缺代 = StartAsync 失败)。
- 与归档(W13/W14)compose:归档单元搬运落盘形态(变换卷 = 压缩/密文字节;缺省卷 =
原始 payload,单元字节不变);变换卷单元流 Header 之后携 16B codec 节(自描述,解析零歧义)。
PITR 重放走解码链(
WalArchiveRestore.RestoreAsync):恢复配置须能解析单元声明 (同 codecId codec + 密钥 provider,历史代保留)——缺件响亮失败;解码明文按目标卷配置 重新编码落卷(跨配置恢复 = 明文单元→加密目标卷合法;加密单元→无密钥目标 = 拒绝)。 - ArchiveIndex 水位/留存/截断语义零变化:变换只在帧字节层,index 簿记/记账恒为明文口径; W9 崩溃窗口矩阵已扩编解码耦合窗(压缩帧写半/轮换窗口中途/解密失败路径——72 格)。
- 已登记边界:镜像快照(本地存储 + 传输格式)内容 = 解码明文帧流——本地快照的静态加密 与传输面加密随协议层/后续波处理;raft 元数据 Opaque 槽(term/vote)不在变换面内。
反模式
- 租约跨 await 持有——
BeginAppendBatch租约持 WAL 写锁(ref struct 编译器强制不逃逸);AppendAsync的背压 await 发生在底层批内部,租约本体不跨 await。 - 把 PersistedIndex 当集群 commitIndex——它是本地 fsync 水位;多数派确认归协议层。
- 跨枚举持有重放切片——
ReadFromSync产出的Data是页缓冲切片(仅枚举存活期有效); 复制读收集后发送须自行拷贝(或用ReadBatchLeaseSync并在租约存活期内消费)。 - 网络介质挂载 / virtual 不带 CarrierWriteThrough——DurabilityValidation 直接 fail-fast
(测量/非 raft 用途显式
WithDurabilityValidation(false))。 - 机械盘 DIO 单独用 / buffered 顶选举窗口——见上(DIO+WT 全介质最优)。
- opaque 容量配 0——TierWAL 必须显式
MetaOpaqueBytes > 0(底层 Settings 基类默认 0 = 无 opaque 区,段表/元数据搭车通道不可用;Options 默认 16KB 已兜底)。 - 高频 SnapshotAsync——快照 = 镜像生成 + 截断(raft 惯例 = leader 定期低频压缩)。
- 未注入 sink 调 RunArchivePipelineAsync——抛 InvalidOperationException(归档管线未启用;
注入
Builder.WithArchiveSink即启用)。 - PITR 目标卷非空卷——恢复要求全新卷(半途失败废弃整卷重来——恢复是幂等冷启动,不是原地续传)。
- 留存字节账当精确配额——RetainedBytes 是进程生命周期口径(重启后的历史区在再归档前不计入, 偏保守方向);容量上限是旋钮不是硬契约。
- 把 ArchivedIndex 当集群提交水位——它是 sink 收讫面(PITR/留存回收底座);raft 语义仍以 PersistedIndex(本地 fsync 水位)为准。
- 编解码配置中途切换——压缩/加密是卷生命周期静态事实(持久描述符绑定):同一卷重开必须 同配置;存量缺省卷启用编解码 = 快照重建或 PITR 恢复到新卷,直接开 = StartAsync 拒绝。
- 轮换下架历史密钥代——帧封套逐帧落代、恢复横跨多代:下架未读尽的旧代 = 读链响亮失败; 代际下架须确认覆盖代之前的帧已随留存/快照回收。
- 用变换卷装近 4MB 单条 entry——封套 + tag 膨胀(+44B)吃掉底层单帧余量,不可压缩大载荷 超出变换帧上限 = 追加响亮失败;大 entry 场景先评估压缩比率再开启。
- 为省 CPU 关认证直接读密文 / 跳过描述符校验——均无开关面(设计即响亮失败),绕行 = 自建第二套存储引擎(组织红线)。
想深入
- 设计文档:tierwal-design / tierwal-mirror-snapshot(内部设计稿,不随包发布)
- 性能数据:
perf/tierwal.md(三契约 + 稳定性矩阵,随包发布) - 跨层持久化稳定性(IO → 引擎 → WAL 三层崩溃一致性 / 水位体系 / 分工矩阵): persistence-architecture.md
- TierWAL 帧/opaque 的精确字节布局(互操作解析手册): binary-format-spec.md
- 结构层积木:EntryLog / 存储引擎使用指南(KernLab.Tier.Runtime 包)