复制运维

• 1: 站点复制概览
• 2: IAM 升级与恢复
• 3: 历史复制状态检查

1 - 站点复制概览

SILO 升级说明： 九月 IAM 修复要求所有参与节点协调升级，并备份完整删除历史。请先阅读 IAM 升级与恢复及历史复制状态检查，并按组件版本表区分主分支修复与已发布制品。

站点复制将多个相互独立的 MinIO 部署配置为一个由副本组成的集群，这些副本称为对等站点。

站点复制要求使用内置的 MinIO Identity Provider (IDP) 或 外部 IDP。 所有已配置的部署都必须使用同一个 IDP。 使用外部 IDP 的部署必须在各站点之间使用相同的配置。

有关站点复制架构和部署概念的更多信息，请参阅 Deployment Architecture: Replicated MinIO Deployments。

除早期开发、评估或一般性实验外，MinIO 不建议在站点复制中使用 macOS、Windows 或未编排的容器部署。生产环境请使用受支持的 Linux 或 Kubernetes 部署，并按照本页的站点复制流程操作。

概览

所有站点之间会复制哪些内容

每个 MinIO 部署（“对等站点”）都会将以下变更同步到其他对等站点：

• 存储桶和对象的创建、修改与删除，包括

  • 存储桶与对象配置
  • 策略
  • mc tag set
  • 锁定，包括保留和 legal hold 配置
  • 加密设置

• IAM 用户、组、策略以及策略到用户或组的映射（针对 LDAP 用户或组）的创建与删除

• 为可由本地 root 凭证验证的会话令牌创建 Security Token Service (STS) 凭证

• 访问密钥 的创建与删除 （不包括 root 用户拥有的访问密钥）

站点复制会在所有复制站点上，为所有新建和现有存储桶启用 存储桶版本控制。

你可以选择在对等站点之间复制 ILM 过期规则。 对于新的站点复制配置，可使用带有 --replicate-ilm-expiry 标志的 mc admin replicate add。 对于现有站点复制配置，则可根据需要使用 mc admin replicate update 配合 --enable-ilm-expiry-replication 或 --disable-ilm-expiry-replication 标志启用或禁用该行为。

哪些内容不会在站点之间复制

处于站点复制配置中的 MinIO 部署 不会 复制以下项目的创建或修改：

• 存储桶通知
• 生命周期管理（ILM）配置
• 站点配置设置

站点复制的初始流程

启用站点复制后，身份与访问管理（IAM）设置会按以下顺序同步：

在对等站点之间完成初始数据同步后，MinIO 会持续在所有站点之间复制并同步任何站点上新发生的 可复制数据。

站点自愈

站点复制配置中的任意 MinIO 部署，都可以从拥有该数据最新版本的对等站点重新同步受损的 可复制数据。

你可以使用 MINIO_SCANNER_SPEED 环境变量或 scanner speed 配置项， 调整 MinIO 在扫描器性能与读写操作之间的平衡方式。

同步复制与异步复制

对于给定的远端目标，MinIO 支持指定异步复制（默认）或同步复制。

在异步复制模式下，MinIO 会在将对象放入 复制队列 之前 完成发起的 PUT 操作。 因此，发起请求的客户端可能会在对象完成复制 之前 就看到 PUT 操作成功。 虽然这可能导致远端对象陈旧或缺失，但它降低了因复制负载而导致写入变慢的风险。

在同步复制模式下，MinIO 会在完成发起的 PUT 操作 之前 尝试复制对象。 无论复制尝试是否成功，MinIO 都会返回一个成功的 PUT 操作结果。 这降低了写入变慢的风险，但代价是远端位置可能出现陈旧或缺失对象。

MinIO 强烈建议使用默认的异步站点复制。 同步站点复制的性能高度依赖站点之间的延迟，较高的延迟可能导致更低的 PUT 性能和复制滞后。 要配置同步站点复制，请使用 mc admin replicate update 并带上 --mode 选项。

代理到其他站点

MinIO 对等站点可以将对象的 GET/HEAD 请求代理到其他对等站点，以检查该对象是否存在。 这样一来，即使某个站点正在自愈或落后于其他对等站点，仍然可以返回已持久化到其他站点的对象。

例如：

1. 客户端向 Site1 发起 GET("data/invoices/january.xls")
2. Site1 无法定位该对象
3. Site1 将请求代理到 Site2
4. Site2 返回请求对象的最新版本
5. Site1 将代理返回的对象响应给客户端

对于 不 包含唯一版本 ID 的 GET/HEAD 请求，代理请求会返回该对象在对等站点上的 最新 版本。 这可能导致取回对象的非当前版本，例如响应请求的对等站点本身也存在复制滞后时。

MinIO 不会代理 LIST、DELETE 和 PUT 操作。

前提条件

先备份集群设置

在配置站点复制之前，使用 mc admin cluster bucket export 和 mc admin cluster iam export 命令分别对存储桶元数据和 IAM 配置进行快照。 如果在配置站点复制过程中发生误配置，可以使用这些快照恢复存储桶/IAM 设置。

初始化时仅允许一个站点包含数据

在初始化时，只允许 一个 站点包含数据。 其他站点必须不包含任何存储桶和对象。

配置站点复制后，第一个部署上的所有数据都会复制到其他站点。

所有站点必须使用相同的 IDP

所有站点都必须使用相同的 Identity Provider。 站点复制支持内置的 MinIO IDP、OIDC 或 LDAP。

所有站点必须使用相同的 MinIO 服务端版本

所有站点都必须使用一致且匹配的 MinIO 服务端版本。 在 MinIO 服务端版本不匹配的站点之间配置复制，可能导致意外或不符合预期的复制行为。

还应确保用于配置复制的 mc 版本尽量与服务器版本保持接近。

访问同一个加密服务

如果通过 Key Management Service (KMS) 使用 SSE-S3 或 SSE-KMS 加密，则所有站点都必须能够访问同一个中心化 KMS 部署。

可以通过一个中心化 KES 服务器，或多个 KES 服务器（例如每个站点一个）连接到同一个受支持的中心化 key vault server 来实现。

复制要求启用版本控制

站点复制 要求 启用 存储桶版本控制，并会自动为所有新建存储桶启用该功能。 在站点复制部署中，不能禁用版本控制。

对于存储桶中被排除在版本控制之外的前缀，MinIO 无法复制其中的对象。

每个站点都应部署负载均衡器

指定该站点的负载均衡器、反向代理或类似网络控制平面组件的 URL 或 IP 地址。 请求会自动路由到部署中的各个节点。

MinIO 不建议为对等站点使用单个节点主机名。 这会形成单点故障：如果该节点离线，复制就会失败。

从存储桶复制切换到站点复制

存储桶复制 与多站点复制是互斥的。 不能在同一组部署上同时使用这两种复制方式。

如果此前已经配置了存储桶复制，而现在希望改用站点复制，则在初始化站点复制时，必须先删除包含数据的那个部署上的全部存储桶复制规则。 可在命令行中使用 mc replicate rm 删除存储桶复制规则。

设置站点复制时，只允许一个站点包含数据。 其他所有站点都必须为空。

教程

配置站点复制

以下步骤将为三个 分布式部署 创建一个新的站点复制配置。 其中一个站点包含 可复制数据。

这三个站点分别使用别名 minio1、minio2 和 minio3，且仅 minio1 包含数据。

1. 使用相同的 IDP，部署 三个或更多彼此独立的 MinIO 站点

   从空站点开始，或 确保最多只有一个站点包含任何 可复制数据。

2. 为每个站点配置别名

   指定该站点的负载均衡器、反向代理或类似网络控制平面组件的 URL 或 IP 地址。 请求会自动路由到部署中的各个节点。

   MinIO 不建议为对等站点使用单个节点主机名。 这会形成单点故障：如果该节点离线，复制就会失败。

   例如，对于三个 MinIO 站点，可以创建别名 minio1、minio2 和 minio3。

   使用 mc alias set 定义管理该站点连接的负载均衡器主机名或 IP。

   mc alias set minio1 https://minio1.example.com:9000 adminuser adminpassword
   mc alias set minio2 https://minio2.example.com:9000 adminuser adminpassword
   mc alias set minio3 https://minio3.example.com:9000 adminuser adminpassword

   或定义环境变量

   export MC_HOST_minio1=https://adminuser:[email protected]
   export MC_HOST_minio2=https://adminuser:[email protected]
   export MC_HOST_minio3=https://adminuser:[email protected]

3. 添加站点复制配置

   mc admin replicate add minio1 minio2 minio3

   如果所有站点均为空，则别名顺序无关紧要。 如果其中一个站点包含任何 可复制数据，则必须将其列在第一位。

   最多只能有一个站点包含可复制数据。

4. 查询站点复制配置进行验证

   mc admin replicate info minio1

   可以使用站点复制配置中任意对等站点的别名。

5. 查询站点复制状态，确认初始数据已复制到所有对等站点。

   mc admin replicate status minio1

   可以使用站点复制配置中任意对等站点的别名。 输出应表明所有 可复制数据 均已同步。

   输出可能类似如下：

   Bucket replication status:
   ●  1/1 Buckets in sync
   
   Policy replication status:
   ●  5/5 Policies in sync
   
   User replication status:
   No Users present
   
   Group replication status:
   No Groups present

   有关检查站点复制的更多信息，请参阅 站点复制状态教程。

扩展站点复制

可以向现有站点复制配置中添加更多站点。

新站点必须满足以下要求：

• 站点已完成部署，并可通过主机名或 IP 访问
• 与配置中的其他站点共享相同的 IDP 配置
• 使用与其他已配置站点相同的 root 用户凭证
• 不包含任何存储桶或对象数据

1. 按照上述要求部署新的 MinIO 对等站点

2. 为新站点配置别名

   指定该站点的负载均衡器、反向代理或类似网络控制平面组件的 URL 或 IP 地址。 请求会自动路由到部署中的各个节点。

   MinIO 不建议为对等站点使用单个节点主机名。 这会形成单点故障：如果该节点离线，复制就会失败。

   要检查现有别名，请使用 mc alias list。

   使用 mc alias set 定义管理新站点连接的负载均衡器主机名或 IP。

   mc alias set minio4 https://minio4.example.com:9000 adminuser adminpassword

   或定义环境变量

   export MC_HOST_minio4=https://adminuser:[email protected]

3. 添加站点复制配置

   使用 mc admin replicate add 命令，将新的对等站点加入站点复制配置中。 先指定 所有 现有对等站点的别名，再指定要添加的新站点别名。

   例如，以下命令将新的对等站点 minio4 添加到现有站点复制配置中，该配置已包含 minio1、minio2 和 minio3 三个站点。

   mc admin replicate add minio1 minio2 minio3 minio4

   说明

   说明

   如果任一站点不可达或已永久丢失，则在使用新站点进行扩展前，必须先使用 mc admin replicate rm 移除不可达站点。

4. 查询站点复制配置进行验证

   mc admin replicate info minio1

修改站点的端点

如果某个对等站点变更了主机名，可以修改复制配置以反映新的主机名。

1. 使用 mc admin replicate info 获取站点的 Deployment ID

   mc admin replicate info <ALIAS>

2. 使用 mc admin replicate update 更新站点的端点

   mc admin replicate update ALIAS --deployment-id [DEPLOYMENT-ID] --endpoint [NEW-ENDPOINT]

   将 [DEPLOYMENT-ID] 替换为要更新站点的 deployment ID。

   将 [NEW-ENDPOINT] 替换为该站点的新端点。

   指定该站点的负载均衡器、反向代理或类似网络控制平面组件的 URL 或 IP 地址。 请求会自动路由到部署中的各个节点。

   MinIO 不建议为对等站点使用单个节点主机名。 这会形成单点故障：如果该节点离线，复制就会失败。

从复制中移除站点

可以随时将某个站点从复制中移除。 后续也可以重新添加该站点，但必须先彻底清除该站点上的存储桶和对象数据。

使用 mc admin replicate rm：

mc admin replicate rm ALIAS PEER_TO_REMOVE --force

• 将 ALIAS 替换为复制配置中任意对等站点的 alias。
• 将 PEER_TO_REMOVE 替换为要移除的对等站点别名。

站点复制配置中的所有健康对等站点都会自动更新，以移除指定的对等站点。

MinIO 要求使用 --force 标志，才能将该对等站点从站点复制配置中移除。

查看复制状态

MinIO 提供跨站点的用户、组、策略或存储桶复制信息。

汇总信息包括各类别中 Synced 和 Failed 项目的数量。

使用 mc admin replicate status：

mc admin replicate status <ALIAS> --<flag> <value>

例如：

• mc admin replicate status minio3 --bucket images

  显示 minio3 站点上 images 存储桶的复制状态。

  输出类似如下：

  ●  Bucket config replication summary for: images
  
  Bucket          | MINIO2          | MINIO3          | MINIO4
  Tags            |                 |                 |
  Policy          |                 |                 |
  Quota           |                 |                 |
  Retention       |                 |                 |
  Encryption      |                 |                 |
  Replication     | ✔               | ✔               | ✔

• mc admin replicate status minio3 --all

  显示 minio3 所属全部复制站点的复制状态摘要。

  输出类似如下：

  Bucket replication status:
  ●  1/1 Buckets in sync
  
  Policy replication status:
  ●  5/5 Policies in sync
  
  User replication status:
  ●  1/1 Users in sync
  
  Group replication status:
  ●  0/2 Groups in sync
  
  Group           | MINIO2          | MINIO3          | MINIO4
  ittechs         | ✗  in-sync      |                 | ✗  in-sync
  managers        | ✗  in-sync      |                 | ✗  in-sync

2 - IAM 升级与恢复

Server #191 与 #192 持久化删除修订及父身份撤销边界，防止延迟的站点事件恢复已撤销身份和旧授权。 所有参与服务器必须协调升级，包括没有配置站点复制、但共享 IAM 后端的节点。不支持共享后端的新旧节点混用，也不支持滚动降级。

发布状态： 修复已进入九月源码基线，尚未进入 Server 20260903。 本页为包含这些修复的构建准备操作流程。隔离升级与恢复的观察结果、剩余恢复检查由 #200 跟踪，参阅验证范围；文档发布不代表生产升级验收通过。

准备维护窗口

列出所有节点、站点、共享 IAM 后端、离线节点和备份。记录原版本与候选版本的 Server SHA、二进制校验值或镜像摘要、 部署配置、root 凭据来源、外部身份提供方设置及 KMS 依赖。按组件版本表选择维护组件组合； 升级独立 Console 不会替换 Server 内嵌的 Console。

使用已安全配置的 mcli 别名。以下命令只读取状态，应逐站点执行并私下保存输出，使用实际别名替换 site-a。 共享验收材料中不得包含凭据，也不要开启 HTTP 调试日志。

umask 077
mkdir -p iam-upgrade-evidence
mcli --version > iam-upgrade-evidence/client.txt
mcli --json admin info site-a > iam-upgrade-evidence/site-a-info.jsonl
mcli --json admin replicate status site-a > iam-upgrade-evidence/site-a-replication.jsonl
mcli ready site-a

复制状态命令适用于已配置站点复制的部署。就绪检查本身不能证明 IAM 正确。 逐节点检查时钟同步，例如在由 chrony 管理的 Linux 主机执行 chronyc tracking，并检查 IAM 加载和复制错误。 升级前先解决时钟漂移：修订排序使用时间戳，受信节点发来的未来时间戳删除可能使后续较旧更新被拒绝，直到使用更新的修订。

暂停 IAM 管理、凭据签发及相关自动化。隔离状态不明的离线节点，防止旧二进制自动重启，为协调停机排空应用流量。 准备已撤销身份、曾重建的父身份及需重新签发凭据的清单。用户记录缺失不能帮助系统重建已经丢失的删除历史。

停止条件： 任何参与节点、后端、备份、必要密钥、未知离线节点或回滚流程尚未核实。 不要为了查看旧快照内容，就把它接回正在运行的复制集群。

升级前按密码策略迁移指南检查所有原有 Deny admin:CreateUser： 若其意图包含禁止修改自身密码，在保留原 scope 与条件的同一 Deny 中加入 admin:ChangeMyPassword，并贯穿回滚窗口。 当前 main 的分段上传默认仍为 legacy；普通升级不要求切换为严格模式。只有主动启用严格模式时才执行 分段上传预检与排空流程。

保存完整恢复点

最终备份前，停止共享各后端的所有 SILO 进程。systemd 部署使用实际服务单元，并逐节点确认已停止； 由 Operator 管理的部署应使用经过演练的维护流程，阻止控制器自动重启旧 Pod。

SILO_UNIT='silo.service' # 替换为实际安装的服务单元名
sudo systemctl stop "$SILO_UNIT"
systemctl is-active "$SILO_UNIT" # 预期 inactive；此时非零退出码正常

etcd 示例使用部署已有的 TLS 认证配置，以及适配该版本的 etcdctl/etcdutl，参阅 etcd 恢复指南。这里只执行备份和校验，不恢复运行中的集群：

etcdctl --endpoints="$ETCD_ENDPOINT" snapshot save iam-upgrade-evidence/etcd.db
etcdutl snapshot status iam-upgrade-evidence/etcd.db --write-out=json

在线 mcli admin cluster iam export 导出可用的活跃记录，但遗漏删除历史，不能作为此次升级的恢复点。 快照校验值只证明文件身份，不能证明恢复与撤销检查有效。分别记录备份时间、范围、校验值及克隆恢复成功的证据。

升级与核验

1. 替换每个共享后端上所有已停止节点的二进制或镜像，只启动已升级节点。 保持旧节点和未知节点隔离，完成所有站点的协调升级后，才能依赖新的撤销保证。

2. 重新执行 mcli --json admin info site-a、mcli ready site-a 和 mcli --json admin replicate status site-a，确认每个进程实际版本、IAM 加载及站点通信正常。 写就绪检查应覆盖每一个进程的 endpoint，不能只检查负载均衡入口。对分布式节点，逐进程核对本次启动日志中的 IAM load(startup) finished.；配置站点复制时，还应确认 Cluster replication initialized。 /minio/health/ready 及 root 请求成功可能早于这些后台初始化，签发 STS 前应等待两者完成。 这些启动消息仍不能替代下面的凭据检查。

3. 检查 IAM 修订数量、修复失败和最近成功修复时间等指标。错误计数没有增加，不能单独证明凭据已撤销。 后台修复定期执行，其间隔不是收敛时间承诺。

4. 在每个站点，使用专用验证别名读取同一个已存在对象。旧撤销凭据必须被授权检查拒绝；刻意重新签发且具备所需权限的凭据必须成功。 超时、5xx 或对象不存在均不能视为有效验证。记录错误码、站点和凭据标签，不记录密钥。

   mcli --json stat --no-list revoked-canary/upgrade-canary/probe
   mcli --json stat --no-list reissued-canary/upgrade-canary/probe

5. 为重建的父身份重新签发服务账户和 STS 凭据。旧凭据缺少父身份撤销后要求的签名边界； 没有保留撤销历史的父身份维持既有凭据行为。只授予当前明确需要的权限。

6. 对仍持有旧记录的站点显式调和升级前已知的删除。使用已确认的状态重建陈旧离线节点，再接回集群。 节点重启、复制追平后，重复凭据检查。

管理员覆盖内置策略后再删除该覆盖，会留下持久化删除记录；重新加载不会再自动创建该策略。 如果需要恢复，应显式执行策略创建。离线期间对旧式组成员关系的普通删除，仍不在父身份持久化删除保证的覆盖范围内。

只有版本身份、后端恢复、IAM 加载、复制和两类凭据检查都通过后，才恢复访问。 如果陈旧凭据仍能成功，保持相关站点隔离并调查；反复重启直到健康检查变绿不能解决授权问题。

错误与可观测性

撤销记录持久化后，依赖清理仍可能失败，返回带 IAM revocation committed; cleanup failed 的 HTTP 500。 这不意味着撤销已回滚。保持 IAM 写入暂停，检查对应身份与日志后重试清理；不要在同名身份已经重建后盲目重复删除。 该路径会通知本地兄弟节点重载，但可能跳过即时跨站钩子，后续站点调和仍需验证。 STS 在无法读取父身份撤销边界时 fail closed，可返回 STSInternalError，不是成功签发或已证实的凭据无效。

从每个进程的 /minio/metrics/v3/cluster/iam 收集：

这些是进程指标，不能直接求和当作唯一撤销数。三个 heal_* 指标只在启用站点复制并持有 leader lease 的节点推进； 未启用站点复制、仅共享后端的部署不会运行该调和，不应把零值当作故障。撤销墓碑没有 TTL 或自动压缩，需计入持久容量与启动读取成本。 初次调和还可能为缺少修订的记录补写时间戳，造成写入突增。间隔与指标均不提供收敛 SLA。

已删除 access key 的验证请求通常应返回 403 InvalidAccessKeyId；其他撤销方式应按其预期授权错误判断，不能强制所有场景同一码。 5xx、超时和对象不存在都不能证明撤销生效。live-record export/import 不保存删除历史；仅靠它恢复无法维持过去撤销的保证。 完整排序与限制见 IAM 设计。

回滚与恢复

先停止并隔离受影响站点，记录选定恢复点之后的所有 IAM 变更和撤销。 将完整且兼容的后端恢复到隔离环境，配套恢复配置、密钥和二进制；不要让旧软件直接启动在已被新版修改的后端上。

较旧备份可能恢复备份后已撤销的凭据。重新开放恢复后的系统之前，重放撤销清单，或轮换受影响身份的密钥。 如果变更记录不完整，在受影响范围调和完毕前保持隔离。不要删除墓碑、截断修订历史或只导入活跃记录来使旧版启动。

恢复后，重新逐进程检查 IAM 和站点复制初始化，再签发凭据。临时会话应与普通用户、服务账户分别验证。 启动完成后重新签发所需 STS 凭据，并检查每一个预期访问的站点；旧会话在某个站点失败，不能证明其父身份已在所有站点安全撤销。

调和已知恢复组

一种有明确边界的恢复策略是：保持退役父身份禁用，删除其清单内的服务账户密钥，解除已撤销授权，并使用不同身份名称签发替代凭据。 按经过核对的变更清单选择用户、密钥和策略；所有已知站点均须在隔离恢复组内在线，陈旧或状态不明的节点保持隔离。 对象存储与 etcd 隔离演练均已在通过下面的凭据检查后验证这一策略；实际恢复组仍须通过同样检查才能开放访问。

以下命令使用已安全配置的恢复别名，将大写名称替换为清单中核实的条目。 创建用户时会提示输入密钥，创建服务账户会输出凭据；这些凭据应进入指定密钥存储，不应写入演练日志。

mcli admin user disable recovery-a RETIRED_USER
mcli admin user svcacct rm recovery-a RETIRED_SERVICE_KEY
mcli admin policy detach recovery-a RETIRED_POLICY --user RETIRED_MAPPING_USER
mcli admin user add recovery-a RECOVERED_USER
mcli admin policy attach recovery-a CURRENT_POLICY --user RECOVERED_USER
mcli admin user svcacct add recovery-a RECOVERED_USER

启动完成后，通过应用正常的认证流程签发专用 STS 验证凭据，并检查每个新会话在所有预期进程上的访问。 签发或跨站点读取失败时保持恢复组隔离，保留失败记录并调查；可在计划维护窗口内重新签发验证会话，但不能仅凭等待时间到期就开放访问。 逐进程检查退役用户、清单内服务密钥、已撤销授权，以及退役父身份在恢复前和恢复后签发的会话， 均应被拒绝；替代用户、服务账户和新签发的 STS 应可用。将调和后的备份完整恢复，再重复这些检查。 任一检查失败就保持隔离；该策略不允许重新接入陈旧旧节点，也不允许在旧软件上重新启用退役父身份。

必须保留的演练记录

对每一种支持的后端，使用隔离的新旧版本、多进程站点，记录精确二进制身份和实际备份、恢复命令。 覆盖节点断连期间删除、旧事件延迟重放、同名身份有意重建与凭据重签；重启、完整恢复后重复验证， 并测试回滚到删除发生之前的恢复点。调和后，旧凭据应保持拒绝，预期的新凭据应可用。

#192 中的源码回归证据支持协议实现；本演练补充部署拓扑、备份完整性、重启与操作恢复证据。 将脱敏观察结果关联到 #200，最终制品验收和真实生产升级分别记录。

验证范围

2026-09-16 在隔离环境中，将 Server 20260903（9b11dc9469e6）协调升级到构建 70c7ec4a9fbf； 后者的运行时代码与基线 40220bd836cb 相同，仅变更日志不同。对象存储与 etcd 3.6.13 两类后端均通过演练。 每次使用三个站点，每站点两个 Server 进程、四块磁盘；etcd 演练每站点使用一个独立 etcd 进程。

协调升级后，未撤销的用户、服务账户和 STS 凭据继续可用。一个站点停机期间执行的撤销，在该站点返回后收敛。 冷启动及撤销后完整备份恢复后，旧凭据和已解除的授权仍被拒绝，明确重建并重新签发的凭据可以访问。 同键重建的服务账户保留新密钥、拒绝旧密钥。拒绝检查使用对已知对象的签名读取，并以 root 成功读取作为对照， 没有把任意请求失败当作撤销生效。

将升级前备份与旧二进制一起恢复后，备份后已撤销的凭据重新可用，证实了上述回滚风险。 后续演练执行上述有明确边界的调和策略，再使用配套旧二进制完整恢复调和后的备份：

对象存储实验也曾在启动检查通过后观察到暂时的 STS 写入和跨站点认证失败；仅使用 Server 20260903 的对照也在冷启动后遇到 STS 写入失败， 不能据此判断是新构建引入的回归，具体原因尚未隔离。在未改变二进制或配置的同一现场，稍后新签发的 STS 通过了检查， 后续完整恢复演练将这些端到端检查作为继续条件。启动消息或固定等待时间都不够；恢复前 STS 会话的持续可用性不在本次接受的恢复范围内。

实验环境为共享时钟、没有外部节点的单个隔离 Linux ARM64 容器，etcd 使用单成员后端。 尚未验证生产存储快照、etcd 高可用集群、外部身份提供方或 KMS、时钟偏差。 这些部署相关检查、启动观察结果及精确制品身份仍由 #200 跟踪。

3 - 历史复制状态检查

升级到包含九月复制修复的版本可以防止新错误， 但不会改写旧 Content-Encoding、重建丢失的标签，也不能证明历史删除标记清除任务已经收敛。 #201 跟踪存量检查与恢复准备；此次评审尚未确认任何受影响的生产部署。

逐版本只读清单

优先检查 #194 涉及的、被存入 Content-Encoding 的传输 token aws-chunked。 权威站点和副本站点都应检查所有版本。只检查当前对象会漏掉历史版本，普通 COPY 也可能保留来源的错误元数据。

下载并检查只读清单脚本。它使用 Python 3 与 boto3， 只调用 ListObjectVersions 和精确版本的 HeadObject，输出 JSON Lines。 它不读取正文、不写对象、不编辑存储文件，也不收集凭据。 使用安全配置的 AWS profile，为目标范围授予 s3:ListBucketVersions 与 s3:GetObjectVersion 只读权限； 该 profile 与 mcli 别名独立。需要检查 Object Lock 的部署还应配置相应只读权限。

下载脚本及其SHA-256 文件，先验证再执行。此版本摘要为 ccc9d035809b2b41157b4a3f1d35a21108ae4b3af2836e99416a1d2eec1efef2。

curl --fail --location --output replica-metadata-audit.py https://silo.pgsty.com/tools/replica-metadata-audit.py
curl --fail --location --output replica-metadata-audit.py.sha256 https://silo.pgsty.com/tools/replica-metadata-audit.py.sha256
shasum -a 256 --check replica-metadata-audit.py.sha256

umask 077
python3 -m venv audit-venv
audit-venv/bin/python -m pip install boto3
audit-venv/bin/python -m pip freeze > audit-requirements.txt
audit-venv/bin/python replica-metadata-audit.py \
  --profile silo-readonly --endpoint-url https://silo.example.com \
  --site site-a --bucket example-bucket --prefix 'review-scope/' \
  > site-a-inventory.jsonl

随清单保存脚本修订或校验值、客户端依赖版本、Server 身份、桶配置、所选前缀和起止时间。 空前缀覆盖整个桶；对每个相关桶和站点分别执行。每个数据版本需要一次 HEAD，应先从小范围前缀开始，根据部署负载安排扫描。 列表不是原子快照，任何后续修复前应暂停相关变更，或比较重复清单。

最后一条 summary 必须包含 listing_complete: true。退出码 0 表示扫描完成且没有待核查记录， 不表示没有发现错误头部；2 表示存在待核查记录，1 表示列表失败。 中断或其他异常导致没有完整 summary 时，该清单均不完整。

检查按 token 匹配：gzip, aws-chunked 是候选，my-aws-chunked 不是该传输 token。 混合编码保留其他 token 的顺序，大小写变体及重复 token 留给人工核查。 缺少密钥的 SSE-C 版本可能 HEAD 失败，并保持待核查；本工具不接受 SSE-C 密钥。 这些记录应使用批准的、支持密钥的只读流程检查，密钥不能写入报告或命令历史。

清单与私密证据

脚本保存精确 bucket/key/version、列表时间/ETag/大小、原始及建议 Content-Encoding、元数据指纹，以及可读的复制、加密和 Object Lock 字段。 不导出用户元数据值和 KMS 密钥标识。对象名和版本 ID 仍可能敏感，完整清单私下保管，共享报告使用稳定的替代标识。

{"site":"site-a","bucket":"redacted-bucket","key":"redacted-key-001","version_id":"redacted-version-002","classification":"confirmed-header","content_encoding":"gzip, aws-chunked","proposed_content_encoding":"gzip"}

这是格式示例，并非已发现的生产对象。批准任何写入前，补齐私密记录中的可信来源和版本关系、完整普通/用户元数据、 精确版本标签、保留期/法律保留、SSE 模式和密钥可用性、独立原始字节校验值及复制状态。 缺失字段应视为未知，直到获得相应的授权读取结果。指纹可以检测差异，但不能用于恢复被省略的元数据。

读取原始字节时禁用客户端 Content-Encoding 自动解压，与可信来源版本或独立的已知校验值比较。 真正的 gzip 字节应原样保留，不重新压缩。ETag 不是通用内容校验值，尤其对于分片或加密对象。 来源缺失、受污染或无法信任时，该对象继续保持未解决。

选择并演练修复

1. 先确定权威精确版本，再确认副本。多向复制须比较所有参与来源。 仍受污染的来源可能使后续 heal/resync 再次选择元数据复制；这不等于已经证明存在持续重试热循环。
2. 形成逐版本的前后变更清单，只移除已确认的传输 token，保留原始字节、实际编码、用户元数据、标签、Object Lock 和加密要求。
3. 在版本控制、Object Lock、SSE 和复制配置相同的隔离克隆中演练所选受支持操作。 普通自 COPY 可能创建新版本、改变修改时间和复制排序，不能当作通用的原地元数据修复 API。 必须创建替代版本时，明确版本身份变化和调用方影响。没有受支持的安全操作时，保持未解决，不编辑 xl.meta 或内部磁盘文件。 逐一核实目标站点的加密配置和密钥可用性；来源已加密，不能单独证明副本也以加密方式存储。 每次重启后，在所有服务进程及复制目标上使用指定的写入/读取探针，再执行 COPY 或回退。 健康检查和读取成功时，写入法定人数仍可能尚未就绪。
4. 真正写入前，在选定的写入协调流程中重新核对精确版本、ETag、大小、元数据指纹、时间戳、标签和锁状态。 先读后写本身不能消除竞争，元数据改变也可能保持 ETag 不变。冲突项跳过并重新检查。
5. 在克隆中核对精确版本 HEAD、原始字节校验值不变、所有保留元数据/锁及副本最终收敛， 并演练重启、旧事件延迟到达和具体回滚操作。本地 COPY 返回成功并不足够。 除当前对象读取外，还要检查每个站点的精确版本列表和来源复制状态。 回退后，所有预期副本都应不再列出替代版本；当前对象正确时，其他站点仍可能有待清除版本。

保留不可变清单、完整私密元数据备份及所选操作经过测试的回滚步骤。 如果操作产生了新版本，回滚必须考虑该版本及当前版本关系；再 COPY 一次不能证明回滚。 回退二进制可能重新打开原来的错误入口，也不会自动撤销先前的元数据写入。 写入失败或结果不确定时，先停止并重新检查精确版本，再决定是否重试。 自动重试 COPY 可能再创建一个版本，重复请求不能代替确认前一次操作的实际结果。

标签与删除标记清除

• 标签丢失或复活： 比较各站点精确版本的标签及可用的修订、审计证据。空标签可能是有意删除，不能根据缺失重建历史。 计划新标签操作前需要权威清单；新的标签操作本身会推进修订。
• 删除标记清除： 将预期版本、桶、键、修改时间与 purge/MRF 状态、复制错误一并记录。 保留的标记可能符合预期，或正在等待出站复制；仅凭 405 响应不能证明找到了预期标记，也不能证明已清除。
• 历史 IAM 撤销： 使用独立的 IAM 恢复流程。

验证范围

2026-09-16 使用只读账户，对真实 Server 20260903 存储、停机快照升级到构建 70c7ec4a9fbf（运行时源码基线 40220bd836cb）的克隆，以及重启后的克隆执行检查。 三次清单均为 21 条版本或标记记录：6 条确认存在传输编码、2 条编码待核查、12 条头部不受影响、1 条删除标记。 夹具覆盖非当前版本、null version、特殊对象键、gzip 原始字节，以及带保留期和法律保留的 SSE-S3 对象。 升级保留了原始字节、标签和已核实的锁状态；旧编码头也如预期保留，未被自动修复。

另一次克隆演练通过明确替换元数据的 COPY 修正了一个未锁定当前对象的编码，保留原始 gzip 字节和标签， 但产生了新版本，原版本的错误头部仍然存在。仅删除该新建、未锁定版本后，原当前版本恢复。 该结果证明版本及回滚的区别，并非通用原地修复。最初的环境为 Linux ARM64 单进程、单盘与静态测试 KMS 密钥。

后续演练使用三个站点，每站点两个 Server 进程、四块盘。将 Server 20260903 的停机备份恢复到上述候选构建， 明确配置各站点的 SSE-S3 桶默认加密，使用静态实验 KMS 密钥。 一个站点离线期间，为两个未锁定 gzip 对象创建纠正后的替代版本；该站点返回后， 六个进程的新版 ID、原始 gzip 字节、元数据和标签一致，来源报告复制状态 COMPLETED。 随后对历史版本的标签更新没有改变替代版本的标签。 未参与改写的对照对象始终保留 SSE-S3、GOVERNANCE 保留期和法律保留。

通过的演练在 COPY 和回退之前，均对每个进程执行了实际签名写入/读取探针。 早期失败记录仍保留：健康检查和读取成功时，写入曾返回 SlowDownWrite； 在重启后立即发起回退的一次尝试中，180 秒后仍能在副本站点列表中看到替代版本。 该观察不能证明复制永久失败，那次尝试的更长恢复路径未测试。 通过的流程要求实际写就绪，并逐版本确认收敛。

多站点实验运行于同一个隔离 Linux ARM64 容器，共享时钟。 尚未验证 SSE-C、外部 KMS、改写锁定版本、所有延迟事件排列或通用的历史版本原地修复。 详细结果和剩余限制由 #201 跟踪。

清单工具用于准备，不执行修复。具体 Object Lock/SSE/复制配置的验证仍由 #201 跟踪。生产清单扫描与写入应针对选定部署和经评审的变更清单分别记录。

对 confirmed-header 行，proposed_content_encoding: null 表示移除整个 Content-Encoding 字段，不是写入空字符串。其它分类的 null 不代表修复建议。设计背景见副本元数据规范化。