Table of Contents

底层二进制格式单元说明(存储 × 线格式)

本文是 KernLab.Tier 全系列二进制格式的互操作手册——外部解析工具 / 审计 / 数据恢复 / 其他语言 实现可据此解析全套磁盘存储格式与网络线格式。每个格式给出字节图、字段表、CRC/校验、版本演进 与源码位置;精确到字节(偏移/宽度/端序),与生成 Codec([BinaryLayout] 声明即代码)一致。

覆盖范围:Runtime 存储结构(磁盘可解析)× Products 产品封装 × Core.Net 网络线格式。 与使用指南的关系:log.md/storage-engine.md/tierwal.md 等讲行为,本文讲字节。

代码引用为仓库相对路径(Structures/… = src/KernLab.Tier.Runtime/Structures/…)。


归属声明:[BinaryLayout] / [WireMessage] 编译期面由组织包 KernLab.Loom(Layout/Wire) 提供,Tier 为消费者(Directory.Build.props 注入);仓内 KernLab.Tier.CodeGen 仅剩 TierFs/KvStore/RingKey/ConstantRegistry 四个域专属生成器。字节布局描述不受归属影响。

分册索引(按格式族分类)

分册 覆盖
Log 族 页帧 8B / EntryLog 22B / DeltaLog 18B / LogMeta 水位块
Ring 族 BlittableRing 40B v2 / VarKeyRing VRHD 变长 / Overflow 18B / RingMeta 132B
段元组·索引·快照 SegmentTuple 36B / 索引帧(Probing/BTree/SkipList)/ 快照帧
TierVolume 虚拟卷盘上格式(超级块/位图/journal)
产品格式 TierWAL opaque / Kv 值帧 / TimeSeries 水位 / Blob 对象表 48B
Meta 家族·Mirror·VersionedMetadata 通用自描述 meta 块 + 五 Payload 对照 / Mirror 帧 / MetadataHeader 42B
网络线格式 Wire FrameHeader / RaftRpc / RaftEntriesRegion / Gossip / HyParView

5. 版本与演进速查

格式 当前版本 演进要点
LogPageFrame 无版本字段 DataLength 即写侧扇区对齐字节数
EntryLogHeader 0x0100 codecId 在 flags bits8-11
DeltaLogHeader 0x0100 同构 EntryLog,CRC32C
LogMetaHeader 0x0100 PreparedTailAddress 追加(旧块零扩展降级)
BlittableRingHeader 0x0200 v2 泛型改版 KeyLength 退役(v1 旧盘不认);Magic "BRHD"
VarKeyRingHeader 0x0200(复用) Magic "VRHD"——与 BRHD 同构 40B 头,记录体变长 prologue 10B
OverflowRecordHeader 0x0100 —
RingMetaHeader 0x0100 —
SegmentTupleHeader Version=2 Magic "TC_SEGTU",Summary 内联
ProbingIndexHeader 0x0100 版本链 N 版轮替
BTree/SkipListHeader 0x0100 —
MirrorFrameHeader(PM) —(魔数型) PMVH 32B/PMFT 40B,CrcPrefixSize=32
MetadataHeader 0x0100 42B 版本链 N=2,Crc@38 in-Header
StreamFrameHeader 0x0100 TotalLength/EntryCount 在 Footer
WalOpaqueHeader 0x0101(v1.1——ArchivedIndex@56 + Flags bit0 编解码扩展段;v1.0 56B 旧容器向后兼容读) 只记 head/tail 锚点(段 anchor 表纯内存)
WalSnapshotHeader 0x0100 —
RaftStoreMeta 1(byte) 前向兼容门归消费面
KvVersionOpaque magic "TKV1" 12B→24B(扫描水位追加),旧块兼容
RaftRpc 线格式 WireFormatVersion=3 信封之死,条目区 blob 化

CRC 校准(外部解析器最容易错的两点):

  1. CRC64 = ECMA-182(多项式 0x42F0E1EBA9EA3693、init 0、无异或输出)——不是 zlib/ISO 常见约定。
  2. CRC32C 为标准 Castagnoli(init 0xFFFFFFFF、final XOR 0xFFFFFFFF)。

6. 相关文档

各分册尾部"源码"锚即格式真源(声明即代码)。

  • 存储行为面:log.md / ring.md / meta.md / snapshot.md / segment-table.md(src/KernLab.Tier.Runtime/docs/)
  • 跨层持久化稳定性:persistence-architecture.md
  • TierVolume 虚拟卷(§2.11 格式的介质行为面):virtual-file-system.md(载体写穿/两档 IO/崩溃窗口谱系)
  • 产品格式使用面:tierwal.md / tierkv.md / tierseries.md / tierblob.md(src/KernLab.Tier.Products/docs/)
  • 网络线格式行为面:transport-architecture.md(§5 线协议帧)、p2p-architecture.md(§3 帧格式)
  • 格式真源(声明即代码):各 [BinaryLayout] 类型 + KernLab.Loom.Layout 生成 Codec;src/KernLab.Tier.Contracts/Layout/(RecordMagic/RecordFlags/CRC footer)
  • 变长键环行为面:tiervarkv.md(§2.5b VRHD 的产品消费面)