MinIO 桶复制设计深度解析：版本不可变性、复制状态机与内部元数据落盘机制

本文基于 MinIO 官方设计文档 docs/bucket/replication/DESIGN.md，系统讲解服务端桶复制（Bucket Replication）的设计原理：从基于版本不可变性的对象/元数据复制，到 DeleteMarker 与版本化删除的同步语义、存量对象重同步（resync）、多目标复制的边界条件，以及 xl.meta 中内部复制元数据的实际存储格式，并结合仓库源码印证状态机、扫描器与配置项的真实实现。读完本文，你将能够理解复制状态（PENDING/COMPLETED/FAILED/REPLICA）的完整生命周期、排查复制延迟与失败的落点，以及依据源码验证配置参数的当前取值范围。

总体设计：依赖版本不可变性的最终一致同步

MinIO 的桶复制不依赖日志重放或快照比对，而是依赖版本控制（versioning）提供的对象不可变性来在源站（source）与复制目标（target）之间同步对象。设计文档给出的核心保证是：复制完成后，对象的数据、元数据、最后修改时间、版本 ID 在源与目标上完全一致，因此版本排序（version ordering）在源、目标集群上自动保持对齐——这是后续所有复制语义（包括删除同步）的根基。

这一设计的直接推论是：复制天然受版本控制约束，只有版本化对象才能被完整复制；null 版本（版本控制启用前创建的对象）会打破不可变性保证，因此被单独处理（见下文“存量对象复制”一节）。

对象版本与元数据的复制：PENDING → COMPLETED/FAILED 状态机

状态流转

当对象满足复制配置中的规则时，复制状态按如下周期流转：

1. PUT 操作完成时，先在源端将 X-Amz-Replication-Status 置为 PENDING 并把复制任务入队（若配置了同步复制则立即执行）；
2. 复制执行后，源端该对象版本的元数据被更新为 COMPLETED（成功）或 FAILED（失败）；
3. 目标端复制出来的对象版本上，X-Amz-Replication-Status 显示为 REPLICA。

失败自愈由扫描器兜底：所有复制失败都会被扫描器（scanner）接管。扫描器以 1 分钟为频率运行，每轮扫描整个命名空间的六分之一（1/16），将标记为 PENDING 或 FAILED 的对象版本重新入队复制。源码层面，扫描逻辑位于 cmd/data-scanner.go，其中即包含对 replication.Replica 等复制状态的分支判断；元数据中用于回传 ObjectInfo 的复制状态字段定义在 cmd/storage-datatypes.go 的 ReplicationState 字段。

元数据变更的复制

源对象版本上的元数据变更——例如通过 PutObjectTagging、PutObjectRetention、PutObjectLegalHold 以及 COPY API 产生的变更——会以与对象复制相同的方式复制到目标版本，X-Amz-Replication-Status 同样经历相同的状态周期。

复制速度与 worker 配置

设计文档指出，复制速度取决于集群负载、对象数量与存储速度，mc admin bucket remote add 上设置的带宽限制也会影响速率。文档原文的默认配置为：

• 复制 worker 数默认为 100；
• 通过 mc admin config set alias api 设置 replication_workers 调整。

结合当前仓库源码需要注意这一配置的演进：在 internal/config/api/api.go 中，replication_workers 与 replication_failed_workers 已被列入废弃 key 列表，当前生效的键为：

• replication_max_workers（环境变量 MINIO_API_REPLICATION_MAX_WORKERS）：默认 500，合法范围 1–500；
• replication_max_lrg_workers（环境变量 MINIO_API_REPLICATION_MAX_LRG_WORKERS）：针对 ≥128MiB 的传输，默认 10，合法范围 1–10（每节点）。

上述解析与校验逻辑见 internal/config/api/api.go，运行期由 cmd/handler-api.go 在配置变更时热更新 worker 上限。此外 MinIO 暴露的 Prometheus 指标可用于规划资源分配与带宽管理，以优化复制速度。

同步复制（Synchronous replication）

若远程目标以同步模式配置（mc admin bucket remote add 时指定 --sync），PUT 在返回响应前会立即尝试复制。若目标不可用，X-Amz-Replication-Status 被标记为 FAILED，待扫描器下一轮运行时重新与目标同步。

双向（Active-Active）复制的语义边界

上述流程描述的是单向上行复制（入站的上传与源端元数据变更）。配置为 active-active 时，目标端新产生版本上的入站上传与元数据变更会反向同步回源站，并在源站上被标记为 REPLICA。

需要明确两个设计约束：

1. REPLICA 版本的元数据默认不回传：AWS 与 MinIO 默认都不同步标记为 REPLICA 的对象版本上的元数据变更回源端。这需要显式开启复制配置中的 “replica modification sync”（副本元数据同步）功能才能实现双向元数据同步。
2. 自动故障转移（failover）：active-active 场景下，GET/HEAD 请求若命中的对象或版本满足复制条件、且在一站缺失而在另一站存在，会发生自动故障转移，使应用在两站尚未完全同步前即可充分利用双向复制。

DeleteMarker 与版本化删除的复制

配置方式

MinIO 通过 mc replicate add 设置复制配置时指定 --replicate delete,delete-marker 来开启 DeleteMarker 复制与版本化删除（versioned delete，即永久删除某一版本）复制。实现基于 V2 复制配置，并扩展了 DeleteMarkerReplication 与 DeleteReplication 两个字段；默认值为 Disabled，除非用户在添加规则时显式指定。

DeleteMarker 复制的状态查询

DeleteMarker 复制与对象版本复制一样经历 PENDING → COMPLETED/FAILED 的状态流转（例如对对象执行不带 version 的 mc rm 即设置 DeleteMarker）。同步完成后，目标端该 DeleteMarker 显示 X-Amz-Replication-Status: REPLICA。查询方式为：

• 状态通过 HEAD/GET 调用 DeleteMarker 版本时返回的 X-Minio-Replication-DeleteMarker-Status 响应头给出，例如 mc stat --version-id dm-version-id。

设计文档同时给出了一个重要的运维警示：active-active 复制若同时开启 DeleteMarker 复制，当源与目标并发设置 DeleteMarker、或两侧集群在复制事件同步前相继宕机时，可能产生重复的 DeleteMarker。这是允许将 REPLICA 状态版本上的 DeleteMarker 回传源端所导致的、active-active 场景下不可避免的副作用。

版本化删除（永久删除）的复制

对某版本执行 mc rm --version-id（永久删除）时，复制实现的语义是：

1. 源端先将该版本标记为 PENDING purge（待清除）；
2. 将该版本同步到目标，并确认目标端版本确实被删除后，才从源端删除该版本；
3. 在同步完成前，被删除的对象版本仍可通过 mc ls --versions 列出，但不可通过 GET/HEAD 访问，会返回 HTTP 405；
4. 状态可通过对相应 versionID 的 HEAD 请求查询，响应头 X-Minio-Replication-Delete-Status 在复制尚未追上时显示 PENDING 或 FAILED。

源码上可以印证这一 “purge 状态” 的元数据承载：cmd/storage-datatypes.go 定义了

// VersionPurgeStatusKey denotes purge status in metadata
VersionPurgeStatusKey = ReservedMetadataPrefixLower + "purgestatus"

即 xl.meta 中 MetaSys 段落的 purgestatus 键，正是版本化删除复制状态的落盘位置（见下文元数据示例）。

另一个关键实现约束：同步复制模式不适用于 DELETE 操作。因为源集群上被删除的版本必须先维持状态、确保操作镜像到目标集群后才能完成，且多 DELETE 操作期间需要对同一对象不同版本的并发删除做串行化处理——所以当前实现中 DELETE 操作无论同步还是异步模式，都统一走队列（queued）。

存量对象复制与 resync

存量对象（existing objects）的复制

存量对象复制机制与常规复制类似，但有两点差异：

• 满足存量复制条件的对象由扫描器运行时检测发现，在开启存量复制且满足规则时被复制；
• 由于复制依赖版本不可变性，只有版本控制启用期间创建的既有对象才能被复制。即便复制规则中途被禁用再重新启用，禁用期间创建的对象也会被扫描器捕获并同步；
• 为节省 iops，满足存量复制条件的对象在复制前不预先标记为 PENDING（常规复制会先置 PENDING）。

对于 null 版本（版本控制启用前创建的对象），它们打破了版本不可变性保证：开启存量复制后，只要目标端不存在该对象、或源端 null 版本比目标端 null 版本更新，就会作为 null 版本复制到远程目标。

mc replicate resync start：远程站点丢失后的重同步

若远程站点整体丢失、之前已复制的对象需要重新同步，需使用 mc replicate resync start 命令（可选 --older-than 参数）触发。该命令的行为：

1. 生成一个 ResetID（唯一 UUID），连同触发时间（默认值，即发起重置的时刻）一起保存到远程目标配置中；
2. 所有创建时间早于该时间的对象，只要满足已开启存量复制的复制规则，即有资格被重新复制；
3. 复制完成时，对象元数据中写入 x-minio-internal-replication-reset-<arn>:<bucket> 键，值为“复制完成时间戳;ResetID”；
4. 同样为节省 iops，被重复制的对象不会先置为 PENDING。

从设计定位看，resync 是一个慢速操作：它不使用复制队列，而是遍历命名空间、逐个对象复制，以避免拖累服务器负载。官方建议不要同时对多个桶发起 resync，进度可通过 mc replicate resync status alias/bucket --remote-bucket <arn> 监控。失败兜底：若 resync 未能复制某些版本，会被扫描器内建的修复机制接管；若 resync 报告失败或期间集群重启，可以重新发起 resync start——代价是此前已同步内容会产生额外的元数据更新开销。

多目标（Multi-Destination）复制的边界条件

多站点复制的总体设计与两站点场景一致，但有若干例外：

• 源集群上的复制状态只有在所有目标均复制完成后才标记为 COMPLETED；任一目标失败则整体状态仍反映为 PENDING；
• 3 个及以上站点参与 active-active 复制时，各站点的 replica metadata sync、delete marker replication、delete replication 配置必须一致，以避免集群间出现不一致的状态视图；
• 不推荐非对称复制拓扑。文档给出的反例：A、B、C 三站参与复制，应避免 “A → [B, C]，B → A” 这类配置——若 B 站开启了 replica metadata sync，在 B 上对副本版本做的元数据更新只会反映到 A 而不会到 C。

其根本原因是：一切复制活动本质上都是单向上行操作，与目标数量无关。

内部元数据：xl.meta 中的复制状态落盘格式

版本控制使用的 xl.meta 文件在复制场景下带有额外的元数据段（源码中的元数据模型见 cmd/erasure-metadata.go 与 cmd/xl-storage-format-v2.go）。以下均为设计文档给出的真实示例。

源端对象复制元数据

...
  "MetaSys": {
      "x-minio-internal-inline-data": "dHJ1ZQ==",
      "x-minio-internal-replication-status": "YXJuOm1pbmlvOnJlcGxpY2F0aW9uOjo2YjdmYzFlMS0wNmU4LTQxMTUtYjYxNy00YTgzZGIyODhmNTM6YnVja2V0PUNPTVBMRVRFRDthcm46bWluaW86cmVwbGljYXRpb246OmI5MGYxZWEzLWMzYWQtNDEyMy1iYWE2LWZjMDZhYmEyMjA2MjpidWNrZXQ9Q09NUExFVEVEOw==",
      "x-minio-internal-replication-timestamp": "MjAyMS0wOS0xN1QwMTo0MzozOC40MDQwMDA0ODNa",
      "x-minio-internal-tier-free-versionID": "OWZlZjk5N2QtMjMzZi00N2U3LTlkZmMtNWYxNzc3NzdlZTM2"
    },
    "MetaUsr": {
      "X-Amz-Replication-Status": "COMPLETED",
      "content-type": "application/octet-stream",
      "etag": "8315e643ed6a5d7c9962fc0a8ef9c11f"
    },
...

Base64 解码后可以直观看到其结构：

• x-minio-internal-replication-status 解码后为 arn:minio:replication::6b7fc1e1-…:bucket=COMPLETED;arn:minio:replication::b90f1ea3-…:bucket=COMPLETED;——即按目标 ARN 分别记录每个目标的复制状态，这与多目标复制 “全部完成才算 COMPLETED” 的设计完全对应；
• x-minio-internal-replication-timestamp 解码后为 2021-09-17T01:43:38.404000483Z，记录复制完成时间；
• MetaUsr 中的 X-Amz-Replication-Status: COMPLETED 是对外可见的用户元数据。

目标端对象复制元数据

...
  "MetaSys": {
      "x-minio-internal-inline-data": "dHJ1ZQ==",
      "x-minio-internal-replica-status": "UkVQTElDQQ==",
      "x-minio-internal-replica-timestamp": "MjAyMS0wOS0xN1QwMTo0MzozOC4zODg5ODU4ODRa"
    },
    "MetaUsr": {
      "X-Amz-Replication-Status": "REPLICA",
      "content-type": "application/octet-stream",
      "etag": "8315e643ed6a5d7c9962fc0a8ef9c11f",
      "x-amz-storage-class": "STANDARD"
    },
...

x-minio-internal-replica-status 解码即为 REPLICA，与 MetaUsr 中对外暴露的 X-Amz-Replication-Status: REPLICA 相互印证。

DeleteMarker 的额外复制元数据

...
 {
      "DelObj": {
      "ID": "u8H5pYQFRMKgkIgkpSKIkQ==",
      "MTime": 1631843124147668389,
      "MetaSys": {
        "x-minio-internal-replication-status": "YXJuOm1pbmlvOnJlcGxpY2F0aW9uOjpiOTBmMWVhMy1jM2FkLTQxMjMtYmFhNi1mYzA2YWJhMjIwNjI6YnVja2V0PUNPTVBMRVRFRDthcm46bWluaW86cmVwbGljYXRpb246OjZiN2ZjMWUxLTA2ZTgtNDExNS1iNjE3LTRhODNkYjI4OGY1MzpidWNrZXQ9Q09NUExFVEVEOw==",
        "x-minio-internal-replication-timestamp": "U3VuLCAzMSBEZWMgMDAwMCAxOTowMzo1OCBHTVQ="
      }
    },
    "Type": 2
}

DeleteMarker 的复制状态同样按 “AR 目标 ARN=状态” 的编码写入 MetaSys，承载于 DelObj 记录（Type: 2 表示删除记录类型）。

版本化删除的 purgestatus 元数据

{
    "DelObj": {
      "ID": "u8H5pYQFRMKgkIgkpSKIkQ==",
      "MTime": 1631843124147668389,
      "MetaSys": {
        "purgestatus": "YXJuOm1pbmlvOnJlcGxpY2F0aW9uOjpiOTBmMWVhMy1jM2FkLTQxMjMtYmFhNi1mYzA2YWJhMjIwNjI6YnVja2V0PUNPTVBMRUVEO2FybjptaW5pbzpyZXBsaWNhdGlvbjo6NmI3ZmMxZTEtMDZlOC00MTE1LWI2MTctNGE4M2RiMjg4ZjUzOmJ1Y2tldD1GQUlMRUQ7",
        "x-minio-internal-replication-status": "YXJuOm1pbmlvOnJlcGxpY2F0aW9uOjpiOTBmMWVhMy1jM2FkLTQxMjMtYmFhNi1mYzA2YWJhMjIwNjI6YnVja2V0PTthcm46bWluaW86cmVwbGljYXRpb246OjZiN2ZjMWUxLTA2ZTgtNDExNS1iNjE3LTRhODNkYjI4OGY1MzpidWNrZXQ9Ow==",
        "x-minio-internal-replication-timestamp": "U3VuLCAzMSBEZWMgMDAwMCAxOTowMzo1OCBHTVQ="
      }
    },
    "Type": 2
}

注意此例中 purgestatus 解码后包含 …bucket=COMPLETED;arn:minio:replication::6b7fc1e1-…:bucket=FAILED;——一个目标 purge 成功（COMPLETED）、另一个目标 purge 失败（FAILED），正对应 “确认目标版本删除后才从源端删除” 的语义与 X-Minio-Replication-Delete-Status 报告 FAILED 的场景。该键在源码中的定义即上文引用的 cmd/storage-datatypes.go VersionPurgeStatusKey。

resync 的 reset 元数据（源端）

...
  "MetaSys": {
    ...
    "x-minio-internal-replication-reset-arn:minio:replication::af470089-d354-4473-934c-9e1f52f6da89:bucket": "TW9uLCAwNyBGZWIgMjAyMiAyMDowMzo0MCBHTVQ7ZGMxMWQzNDgtMTAwMS00ODA3LWFhNjEtOGY2MmFiNWQ5ZjU2",
    ...
  },
...

解码后值为 Mon, 07 Feb 2022 20:03:40 GMT;dc11d348-1001-4807-aa61-8f62ab5d9f56，即 “复制完成时间戳;ResetID” 的固定格式，键名中嵌入了目标 ARN——与上文 resync 章节描述的 ResetID 机制一一对应。该键在 DeleteMarker 的 resync 场景下同样适用。

配套实操入口与延伸阅读

设计文档建议先阅读使用指南 docs/bucket/replication/README.md 再深入本设计。仓库内还附带了一组可直接参考的复制实操脚本，均位于 docs/bucket/replication/ 目录：

• setup_replication.sh：两站点复制的基础搭建；
• setup_2site_existing_replication.sh：开启存量对象复制的两站点场景；
• setup_3site_replication.sh：对应本文“多目标复制”一节的三站点拓扑；
• delete-replication.sh：DeleteMarker 与版本化删除复制的验证脚本；
• test_del_marker_proxying.sh：active-active 下 DeleteMarker 故障转移行为的相关脚本。

版本控制（复制不可变性前提）的设计说明见 docs/bucket/versioning/ 目录下的文档；桶级复制配置的 API 入口实现位于 cmd/bucket-replication-handlers.go 与 cmd/bucket-replication.go。

小结

MinIO 桶复制设计的核心可以归纳为三点：其一，复制语义完全建立在版本不可变性之上，源/目标的版本顺序与元数据一致性由此天然保证；其二，所有复制（含删除）都是“状态标记 + 队列 + 扫描器兜底”的最终一致模型，同步模式仅作用于 PUT 而不作用于 DELETE；其三，全部复制状态都以 Base64 编码的键值对落盘在 xl.meta 的 MetaSys 段落中（x-minio-internal-replication-status、x-minio-internal-replica-status、purgestatus、reset-arn 键），并按目标 ARN 分别记录状态——这使得多目标 COMPLETED 语义、purge 失败重试与 resync 断点都能在元数据层面被直接验证与排查。