MinIO Bucket 版本化设计详解：xl.meta 磁盘格式、v1.0 到 v1.3 的演进与源码实现原理

本文以 MinIO 官方设计文档 DESIGN.md 为主体，完整讲解支撑 S3 兼容版本化（Bucket Versioning）的核心存储格式 xl.meta：从 8 字节 XL 头、各小版本的二进制布局，到 v1.3 索引化布局与 Inline Data 编码，并结合 cmd/xl-storage-format-v2.go 等源码印证读写、排序、多盘仲裁合并（quorum merge）的真实实现，帮助读者掌握版本化对象在磁盘上的“真相来源”（source of truth）是如何被序列化、校验与合并的。

1. xl.meta 的定位：每个版本在盘上的唯一事实来源

xl.meta 是 MinIO 为支持 AWS S3 兼容版本化而采用的自描述后端格式。对启用版本的桶而言，同一对象路径下的多个版本共享同一个 xl.meta 文件，该文件因此成为每个版本在盘上（at rest）的事实来源：它记录版本 ID、修改时间、纠删码参数、分片信息、用户元数据与内部元数据。文件本身是一个 msgpack 序列化的数据流，反序列化器只需先读取文件开头的 8 字节 XL 头，即可判断当前格式与格式版本，从而选择正确的数据结构去解析后续内容。

在源码中，这个 8 字节头由 cmd/xl-storage-format-v2.go#L42-L71 定义并初始化：

• xlHeader 固定为 [4]byte{'X', 'L', '2', ' '}；
• xlVersionMajor = 1：发生不兼容变更时递增，防止降级到不兼容版本；
• xlVersionMinor = 3：非破坏性变更时递增，便于事后识别数据的确切版本；
• init() 中用 binary.LittleEndian.PutUint16 将 major/minor 打包写入 xlVersionCurrent。

解析入口是 checkXL2V1：它校验 XL2 魔数，若第 4~8 字节恰好是历史字节序列 "1 " 则按 v1.0 处理，否则按 little-endian 的 uint16 major + uint16 minor 解析，并对 major > 1 的未知格式直接报错。测试夹具 cmd/testdata/xl.meta 与 cmd/testdata/xl.meta-v1.2.zst 保留了不同格式版本的真实样例，可用于对照。

1.1 v1.0 布局

设计文档给出的 v1.0 布局如下：

Entry	Encoding	Content
xlHeader	[4]byte	'X', 'L', '2', ' '
xlVersion	[4]byte	'1', ' ', ' ', ' '
xlMetaV2	msgp object	所有版本序列化为单个 messagepack 对象
[EOF]

1.2 v1.1+ 布局

1.1 版本引入了 Inline Data（小对象内容直接内嵌在元数据文件尾部）。为让读取方能“整体跳过”元数据段直达数据段，元数据被包裹成一个二进制数组（bin array）：

Entry	Encoding	Content
xlHeader	[4]byte	'X', 'L', '2', ' '
xlVersionMajor	uint16	xl-meta 主版本
xlVersionMinor	uint16	xl-meta 次版本
xlMetaV2	msgp bin array	序列化元数据的二进制数组
crc	msgp uint	前一个数组内容 64 位 xxhash 的低 32 位（仅 v1.2+）
inline data	binary	内联数据（若有），编码见下文 Inline Data 一节
[EOF]

其中 CRC 对应源码中的 xxhash 校验：加载路径在 xlMetaV2.loadLegacy 中对 v1.2+ 数据执行 uint32(xxhash.Sum64(v)) != crc 则报 CRC mismatch；而 readXLMetaNoData 展示了如何只读取元数据段、精确裁剪掉 CRC 段（v1.2 之前 CRC 为变长 msgp uint，v1.3 起固定 5 字节）而不触碰尾部数据。

从源码结构看，每个纠删集合（erasure set）中的每块盘都会保存一份该对象的 xl.meta，对象目录结构如 cmd/xl-storage-format-v2.go#L90-L102 注释所示：

disk1/
└── bucket
    └── object
        ├── a192c1d5-9bd5-41fd-9a90-ab10e165398d   // 某版本的数据目录
        │   └── part.1
        ├── c06e0436-f813-447e-ae5e-f2564df9dfd4
        │   └── part.1
        ├── legacy                            // xlV1 遗留对象的数据目录
        │   └── part.1
        └── xl.meta

2. 版本条目类型：ObjectType、DeleteMarker、Legacy 与 Free-Version

设计文档指出，xl.meta 承载三类版本条目，分别标记该条目的版本对象类型：

• ObjectType（默认）：常规对象，通过 PutObject / MultipartUpload / CopyObject 写入；
• LegacyObjectType：保留旧部署中的 xl.json（xlV1）格式，直到其被覆写；
• DeleteMarker：为捕获 DELETE 序列而生成的版本 ID，主要服务于 AWS 规范兼容——软删除不销毁数据，而是让 delete marker 成为最新版本。

源码中对应 VersionType：ObjectType = 1、DeleteType = 2、LegacyType = 3。每条记录由 xlMetaV2Version 统一封装，Type 决定访问哪一个具体结构：xlMetaV2Object（V2Obj）、xlMetaV1Object（V1Obj）或 xlMetaV2DeleteMarker（DelObj）。

设计文档附带的 msgpack-JSON 样例（解码 v1.0 时代文件时 xl-meta 工具的输出形态）如下，其字段与 xlMetaV2Object 一一对应：

{
  "Versions": [
    {
      "Type": 1,
      "V2Obj": {
        "ID": "KWUs8S+8RZq4Vp5TWy6KFg==",
        "DDir": "X3pDAFu8Rjyft7QD6t7W5g==",
        "EcAlgo": 1,
        "EcM": 2,
        "EcN": 2,
        "EcBSize": 10485760,
        "EcIndex": 3,
        "EcDist": [3, 4, 1, 2],
        "CSumAlgo": 1,
        "PartNums": [1],
        "PartETags": [""],
        "PartSizes": [314],
        "PartASizes": [282],
        "Size": 314,
        "MTime": 1591820730,
        "MetaSys": {
          "X-Minio-Internal-Server-Side-Encryption-S3-Kms-Key-Id": "bXktbWluaW8ta2V5",
          "X-Minio-Internal-Server-Side-Encryption-S3-Kms-Sealed-Key": "ZXlKaFpXRmtJam9pUVVWVExUSTFOaTFIUTAwdFNFMUJReTFUU0VFdE1qVTJJaXdpYVhZaU9pSkJMMVZzZFVnelZYVjZSR2N6UkhGWUwycEViRmRCUFQwaUxDSnViMjVqWlNJNklpdE9lbkJXVWtseFlWSlNVa2t2UVhNaUxDSmllWFJsY3lJNklrNDBabVZsZG5WU1NWVnRLMFoyUWpBMVlYTk9aMU41YVhoU1RrNUpkMDlhTkdKa2tuaGpLMjFuVDNnMFFYbFJhbE15V0hkU1pEZzNRMk54ZUN0SFFuSWlmUT09",
          "X-Minio-Internal-Server-Side-Encryption-Seal-Algorithm": "REFSRXYyLUhNQUMtU0hBMjU2",
          "X-Minio-Internal-Server-Side-Encryption-Iv": "bW5YRDhRUGczMVhkc2pJT1V1UVlnbWJBcndIQVhpTUN1dnVBS0QwNUVpaz0=",
          "X-Minio-Internal-Server-Side-Encryption-S3-Sealed-Key": "SUFBZkFPeUo5ZHVVSEkxYXFLU0NSRkJTTnM0QkVJNk9JWU1QcFVTSXFhK2dHVThXeE9oSHJCZWwwdnRvTldUNE8zS1BtcWluR0cydmlNNFRWa0N0Mmc9PQ=="
        },
        "MetaUsr": {
          "content-type": "application/octet-stream",
          "etag": "20000f00f58c508b40720270929bd90e9f07b9bd78fb605e5432a67635fc34722e4fc53b1d5fab9ff8400eb9ded4fba2"
        }
      }
    }
  ]
}

字段含义对照源码：ID 是 16 字节版本 UUID；DDir 是该版本数据目录的 UUID；EcM/EcN/EcBSize/EcIndex/EcDist 是纠删码参数（数据块、校验块、块大小、本盘索引与分布顺序）；PartNums/PartSizes/PartASizes 分别记录分片号、逻辑大小与压缩后实际大小；MetaSys 是内部元数据（如本例中的 SSE-S3 KMS 密封密钥），MetaUsr 是用户自定义元数据。

除文档列出的三类外，源码还定义了第四种特殊条目 free-version：cmd/xl-storage-format-v2.go#L85-L88 注释说明它以一个带特殊 MetaSys 条目的 delete marker 表示，用于跟踪已被删除/覆写版本的分层（tiered）内容，仅对扫描器（scanner routine）可见，供后续异步删除——因为版本的分层内容是异步删除的，必须留一个“追踪版本”。其创建逻辑见 xl-storage-free-version.go：InitFreeVersion 在原对象 TransitionStatus == TransitionComplete 时生成，并携带 x-minio-internal/free-version 标记及分层目标信息。

3. v1.3+ 索引化布局：为更快读取与更新元数据而生

设计文档指出，1.3 版本引入了面向“更快元数据读取与更新”的改动，其条目顺序为：

Entry	Encoding	Content
xlHeaderVersion	msgp uint	头版本标识
xlMetaVersion	msgp uint	元数据版本标识
versions	msgp int	后续版本数量
header_1	msgp bin array	第 1 个版本的头
metadata_1	msgp bin array	第 1 个版本的元数据
…header_n	msgp bin array	最后一个版本的头
…metadata_n	msgp bin array	最后一个版本的元数据

核心思想是头与体分离：每个版本先写一个紧凑的“头”（含版本 ID、修改时间、签名、类型与标志位），再写完整的元数据体。查找最新版本或某版本时，只需解码头即可，无需反序列化整个文件。

3.1 版本头结构与标志位

文档给出的 xlHeaderVersion == 1 时的头结构如下：

//msgp:tuple xlMetaV2VersionHeader
type xlMetaV2VersionHeader struct {
 VersionID [16]byte  // Version UUID, raw.
 ModTime   int64     // Unix nanoseconds.
 Signature [4]byte   // Signature of metadata.
 Type      uint8     // Type of the version
 Flags     uint8
}

对应标志位定义：

const (
 FreeVersion = 1 << 0
 UsesDataDir = 1 << 1
 InlineData  = 1 << 2
)

对照当前源码 xlMetaV2VersionHeader：结构与文档一致（Signature 为元数据的 4 字节签名，用于跨盘一致性比对），并且从源码结构看，当前实现还扩展了 EcN, EcM uint8 两个字段——注释明确这些字段“对非 v2 对象和更老的 xl.meta 为 0/0”，属于向后兼容的增量扩展。标志位常量见 xlFlags，语义与文档一致：FreeVersion 标记 free-version，UsesDataDir 表示内容仍在本地数据目录（未分层或已从远端恢复），InlineData 表示内容内嵌在 xl.meta 中。头的 String() 方法还会打印 N/M 纠删参数，便于排障。

3.2 头部解码与序列化路径

• decodeXLHeaders：依次读取 header version、meta version（当前常量 xlHeaderVersion = 3、xlMetaVersion = 3，见 cmd/xl-storage-format-v2.go#L463-L466），再读取版本计数，超过已知上限或出现负计数即报错；
• decodeVersions：按“最新在前”顺序逐对读取 header_i 与 metadata_i，全程零拷贝（msgp.ReadBytesZC）回调处理，回调返回内部错误 errDoneForNow 可提前停止——这正是“只需读头就能回答多数查询”的实现基础；
• xlMetaV2.AppendTo：写出顺序与文档布局完全对应——xlHeader + xlVersionCurrent + 预留 4 字节 bin 长度占位 → 写入 xlHeaderVersion、xlMetaVersion、版本数 → 逐版本追加 header 与完整 meta 的 bin array → 回填长度 → 追加固定 5 字节的元数据 CRC（0xce + uint32(xxhash.Sum64(...))，注释说明 v1.3 之前为变长）→ 追加尾部 inline data。

此外，读取侧还有 readXLMetaNoData：首次只读 metaDataReadDefault = 4 << 10（4 KiB）并按需扩展，专门用于“数据段根本不关心”的场景（例如只需最新版本元数据），这是对 v1.3 目标“更快元数据读取”的直接支撑。

4. Inline Data：把小对象内容直接写进 xl.meta

设计文档规定 Inline Data 是可选的：没有内联数据时编码为 0 字节；存在时编码如下：

Entry	Encoding	Content
xlMetaInlineDataVer	byte	版本标识
id -> data	msgp map[string][]byte	字符串 id 到字节内容的映射

文档说明目前只存在 xlMetaInlineDataVer == 1，且 id 为对应版本版本的字符串形式 Version ID——也就是说，内联段是按版本 ID 索引的 map，一个 xl.meta 可同时内嵌多个小版本的内容。

源码实现在 cmd/xl-storage-meta-inline.go：

• 常量 xlMetaInlineDataVer = 1（L32），与文档“only xlMetaInlineDataVer == 1 exists”一致；
• serialize 先写 1 字节版本号，再写 msgp map 头与逐条 key/value；
• find 按 Version ID 键做零拷贝检索；validate 在加载时校验结构，repair 在损坏时保留仍可解析的条目以维持可操作性；
• 写入时机在 xlMetaV2.AddVersion：当 fi.Data 非空或对象大小为 0 时执行 x.data.replace(fi.VersionID, fi.Data)，把内容以该版本的字符串 Version ID 为键写入内联段；
• xlMetaV2TrimData 则在不反序列化元数据的前提下按布局截掉内联段，供“仅保留元数据”的写回路径使用。

内联化的收益在于：小对象无需在每块盘上额外创建数据目录与 part.1 文件，读写少一次随机 I/O；这与版本头 InlineData 标志、UsesDataDir 标志（UsesDataDir 对已分层且未恢复的对象返回 false）共同决定了“某版本的内容到底在哪”。

5. 多盘读写与仲裁合并：Load、AddVersion、DeleteVersion 与 Quorum Merge

理解 xl.meta 格式之后，再看它在版本化生命周期中的实际使用路径（以下均以 cmd/xl-storage-format-v2.go 为准）：

• 加载与兼容转换：LoadOrConvert 先判断是否 XLv2 格式，否则按旧 xl.json 解析并调用 AddLegacy 包装成 LegacyType 条目——这就是设计文档中 “preserves existing deployments and older xl.json format” 的落地：老对象在被覆写前始终以 legacy 条目保活。
• 新增版本：addVersion 先校验 Valid() 并检查版本总数是否超过 globalAPIConfig.getObjectMaxVersions()（超出返回 errMaxVersionsExceeded），然后在“最新在前”的有序数组中按 ModTime 降序插入新条目；AddVersion 进一步处理同 VersionID 的覆盖语义——已存在的 Legacy/ObjectType/DeleteMarker 条目会被 setIdx 原地替换（例如 delete marker 可被真正的对象数据替换）。
• 删除版本：DeleteVersion 返回需要删除的数据目录并指示是否最后一个版本。对 ObjectType 条目，它会调用 SharedDataDirCount 检查是否有其他版本引用同一 dataDir（有引用则只删条目、不删数据），并对已分层的版本通过 InitFreeVersion 追加 free-version 供扫描器异步清理远端内容；对 DeleteType 条目则区分“直接移除”与“更新复制/清除状态后再 setIdx”。
• 跨盘仲裁合并：由于每块盘各持一份 xl.meta，读取路径需要把多盘结果合并。mergeXLV2Versions 要求每个输入序列已排序、quorum 为“至少匹配的最小盘数”，其核心机制是：
  • 逐轮比较各盘“顶部版本头”，若各盘头完全一致（ver.header == topSig，其中 Signature 参与比较）直接采纳；
  • 不一致时按 sortsBefore 取“修改时间最新、类型更小、签名与 VersionID 依次 tie-break”的候选，并统计达到 quorum 的匹配数（matchesNotStrict 允许 VersionID 为空时回退到 ModTime 比较）；
  • 签名来自 xlMetaV2Object.Signature：将 ErasureIndex 归零（该字段跨盘必然不同）后，对 MetaUser/MetaSys 做确定性哈希，再与整个结构的 msgpack 序列化结果一起做 xxhash.Sum64，折叠为低 32 位存入头的 Signature 字段——这正是 v1.3 布局中“跨盘一致才能快速采纳”的依据。
• 只读头的快速路径：xlMetaBuf 提供不实例化完整 xlMetaV2 的轻量 API：ToFileInfo 按 versionID 精确解码命中版本、IsLatestDeleteMarker 只看第一个版本头即可判断“最新是否为删除标记”（对应 GET 返回 404 的语义）、AllHidden 判断是否所有可见条目都是 free marker。这些函数都只依赖“头”，体现了 v1.3 头体分离的设计红利。

上述行为与 docs/bucket/versioning/README.md 中描述的外部语义一一对应：PUT 同名对象时旧版本保留并生成新版本、DELETE 只添加 delete marker、按 versionID 的 GET/DELETE 才能定位并永久删除具体版本。

6. 实操：用 xl-meta 工具观测 xl.meta

设计文档提示可用 xl-meta 程序调试 xl.meta 内容（原文档中的外链对应本仓库的 docs/debugging/README.md “Decoding Metadata”一节）。按该文档，安装与使用方式如下（前提是本机已安装 Go）：

# 安装二进制
go install github.com/minio/minio/docs/debugging/xl-meta@latest

# 在当前目录查找 xl.meta 并解码为 JSON
xl-meta

# 递归解码多个文件
xl-meta ./**/xl.meta

# 查看内联数据（输出 id -> data size）
xl-meta --data xl.json

# 将内联数据导出到文件
xl-meta --export xl.json

该工具还接受 zip 输入，会输出压缩包内所有 xl.meta。远程排查时可用 mc support inspect ALIAS/bucket/path/to/file.txt/xl.meta 从后端各盘收集该对象的 xl.meta（支持通配符），下载得到 zip 后再喂给 xl-meta，即可离线比对多盘之间的版本头、签名与元数据，是验证第 5 节所述 quorum 合并行为是否如预期的最直接手段。

7. 小结与延伸阅读

• 格式演进主线：v1.0 单对象序列化 → v1.1 引入内联数据（元数据包成 bin array 以便跳过）→ v1.2 增加 xxhash 低 32 位 CRC → v1.3 头体分离的索引化布局（header/metadata 成对、固定 5 字节 CRC、xlHeaderVersion/xlMetaVersion 标识），目标是降低元数据读取与更新的成本；
• 三个版本类型（ObjectType / LegacyObjectType / DeleteMarker）加上仅扫描器可见的 free-version，共同承载了 S3 兼容软删除、旧格式兼容与分层内容异步清理三类需求；
• 内联数据段以 xlMetaInlineDataVer = 1 + map[string][]byte 编码，键为字符串 Version ID，是小型对象“元数据即数据”的存储通道；
• 多盘场景下，Signature + quorum 合并算法（mergeXLV2Versions）保证了在部分盘不一致时仍能确定性选出最新且一致的版本集合。

继续深入可参考的仓库资源：

• docs/bucket/versioning/DESIGN.md：本格式的权威设计文档（本文主体）
• docs/bucket/versioning/README.md：版本化行为、桶状态配置（Enabled/Suspended、ExcludedPrefixes）与 SDK 示例
• cmd/xl-storage-format-v2.go：格式常量、头解析、增删改与仲裁合并主实现
• cmd/xl-storage-format-v1.go：被 legacy 条目引用的旧 xlV1 结构
• cmd/xl-storage-meta-inline.go：内联数据编解码
• cmd/xl-storage-free-version.go：free-version 的创建与判定
• cmd/xl-storage-format-v2_test.go：格式读写与合并的测试用例
• docs/debugging/README.md：xl-meta、mc support inspect 等观测手段