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——持久化机制与恢复协议