Table of Contents

Snapshot——持久化机制与恢复协议

分册导航:snapshot.md | [snapshot-api.md](API 与工厂) | snapshot-persistence.md | Snapshot——Settings / API 详表 / 注入工厂 | Snapshot——持久化机制与恢复协议

6. 持久化机制

6.1 流式帧格式(StreamFrameCodec)

两子类共用同一帧格式:

[Header 14B][Data][Footer 28B][padding 对齐到扇区]
  • Header 14B(StreamFrameHeader):MagicValue(4B,"SNHD") + Version(2B,major=1/minor=0) + Flags(2B) + PayloadLength(4B) + PaddingLength(2B)
  • Footer 28B(StreamFrameFooter):Magic(4B,"SNFT") + TotalLength(8B) + EntryCount(8B) + Crc(8B)
  • CRC64:覆盖 Header + Data + Footer 前 20B(CRC 自身 8B 不参与)。流式增量累积(UnifiedCrc64,边写边算,不驻内存整块)——GB/TB 级快照可零内存压力流式写
  • FooterMagic:供 Backward 扫描定位帧尾(恢复取真尾——从尾向头扫 chunkSize=64KB 块找 FooterMagic 命中)
  • 对齐粒度:扇区(codec Alignment=512);StreamSnapshotSettings 默认段几何 256MB + 分段开启 + 不预分配(GB/TB 流式跨段扩容)

6.2 按字节截断 vs Mirror 版本号截断

维度 Snapshot(StreamSnapshot/IncrementalSnapshot) Mirror(WholeMirror/PagedMirror)
截断坐标系 字节(LogicalAddress——头/尾字节地址) 版本号(版本链 N=2 轮转)
append 可回滚 ✅ TruncateSuffix(CommittedWriteAddress)——尾部字节回滚 ❌(版本链不可回滚,靠 N=2 轮转回收旧版本)
Overwrite 不可回滚 ✅ 独立方法名显形(覆写破坏旧数据,2PC 不覆盖) 走 WritePage 等覆写语义
版本链 ❌ 无版本概念 ✅ N=2 轮转
epoch ❌ 无 ✅
同族定位 纯流式形态(基线导出) 版本链形态(基线镜像)

同族异坐标系:两者都承载"完整状态基线",但 Snapshot 是追加流(Append 可回滚、Overwrite 不可回滚、无版本链),Mirror 是版本链(N=2 轮转、覆写历史可读)。raft 日志压缩选哪个看场景:流式整体导出 → StreamSnapshot;版本化镜像 → Mirror;段级增量(新段不重写旧段) → IncrementalSnapshot。

6.3 IncrementalSnapshot 段累积机制

段1:[Header 14B][N0₁ 8B][条目流₁][Footer 28B]  ← append,不重写
段2:[Header 14B][N0₂ 8B][条目流₂][Footer 28B]  ← append
...
段N:[Header 14B][N0_N 8B][条目流_N][Footer 28B] ← append
[合并达阈值 → CompactSegments → 新基线段(N0_N 不变)+ 旧段物理回收]
  • 新段 append 不重写旧段:段写 = OpenWriteSession(physStart) 物理续接,不动旧段;段表注册在 2PC ConfirmCommitted 后(SetOpaqueMeta(SerializeSegments()) + WriteMeta()),opaque meta 搭水位线原子落盘(同一块同一 CRC)
  • 段表 = O(1) 恢复定位:恢复时 DeserializeSegments(ReadOpaqueMeta()) 一次拿到全部段起点(LogicalStart + PhysStart + N₀),免全盘扫描
  • 段表条目 40B:LogicalStart 16B + PhysStart 16B + N₀ 8B(PhysStart 必须持久化——逻辑↔物理有 flush padding 偏差,无法从逻辑推算)
  • 段级 CRC64:每段独立帧 CRC——崩溃 = 旧段完好、半写段恢复期被悬干裁决截掉
  • 阈值合并:段数 ≥ CompactSegmentThreshold(默认 8)自触发 CompactSegmentsCoreAsync——读全段拼接 → 写新基线帧 → 截旧段(TruncatePrefix 到新基线帧起点向下 4096 对齐)→ 段表=单段 + meta 落盘。低频——成本 = 一次全量写;raft 只需最新快照,段累积不无限增长

6.4 StreamFrameWriter checkpoint 机制(逻辑↔物理换算)

StreamSnapshot 内部维护帧 checkpoint 列表 _frameCheckpoints——每次 OpenWrite / OpenWriteRange 调用 RecordCheckpoint(logical, physical) 追加(按 logical 单调)。LogicalToPhysical(logical) 二分查找最后一个 logical <= 目标 的 checkpoint,再叠加偏移得到物理地址。

为何需要:DIO 写要求扇区对齐(每次 flush 块 = AlignUp(logicalBytes, SectorSize)),但逻辑字节流非对齐。多次 flush 后逻辑↔物理产生 padding 偏差累积,不能简单线性换算。checkpoint = 每个 OpenWrite 起点的双坐标系锚点,二分 + 偏移叠加 = O(log N) 换算。

OpenWriteRange(start, end) 的 flush 回调只推进物理尾(不推进逻辑尾)——逻辑区间由调用方拥有,物理续接。读侧 OpenRead / OpenReadRange 用 AlignDownAddress(LogicalToPhysical(start)) 定位物理预读起点。

7. 恢复协议

SnapshotBase 走 LifecycleBase<SnapshotRecoveryHints> 模板——Initialize → CreateRecovery() 单点 → RecoveryBase<SnapshotRecoveryHints> 状态机驱动(状态机/闸门/进度全在模板)。

7.1 StreamSnapshot 恢复(DefaultSnapshotRecovery)

三级回退(按优先级):

  1. hints(外部注入水位):SnapshotRecoveryHints.WriteAddress 非 null → 直接采用;PhysicalWriteAddress 缺省走 AlignUpToSector(hints.WriteAddress)
  2. meta O(1) 水位:MetaPolicyKind != Disabled 时 MetaPolicy.LoadAsync + ReadMetaPayload → 一次拿到 WriteAddress/PhysicalWriteAddress/TruncatedAddress/CommittedWriteAddress/LastCommittedSeq/LastPreparedSeq
  3. Backward 扫描兜底(Disabled):LocateLastFrameEnd()——从 CommittedTail 向头按 64KB 块扫,找 FooterMagic 命中 + Footer 完整可读 → 帧尾 = magic 位置 + FooterSize。前缀洞天然免疫(从尾向头扫,TruncatePrefix 段内打洞不影响)

悬干裁决(append 回滚):meta LastPreparedSeq > LastCommittedSeq = append 写崩溃(Prepare 后 Confirm 前)→ TruncateSuffix(CommittedWriteAddress) 回滚 append 部分(Overwrite 不可回滚,悬干不涉及)。

7.2 IncrementalSnapshot 恢复(IncrementalRecovery)

三步核心:

  1. 三水位恢复(同 StreamSnapshot 三级回退——hints → meta → Backward 扫描)
  2. 悬干裁决(段写崩溃):meta LastPreparedSeq > LastCommittedSeq = 段写 Prepare 后 Confirm 前崩溃 → TruncateSuffix(CommittedWriteAddress) 尾截断回滚(未提交段物理清除——失败即清理;已提交段表/数据完好)。无"自动认领未提交段"语义——未提交 = 失败 = 清理
  3. 段表 O(1) 加载:DeserializeSegments(ReadOpaqueMeta()) 一次拿到全部段起点(仅已提交段;恢复免全盘扫描)+ _nextSeq = _lastCommittedSeq + 1(2PC 事务序号续接——段写事务单调)

恢复后 SegmentCount / LatestN0 可直接查询;调用方即可 ReadAllChunksAsync 拿最新快照条目流,或继续 AppendSegmentAsync 追加新段,或 ImportSegmentAsync 安装新快照。

7.3 SnapshotRecoveryHints 注入

// 上层(如 raft 节点)已知 apply 序号或外部水位时注入
var hints = new SnapshotRecoveryHints
{
    WriteAddress = knownWriteTail,           // 优先采用
    PhysicalWriteAddress = knownPhysTail,   // 可选;缺省走 AlignUpToSector
};
stream.Initialize(hints);   // LifecycleBase<>.Initialize(hints) 透传给恢复核心
stream.WaitForReady();

hints 优先级最高——适合 raft 节点重启时已知 apply 序号场景;缺省走 meta O(1);meta 禁用时走 Backward 扫描。

7.4 阈值合并与 raft 日志压缩

raft 日志压缩的核心需求:只需最新快照。IncrementalSnapshot 的段累积机制契合——

  • 每次 raft 快照 = 一段(N₀ = apply 序号)
  • 新段 append 不重写旧段(快照越频繁写省越多)
  • 段表 O(1) 恢复定位(免全盘扫描)
  • 段数达阈值自合并为新基线段(低频全量重写——成本可控)
  • ImportSegmentAsync 用于 raft 快照安装(替换语义——新镜像段替旧快照集)

raft 节点重启 → IncrementalRecovery 段表加载 → ReadAllChunksAsync 拿最新快照 → 从 LatestN0 续接 raft log replay。

7.5 恢复全景(端到端时序)

┌─ SnapshotBase.Initialize(hints) ─────────────────────────────┐
│  ① OnInitializeBegin: _engine.Initialize()(同步)          │
│     _metaEngine?.Initialize()(Managed 模式——并行启动)    │
│  ② CreateRecovery() → 默认/注入 IRecovery<SnapshotRecoveryHints>  │
│  ③ RecoveryBase 状态机驱动:                                  │
│     a. WaitForDependenciesAsync: join 主引擎 + meta 引擎就绪 │
│     b. OnRecoveryCoreAsync(hints): 三水位 + 悬干 + 段表     │
│  ④ WaitForReady 返回——水位已裁决、段表已加载、可读写        │
└──────────────────────────────────────────────────────────────┘

三水位恢复链(IncrementalSnapshot):
  hints.WriteAddress?  ─┬─►  采纳 + AlignUpToSector  (RaiseProgress 50)
  缺省 → meta.LoadAsync ─┼─►  SnapshotMetaPayload 推三水位 + CommittedWriteAddress
  缺省 → Backward 扫描 ─┴─►  LocateLastFrameEnd() 找 FooterMagic (RaiseProgress 50→90)

悬干裁决: meta.LastPreparedSeq > LastCommittedSeq
  ─► TruncateSuffix(CommittedWriteAddress)  (RaiseProgress 60)
     未提交段物理清除;已提交段表/数据完好

段表加载: DeserializeSegments(ReadOpaqueMeta()) → _segments
  _nextSeq = _lastCommittedSeq + 1  (RaiseProgress 90)

10. 端到端示例:raft 日志压缩场景

raft 节点周期性快照 + 重启恢复的典型编排:

using var fs = TierFs.New("local:///var/tier/raft-node-1");
var settings = new IncrementalSnapshotSettings
{
    MetaPolicyKind = MetaPolicyKind.Managed,   // 段表靠 opaque 落盘——必开
    MetaOpaqueBytes = 4096,                   // 容纳 ~100 段表条目
    CompactSegmentThreshold = 8,              // 8 段自合并
};
using var snap = new IncrementalSnapshot(fs, settings);
snap.Initialize();
snap.WaitForReady();

// ── 周期性快照(raft apply 回调里调) ──
async Task OnRaftApplySnapshot(long applyIndex, IAsyncEnumerable<ReadOnlyMemory<byte>> stateStream, CancellationToken ct)
{
    // 段 = raft apply 序号快照点;新段 append 不重写旧段
    await snap.AppendSegmentAsync(applyIndex, stateStream, ct);
    // 段数 ≥ 8 时自合并为新基线段(覆盖点不变),旧段物理回收
}

// ── raft 快照安装(外部镜像注入——如 Leader 同步快照) ──
async Task OnRaftInstallSnapshot(long applyIndex, IAsyncEnumerable<ReadOnlyMemory<byte>> fullImage, CancellationToken ct)
{
    // 替换语义:段表替换为单段,旧段物理回收
    await snap.ImportSegmentAsync(applyIndex, fullImage, ct);
}

// ── 重启恢复 ──
// Initialize() 内部 IncrementalRecovery:
//   1. 三水位恢复(hints → meta → Backward 扫描)
//   2. 悬干裁决(meta prepared > committed → 尾截断回滚)
//   3. 段表 O(1) 加载 + _nextSeq 续接
// 恢复后即可读最新快照 + raft log replay 续接
async Task<IAsyncEnumerable<ReadOnlyMemory<byte>>> LoadLatestSnapshot(CancellationToken ct)
{
    Console.WriteLine($"段数={snap.SegmentCount}, 最新N0={snap.LatestN0}");
    return snap.ReadAllChunksAsync(ct);   // 逐段顺序拼接 + CRC64 校验
}

关键点:

  • MetaPolicyKind=Managed 必开——段表 opaque 落盘,恢复 O(1) 定位
  • CompactSegmentThreshold 调到实际段数上限内(默认 8 适合多数场景)
  • ImportSegmentAsync 用于 raft 快照安装(Leader → Follower 同步)
  • 段级 CRC64 + 悬干裁决 = 崩溃安全(未提交段物理清除,已提交段完好)
  • raft log replay 从 LatestN0 + 1 续接(apply 序号单调递增)