Table of Contents

Mirror 使用指南——字节镜像 / 版本链 / 整体 vs 分页

给谁看:需要整体状态基线外存的组件开发者(镜像备份 / SortedIndex 桥接主存储 / 跨重启恢复)。 回答什么:WholeMirror vs PagedMirror 怎么选 / 三拍会话 / 版本链 / 2PC Abort 语义 / 恢复。 本篇只讲机制——帧字节布局见源码注释(Structures/Mirror/Contracts/MirrorFrame.cs)。 定位:Structures/ 6 子族之一,搭配件;与 Snapshot 同族异坐标系(版本号截断 vs 字节截断)。


0. 一句话总纲

Mirror = 字节镜像 + 版本链 + 2PC 六件套(Abort = 丢弃未确认会话)。 WholeMirror 整体流式(三拍会话:BeginSession → AppendChunk × N → EndSession,不知尺寸、零缓冲、CRC64 边写边累积);PagedMirror 逐页增量(WritePage 一页一帧,可乱序,CRC32C);EndSession flush 才落盘;版本链 N=2 轮替(当前 + 上一 checkpoint,更老即收)。

最小可用代码(WholeMirror,单 checkpoint + 2PC 提交):

using var mirror = new WholeMirror(fs, new WholeMirrorSettings { MetaPolicyKind = MetaPolicyKind.Managed });
mirror.Initialize();                                              // 后台恢复
mirror.WaitForReady();                                            // 等就绪

var head = mirror.BeginSession();                                 // 帧三拍①:圈头 + 写瘦头
mirror.AppendChunk(stateBytes);                                   // 帧三拍②:追加 payload
mirror.EndSession();                                              // 帧三拍③:CRC 收官 + flush
mirror.Prepare(seq: 1);                                           // 2PC①:数据 fsync + meta 落 LastPreparedSeq
mirror.ConfirmCommitted(seq: 1);                                  // 2PC②:CAS 推进 + 链头推进 + N=2 回收

int n = mirror.ReadChunk(mirror.HighestVersionAddress, 0, dst);   // 读已提交链头

最小模型四步即覆盖 Mirror 全部核心机制(帧三拍 + flush + 2PC + 链头推进 + N=2 回收);恢复时构造 + Initialize + WaitForReady 三步自动重建链头。


1. 定位

  • 角色:整体状态基线外存。与 Ring/Log 主结构搭配——主结构是数据真相源,Mirror 是基线镜像(恢复时按基线截断 + 增量重放)。
  • 形态差异:
    • WholeMirror:整体单链 checkpoint。每 checkpoint 一个完整新版本,整帧流式写入(不知总长也能写),适合"整体快照外存 / SortedIndex 桥接主存储"。
    • PagedMirror:per-page 多链。每 checkpoint 内每页一个帧(按 PageId 寻址独立链),可乱序写入,适合"按页增量镜像"。
  • 与 Snapshot 同族异坐标系:
    • Mirror 按版本号截断——保留 N=2 个 checkpoint 版本,更老物理回收;恢复按版本号识别"最后一批未裁决 record"。
    • Snapshot 按字节截断——纯流式形态,无版本概念(详见 snapshot.md)。
  • 桥接器 WholeMirrorPersistence(位于 Runtime/DataMirror/):ITransferPersistence 的内置桥接器,自持一个 WholeMirror(三段式相位 ↔ 三拍会话;Confirm 挂 WriteFooter,Abort 挂尾截断)。注:索引族(HashIndex/SortedIndex)现已改用自建主存储(PersistenceKind.Builtin),镜像通道注入面已退役——见 index.md §6;此桥接器仍保留给其他需"借镜像存储能力"的组件(按 Runtime/COORDINATION.md §6 铁律 8 桥接模式)。

1.1 选型速查

维度 WholeMirror PagedMirror
链拓扑 全局单链(MirrorChainKind.Single) per-page 多链(MirrorChainKind.PerKey,按 PageId)
写门面 三拍会话:BeginSession → AppendChunk × N → EndSession(流式,不知尺寸) 逐页 WritePage(每页一帧,可乱序)
CRC 算法 CRC64(FLAG_CRC64,magic WMHD/WMFT) CRC32C(FLAG_CRC32C,magic PMVH/PMFT)
恢复快路径 尾锚直达(Locate(尾 magic, Last) + PreviousVersion 回跳 N=2) 全走链按 PageId 重建(每页独立链头)
适用形态 整体快照外存 / 桥接 SortedIndex 主存储 按页增量镜像(页粒度更新)
N=2 保留窗口 全局第二新地址 所有页 keepAddr 最小值(误删某页在用版本由全局水位兜底)
flush 时机 EndSession 内部 flush 逐页不 flush,Prepare 统一 flush
写并发模型 单线程会话(多生产者经队列汇聚) 单线程会话,多链在会话内可乱序

选型口诀:整体镜像(一整段状态序列化)→ WholeMirror;按页镜像(页粒度独立更新,部分页不变即跳过)→ PagedMirror。两者均与 SortedIndex 同协议(2PC 六件套 + meta 三模式),可在不同 checkpoint 域并存。


3. 构造与生命周期

Mirror 子类无 Create 工厂(区别于 RingOfLong.Create 那种封闭类型一步就绪)——直接 new + Initialize + WaitForReady 三步。Initialize 启动后台恢复(非阻塞);WaitForReady 等恢复完成。Dispose 幂等。

using var mirror = new WholeMirror(fs, settings);
mirror.Initialize();          // 启动后台恢复(OnInitializeBegin:主引擎 + Managed meta 引擎并行启动)
mirror.WaitForReady();        // 等恢复核心完成(meta Load → 三级回退 → 悬干裁决 → 链头重建)
// 此处 IsReady=true,可读写

桥接形态(WholeMirrorPersistence):构造零 IO,首次 TryOpenWrite/TryOpenRead 触发 Initialize + WaitForReady——checkpoint / 恢复路径天然是等待点。

关键状态查询:

属性 类型 语义
IsReady bool 恢复完成可服务
CurrentVersion long 已提交 checkpoint 版本号(单调;空卷=0)
HighestVersionAddress LogicalAddress 已提交链头地址
HasCommittedVersion bool 是否已有已提交版本——Empty 是合法地址(首 record 在地址 0),不能用地址值判有无
LowestVersionAddress LogicalAddress 回收边界(最老保留版本地址;Empty=未回收过)

跨实例恢复示例——同一卷上第二实例构造期尾锚扫盘恢复链头:

// 第一实例:写两个 checkpoint 后 Dispose(卷上保留数据)
var vol = new TestVolume();
var settings1 = new WholeMirrorSettings(
    new StorageEngineOptions("test.0", 1L << 24, enableSegmentation: false).WithDeleteOnClose(false));
LogicalAddress v2Addr;
using (var mirror1 = new WholeMirror(vol.Fs, settings1))
{
    mirror1.Initialize();
    mirror1.WaitForReady();
    WriteCheckpoint(mirror1, 4096, 0x11);
    mirror1.Prepare(1);
    mirror1.ConfirmCommitted(1);
    WriteCheckpoint(mirror1, 4096, 0x22);
    mirror1.Prepare(2);
    mirror1.ConfirmCommitted(2);
    v2Addr = mirror1.HighestVersionAddress;
}

// 第二实例(同卷):尾锚扫盘恢复链头
var settings2 = new WholeMirrorSettings(
    new StorageEngineOptions("test.0", 1L << 24, enableSegmentation: false).WithDeleteOnClose(true));
using var mirror2 = new WholeMirror(vol.Fs, settings2);
mirror2.Initialize();              // 后台启动恢复
mirror2.WaitForReady();            // 等恢复完成

// 恢复后 mirror2.CurrentVersion == 2;HighestVersionAddress == v2Addr(尾锚直达最新数据帧)
vol.Dispose();

关键点:跨重启组合必须 DeleteOnClose=false(否则恢复时真相源被清)。Initialize 非阻塞——后台启动恢复,WaitForReady 才是等待点。桥接形态(WholeMirrorPersistence)将 Initialize + WaitForReady 延迟到首次 TryOpenWrite/TryOpenRead,因为 checkpoint / 恢复路径天然是等待点。

3.1 生命周期钩子链(继承 LifecycleBase<MirrorRecoveryHints>)

阶段 钩子 MirrorBase 实现
Initialize 第一阶段【前】 OnInitializeBegin _engine.Initialize() + Managed meta 引擎并行启动
恢复算法工厂 CreateRecovery 返回 new DefaultMirrorRecovery(this)
依赖 join WaitForDependenciesAsync 主引擎 + meta 引擎双 await(全异步轨,零同步阻塞)
恢复核心 OnRecoveryCoreAsync meta Load → 三级回退 → 悬干裁决 → 链头重建
Dispose DisposeOverride / DisposeOverrideAsync 释放帧 IO 缓冲 + 基类资源(幂等)

生命周期详细机制(CAS 闸门 / 状态机 / 进度上报 / MarkReady)见 src/KernLab.Tier.Core/docs/lifecycle.md,本篇只讲 Mirror 侧职责。

3.2 桥接形态(WholeMirrorPersistence)

ITransferPersistence 的内置桥接器(3a 托管模式——构造零 IO,首次使用启动恢复)。注:索引族已退役此桥接(改用自建主存储 PersistenceKind.Builtin,见 index.md §6);此桥接器仍保留给其他需"借镜像存储能力"的组件消费。

阶段 WholeMirrorPersistence 行为
构造 new WholeMirror(fileSystem, settings, ...) 自持;零 IO
TryOpenWrite/TryOpenRead 首次 EnsureStarted() 触发 mirror.Initialize() + WaitForReady()(惰性启动)
写会话 三段式相位 ↔ WholeMirror 三拍会话(BeginSession 一族——尺寸后知)
Confirm 挂 WriteFooter(checkpoint 单人写完即提交)
Abort 挂未写尾 Dispose(镜像会话尾截断回退,悬干弃置)
读侧 Verify = 账面机制——内容有效性由消费方格式裁决
传输上限 会话打开声明 maxTransferBytes(默认 128K),单次超限直接抛
并发 单写者(并发双开 → TryOpenWrite false,非抛)
Dispose 转发 _mirror.Dispose()(幂等)

详见 src/KernLab.Tier.Runtime/DataMirror/WholeMirrorPersistence.cs。


8. 反模式

# 反模式 后果 正确
1 会话未 EndSession 跨 await 帧三拍单线程契约破坏;下个 BeginSession 抛"上一帧未收官" 三拍同线程顺序完成;跨 await 前 EndSession
2 跨实例组合 DeleteOnClose=true 跨重启恢复时引擎被清,真相源丢失 跨重启组合 DeleteOnClose=false;测试一次性卷才用 true
3 绕过 2PC 直接靠 EndSession 当提交 LastCommittedSeq 不推进,恢复时该 checkpoint 视为悬干被截断 提交点走 Prepare + ConfirmCommitted
4 Abort 后读会话内地址 悬干已物理丢弃,帧头 magic 被 punch hole 清零 Abort 后只读 HighestVersionAddress(已提交链头)
5 用 HighestVersionAddress == Empty 判"无版本" 首 record 就在 Empty(合法地址空间起点),误判为无版本 用 HasCommittedVersion 标志判存在性
6 WholeMirror 多线程并发 AppendChunk 帧三拍单线程契约破坏,CRC 累积错乱 单线程顺序追加;多生产者经队列汇聚到单写者
7 PagedMirror 跨会话不 Confirm 就写下页 上次会话 pending 帧未裁决,链头推进错乱 每 checkpoint 会话写完走 Prepare + ConfirmCommitted/Abort
8 给 Disabled meta 调 SetOpaqueMeta 抛 InvalidOperationException(禁用即报错) 配置 MetaPolicyKind=Managed/Transport 再写 opaque
9 跨 checkpoint 会话复用同 seq Prepare/Confirm CAS 推进错乱(seq ≤ current no-op) 每 checkpoint 单调推进 seq;悬挂用独立 seq
10 未调 ReclaimOldVersions 期望自动回收 旧 checkpoint 累积,版本链变长(ConfirmCommitted 已自动调,但显式调合法) ConfirmCommitted 内置自动回收;如有自定义触发点,调 ReclaimOldVersions 即可

9. 想深入?指路

想懂什么 去哪
源码 src/KernLab.Tier.Runtime/Structures/Mirror/(MirrorBase.* partials + WholeMirror* / PagedMirror* + Contracts/)
帧字节布局 / Codec 内部 Structures/Mirror/Contracts/MirrorFrame.cs + IMirrorCodec.cs 源码注释
横切:meta 协议(opaque 搭车 / Managed/Transport/Disabled 三模式) meta.md
横切:Session 协调协议(写 / 检查点 / 悬挂裁决) session.md
横切:StorageEngine 使用(读写 / 水位 / Compact) storage-engine.md
横切:段表机制 segment-table.md
横切:lease 协议 lease-protocol.md
同族:Ring 主结构 ring.md
同族:Log 主结构 log.md
同族:Index 索引族 index.md
同族:VersionedMetadata versioned-metadata.md
同族:Snapshot(字节截断形态) snapshot.md
WholeMirrorPersistence 桥接器源码(索引族已退役,仍保留给其他借镜像能力的组件) src/KernLab.Tier.Runtime/DataMirror/WholeMirrorPersistence.cs 源码注释
总览(6 子族速查 + KV 组合) structures.md

机制级细节(8 水位全表、帧字节布局、CRC 增量算法、2PC 内部状态机、扫盘重同步策略)按需从源码与设计稿查阅——使用面不需要这些细节;能力全集以类型 XML 注释为准。

9.1 配套阅读顺序建议

顺序 文档 目的
1 structures.md 6 子族全貌 + 选型坐标
2 本篇(mirror.md) Mirror 子族机制 + 两种形态
3 storage-engine.md 引擎读写 / 水位 / Compact 基础
4 meta.md opaque 搭车 / 三模式
5 session.md 跨结构 2PC 协调协议
6 snapshot.md 同族异坐标系对比

核心要点回顾:Mirror 是字节镜像 + 版本链 + 2PC 六件套;选型看颗粒度(整体流式 → WholeMirror,按页增量 → PagedMirror);提交点必走 Prepare + ConfirmCommitted(EndSession 只 flush 数据不推进 seq);Abort = 丢弃未确认会话(committed 链头不被触碰);恢复按版本号截断(与 Snapshot 字节截断异坐标系)。

9.2 FAQ

  • Q:为什么没有 Create 工厂? A:Mirror 子类构造 + Initialize + WaitForReady 三步即就绪(区别于 Ring 封闭类型的 Create 一步就绪)。桥接形态 WholeMirrorPersistence 将此三步推迟到首次使用。
  • Q:非 2PC 用法(单 checkpoint)如何提交? A:EndSession 已 flush;不走 Prepare/Confirm 时数据已持久,但 LastCommittedSeq 不推进——恢复时该 checkpoint 视为悬干可能被截断。生产用法必走 2PC。
  • Q:WholeMirror 与 Snapshot 怎么选? A:需要 N=2 版本链 / 多链 / 2PC → Mirror;纯流式字节截断 / 无版本概念 → Snapshot(同族异坐标系,详见 snapshot.md)。
  • Q:跨实例恢复需要配 meta 吗? A:不需要。MetaPolicyKind=Disabled 时走扫盘兜底(WholeMirror 尾锚 O(最新帧),PagedMirror 全走链按 PageId 重建);Managed 模式下 meta O(1) 加速。

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