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)物理续接,不动旧段;段表注册在 2PCConfirmCommitted后(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)
三级回退(按优先级):
- hints(外部注入水位):
SnapshotRecoveryHints.WriteAddress非 null → 直接采用;PhysicalWriteAddress缺省走AlignUpToSector(hints.WriteAddress) - meta O(1) 水位:
MetaPolicyKind != Disabled时MetaPolicy.LoadAsync+ReadMetaPayload→ 一次拿到WriteAddress/PhysicalWriteAddress/TruncatedAddress/CommittedWriteAddress/LastCommittedSeq/LastPreparedSeq - 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)
三步核心:
- 三水位恢复(同 StreamSnapshot 三级回退——hints → meta → Backward 扫描)
- 悬干裁决(段写崩溃):meta
LastPreparedSeq > LastCommittedSeq= 段写 Prepare 后 Confirm 前崩溃 →TruncateSuffix(CommittedWriteAddress)尾截断回滚(未提交段物理清除——失败即清理;已提交段表/数据完好)。无"自动认领未提交段"语义——未提交 = 失败 = 清理 - 段表 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 序号单调递增)