Table of Contents

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× 字节差);段累积达阈值自动合并。
  • 与 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——持久化机制与恢复协议