底层二进制格式单元说明(存储 × 线格式)
本文是 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 校准(外部解析器最容易错的两点):
- CRC64 = ECMA-182(多项式
0x42F0E1EBA9EA3693、init 0、无异或输出)——不是 zlib/ISO 常见约定。 - 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 的产品消费面)