Snapshot 使用指南——流式快照 / 增量快照 / 段表恢复
给谁看:需要流式帧文件快照 / raft 日志压缩的组件开发者 回答什么:StreamSnapshot vs IncrementalSnapshot 怎么选 / 按字节截断 vs 版本号截断 / 段表 O(1) 恢复 / 阈值合并 本篇只讲机制——帧字节布局见源码(
Structures/Snapshot/各 partial) 定位:Structures/ 6 子族之一,搭配件;与 Mirror 同族异坐标系(字节截断 vs 版本号截断)
0. 一句话总纲
Snapshot = 完整状态基线纯流式形态 + 按字节截断 + 增量形态(新段 append 不重写旧段)
StreamSnapshot= 流式帧文件([Header 14B][Data][Footer 28B]多帧)IncrementalSnapshot= 段=帧的增量快照:新段 append 不重写旧段 + 段表 O(1) 恢复 + 阈值合并
两者共用同一帧格式(StreamFrameCodec,Magic=SNHD/SNFT)与 SnapshotBase 三水位/2PC 能力;区别在语义层——StreamSnapshot 的帧 = 数据帧,IncrementalSnapshot 的帧 = 段(带 N₀ 8B 前缀)。
1. 定位
- 搭配件:与 Ring/Log 主结构搭配,承载"完整状态基线"。Ring 是数据真相源(record 流),Snapshot 是基线导出/恢复加速件——存在性=优化非正确性,无快照也能走全量重放。
- 形态差异(StreamSnapshot vs IncrementalSnapshot):
- StreamSnapshot:流式帧文件——单条快照 = N 帧(每帧
[Header][Data][Footer],CRC64 流式增量);适合一次性整体导出。 - IncrementalSnapshot:段=帧的增量——每段 = 一帧(
[Header][N₀ 8B][条目流][Footer]);新段 append 不重写旧段,快照越频繁写省越多(基准 8 次快照 4.5× 字节差);段累积达阈值自动合并。
- StreamSnapshot:流式帧文件——单条快照 = N 帧(每帧
- 与 Mirror 同族异坐标系:Mirror 按版本号截断(版本链 N=2 轮转回收),Snapshot 按字节截断(纯流式无版本链)。两者都承载"完整状态基线",但 Mirror 是版本链形态(覆写历史可读),Snapshot 是追加流形态(append 可回滚、Overwrite 不可回滚)。
- ⚠️ 与 Ring 自带区间快照(
OpenSnapshotReader/Writer)无引用关系——Ring 那是导出能力(区间字节流),本子族是独立文件形态(SnapshotBase持有独立StorageEngine)。同名为"快照"是历史巧合,不要混用。 - raft 日志压缩场景:
IncrementalSnapshot= 镜像快照设计稿第三部件(TierWAL 内部快照)——段 = raft apply 序号快照点,新段不重写旧段契合"快照越频繁写省越多"的 raft 日志压缩特征。
1.1 选型决策
| 场景特征 | 选型 | 理由 |
|---|---|---|
| 一次性整体导出(备份/迁移/冷存档) | StreamSnapshot | 单条快照 = N 帧流式追加,CRC 增量累积零内存压力;不需要段表/合并 |
| raft 日志压缩(周期性快照点) | IncrementalSnapshot | 新段 append 不重写旧段契合 raft 周期快照;段表 O(1) 恢复定位;阈值合并控制段数 |
| raft 快照安装(外部镜像注入) | IncrementalSnapshot + ImportSegmentAsync |
替换语义——段表替换为单段,旧段物理回收 |
| 整体快照外存 + 版本化历史可读 | Mirror(mirror.md) |
版本链 N=2 轮转——覆写历史可读;与 Snapshot 同族异坐标系 |
| 区间字节流导出(依附 Ring 生命周期) | Ring 的 OpenSnapshotReader/Writer |
不是本子族——Ring 导出能力,无独立 StorageEngine |
关键判断点:要"周期性快照 + 越频繁越省写"→ IncrementalSnapshot;要"一次性整体流"→ StreamSnapshot;要"版本化历史"→ Mirror。
3. 构造与生命周期
SnapshotBase 继承 LifecycleBase<SnapshotRecoveryHints>——三段式生命周期:new → Initialize()(同步 void,启动后台恢复)→ WaitForReady()(等恢复就绪);异步调用方用 WaitForReadyAsync。无便捷工厂(与 Log 族同形态——封闭结构才有 CreateAsync)。
using KernLab.Tier.Core.IO;
using KernLab.Tier.Runtime.Storage;
using KernLab.Tier.Runtime.Structures.Snapshot;
// ① 文件系统(组合根;示例用 mem,真磁盘改 "local:///path")
using var fs = TierFs.New("memory:");
// ② StreamSnapshot:流式帧文件(meta 关闭,走 Backward 扫描兜底)
var streamSettings = new StreamSnapshotSettings();
using var stream = new StreamSnapshot(fs, streamSettings);
stream.Initialize();
stream.WaitForReady();
// ③ IncrementalSnapshot:增量快照(meta 开启——段表靠 opaque 落盘)
var incSettings = new IncrementalSnapshotSettings
{
MetaPolicyKind = MetaPolicyKind.Managed,
MetaOpaqueBytes = 4096, // 容纳 ≥100 段表条目(8 + 100×40 = 4008B)
CompactSegmentThreshold = 16,
};
using var inc = new IncrementalSnapshot(fs, incSettings);
inc.Initialize();
inc.WaitForReady();
// Dispose 幂等——Resources 链统一释放(主引擎/meta 引擎/MetaPolicy 全 owned)
Dispose 幂等:SnapshotBase 把主引擎、Managed 模式下的 meta 引擎、MetaPolicy 全部登记进 Resources(owned),统一释放顺序。Initialize 后台启动恢复(OnInitializeBegin 同步 init 主引擎 + meta 引擎,WaitForReadyAsync 等 join 完成),恢复算法经 CreateRecovery 工厂单点创建(注入实例则直接用)。
3.1 分步构造 + hints 注入(观察恢复/注入水位)
raft 节点重启已知 apply 序号时,可注入 SnapshotRecoveryHints 优先于扫盘:
// 已知写尾(如 raft 节点重启前持久化的 apply 水位)
var hints = new SnapshotRecoveryHints
{
WriteAddress = knownWriteTail,
PhysicalWriteAddress = knownPhysTail, // 可选;缺省走 AlignUpToSector
};
using var inc = new IncrementalSnapshot(fs, incSettings);
inc.Initialize(hints); // 透传给 IncrementalRecovery.OnRecoveryCoreAsync
inc.WaitForReady();
// 恢复后段表已加载、_nextSeq 已续接,可直接 ReadAllChunksAsync 或 AppendSegmentAsync
注入恢复算法实例(替换默认 IncrementalRecovery):
IRecovery<SnapshotRecoveryHints> customRecovery = new MySnapshotRecovery(...);
using var inc = new IncrementalSnapshot(fs, incSettings, recovery: customRecovery);
// 基类构造透传——CreateRecovery() 工厂被跳过(注入实例优先)
8. 反模式
| # | 反模式 | 后果 / 正解 |
|---|---|---|
| 1 | 混淆 Ring 区间快照与 StreamSnapshot/IncrementalSnapshot | Ring 的 OpenSnapshotReader/Writer 是 Ring 导出能力(区间字节流,依附 Ring 生命周期),本子族是独立文件形态(自有 StorageEngine)。混用 = 生命周期错绑/资源泄漏。正解:独立选型,Ring 区间导出走 Ring API,文件快照走本子族 |
| 2 | IncrementalSnapshot 段累积不合并 | 段数无限增长 → 恢复期段表解析/读段拼接 O(N) 线性退化;磁盘空间累积。正解:设 CompactSegmentThreshold(默认 8)或定期显式 CompactSegmentsAsync |
| 3 | 跨实例组合 DeleteOnClose=true |
跨重启组合必须 DeleteOnClose=false——否则真相源(Ring)重建时快照被清。SnapshotSettings 默认 false,勿改 true |
| 4 | IncrementalSnapshot 关闭 meta(MetaPolicyKind=Disabled) |
段表靠 opaque meta 落盘,禁用 = 段表丢失 → 恢复走 Backward 扫描 O(N) 全盘 + 段表无法续接。正解:开 Managed + MetaOpaqueBytes ≥ 8 + 段数上限 × 40 |
| 5 | Overwrite 当 Append 用 |
Overwrite 不可回滚——覆写破坏旧数据,2PC 不覆盖,Abort 不能回滚。正解:要回滚走 Append/AppendAsync |
| 6 | 多生产者并发 AppendSegmentAsync |
单写者硬性要求(_writing 0/1 闸门)——并发抛 InvalidOperationException。正解:多生产者经外部队列汇聚到单写者;raft 快照低频串行天然契合 |
| 7 | StreamFrameWriter 不 CompleteAsync 也不 using |
未完成帧无 Footer → 读侧 magic 校验失败/CRC 无法验。正解:await using 自动闭环(DisposeAsync 等价 CompleteAsync) |
| 8 | MetaOpaqueBytes 容量不足(IncrementalSnapshot) |
段表序列化超容量 → SetOpaqueMeta 抛 ArgumentException,段表无法落盘。正解:按 8 + 段数上限 × 40 估算,留余量(如 100 段 → ≥4008B → 设 4096B) |
| 9 | 零拷贝 span 跨 await 消费 StreamFrameReader.ReadDataAsync |
ReadDataAsync 已是拷贝交付(填充 caller buffer),但若用 ReadAllChunksAsync 返回的 ReadOnlyMemory<byte> 跨 await 持有需注意——ArrayPool 租用块在枚举下一次迭代后归还。正解:跨 await 持有须拷贝出去 |
9. 想深入?指路
| 想懂什么 | 去哪 |
|---|---|
| Snapshot 子族源码(帧布局/段表/恢复算法/会话双 buffer 流水线) | src/KernLab.Tier.Runtime/Structures/Snapshot/(各 partial) |
| meta 统一协议(opaque 搭车水位线/块格式/Managed/Transport 三模式) | meta.md |
| Session 协调协议(写/读/检查点三 op、悬挂裁决、故障模型——2PC 协调层) | session.md |
| StorageEngine 使用(读写/水位/恢复/Compact/Allocate 写窗口) | storage-engine.md |
| 段表恢复细节(IncrementalSnapshot opaque 段表载体/序列化格式) | segment-table.md |
同族 Ring(数据真相源——OpenSnapshotReader/Writer 区间导出能力) |
ring.md |
| 同族 Log(WAL——raft log replay 续接点) | log.md |
| 同族索引(HashIndex/BTreeIndex/SkipListIndex——派生数据) | index.md |
| 同族 Metadata(版本链单值元数据——跨重启单值状态) | versioned-metadata.md |
| 同族 Mirror(同族异坐标系——版本号截断的镜像形态) | mirror.md |
| Lease 协议(raft 共识层 lease) | lease-protocol.md |
| Structures 总览(6 子族选型/组合 KV/恢复统一模型) | structures.md |
| raft 日志压缩(IncrementalSnapshot 镜像快照第三部件) | src/KernLab.Tier.Products/Wal/(TierWal) |
分册导航:snapshot.md | [snapshot-api.md](API 与工厂) | snapshot-persistence.md | Snapshot——Settings / API 详表 / 注入工厂 | Snapshot——持久化机制与恢复协议