设计归档

• 1: SILO、KES 与 OpenBao：密钥归属和恢复
• 2: 写死 TLS 参数与握手兼容性
• 3: 桶配置复制：来源时间、删除与确定性收敛
• 4: SigV4 签名头覆盖边界：拒绝未签名的 x-amz-* 请求头
• 5: Object Lock 复制排序
• 6: SSE-C 副本完整性
• 7: 持久化 IAM 撤销
• 8: 多池对象一致性
• 9: 联邦 CopyObject：保持目标对象契约
• 10: 复制可靠性：删除完成、MRF 可见性与 resync 取消
• 11: FULL_OBJECT 校验和复制：在初始化上传时保留类型
• 12: Alias 区域：小配置改动的兼容性边界
• 13: IAM 策略重载：锁粒度、请求取消与超时预算隔离
• 14: LDAP 长 DN：恢复登录可用性并守住 IAM 撤销安全边界
• 15: 复制标签排序：修订时间戳、墓碑与复活
• 16: SILO Server 20260903 发布前复审
• 17: 多池覆盖亲和：为何最终没有采纳 #245
• 18: 副本元数据归一化：可信复制不得重新注入什么
• 19: 为 SILO 提供多语言支持
• 20: Multipart 提交失败可能让上传卡死
• 21: 局部视图不能把存在的对象报成不存在
• 22: 两阶段原生恢复
• 23: Console 的桶配额：列表显示与数值校验
• 24: Heal 演练不能删除数据
• 25: 大型单池集群的锁域
• 26: 多池生命周期过期：按整个对象决策
• 27: 恢复副本：过期的是副本，不是对象
• 28: 生命周期"删除全部版本"只能作用于一个 key
• 29: Peer 重载后的审计 Webhook
• 30: 失败写入与幽灵空前缀
• 31: 存储池迁移完整性审查：#261、#263 与 #265
• 32: 请求头截止时间：绝对头部上限与滚动的正文空闲超时
• 33: 条件 DELETE：一个条件对应一个逻辑对象
• 34: 只预览文本，绝不执行：SILO Console 文本预览设计
• 35: 数据库通知统一连接串：#53 的兼容性边界
• 36: 混合 EC 布局与迁移列表
• 37: 多池删除：失败时保住最新副本
• 38: Go 1.27 TLS 默认值与 OIDC Discovery 故障诊断
• 39: Tier free version 是内部清理记录
• 40: 鉴权前不做 I/O，Header 不授予权限
• 41: ILM 过期与存储池迁移顺序
• 42: 一个端点，两种权限：彻底分离用户与组状态
• 43: IAM Admin API 授权边界修复
• 44: 配置环境文件不是 Shell 脚本
• 45: 两把 SSE-C 密钥，一份 CopyObject 响应
• 46: ListMultipartUploads 行为契约与设计权衡
• 47: 为什么 CompleteMultipartUpload 必须返回 ChecksumType：PR #57 评审记录
• 48: 总量未知时，进度条应该说什么
• 49: 列举不能丢掉仍有仲裁的 null 版本
• 50: ListObjects 快捷路径不能把不存在的桶伪装成空桶
• 51: 只读 Checksum 审计与可靠的 CLI 输出契约
• 52: 可选校验和，强制失败：修复 UploadPart 与 UploadPartCopy 兼容性
• 53: BadDigest、InvalidRequest 与 CompleteMultipartUpload 校验和契约
• 54: 旧版元数据与扫描响应复用时的残留字段修复
• 55: LIST 漏项修复：仅对存疑对象补读确认并收敛锁等待开销
• 56: 对象锁保留期越权与版本覆写漏洞修复设计（SN-2026-015 / SN-2026-016）

1 - SILO、KES 与 OpenBao：密钥归属和恢复

SILO 通过 PGSTY KES（MINIO_KMS_KES_ENDPOINT）接入外部密钥管理系统。当前最新版本为 KES 20261026（使用 Go 1.27.3 构建并更新云服务依赖，保持本文的 API、配置与密钥格式不变）；此前的 PGSTY KES 20261018（源码 2f7e741db905）完成了将 AWS Secrets Manager 后端迁移至 AWS SDK for Go v2 的主体改造。

三个服务的职责边界

+-------------+       mTLS (KES API)       +-------------+    AppRole / TLS    +--------------------+
| SILO Server | -------------------------> |  PGSTY KES  | ------------------> | OpenBao (KV v1/v2) |
+-------------+  MINIO_KMS_KES_ENDPOINT    +-------------+   keystore.vault    +--------------------+

MINIO_KMS_KES_ENDPOINT 必须指向 KES 服务端点，因为 OpenBao 本身不实现 KES 密钥封装 API。KES 通过内置的 keystore.vault 配置访问 OpenBao（针对 OpenBao KV v2 挂载点需设置 version: v2）。同一个 kes 可执行文件同时提供服务端与管理 CLI，多个无状态 KES 实例可共享同一个外部 OpenBao 密钥存储。

SILO 将加密后的数据密钥（DEK）随对象元数据保存在存储桶中。对象存储桶本身不包含外部根密钥备份；一旦丢失 OpenBao 中的根密钥，即便磁盘上的所有对象纠删分片完好无损，已加密对象也将无法解密恢复。

对接 OpenBao KV v2 的最小 KES 配置示例：

address: 0.0.0.0:7373

admin:
  identity: ${KES_ADMIN_IDENTITY}

tls:
  key:  /etc/kes/kes-server.key
  cert: /etc/kes/kes-server.crt
  ca:   /etc/kes/client-ca.crt

policy:
  silo-server:
    allow:
      - /v1/key/create/*
      - /v1/key/generate/*
      - /v1/key/decrypt/*
      - /v1/key/describe/*
      - /v1/key/list/*
      - /v1/status
      - /v1/version
    identities:
      - ${SILO_CLIENT_CERT_IDENTITY}

keystore:
  vault:
    endpoint: https://openbao.internal:8200
    engine:   secret
    version:  v2
    prefix:   kes
    approle:
      engine: approle
      id:     ${OPENBAO_ROLE_ID}
      secret: ${OPENBAO_SECRET_ID}
      retry:  15s
    tls:
      ca: /etc/kes/openbao-ca.crt

针对名为 secret、前缀为 kes 的 KV v2 挂载点，KES AppRole 所需的最小 OpenBao ACL 策略：

path "secret/data/kes/*" {
  capabilities = ["create", "read", "delete"]
}

path "secret/metadata/kes/*" {
  capabilities = ["list", "read", "delete"]
}

身份认证与故障行为

部署时应分别配置 SILO → KES 与 KES → OpenBao 两段链路的 TLS 信任。KES 依据客户端证书的 SHA-256 摘要（kes identity of <cert>）授权 SILO 访问指定密钥名；OpenBao 则通过 AppRole 授权 KES 后端身份。

请妥善保管持久化密钥库备份、KES 配置、TLS 信任根、身份与策略配置以及 OpenBao 解封恢复材料，并在演练中验证恢复后的密钥名称与密钥值完全一致。KES 开发模式（内存模式）仅将密钥保存在进程内存中，严禁用于持久化加密存储。

SDK 迁移与兼容性

PGSTY KES 20261018（2f7e741db905）将 keystore/aws/secretsmanager 从已归档的 github.com/aws/aws-sdk-go（v1）迁移至模块化的 AWS SDK for Go v2（github.com/aws/aws-sdk-go-v2、config、credentials、service/secretsmanager 与 github.com/aws/smithy-go）。

迁移保持以下兼容性不变量：

• 完整保留既有密钥存储格式与 YAML 配置字段。
• KES YAML 中显式配置的凭据继续优先；留空时回退至 SDK 标准凭据链。
• KES 不会隐式加载 ~/.aws/config，且配置文件中的 endpoint 始终优先于 SDK 端点环境变量覆盖。
• AWS Secrets Manager 的 ResourceNotFoundException、ResourceExistsException 与参数错误保持与原内部错误（errKeyNotFound、errKeyExists）相同的映射语义。

兼容性验收矩阵（testing/kms-compat.sh）覆盖了 OpenBao KV v2 与 Moto Secrets Manager 的 SDK-v1 -> SDK-v2 -> 回滚 全流程切换，每次切换均重启 SILO 以清空内存密钥缓存并验证加密对象回读。

升级与恢复检查

1. 记录当前 SILO 与 KES 版本、主密钥名称、后端端点及客户端证书 Identity，并在确认恢复成功前保留既有密钥与后端备份。
2. 变更前读取一个既有加密对象并记录其预期摘要（Digest）；基于同一持久化后端将 KES 升级为 PGSTY KES 20261026 二进制。
3. 重启 KES 与 SILO（清空热缓存），读取旧加密对象、写入新加密对象并校验两者摘要，验证生产环境实际使用的 TLS 身份与访问策略。
4. 在隔离演练环境中，基于同一密钥存储恢复旧版 KES 二进制，重启两项服务并重复验证加密对象回读。

分步配置与运维命令详见配置 KES 与 OpenBao 服务端加密指南、KES 参考配置以及 KES 兼容性测试脚本。

2 - 写死 TLS 参数与握手兼容性

Go TLS 默认值修复 48e184652 随 Server 20260916 发布后，issue #154 的报告人在该版本复测，OIDC discovery 仍然报同一条 connection reset by peer。与此同时，上游 Go 社区的同类 issue 将完全一致的症状定位到检查 signature_algorithms_cert 扩展并发送重置的 TLS 中间设备（见上游的同款案例）。本文在《Go 1.27 TLS 默认值与 OIDC Discovery 故障形态》的基础上，补充发布后的复测与机制分析、20260916 修复的覆盖边界、受影响部署的可选解法，以及由此确立的发布与沟通门禁。

先把本质说清楚

TLS 连接的第一条消息是 ClientHello，客户端在其中列出自己支持的算法。许多企业网络会在链路中部署中间设备（WAF、TLS 检查防火墙、负载均衡器）解析这条消息。部分设备在遇到不认识的算法编号时会直接重置连接。

Go 1.27 在这条消息中新增了三个编号——ML-DSA 后量子签名方案——共计 12 个字节。使用 Go 1.27 编译后，SILO 发出的 TLS 1.3 ClientHello 比 Go 1.26 多出这 12 个字节。报告人 IdP 前方的中间设备拒绝了该报文并返回 TCP RST。同一容器内的 curl 之所以正常，是因为 curl 使用 OpenSSL，不会发送这些编号。

Go 针对混合密钥交换提供了兼容开关 GODEBUG=tlsmlkem=0，但该开关有一个生效前提：仅当应用未显式指定曲线清单（Config.CurvePreferences == nil）时生效。 SILO 此前保留了一份从上游继承的显式曲线清单，其中恰好包含一个后量子条目，导致 GODEBUG=tlsmlkem=0 失效。48e184652 修复移除了这些硬编码曲线清单，使该开关恢复生效。

需要注意两者的区别：GODEBUG=tlsmlkem=0 只能关闭后量子密钥交换（ML-KEM），无法关闭后量子签名算法声明（ML-DSA），而 Go 1.27 新增的 12 个字节正是 ML-DSA。Go 标准库未提供关闭 ML-DSA 的开关。如果中间设备是因为 ML-DSA 编号而重置连接，仅移除显式曲线清单无法消除这 12 个字节——这与报告人的复测结果完全吻合。

Go 到底在解决什么问题

后量子密钥交换需要提前迁移。 在“现在截获、未来解密”（harvest-now-decrypt-later）威胁模型下，攻击者可以先录制当下的加密流量，待未来出现具备密码学破解能力的量子计算机后再行解密。因此，密钥交换的机密性迁移必须在量子计算机实用化之前完成。NIST 于 2024 年正式发布 ML-KEM（FIPS 203）与 ML-DSA（FIPS 204），当前部署采用混合模式：X25519MLKEM768 同时运行经典 X25519 与 ML-KEM 并合并双方共享密钥，即便 ML-KEM 存在未知弱点，连接安全性也不低于单独的 X25519。主流浏览器、CDN 与 SSH 实现自 2024 年起已默认启用混合密钥交换，Go 在 1.24 中跟进。

握手签名的时间表则不同。 握手签名无法被事后追溯伪造——未来的量子计算机无法令 2026 年已完成的握手失效。因此目前 TLS 1.3 中的 ML-DSA 仅用于在握手中声明客户端支持验证 ML-DSA 证书。Go 1.27 将 MLDSA44、MLDSA65、MLDSA87 加入默认签名算法列表，新增的 12 个字节正来源于此：

// crypto/tls/defaults.go，Go 1.27.1
func defaultSupportedSignatureAlgorithms() []SignatureScheme {
    return []SignatureScheme{
        MLDSA44,        // 0x0904
        MLDSA65,        // 0x0905
        MLDSA87,        // 0x0906
        PSSWithSHA256,
        ECDSAWithP256AndSHA256,
        ...

这些编号只在 TLS 1.3 下定义。isDisabledSignatureAlgorithm 会在配置无法协商到 TLS 1.3 时将其剔除——如下文所述，这也是应用层对它唯一的杠杆。

这个开关本来就不管显式清单

暴露 SILO 写死曲线列表的那处变更，在 Go 1.27 发布说明中有明确记载：

Post-quantum hybrid key exchanges can now be explicitly enabled in Config.CurvePreferences even if the tlsmlkem=0 or tlssecpmlkem=0 GODEBUG options are used. Those options were always meant to only apply to the default set used when Config.CurvePreferences is nil.

（后量子混合密钥交换现在可以在 Config.CurvePreferences 中显式启用，即使设置了 tlsmlkem=0 或 tlssecpmlkem=0。这些选项本来就只适用于 Config.CurvePreferences 为 nil 时所用的默认集合。）

标准库自 Go 1.24 起就把两条路径写成二选一：

// CurvePreferences ... If empty, the default will be used.
//
// From Go 1.24, the default includes the [X25519MLKEM768] hybrid
// post-quantum key exchange. To disable it, set CurvePreferences
// explicitly or use the GODEBUG=tlsmlkem=0 environment variable.

代码里就是一个分支：给了显式清单就原样使用，只有为空时才查默认集合，而 GODEBUG 住在默认那条路上。

// crypto/tls/common.go，Go 1.27.1
func (c *Config) supportsCurve(version uint16, x CurveID) bool {
    if c != nil && len(c.CurvePreferences) != 0 {
        if !slices.Contains(c.CurvePreferences, x) { return false }   // 只看你的清单
        ...
    } else {
        if !defaultCurveEnabled(x) { return false }                   // GODEBUG 在这里
    }

其中的原则是显式配置应当压过环境变量——否则运维改一个环境变量，就能悄悄推翻开发者写在代码里的安全策略。Go 1.26 及更早版本会把显式清单也过滤一遍，因此 SILO 在 Go 1.26 上「开关有效」其实是依赖了一个 Go 认定的错误行为。

此外，Go 把 GODEBUG 的默认值绑定在主模块的 go 指令上，声明旧版本的模块会保持旧行为直到主动上调。SILO 的 go.mod 写的是 go 1.27.1，等于明确声明采用 1.27 的行为。

SILO 的技术债在哪，以及哪些还没还

出问题的清单是 {X25519MLKEM768, CurveP256, X25519, CurveP384, CurveP521}，继承自上游，后来被加入了那个后量子条目。写死它带来的是两头不靠：既享受不到标准库默认值的演进，又用不了标准库提供的兼容开关。

48e184652 在全部 8 个 Server TLS 配置点移除该赋值——外部通用 HTTP transport、复制 transport、带客户端证书的云 transport、节点间 transport、两条 grid 链路、etcd，以及入站 S3/Console 监听器——退役 TLSCurveIDs helper，并补充了跨 5 个出站构造函数、2 个对端 TLS 版本、2 种 GODEBUG 设置的线上级回归测试。证书与主机名校验、密码套件策略、代理处理、HTTP/2 选择均未改变，也没有引入任何失败后降级或重试。此前只改 OIDC 的候选补丁被放弃，是因为同一个 transport 还服务身份插件、通知与 Lambda 可达性检查、审计 webhook 和 S3 云分层。

同一类债在下一层依然存在。 密码套件仍然写死：crypto.TLSCiphers() 与 crypto.TLSCiphersBackwardCompatible() 被赋值在出站 transport、LDAP、etcd、grid 链路和入站监听器上。监听器至少还有 MINIO_API_SECURE_CIPHERS 可以在两套之间切换，所有出站路径一个开关都没有。

本设计确立的通用准则：设 MinVersion，其余交给标准库。 如果确有不兼容的对端需要更窄的配置档位，把它做成产品配置——在 mcli admin config 与支持包里可见——而不是写死在源码里。协议僵化是个老问题：TLS 1.3 不得不在线上伪装成 TLS 1.2，GREASE 的存在正是为了逼中间设备容忍自己不认识的编号。

线上真正的差异

在同一个合成 IdP 夹具前测量，默认设置下：

有两点容易被忽略，但至关重要：

• 能正常工作的版本本来就在发 ML-KEM。 除非运维在升级之前就设过 tlsmlkem=0，否则 ML-KEM 不是新旧版本之间的变量，恢复这个开关也就无法单独解释或修复他们的故障。
• 默认设置下，两个版本之间只有两处变化： 三个 ML-DSA 编号，以及改名带来的 HTTP User-Agent 变化（MinIO (…) → Silo (…)）。后者只有在 RST 发生于握手完成之后时才成立。

影响面，以及症状为什么具有误导性

写死的清单覆盖了所有 TLS 路径的两个方向，但后果差别很大：

只有身份路径会阻塞启动，因此它最先被报告。其余几条会安静降级，所以一个部署完全可能已经受影响而无人提单。

哪些部署有暴露面：

出站链路上没有检查设备的部署不受影响，也不应设置下文任何兼容选项。

四个特性叠加，使这个症状在现场几乎无法诊断：身份初始化以随机 0–3 秒间隔重试；discovery 与 JWKS 抓取没有总超时，启动可以无限期挂住；身份离线期间 /minio/health/live 与 /minio/health/ready 都保持 200，Kubernetes 就绪探针会报成功（只有 /minio/health/cluster 返回 503 并携带 X-Minio-Server-Status: iam-offline）；而错误文本 read: connection reset by peer 不说明 TLS 握手是否完成。此时从同一镜像跑 curl 还会成功，因为 curl 用的是另一套 TLS 栈并协商了 HTTP/2。

20260916 自身带来的变化

移除写死清单不会恢复此前的线上格式，而是采用当前 Go 默认值，而它更大：

因此对于什么都不设置的运维，20260916 会在每一个 TLS 端点（入站与出站）多提供两个后量子编号。对绝大多数部署这无害，但一个按 group 编号做白名单的入口，理论上可能在 20260903 正常而在 20260916 失败。GODEBUG=tlssecpmlkem=0 可以只关掉这两个并保留 X25519MLKEM768。而对于确实设置了 tlsmlkem=0 的运维，20260916 产生的握手比此前任何版本都更小更保守——这正是修复的目的。

三种机制，一个决定性事实

调查复现了三种都能产生所报错误文本的机制，而 20260916 修复覆盖其中一种。

还有第四项观察解释了 curl 对照为什么具有误导性：discovery transport 禁用 HTTP/2 且不发 ALPN，而 curl 协商了 h2。这个差异在正常版本和故障版本里都存在。

一个事实能把 A/B 与 C 分开，夹具结果能把 B 与 A 分开： RST 是紧跟 ClientHello 到达，还是在 GET 写出之后才到达。在故障网络位置做一次抓包，或者拿到入口在同一秒的拒绝原因，就能定案。

上游的同款案例

分支 B 不是假设。上游 Go 有两条 issue 描述了它：

• golang/go#81199，标题即 “add a GODEBUG to disable advertising ML-DSA signature algorithms in the ClientHello (Go 1.27 regression against TLS-inspecting middleboxes)"，2026-08-28 至今 open。所报症状与 #154 完全一致：经过 TLS 检查防火墙的所有 TLS 1.3 连接 read: connection reset by peer，而同一台主机上的 curl、OpenSSL 3.6、Node.js 24 正常，同一程序用 Go 1.26 编译正常，设置 MaxVersion: tls.VersionTLS12 也正常。其中点名的产品是 Palo Alto Prisma Access，PAN-OS 10.2.10-h37；Go 团队的回复指出该产品已有修复版本。
• golang/go#79626 已关闭，但其中有完整诊断：一位网络管理员与本单位防火墙团队一起定位到，Palo Alto 的一条 IDS/IPS 威胁特征——针对 OpenSSL CVE-2020-1967，该 issue 中记为 PA 威胁 ID 58033，最后更新于 2022-07-12——会检查 signature_algorithms_cert 扩展，并对其算法列表不符合预期的连接发送重置。Palo Alto 已于 2026-06-23 发布内容更新禁用该特征。

CVE-2020-1967 当年正是通过畸形的 signature_algorithms_cert 触发的空指针解引用；厂商为它写的检测规则对合法的现代握手触发了重置。这也精确解释了那 12 个字节：Go 1.27 把三个 ML-DSA 编号同时加进了 signature_algorithms 和 signature_algorithms_cert，即两个扩展各 3 × 2 字节。

Go 不会提供开关。 安全负责人在 #81199 的立场是：不可能为 ClientHello 的每一处底层变化都加 GODEBUG；以往加开关的是会改变协商结果的变更；而增加一个签名算法本不应该改变任何东西。提出的 tlsmldsa 设置（golang/go#81307）尚未合入，此外 Chrome 预计将开始对 signature_algorithms_cert 做 GREASE，这会让剩余的问题设备更快暴露。

对 SILO 有两个直接结论：

1. SILO 不能依赖上游新增 GODEBUG 开关：针对受分支 B 影响的部署，需要在 SILO 自身提供显式的出站 TLS 兼容配置档位。
2. 排查出站链路上的 TLS 检查设备：更新防火墙厂商的威胁特征库即可在网络侧直接消除根因。

全部可选解法

按「谁来动手」分组，每一行只解决特定分支：

入口侧——唯一完整的解法。

部署侧——今天就能用。

目前无法通过 GODEBUG 关掉 ML-DSA。 Go 没有为签名算法提供 GODEBUG——internal/godebugs/table.go 中 crypto/tls 的条目只有 fips140ems、tlsmaxrsasize、tlsmlkem、tlssecpmlkem、tlssha1——tls.Config 也没有签名算法字段。唯一的杠杆是版本门：这些编号只在 TLS 1.3 下定义，把 MaxVersion 压到 TLS 1.2 即可抑制。

为什么不回退工具链

用 Go 1.26 重新编译确实能恢复到正常版本的那份握手，上游的报告也确认降级有效。但它仍然是错误的手段，有五条理由：

1. 用整个产品的工具链，去替中间设备的缺陷买单。 而那台设备的厂商已有修复。
2. 它有保质期。 Go 只维护最近两个版本。Go 1.28 一发布，1.26 构建就运行在不再收安全修复的标准库上，同一个决定会带着更差的选项回来。
3. 上游保持新默认值。 Go 已明确拒绝增加开关，Chrome 也计划对同一扩展启用 GREASE。
4. 四个核心仓库均已要求 Go 1.27。 Server、Console、mcli 和 silo-pkg 均声明 go 1.27.1，使用 Go 1.26.7 编译当前源码会被模块要求拒绝，且传递依赖也已要求 1.27。
5. 只覆盖单一分支。 如果连接重置源自分支 C 的 HTTP 层规则，工具链版本根本无关。

保持用 Go 1.27 编译而仅下调 go.mod 中的 go 版本指令同样无效：该机制仅控制绑定了 GODEBUG 的行为，而 ML-DSA 声明没有对应的 GODEBUG 开关。

对于正在等待网络设备更新特征库的受影响环境，在过渡期内暂时停留在 20260804 镜像是合理的应急措施。

由此确立的需求

1. 为 discovery 与 JWKS 抓取加上分阶段诊断。 通过 httptrace 记录连接建立 → 握手开始 → 握手完成（附协商到的版本、套件、group）→ 请求写出 → 首个响应字节，并在返回的错误中标明最后到达的阶段。无需配置、不改协议行为，且可以用一条日志代替抓包来区分 A、B、C 三条分支。
2. 显式的出站 TLS 兼容档位，至少覆盖身份提供方：经典曲线，以及可选的 TLS 1.2 上限。必须 opt-in、启动时打出醒目警告，并在 mcli admin config 与支持包中可见。MINIO_API_SECURE_CIPHERS 是既有先例。这是分支 B 唯一的进程内解法。
3. 启动健壮性：为 discovery 与 JWKS 抓取加总期限与 context 取消，并明确就绪检查是否应当反映身份状态。
4. 受支持的诊断子命令，由调查用探针演化而来：握手分阶段、协商参数，以及 classical / TLS 1.2 / User-Agent 对照，使运维可以直接定位这类故障。
5. 清理剩余的写死密码套件，至少让出站路径拥有监听器已有的那个开关。

有两个选项被明确否决：

• 发布一个降低了的默认值——在 go.mod 写 godebug 指令，或在镜像里塞 ENV GODEBUG=…——会悄悄削弱所有连接的后量子保护，而且仍然解决不了分支 B。
• 握手被 RST 后自动降级重试等于把「注入一个 RST 就能把连接压到 TLS 1.2 加经典曲线」交给主动攻击者；浏览器正是因为这个原因移除了这类 fallback。

发布与沟通门槛

这次修复的兼容前提写在 Server README 的 TLS 小节、Go 1.27 TLS 与 OIDC，以及 20260916 发布说明 中。但在 issue 处置中有三件事没有做到位：

• 未在 issue 中直接说明该修复需要配合设置 GODEBUG=tlsmlkem=0 才会生效，以及它针对的是哪条故障分支。
• 该配置要求仅作为变更记录写入说明，而未作为受影响环境升级时的显式操作项列入升级检查清单。
• issue 在补丁合并时即被关闭，未等待报告人复测确认。

当一项修复依赖运维人员显式配置环境变量才能生效时，必须按兼容变更流程执行以下三条门禁：

1. 任何「效果取决于运维动作」的修复，都要在发布说明和升级检查清单中列为 required action，与协调升级类条目同等待遇。
2. 外部用户报告的 issue，只有在报告人确认复测通过后才能关闭；补丁合并只改变状态标签，不改变 issue 状态。
3. 修复无法覆盖所报症状的全部可能分支时，issue 中必须写明：处理的是哪条分支、还剩哪些分支、以及具体需要什么定位证据。

归属

本文在 #154 调查与九月 Go 1.27 栈评审的基础上，补充发布后的复测分析、上游 Go 社区案例、解法空间与流程门槛。Go 行为以 Go 1.27.1 标准库源码与官方发布说明为依据。

3 - 桶配置复制：来源时间、删除与确定性收敛

#77 是已在 Server 20260916（PR #180，提交 48ec10312）中修复的站点复制正确性缺陷。修复前，接收站点将对端事件的来源时间改写为本地到达时间（UTCNow），导致后续真正较新的删除请求因早于本地到达时间而被当作旧事件拒绝；同时部分配置在删除后不再导出时间戳，断连期间遗漏的删除也无法通过自愈（heal）恢复。仅补一个 DELETE 分支无法同时解决这两类问题，确定性收敛必须同时具备来源时间保留、持久化删除墓碑（tombstone）、规范化内容比较键以及整桶元数据锁。

既有工作与本轮范围

此前的发布说明、20260903 安全加固记录与 Server 兼容性说明已概述 #77 的删除收敛限制。本文完整记录其状态模型、方案取舍与验证证据（原始实验记录归档于 docs/investigations/issue-77.md）。

本修复处理 Policy、Tags、SSE、Quota、Versioning 与 Object Lock 六类配置。Lifecycle/expiry 保持其合并载荷时间语义；CORS 保留独立机制；notification、IAM、对象复制可靠性、MRF、resync 与公开统计各自独立维护。

复现确立的故障事实

原始缺陷在 ErasureSD 和 16 盘 Erasure 两种对象层上均稳定复现：源站在过去时刻 $T$ 写入配置，接收端落盘时却写入当前到达时间；随后收到源时间为 $T + 1\text{ 分钟}$ 的删除事件时，接收端因该时间早于刚才记录的到达时间而将其拒绝。因此单看 RPC 返回成功，并不能保证各站点最终状态一致。

排查过程中还定位了三个必须在入口层修复的问题：

1. 较旧的批量（bulk）事件可以覆盖较新的单字段配置。
2. 请求在锁外完成新旧判断后再排队等待 metadata.lock，拿到锁时仍按已过期的判断覆盖新状态。
3. Tag 的远端 heal 请求漏传了 UpdatedAt 时间戳。

因此修复不能只改动 heal 的选源条件，必须覆盖所有真实写入与同步入口。

字段状态模型与确定性排序

状态模型复用 .metadata.bin 中既有的字段载荷、字段 UpdatedAt 和桶 Created，不新增磁盘格式、SDK 字段或持久化 deployment ID。

Versioning 和 Object Lock 的空事件继续保持无操作，不会因共用排序辅助函数而获得删除语义。零时间字段在比较时使用 Created 作为基线，不会把历史空值误判为一次新删除。

状态比较按以下四条规则依次裁决：

1. 真实状态（UpdatedAt > Created）优先于基线状态。
2. 真实状态之间，来源时间 UpdatedAt 较晚者胜出。
3. 来源时间相同时，删除墓碑优先于有值载荷。
4. 同级且同时间的有值冲突，按规范化内容键的字典序裁决，字典序较大的键胜出。

对于带时间戳的对端事件和 heal，当计算出的有效状态与磁盘已有状态完全相同时，接收端既不写盘也不触发事件通知；本地写入则即使可见载荷不变，也始终分配新的单调递增修订时间。有值基线之间同样按内容键排序，防止较晚创建的默认状态压过真实修改。字典序决胜保证多站点在并发冲突下收敛到同一结果；若业务期望特定配置，管理员仍应在冲突后在权威站点重新提交期望值。

比较键必须与落盘行为一致

复制状态统计、heal 选源与对端应用必须比较与持久化完全一致的表示：

• Policy： Go 中策略集合由 map 支撑，直接 JSON 编码会受 map 遍历顺序影响。服务端对已校验策略的完整 JSON 树（Statement、Action/NotAction、Resource/NotResource、Principal、Condition）执行递归排序，并保留 Sid 和数字精度。此外，既有策略解析器支持 NotAction 与 NotResource，但原结构体必填 Action/Resource 的编码会对空集合报错。修复统一采用显式字段编码，并同步应用于 GetBucketPolicy、管理导出和对端复制，既防止含负集合的合法策略“写得进、读不出”，也保证状态统计与 heal 使用完全一致的比较键。
• Quota： 使用解析结果的 JSON 编码作为比较键。{}、JSON null 或合法零配额文档仍是有值文档。旧版发送端曾将零配额 PUT 转为对端删除而在本地保留文档；对于 mcli quota clear 发送的零配额，升级后各站点统一保留该有值零配额文档，容量限制同样处于关闭状态。空 Policy 则遵循既有删除语义：合法的空策略 PUT 清除策略，后续 GET 返回 NoSuchBucketPolicy。
• XML 配置（Tags、SSE、Versioning、Object Lock）： 直接使用有效 XML 文档的字节切片作为比较键，不引入通用 XML 规范化器。Versioning 是唯一需要预处理的例外：比较前必须先应用 Object Lock 约束（启用 Object Lock 时强制 Enabled），再比较最终会落盘的有效文档；否则比较器接受未开启版本控制的文档而 Save 落盘时将其改写，会导致下一轮 heal 无限重复发送。

在同一把锁内完成决策与落盘

六类字段共同存储在一份 .metadata.bin 中。读取原始记录、校验载荷、比较时间戳、修改字段和写盘保存必须全部位于同一把 metadata.lock 锁内：若先在锁外比较、再进锁内写盘，并发写入下仍会使用过期状态；若拆成按字段加锁，整条记录的读改写又会互相覆盖。

本地写入在 metadata.lock 锁内分配单调时间：

max(当前 UTC 时间, Created + 1ns, 当前字段时间 + 1ns)

该规则使本地纠正操作能够超过已保存的未来字段时间。带来源时间的对端事件保留其原始 UpdatedAt；完全重复或较旧的带时间对端事件在锁内直接返回，不产生磁盘写入。

批量（bulk）路径仅处理显式提供的字段，逐项校验通过后至多保存一次：省略字段保持不变，显式 null 按类型删除语义处理，任一字段非法都会在落盘前中止整批更新。导入（import）在每桶最终提交锁内为涉及的六类字段分配统一提交时间，磁盘状态和出站复制事件均使用本次提交返回的归一化快照，不在解锁后重新读取存储拼接旧时间。空 Policy 通过专用删除事件发送，避免被批量结构的 omitempty 丢弃。

桶接管不能制造假删除

桶接管（adoption）可能调整桶的 Created 时间戳。若把 Created 改早，却保留空字段原本等于旧 Created 的默认时间戳，空基线就会因 UpdatedAt > Created 被误判为真实删除；若把 Created 改晚，又可能使历史初始配置因 UpdatedAt < Created 变成无效状态。

修复在既有接管锁内，仅将这六类字段中原本为零或等于旧 Created 的默认时间同步调整为新 Created，真实更新和真实删除的时间戳保持不变。

所有入口共用同一套状态规则

首次同步保留既有五类配置发送路径，Versioning 仍通过 MakeBucketHook 初始化并由 heal 对齐。当桶元数据未记录 Created 时间戳时，GetBucketInfo 与 ListBuckets 一致地返回物理目录探测时间，首次同步将该恢复时间传给建桶钩子并落盘，避免无元数据记录的旧桶无法写入配置。

heal 不再先取 map 第一项作为胜者再过滤默认时间，而是先筛选有效候选再取最大状态。公开 mismatch 计数不再作为唯一门控：内容相同但来源时间不同仍需同步；反之，最终有效状态相同时不再重复写盘或发送 RPC。

为什么需要默认关闭的升级开关

启动环境变量 MINIO_SITE_REPLICATION_METADATA_TOMBSTONES 默认为 off，用于控制无载荷的 Tags、SSE、Quota 删除墓碑时间是否在状态接口与首次同步中向外导出。

旧版节点无法安全消费全部新增的删除墓碑信息——例如旧版 Quota heal 会在清空原始载荷后保留已解析的内存缓存值。默认保持 off 能够安全隔离滚动升级窗口。

协调升级与降级步骤

1. 将所有参与站点的全部节点升级至 Server 20260916 或更高版本，确认同站点配置一致并排空在途请求。
2. 在全部节点统一设置 MINIO_SITE_REPLICATION_METADATA_TOMBSTONES=on 并重启。
3. 如需回滚到旧版本，先在全部节点设置 MINIO_SITE_REPLICATION_METADATA_TOMBSTONES=off 并重启，再滚动降级软件二进制。

在 off 模式下，被隐藏的 Tags、SSE、Quota 删除墓碑可能导致对端在 heal 时重复发送旧状态并由已升级接收端拒绝；只有全站点统一开启 on 且状态稳定后，后续 heal 周期才会达到零元数据 RPC。

保留与否决的候选方案

生产代码共新增 729 行、删除 692 行 Go 代码（净增 37 行），主要以统一的状态比较器替换原先重复的各类型应用与 heal 分支。每一项保留机制都对应已复现的故障模式：去掉整桶锁会重现跨字段读改写覆盖，去掉规范化 Policy 比较键会在负集合策略上造成永久假 mismatch，去掉升级开关则会在滚动升级期间击穿旧版节点的 Quota 缓存。

验证与测试证据

位于 cmd/site-replication-metadata_test.go、cmd/site-replication-metadata-heal_test.go 与 cmd/site-replication-metadata-gate_test.go 的回归测试套件在 ErasureSD 和 16 盘 Erasure 两种对象层上验证了完整契约：

在测试复核中，早期使用桩对象（stub）伪造创建时间探测的测试被替换为操作真实本地盘桶目录时间戳的测试——确保该用例在叠加修复前生产代码时必定失败，仅在真实恢复链路生效时通过。

实现复核与演进记录

从基线 5c5765816 与初版实现 1ee64a8d8 出发，复核发现的三处问题（真实磁盘创建时间恢复、旧顺序 Policy 状态键与 heal 诊断去重）已在 62cf066ff 与 fcbb93e89 中补齐，最终在 461e9a721 完成测试格式整理并通过全量 cmd/internal 测试与 lint 检查。

运维边界与已知限制

1. 历史时间污染无法自动还原。 升级前被本地到达时间覆盖的配置和无时间戳旧事件已经丢失原始来源时间。部署升级后，应核对各站点配置并在权威站点重新提交期望的配置或删除操作。
2. 零时间专用事件继续兼容。 不带时间戳的专用对端事件会分配本地单调时间并记录限频 legacy-zero 警告；bulk 导入的零时间校验约束保持不变。
3. 桶创建世代冲突不自动合并。 早于目标桶 Created 的事件不予应用（记录 before-created）。缺失 Created 的桶仅从真实物理桶目录修改时间恢复近似值；若已存在桶的物理创建时间仍为零，配置写入返回 500 InternalError（缺失桶返回 404 NoSuchBucket）。在配置写入或首次站点同步将该恢复时间落盘前，周期性 heal 会在两个方向上跳过该桶。
4. 物理时钟不是因果时钟。 本地单调时间允许管理员在未来时间戳之后继续发起本地修正，但跨站点并发写入若与字典序决胜结果不符，仍需人工确认并重新提交。
5. 诊断按桶、字段与原因有界去重。 legacy-zero、before-created、indeterminate、unreachable 与 peer-error 复用 LogOnceIf 以 Warning 级别输出并按小时清理；空基线以及尚未拥有该桶的对端保持静默，而损坏的存量配置即使无可用来源也会输出 indeterminate 警告且不触发出站 RPC。

关联记录：复制标签排序 · 副本元数据归一化 · 请求头超时控制 · 副本元数据审计

4 - SigV4 签名头覆盖边界：拒绝未签名的 x-amz-* 请求头

本文记录 SILO 的未签名请求头覆盖修复（核心提交 123325430，经 PR #173 合入，安全通告编号 SN-2026-011）以及 PR #177 中的后续签名与载荷校验修复（安全通告编号 SN-2026-012）。上述修复已随 Server 20260916 发布。该漏洞由 Oren Yomtov 报告，并在本地预签名与 Authorization 请求头两条 SigV4 路径上复现。

核心结论（TL;DR）

预签名 PUT URL 可以只对 host 一个请求头签名。此前 SILO 只校验签名头列表（SignedHeaders）中声明的请求头是否已到达，却未反向检查请求实际携带的全部请求头，导致列表之外的 x-amz-* 请求头被直接接受并参与业务处理。与此同时，cmd/api-router.go 仅凭请求中存在 x-amz-copy-source 头，就会将任意 PUT 请求分发至 CopyObjectHandler。两处逻辑叠加后，原本仅授权写入单个对象的预签名 URL，可被攻击者转化为以签名者身份读取该密钥可访问的任意对象的服务端复制操作（混淆代理，confused deputy）。当 Authorization 头签名请求未将 x-amz-copy-source 纳入 SignedHeaders 时，同样会触发该问题。

本次修复确立了一条核心不变式：

在普通签名与预签名 SigV4 路径中，收到的所有 x-amz-* 请求头均须在签名覆盖范围内；
唯一豁免项为通过规范请求单独绑定和校验的 X-Amz-Content-Sha256。

这一行为与 AWS S3 一致——AWS S3 对携带未签名 x-amz-* 头的同类请求同样返回 AccessDenied（“There were headers present in the request which were not signed”）。

缺陷机制：单向覆盖缺口

cmd/signature-v4-utils.go 中的 extractSignedHeaders 遍历签名头列表，按名称逐一从请求头（或 query 参数）中提取对应值。这仅验证了签名声明的请求头均已存在，却遗漏了反向检查：实际收到的每一个 x-amz-* 请求头是否都包含在签名头列表中？

此前代码中唯一遍历实际到达请求头的函数是 checkMetaHeaders，但它仅匹配 X-Amz-Meta- 前缀，且只在预签名路径（doesPresignedSignatureMatch）中调用；Authorization 头验签路径（doesSignatureMatch）则完全没有对应检查。因此，未签名的 x-amz-copy-source（或任何其他影响操作语义的 x-amz-* 请求头）在两条路径上均能畅通无阻：

预签名 PUT（SignedHeaders=host）  ->  附加未签名的 x-amz-copy-source: /src/secret
  -> 路由层检测到 x-amz-copy-source  -> 分发至 CopyObjectHandler
  -> 以签名者身份执行服务端复制，读取预签名 URL 从未授权的源存储桶

本地复现结果：对照组普通 PUT 返回 200 且响应体为空；对同一预签名 URL 附加一个未签名的 x-amz-copy-source 头后，请求同样返回 200，但响应体变为 CopyObjectResult（其 ETag 即为源对象的 MD5），从目标对象回读即可拿到源对象的完整内容。若目标存储桶本身允许匿名 GetObject，攻击者无需任何凭据即可直接读取被复制出来的私有对象。

历史溯源

该缺陷继承自上游 MinIO。cmd/signature-v4-utils.go 中的 SigV4 验签逻辑与 cmd/signature-v4.go 中的 doesSignatureMatch 可追溯至 2016 年；cmd/api-router.go 中基于请求头分发 CopyObject 的路由规则可追溯至 2019 年。上游曾在 2023-07-27 通过 minio/minio#17737（提交 535f97ba6）引入 checkMetaHeaders，当时已注意到未签名请求头需与签名集合保持一致，但将该检查局限在 X-Amz-Meta- 前缀与预签名路径，遗漏了 x-amz-copy-source 等操作控制头以及整条 Authorization 头验签路径。

在本次修复前，SILO 对 cmd/signature-v4-utils.go 仅做过一行依赖导入路径调整（9b11dc946 将 policy 包导入迁移至 pgsty/silo-pkg/v3）。核心修复（123325430）与 PR #177 的后续加固完整闭合了这一边界。

修复设计

修复将 checkMetaHeaders 重命名为 checkUnsignedHeaders，将匹配前缀从 X-Amz-Meta- 扩展至整个 X-Amz- 命名空间，并在预签名与 Authorization 头两条路径上统一调用。任何未被签名集合覆盖的 x-amz-* 请求头，都会在进入业务 handler 之前被直接拒绝并返回 ErrUnsignedHeaders。

以下四项设计决策界定了具体的检验边界：

检查集合成员资格

原先的 checkMetaHeaders 采用 signedHeadersMap.Get(k) == val[0] 比较值是否相等。对于不在签名映射表中的请求头，Get 会返回空字符串 ""；一旦攻击者构造首个元素为空串的多值请求头（例如 X-Amz-Copy-Source: ["", "/src/secret"]），val[0] 同样为空串，就能绕过相等比较并将第二个未签名的复制源路径注入后端。修复改为直接检查键是否存在于 signedHeadersMap 中：只要请求头已纳入签名列表，其具体取值自然受签名摘要保护，验签阶段只需判定集合成员资格。

豁免 X-Amz-Content-Sha256

客户端发送 X-Amz-Content-Sha256 时可以不将其列入 SignedHeaders，因为有效载荷哈希已作为独立字段写入 SigV4 规范请求（Canonical Request）。预签名请求优先取 query 参数中的哈希值，仅在 query 未提供时回退读取请求头，显式的 UNSIGNED-PAYLOAD 同样受支持。PR #177 将 IAM 策略条件求值统一对齐到这一有效哈希值（同时保留判断请求头是否存在的语义），并在通用认证路径中补齐了仅通过请求头携带哈希的预签名请求正文摘要校验，确保签名绑定、策略评估与正文校验使用同一个值。

直接从签名日期计算签名年龄

初版修复曾豁免验签后写入内部请求头的临时字段 x-amz-signature-age，但 PUT 和 UploadPart 的授权评估发生在流式验签之前，此时该内部头尚未生成。PR #177 改为直接根据已受签名保护的 X-Amz-Date 计算 s3:signatureAge，并彻底移除了内部临时头、相关常量及豁免分支。伪造日期会直接导致验签失败，客户端自行传入的同名未签名头则会被拦截；同时验签过程不再修改请求头映射，多次调用保持幂等。

将 X-Amz-Tagging 注入移至验签之后

PutObjectTaggingHandler 会从请求正文 XML 中解析并合成 X-Amz-Tagging 请求头供 IAM 策略条件评估读取，而原先这一注入发生在调用 authenticateRequest 之前。将未签名头检查扩展到全部 X-Amz- 前缀后，这个由服务端合成、客户端从未签名的请求头会被误判为未签名头而遭到拒绝。修复将注入时机调整至签名验证通过之后、策略授权评估之前，既不影响策略条件读取标签，又保持了验签边界的纯净。我们否决了“像豁免 content-sha256 一样全局豁免 X-Amz-Tagging”的替代方案——因为一旦全局豁免，客户端就能在任意签名或预签名写入请求上附加未签名的 X-Amz-Tagging 头来篡改对象标签。

跨签名模式的适用范围

• Authorization 头签名与预签名 SigV4： 两条路径均已强制执行 checkUnsignedHeaders。
• 流式 SigV4（Streaming SigV4）： 种子签名校验器未调用 checkUnsignedHeaders。Copy 系列 handler 通过常规认证分发直接拒绝流式认证，而流式 PUT / UploadPart 的请求头覆盖属于独立边界。
• SigV2： 不受影响。SigV2 规范化算法在构造待签字符串（string-to-sign）时默认纳入全部 x-amz-* 请求头，任何额外附加的 x-amz-* 头都会改变计算出的签名并触发签名不匹配错误。

状态码权衡：400 与 403

AWS S3 对未签名请求头返回 403 Forbidden，而 SILO 沿用上游 ErrUnsignedHeaders 定义返回 400 AccessDenied。两者的 S3 错误码字符串均为 AccessDenied，仅 HTTP 状态码不同。若将 cmd/api-errors.go 中的状态码改为 403，虽然只需修改一行代码，但会同步改变既有的未签名 x-amz-meta-* 请求头返回码。为避免在安全补丁中引入额外的状态码兼容变更，此处保持 400 AccessDenied 不变。

回归测试

代码中原有的若干单元测试会先构造签名请求，在完成签名之后再手动追加 x-amz-copy-source、x-amz-copy-source-range 或 x-amz-metadata-directive 请求头。这些测试已更新为在设置完操作控制头后重新调用 signRequestV4 签名（signRequestV4 会自动将已有的 Authorization 头排除在签名集合外，因此可安全重签）。新增单元测试覆盖了 checkUnsignedHeaders 的空首值多值头拦截、X-Amz-Content-Sha256 豁免、旧版未签名 x-amz-signature-age 头拒绝，以及对同一预签名请求连续验签两次的幂等性测试 TestPresignedVerifyIdempotent。

验证证据

• 在真实构建的服务端实例上，复现脚本在预签名与 Authorization 头两条路径上均确认了修复前的混淆代理行为，并在修复后验证两者均被拒绝；与此同时，对照组的普通 PUT、标准 minio-go CopyObject、携带用户元数据与标签的 PutObject 以及基于请求正文的 PutObjectTagging 均正常通过。
• go test ./cmd/ 全量通过，gofmt、gofumpt 与 go vet 检查无告警。
• 首轮代码审查指出的三处边界问题（临时请求头破坏验签幂等性、空首值绕过相等检查、未签名 x-amz-content-sha256 误拒）均已修复并通过回归测试验证。
• 第二轮复核确认重签后的既有测试保持原有测试意图：无效 AccessKey 仍返回 InvalidAccessKeyId，错误的 SSE-C 密钥在签名校验通过后仍返回 403。

兼容性与运维影响

• 标准客户端： 零影响。遵循 SigV4 规范的客户端与 SDK 会自动将发送的非豁免 x-amz-* 请求头纳入 SignedHeaders。
• 附加未签名 x-amz-* 头的客户端： 请求将被拒绝并返回 AccessDenied，与 AWS S3 行为一致。
• 滚动升级： 线协议与底层存储格式无变化。升级过程中，已升级节点立即强制执行新边界，未升级节点在完成替换前仍存在暴露窗口。
• 版本回滚： 新版本写入的数据可被旧版本正常读取，但回滚服务端二进制会重新暴露该混淆代理漏洞。

关联修复与延伸原则

• 安全通告编号： 未签名请求头覆盖修复对应 SN-2026-011，PR #177 中的相邻签名与载荷校验修复对应 SN-2026-012。
• HTTP 状态码： 上述 400 与 403 的状态码对齐留待后续大版本评估。
• 相邻签名修复： PR #177 一并消除了重复 x-amz-copy-source 请求头的解析歧义、修正了签名年龄的授权评估时序与载荷哈希策略条件取值，并补齐了仅通过请求头携带哈希的预签名请求正文摘要校验。回归测试覆盖了普通签名与预签名请求、上传验签前的策略评估以及真实 HTTP 存储桶策略防篡改验证。
• 通用设计原则： 凡是允许请求语法改变服务端操作语义的控制项，都必须在进入路由或业务分发前确认其已受签名保护，且验签所绑定的值与业务处理器实际消费的值必须严格一致。

总结

SigV4 验签不仅要确认签名头列表声明的请求头悉数到达，还必须反向确认实际收到的每一个 x-amz-* 请求头都已纳入签名列表。在业务处理器执行前拒绝未签名的 x-amz-* 请求头，从根源上闭合了普通签名与预签名 SigV4 路径上的混淆代理漏洞。虽然签名校验改动本身不涉及存储格式变更，但升级至 Server 20260916 同时包含需要协调升级的 IAM 变更。

5 - Object Lock 复制排序

Object Lock 复制时间戳排序的初始修复（f4c1286c9）已随 SILO Server 20260903 发布（收录于安全公告台账）。针对仅携带时间戳的删除（墓碑）、SSE-C 副本完整重传以及跨存储池 Object Lock 状态合并的后续修复（PR #129、PR #134 与 PR #178）已随 SILO Server 20260916 正式发布。

在重建目标元数据前捕获已存状态

此前，副本 COPY 在比较 Object Lock 保留期（Retention）与法务锁定（Legal Hold）修订时间戳之前，会先根据入站请求重建目标端元数据映射表。这导致目标端原有的修订时间戳在比较前即被覆盖丢失，使迟到的旧复制请求能够覆盖目标端较新的锁定状态；此外，旧逻辑还误将法务锁定的时间戳写入了保留期的时间戳键名下。

提交 f4c1286c9 改为在重建目标元数据映射表之前先捕获已落盘的 Object Lock 状态，并将每个字段的修订时间戳独立保存在各自的内部元数据键中。

保留期（mode + retain-until-date）与法务锁定（status）是两个彼此独立的状态寄存器：

• 较新的保留期时间戳不会使同一请求中较旧的法务锁定生效（反之亦然）；
• 对象数据本体的修改时间（ModTime）不能替代任一字段自身的显式修订时间戳；
• 仅当入站字段的时间戳严格新于目标端已存储的对应字段时间戳时才应用更新；对于更旧或时间戳相等的入站更新，一律保留目标端已存状态。

将删除操作同样视为带时间戳的有序状态

清空对象的保留期或解除法务锁定后，字段本身不再包含有效值，但仍携带产生该变更的源端时间戳。如果因为字段值为空就丢弃对应的时间戳，网络中延迟到达的旧复制请求就会将已移除的旧保留期或旧法务锁定重新写回。

PR #129 与 PR #134 在复制接收、时间戳比对与重新发送路径中完整识别并传递“仅含时间戳的空值删除”，严格区分“从未设置过该字段（无排序证据）”与“在指定时刻显式清空了该字段（有时间戳的删除）”。

接收端在普通元数据 COPY 与完整的 SSE-C 副本对象重传路径中均保持这一语义：即便因 SSE-C 重传而重写整个对象密文数据流，也不会抹去目标端已有的更新法务锁定或回退目标端更新的保留期。

跨存储池权威状态合并

当同一对象版本在多个存储池中存在物理副本时（例如扩容或退役迁移期间），仅读取单个本地纠删集无法决定最新的字段状态。多池一致性协调层（PR #178，关闭 #133）会在共享命名空间对象锁下收集所有存储池中的同版本副本，并按各自的时间戳分别合并保留期与法务锁定状态。不可读或未达法定人数的存储池会直接报错，而不会被视为空状态。

授权与运维边界

时间戳排序仅用于在已获授权的副本写入上裁决新旧冲突，本身不会授予修改 Object Lock 的权限；复制信任边界校验与相应的 S3/管理端权限（s3:ReplicateObject、s3:BypassGovernanceRetention、s3:PutObjectRetention、s3:PutObjectLegalHold）依然强制执行。该机制建立的是基于源端时间戳的逐跳字段顺序，不提供跨站点未同步时钟之间的因果全序，也不提供部分磁盘故障后的分布式事务回滚。

升级至包含修复的版本可阻止旧复制事件再次覆盖较新的锁定状态，但无法自动重建升级前已被旧事件覆盖的历史状态。运维人员在确认恢复前，应结合权威记录核对各站点精确版本的保留期与法务锁定状态。

验证与参考

cmd/erasure-server-pool-consistency.go 中的 Object Lock 合并实现与 cmd/erasure-object.go 中的副本写入路径已通过新旧字段更新、空值删除墓碑、独立字段时间戳、SSE-C 重传与多池场景回归测试验证。

请结合副本元数据审计手册、SSE-C 副本完整性记录以及组件版本矩阵使用，并在依赖完整排序契约前协同升级所有参与复制的节点。

6 - SSE-C 副本完整性

本文记录由 #122、#123、#124、#126 和 #134 共同构成的 SSE-C 副本完整性契约（随 Server 20260916 发布），与此前在 Server 20260903 中发布的零字节/属性读取认证及目标密钥 checksum 响应修复衔接。

密文与信任

普通 SSE-C 请求提供客户密钥，操作明文。经过授权的副本传输可以携带原始密文和保留原对象所需的密封对象密钥元数据。目标必须原样存储这些字节，再加密一次会产生不可读的双重加密对象。内部标记本身不是授权：仍需精确复制标记和要求的复制权限。

该路径不会泄露客户密钥，也不会允许普通无密钥读取。普通 GET/HEAD 与 GetObjectAttributes 保留各自密钥/权限检查。联邦原始 SSE-C 副本 COPY 明确不支持。

分段大小与校验和

加密分段大小与逻辑明文分段大小不同。副本多段记录必须保留每段实际逻辑大小，使覆盖后的 partNumber 读取、范围读取和 GetObjectAttributes 与源一致。Checksum 必须保留正确加密上下文和逻辑含义；对象已用另一把目标密钥提交后，不能仍用源密钥解密响应 checksum。

普通 SSE-C 密钥轮换只要显式请求 checksum 算法，就走完整重写，即使算法与原值相同。多段源成为单段目标，ETag 可能变化，复制重传对象字节。不带该请求且满足元数据原位更新条件时，保留原 checksum 状态，包括缺失状态。详见操作步骤。

重传与 Object Lock

目标无密钥 HEAD 可能把已存在的 SSE-C 对象报告为不可访问，而不是不存在。发送方须区分它与 NoSuchKey，不能假设普通元数据 COPY 能修好副本。已存在 SSE-C 副本走对象重传。旧副本状态无法解码时，可通过修复后的重传路径替换，同时保留目标更新的 Object Lock 状态，并正确排序删除时间戳。

升级 Server 不会自动修复已损坏的历史副本。审计存量副本时，应使用批准的密钥访问流程重新读取精确源/副本版本，比较逻辑字节和分段边界，并另行检查保留期及 legal hold，不能仅凭元数据 HEAD 成功推断完整性。

压缩与历史对象

SILO 排除所有新 SSE-C 写入的压缩，包括普通 PUT、多段初始化、COPY 和 Snowball。SSE-S3/SSE-KMS 仍服从加密压缩选项。这避免生成传送密文却缺少所需压缩元数据的副本格式。

历史压缩 SSE-C 对象不会自动重写。应保留密钥和精确版本身份，清点影响范围并演练受支持的重写/恢复路径。

验证边界

压缩判定、replication-trust-ssec-replica_test.go、erasure-multipart-ssec-replica_test.go、replication-ssec-retransmit_test.go 和 compression-ssec_test.go 固定了相关源码及回归契约，涵盖错误密钥/未授权对照、多段字节比较和重传场景。

相关内容见 Object Lock 排序、多池一致性及副本恢复。依赖组合行为前须升级所有参与 Server。

7 - 持久化 IAM 撤销

SILO 保留已删除 IAM 记录的版本（Revision），使离线站点在重新连接后无法将已删除的旧身份或旧授权恢复为有效状态。该机制覆盖内置用户、服务账号、组、策略文档，以及用户、STS 父身份和组各自命名空间中的策略映射。内置用户被删除后，即使管理员有意重建同名用户，此前签发的旧服务账号、STS 临时凭证与组授权也不会因此复活。

持久化 IAM 撤销架构（PR #191、#192，提交 f99ed829b5eba549160725f035156c9e020b6a07）已随 Server 20260916 发布并关闭 SN-2026-013；针对直接 RevokeTokens 的按范围 STS 撤销扩展（0cd388c66）已随 Server 20261018 发布。多站点协调升级步骤见 IAM 升级与恢复手册。

十月十八日：按范围撤销 STS

Server 20261018 中的提交 0cd388c66 将九月持久化撤销机制扩展到直接 RevokeTokens 操作。

在旧实现中，节点可能漏掉某次签发通知，进而在执行撤销时只清理自身内存缓存中已有的令牌。修复后，RevokeTokens 会读取持久化的 STS 身份记录并与内存缓存合并，按操作截点（Cutoff）筛选指定父身份及可选令牌类型，为每个命中的不可变令牌 key 提交独立的删除墓碑（Tombstone）。即使批次中某个 key 保存失败，所有已提交的 key 仍会立即通知同集群兄弟节点并发送给站点复制对端，同时向调用者返回保存错误以便重试。

私有 IAM 复制消息携带令牌删除标记与过期时间。即使撤销消息先于创建消息抵达，墓碑仍能阻止随后的重放；带有更晚事件时间戳的创建消息也无法复活这一不可变令牌。既有删除自愈（Deletion Healing）机制负责离线重投。对象存储和 etcd 的完整 IAM 刷新会重建 STS 修订记录——即使并发 IAM 写入推迟了整表缓存替换，也会先从活动缓存中剔除已撤销条目。墓碑保留至令牌自然到期时间加上时钟偏差容限；若过期时间未知则采取保守保留。

单次撤销快照覆盖请求集群在截点之前已知的 STS 身份；在孤立站点签发且从未复制到本集群的令牌不在该快照内。截点之后新签发的 key、无关用户及可复用的父身份策略映射不受影响。所有参与节点须协调升级，旧版本节点未实现新增的私有 STS 复制消息。

执行开销： 管理端撤销会枚举持久化的 STS 身份并按父身份与类型过滤，其读取量与临时映射内存随活跃令牌数量线性增长。扫描期间会释放鉴权缓存锁，但仍持有 IAM 写串行锁，因此其他并发 IAM 写操作可能短暂等待。etcd 既有的周期性刷新也会读取 STS 记录。普通缓存命中鉴权不增加任何网络调用，也未引入新的后台定时器或外部依赖。

回归测试位于 iam-sts-revocation_test.go，覆盖三站点断连／重启恢复以及四进程共享 IAM 存储场景。升级后应逐端点验证旧令牌被拒绝、新令牌继续有效以及节点重启后的状态恢复，详见升级流程。

排序与持久化

删除记录保存在原 IAM 配置路径下，包含源时间戳、Deleted 标志以及必要的 RevokedBefore 边界；身份删除记录不保存 secret key 或 session token。常规 IAM 列表查询与策略求值自动隐藏已删除记录。对象存储与 etcd 均通过分布式锁串行化每个配置路径的版本比较与写入；接收端直接持久化源时间戳，绝不将其替换为接收节点的本地时钟。

版本演进遵循以下确定性规则：

• 旧事件不能覆盖新版本；相同时间戳下，删除记录优先于活记录。
• 有意的本地同名重建会获得比已存储删除记录更新的版本号。
• 若旧的用户或组删除消息在同名重建之后才延迟到达，系统会更新并保留其 RevokedBefore 撤销边界，同时完整保留较新的重建活记录。
• 重复收到已应用的 tombstone 不会触发重写或推进版本号。
• 节点冷启动加载持久化 IAM 状态时同样执行上述合并规则。

用户或组的版本写入是删除操作的权威提交点，策略映射与子凭证清理在其后执行。即使后续附属清理失败，也不会回滚已提交的父身份撤销；API 会向调用方返回清理错误，但仍会通知同后端兄弟节点重载已提交的撤销状态。因此，管理接口返回 HTTP 500 清理错误并不代表旧身份仍然有效。管理员可在暂停同名重建与其他 IAM 变更的前提下安全重试该删除操作。当发生“撤销已提交但附属清理失败”时，Admin Handler 不会触发即时跨站点推送钩子，而是交由常规后台删除自愈循环（Deletion Healing）重试跨站点传播。同后端兄弟节点收到删除通知后会重读当前共享状态，因此延迟到达的通知不会误删随后合法重建的同名身份；etcd 部署下兄弟节点还会通过 watch 机制接收持久化变更。

运维上必须保持各节点时钟同步并监控时钟偏移。版本排序基于源端墙钟时间戳，并对同一路径的本地连续写入保证单调递增，但不跨站点建立并发写入的因果偏序。

2026 年 11 月持久化记录编辑与缓存新鲜度加固（a0de92fcb、70914759e、7eed95bc8、07ce95dfd、00270e9f6、c78ef6a6f、bb31c2618）： 在多节点集群中，管理端增量修改（SetUserStatus、UpdateGroupMembers、SetGroupStatus、SetPolicy、UpdateServiceAccount 以及每小时一次的 LDAP 组成员刷新）均在跨节点版本锁内读取并修改底层持久化记录，而不再先就地修改当前节点的内存缓存。当写入或创建因底层已存在更新版本或删除墓碑而被拒绝时，当前节点会立即重载或驱逐本地陈旧缓存条目，不再继续提供旧缓存直至下一轮定时刷新。单条目按需加载（Lazy Load）按 key 通过 singleflight 合并并发未命中，并在读取存储前记录 loadedAt，防止跨通知或本地新写入之前启动的慢速读取在返回时覆盖更新的缓存版本或墓碑。

用户、子凭证与组

同名重建后的用户会保留历史 RevokedBefore 边界。新创建的服务账号与内置 STS 临时凭证均携带经加密签名的 siloParentRevocation 声明（Claim），记录签发时刻已知的父身份撤销边界。编辑或重放旧子凭证不会更新这一签名声明；因此即使旧子凭证自身的更新时间晚于父身份删除时间，鉴权时仍会被判定为失效，而针对重建后父身份新签发的子凭证则正常有效。凭证加载与写入时均从已验签的令牌中提取该声明。

在站点复制中，版本号更新的服务账号快照可以替换相同 AccessKey 的旧服务账号（包括有意更换所属父用户或轮换密钥），而本地直接重复创建相同 AccessKey 仍会被拒绝。复制快照会保留禁用状态（Disabled）与服务账号自身的撤销边界，防止旧策略映射重新附着到新服务账号上。相同版本号的重试仅触发重新加载已提交身份而不重复落盘。周期性活记录自愈（Live Healing）会直接比较源版本号（即使公开状态摘要未发生变化），并将已禁用身份一并纳入自愈源。

服务账号快照同时保留绝对过期时间，接收站点不会将本地新签发凭证的最短有效期规则重新套用到复制快照上。版本号更新但已过期的快照仍会覆盖旧密钥、在鉴权时被拒绝，并在常规加载流程中被归集为持久化服务账号墓碑。若缓存或声明加载失败，接收端会直接返回错误以触发重试，而不会提前确认成功；一旦替换提交完成，内存中陈旧的缓存密钥会被立即驱逐。若复制快照与现有内置用户或已缓存 STS 身份发生 AccessKey 类型冲突，系统会拒绝静默转换凭证类型并报错，交由管理员显式处置。

用户组的每个成员都拥有独立的 MemberGrants 授权时间戳。增删其他成员或切换组的启用状态不会刷新既有成员的授权时间。成员关系唯有在其 MemberGrants 时间戳同时晚于该用户与该组各自保留的 RevokedBefore 边界时才算有效；列表展示与 IAM 策略求值共用同一套有效成员判定逻辑。对端复制快照会保留原始授权时间戳（包括旧格式下的未知授权时间），不会把近期快照同步时间当作对已撤销身份的新授权；唯有管理员发起新的显式入组授权才能恢复其组权限。

继承自上游的活组快照合并逻辑仅作增量添加成员，不会自动消解站点断连期间漏掉的普通成员移出操作；本文机制聚焦于用户或组删除边界以及同名重建后的隔离保证。

保留期与过期回收

永久身份（内置用户、服务账号）、用户组、策略文档及策略映射的墓碑记录不设自动 TTL。断连的远端站点或旧备份可能在任意时长后重新接入；对端重放成功确认仅用于抑制重复网络发送，不作为物理回收墓碑历史的依据。

不可变 STS 临时令牌自然过期时，系统会物理删除其 token-key 记录及遗留映射，不会产生永久墓碑。而被提前显式撤销的 STS 令牌墓碑则会保留至该令牌原定过期时间加上时钟偏差容限，从而阻止带更晚事件时间戳的重放请求将其复活。etcd 后端利用原生过期租约（Lease）自动回收；对象存储后端则在既有的凭证加载与清理周期中顺带清理已过期的 STS 墓碑。过期时间未知的记录按保守策略持久保留。

可选的过期回收写入使用短锁超时预算并以尽力而为（Best-Effort）方式执行：若某次清理写入失败，当轮加载会停止可选回收、记录错误日志并继续加载正常用户；已过期凭证依然处于拒绝访问状态并保留既有持久化版本，留待下一轮加载重试。外部 IdP 身份禁用属于提前撤销而非自然过期，其关联的缓存 STS 与服务账号同样纳入清理。带过期时间的服务账号由于其 AccessKey 可被更新复用且旧版本可能未设过期时间，仍会保留持久化修订记录。

在九月 20260916 实现中，删除内置父用户通过持久化父边界即可使所有旧子凭证失效（含未出现在当前删除节点缓存中的子凭证）；而跨站点逐令牌的直接 RevokeTokens 同步则由上文十月十八日按范围撤销 STS 补齐。

自愈循环、故障处理与运维成本

每个服务进程启动单个后台自愈循环（Healing Loop）。当节点失去分布式 Leader 租约时，循环暂停等待重新获得领导权，不会永久退出；配置热重载也不会派生额外循环。每次取得领导权后以及每轮自愈完成后等待 30 秒再启动下一轮。

常规 IAM 加载器在内存中维护一份不含敏感密钥的删除记录与撤销边界索引。自愈循环直接读取该内存索引，避免在每个 30 秒周期内重复全量遍历磁盘上的 config/iam/ 目录；仅在进程启动与全量 IAM 刷新时扫描包含墓碑在内的持久化存储记录。

自愈同步按每个对端每批最多 128 条记录发送。发送方记录每个对端已确认的路径与版本号，任一站点上无关路径的新变更不会重置既有确认进度。若某批次发送失败，该批次保持挂起待重试，后续独立批次仍可继续推进；响应丢失只会触发安全的幂等重放。单轮自愈设有总时长上限，超时前已收到的成功确认会被保留。同步协议会汇报节点名称与进程实例 ID：负载均衡器在已知实例间切换不会重置确认进度，唯有检测到全新进程实例首次出现时才会保守地作废旧确认并重新核对一次。因此在从备份恢复持久化状态前，必须先停止相关服务进程，防止恢复后误复用旧进程留下的内存确认记录。

稳态运行下，自愈循环仅遍历并排序内存中的保留集合、检查对端协议状态，并在对端确认后抑制重复的删除 PUT 请求。内存占用随保留路径数与对端站点数量线性增长，冷启动存储读取量随历史记录数增长。首次升级后，若部分存量活记录此前在各接收站点上被赋予了不同的本地时间戳，升级后会触发一轮初始版本对齐写入；规划维护窗口时应预留相应的存储写入与兄弟节点通知开销。

缓存凭证查找仅比对内存中的父版本索引，不产生额外存储读取；STS 签发与冷凭证加载则会核对持久化父版本。版本 I/O 与分布式锁等待期间会释放 IAM 缓存读/写锁，由独立的本地写入互斥锁（writeMu）维护本节点写入顺序，且所有存储与 etcd 锁/租约操作均受超时上下文约束（详见 IAM 策略重载：锁粒度、请求取消与超时预算隔离）。

复制协议与协调升级要求

服务端专用的版本化复制路由为 /minio/admin/v3/site-replication/peer/iam-revisions，在内部传输源版本号、成员授权时间戳以及独立的用户/组撤销条目，不改变公开 Admin 客户端 SDK 或 S3 API。旧版本服务端会拒绝该路由，发送方会直接报告同步失败，而不会降级回退到会丢失版本元数据的旧路由。既有旧 IAM 路由仍保留读取兼容。

集群中的所有参与节点（包括未启用跨站点复制但共享同一 IAM 存储后端的节点）必须统一升级，不支持同一后端下新旧二进制混跑或滚动降级，因为旧版本二进制无法识别墓碑记录与签名父边界。请按以下维护窗口步骤执行协调升级：

1. 暂停所有 IAM 变更，并隔离状态未知的离线站点或旧备份。
2. 完整备份各站点的底层 IAM 存储及所需 KMS/加密材料；常规在线 IAM Admin 导出不包含删除墓碑历史，不能替代底层存储备份。
3. 停止共享同一 IAM 后端的全部节点，替换二进制文件后以新版本启动。所有参与站点完成升级后再恢复 IAM 写操作。
4. 检查 IAM 加载日志、站点复制状态与撤销收敛指标，验证代表性的已撤销旧凭证被拒绝、新签发凭证正常可用。
5. 显式处置升级前已遗失的撤销记录：若某些旧记录仍残留在部分站点，应在这些站点上再次执行删除；长期离线的陈旧站点应在重新接入前基于已批准的最新状态重建，切勿为了查看其旧凭证而直接将未知旧快照并网。

旧版本服务端曾为同名重建父身份签发的子凭证缺少签名父边界声明，升级后必须由新版本服务端重新签发；从未发生过删除与同名重建的父身份则完全保持既有凭证行为。

20261026 内置策略 Reset 更新： 未经修改的内置默认策略仍受保护，禁止本地直接删除。在 Server 20261026中，删除对内置策略的显式覆盖内容会立即恢复原生内置定义，并保留删除版本以拒绝旧覆盖回放（取代了 Server 20260916/20261018 阻止自动恢复默认策略的旧行为）。对端与 etcd 通知会重新加载已提交状态，保留延迟删除事件之后的新编辑；在用策略检查与自定义策略删除语义保持不变。本地删除不存在的策略保持幂等，不新增墓碑；对端同步来的未知策略删除则保留其版本记录。

如需回滚，必须先停止并隔离受影响站点，评估自备份以来的权限变更后再恢复兼容状态。恢复旧备份本身会丢失备份点之后的撤销记录，重新开放访问前必须完成权限核对与密钥轮换。切勿在线手动删除墓碑文件或仅转换活记录以强行启动旧二进制。

回归与性能验证

专项测试集位于 iam-revocation_test.go、iam-revision_test.go、iam-revision-lock_test.go、iam-revision-boundary_test.go、iam-replication-protocol_test.go、iam-credential-retention_test.go、iam-peer-reload_test.go 与 iam-replay_test.go。将环境变量 SILO_TEST_IAM_REVOCATION_ETCD 指向测试用 etcd 实例即可运行包含隔离命名空间的 etcd 生命周期、分布式锁与边界测试。

基准测试覆盖：

• BenchmarkIAMCachedCredential 与 BenchmarkIAMSetTempUser：测量缓存鉴权与临时用户签发的基线开销。
• BenchmarkIAMRevisionConvergedHealing：覆盖 1,000 与 10,000 条保留记录下的稳态内存索引遍历与零重复 PUT 断言。
• BenchmarkIAMColdLoadExpiredServices：测量存在 100 或 1,000 个已过期可复用凭证时的冷启动加载与清理耗时（使用 -benchtime=1x 运行）。

错误语义与可观测性

十月二十三日补充（pgsty/silo#250）：LDAP 长 DN：恢复登录可用性并守住 IAM 撤销安全边界区分了“单分量超过 255 字节、物理上无法存入对象后端的纯 ASCII 键”与“当前无法读取的已存在记录”。loadIAMConfigBytesWithMetadata 仅将前者按 errConfigNotFound（记录不存在）处理；完整路径超限（PATH_MAX）与真实存储故障继续按 Fail-Closed 向上报错，确保磁盘上已有的撤销墓碑绝不会被掩盖。对象存储后端仍不支持写入超长路径分量的个人策略映射或父身份版本记录。

当权威撤销版本已成功落盘、但后续附属清理步骤失败时，Admin 删除请求可能返回 HTTP 500；这并不代表旧身份仍可使用。此时应在暂停 IAM 写入与同名重建的前提下重试删除，并在各站点验证旧凭证已被拒绝。当持久化父身份版本不可读或签发记录无法提交时，STS 会通过内部错误路径（含 STSInternalError）Fail-Closed 拒绝签发，绝不通过猜测缺失边界来放行新令牌。

可通过每个进程需认证的 /minio/metrics/v3/cluster/iam 端点采集以下指标：

上述索引指标按单进程统计，对共享同一后端的多个节点直接求和会重复计数。自愈指标仅在启用了跨站点复制且当前节点持有 Leader 租约时推进；仅共享后端而未启用站点复制的部署不运行跨站点自愈循环，后三项指标为零属于正常现象。

为什么更简单的方案不成立

在多站点与离线重连场景下，以下看似更简单的方案均存在安全漏洞：

1. 直接物理删除配置记录：一旦物理删除，重新连入的离线节点或延迟复制消息将缺少判断新旧顺序的墓碑证据，导致已删除身份被旧快照重新写回。
2. 仅比较子凭证自身的更新时间（UpdatedAt）：父用户被删除并重建后，攻击者或延迟重放若对旧子凭证执行一次元数据编辑，其更新时间就会晚于父用户删除时间并借此恢复访问；而签发时写入加密令牌的 siloParentRevocation 签名父边界不会随编辑而改变。
3. 用接收节点的本地时间覆盖源事件时间戳：会破坏跨站点因果与源端顺序，甚至将一次幂等网络重试变成一次具有更新时间戳的新写入。本实现严格保留源时间戳，仅对有意的本地写入推进单调版本号。
4. 为永久身份墓碑设置固定 TTL 或仅导入导出活记录：离线站点或冷备份的断连时长无法预设上限，提前淘汰永久身份墓碑或仅恢复活记录导出会直接抹去阻止旧身份重放的历史边界。

具体实现契约参见 cmd/iam-revision.go 与 cmd/metrics-v3-cluster-iam.go。

8 - 多池对象一致性

随 SILO Server 20260916 发布的 PR #178 修复了多存储池修改顺序问题，PR #207 将当前逻辑对象选择扩展至条件 PUT（关闭 #133 与 #144），提交 fced86303 则修复了跨池再平衡（rebalance）与退役（decommission）迁移丢失对象标签的缺陷。随后的 SILO Server 20261018 进一步合入 60c7179dd（纳入 PR #248）与 1748f62c7，修复了跨池迁移期间旧数据覆盖新副本以及删除标记（Delete Marker）丢失的问题。

10 月 26 日：存储超时与回滚边界

Server 20261026 完整保留了下文的多池删除保护，并转发覆盖写回滚所需的存储 RPC 删除选项（旧数据目录）。在最终发版前，提交 dcc2f20ba 撤回了 10 月维护草稿中的已接纳 I/O 排空等待、逐对象变更锁（mutation guard）、回滚所有权校验与备份互斥方案，维持既有的磁盘/RPC 超时、请求取消、对象锁、读仲裁与自愈行为。

需要注意：客户端收到超时响应并不代表底层磁盘或 RPC I/O 已经停止，也不代表写入未提交。 在部分磁盘故障、锁租约失效或网络分区后，仍可能出现迟到提交、延迟回滚，或在部分元数据更新后短暂读到旧值与旧标签；对象锁本身不提供跨节点分布式 fencing，升级也不会自动修复存量不一致对象（更严格的诊断检查仍保留在非默认的 consistency_strict 构建标签下）。

10 月 24 日更新：删除失败时保护最新副本

PR #257（提交 aafe4f8886）将多池删除保护扩展到普通无条件删除与批量删除入口。批量数据删除复用既有共享锁与解析器，先清理非权威池中的旧副本，再删除每项的权威副本，同时完整保留请求项的响应身份、支持部分物理删除后的 quorum 重试，并保护共享远端分层引用。该修改直接作用于现有的容量加权分配器，不依赖 #245。详见多池删除：失败时保住最新副本。

10 月 18 日更新：在池迁移期间保护数据与删除标记

SILO Server 20261018 新增的 60c7179dd（PR #248）与 1748f62c7，补齐了九月修复尚未覆盖的两类 rebalance / decommission 迁移竞态：旧载荷覆盖新副本以及删除标记丢失。

在向目标池提交迁移版本前，池协调层会在共享命名空间对象锁内检查所有池中的当前副本，拒绝源快照已消失、已被替换或其他存储池中已存在更新副本的搬迁操作。若修改时间戳完全相同，则沿用读取路径的池索引决胜规则。验证通过的元数据快照会直接复用于后续字段协调，避免重复读取；多段上传（Multipart）完成阶段会在复制完所有分片后再次复核，分层对象（Tiered Object）搬迁同样启用该保护。

即便删除标记是源池中的唯一版本，迁移流程也会将其迁移至目标池，因为其他存储池中可能仍存有该键的更旧数据版本。null 版本与 UUID 版本的删除标记均保留各自的替换与重试语义。源池清理改为在对象写锁内逐一复核并仅删除遍历快照中确认过的具体版本；若源版本已发生变化，或没有任何目标池副本能继续维持当前外部读取结果，则立即中止源清理，不再盲目删除可能已包含并发新写入或新删除标记的整个对象前缀。

运行时成本与边界： 迁移流程增加了逐池元数据读取与逐版本清理。对于 $P$ 个存储池和 $V$ 个源版本，清理阶段至少执行 $\mathcal{O}(P \times V)$ 次元数据操作，且解码与重写版本元数据的开销随版本历史长度增长。普通已解析的读取请求不会进入该迁移检查路径；本修复未引入新的磁盘格式、公开 S3 参数或外部依赖。历史版本迁移中已经丢失的数据、标签或删除标记无法自动重建，跨站点延迟到达的删除标记问题（#217）仍属独立议题。

版本验收测试实际运行了 2 池与 3 池的 rebalance 和 decommission，完整覆盖普通对象、多段对象、null/UUID 版本与删除标记、并发写删以及双池迁移中断恢复四组场景（详见 20261018 发布验证记录）。在生产环境正式退役源池前，应通过公开 S3 API 核对已确认的版本 ID、字节数、ETag、标签及删除状态。

为什么同一个键会存在多份物理副本

扩容存储池、退役旧池或清理中途中断，都可能在不同存储池中留下同一个对象键的多份物理副本。单纠删集（per-set）锁无法与路由到另一存储池的并发写入串行化；仅读取第一个响应的副本也无法证明其 ETag、标签或 Object Lock 保留期代表当前的逻辑对象。

缺乏跨池协调会导致三类典型故障：

1. 某个池中的陈旧 ETag 错误地满足了条件写入（If-Match / If-None-Match）或条件删除；
2. 某个池中较新的保留期（Retention）或法务锁定（Legal Hold）被另一池中较旧的对象元数据遮蔽；
3. 删除当前选中的副本后，另一池中的旧副本重新暴露，导致已删除数据“复活”。

孤立地操作每个存储池并在最后仅汇总成功状态，无法消除上述并发竞争。

共享选择与锁边界

在 cmd/erasure-server-pool-consistency.go 与 cmd/erasure-server-pool.go 中，池协调层在“选择候选对象”到“完成修改”的全过程中持有同一把命名空间对象锁。objectPoolInfos 会读取每个池（包括正在排空的退役池）中的指定版本；未知或不可读状态会被直接判定为错误，而不会当作“对象不存在”的证据。各池副本按修改时间（ModTime）排序，时间戳相同时以存储池索引决胜。

不带 versionId 的元数据请求会先选定逻辑当前版本，再收集所有池中属于该特定版本的物理副本，绝不混合不同对象版本的元数据。Object Lock 保留期、法务锁定和用户标签各自拥有独立的源修订时间戳；mergedPoolObjectInfo 按各字段自身的修订时间戳顺序合并，而非把对象数据本体的修改时间当作所有元数据字段的版本号。带时间戳的标签清空或锁定解除同样作为显式状态参与排序。

元数据修改、相关对象写入与后台自愈（healing）共用同一把协调锁。需注意，该锁用于串行化并发访问，但并非跨池回滚事务——若在多池落盘中途遭遇底层磁盘故障，已完成写入的池不会自动回滚。

条件请求与删除

对于条件 DELETE，协调层在执行跨池清理前针对选定的逻辑对象统一校验一次前置条件，并在调用下层各池删除接口前清除条件回调；若请求指定了显式 versionId，则针对该特定版本进行比对。

对于条件 PUT，PR #207 在外层命名空间锁保护下先跨所有可用池选出最新的逻辑对象表示（包括删除标记状态），再写入新内容。这修复了目标池中残留的陈旧副本导致 If-Match / If-None-Match 判断结果与集群当前逻辑对象不一致的缺陷。在下一版本 SILO 构建（PR #292，提交 1f3377862 与 af3064f2b）中，PutObject、NewMultipartUpload 与 CompleteMultipartUpload 共用 checkCurrentPreconditions：条件分片上传初始化同样在池协调层写锁保护下跨池评估当前逻辑对象的前置条件，并在放置上传记录期间持续持有写锁；分片完成前置条件失败时保留已上传分片以便重试。

若跨池清理或元数据传播在修改了部分物理副本后遇到存储错误，恢复后应重新核对对象状态并重试。批量 XML DeleteObjects 的 ETag 条件仍不受支持，详见条件 DELETE 设计说明。

Object Lock 与桶复制

副本写入会跨所有存储池与同版本的权威副本协调目标端保留期和法务锁定状态，防止乱序到达的旧副本缩短较新的保留期或关闭较新的法务锁定。对象标签同样携其修订时间戳（包括表示删除的空值）一同传递与比对。详见 Object Lock 复制顺序保护与复制标签顺序一致性。

跨池迁移中的对象标签保持

rebalance 与 decommission 会将每个对象版本读取为 FileInfo，再转换为 ObjectInfo——这一步会将内部标签头从普通 UserDefined 元数据映射表移至独立的 UserTags 字段——随后再将对象写入目标池。自 2022 年引入迁移写入逻辑以来，四个迁移写入入口仅复制了普通 UserDefined 元数据映射表，导致普通对象与多段对象在 rebalance 和 decommission 过程中均会丢失用户标签（2020 年引入的字段拆分本身并无问题）。

提交 fced86303 让四个迁移写入入口共用统一的元数据组装函数：在既有协调锁保护下克隆元数据映射表、写回 UserTags，并原样保留已落盘的标签修订时间戳字段而不伪造新时间戳。回归测试覆盖了普通对象与多段对象、初始标签、更新后标签、清空标签以及版本化与旧格式读取。此前在旧版本迁移中已丢失的标签需从源端或备份恢复。

验证与运维指引

cmd/erasure-server-pool-consistency.go 与 cmd/erasure-server-pool.go 中的多池协调实现已通过多存储池、陈旧副本、删除标记、显式版本、并发写入及故障路径测试验证。

在依赖共享锁一致性保证前，请协同升级集群中的所有参与节点。对于此前曾执行过跨池迁移或多池并发写入的存量部署，建议结合副本元数据审计手册与组件版本矩阵盘点存量副本、标签及 Object Lock 状态。

9 - 联邦 CopyObject：保持目标对象契约

Server 20260916 通过 PR #157、PR #159、PR #163、PR #177 与 PR #179 修复了旧版 etcd 存储桶联邦（bucket federation）的 CopyObject 转发路径。当代理节点将跨集群复制作为远端 PutObject 转发到目标集群时，代理节点流式读取并发送源对象的逻辑字节，由目标端执行加密与 Object Lock 规则，校验完整对象校验和，并原样返回目标端实际提交的写入元数据。

转发一次逻辑字节，由目标端执行加密

代理节点在本地按需解密并解压源对象，读取其逻辑字节流，并在向目标集群发起的 PutObject 请求中声明逻辑字节长度：

• 禁止双重转换： 代理节点绝不在本地预先加密或压缩后再转发给远端重复处理。
• SSE-C 与 SSE-KMS 边界： 读取 SSE-C 源对象仍要求提供源客户密钥并使用安全传输。新对象的加密方式完全由客户端显式携带的目标 SSE 请求头或目标桶自身的默认加密配置决定；当客户端未指定加密头时，代理节点不会注入本地默认加密配置。SSE-KMS 上下文按标准 JSON 对象格式转发。
• 拒绝原始 SSE-C 副本复制： 联邦路径在创建目标对象前以 501 NotImplemented 显式拒绝可信原始 SSE-C 副本的 CopyObject 请求。

校验和与元数据过滤规则

普通转发写入按大小写不敏感规则剥离所有保留的内部元数据前缀，仅通过标准 S3 字段转发公开的用户元数据与对象标签。转发写入的校验和必须描述实际写入目标端的完整逻辑对象：

• 整对象校验和转换： 当请求显式指定校验和算法，或源对象携带分段复合校验和（COMPOSITE）时，目标端必须生成并保存整对象校验和（FULL_OBJECT）。
• 流式 trailer 与请求头传递： 非空对象流通过 x-amz-trailer 传递尾部校验和并由目标端验证；零字节对象无流式尾部，改用普通 x-amz-checksum-* 请求头；源对象已有的 FULL_OBJECT 校验和可直接作为普通校验和请求头转发给目标端验证。
• 远端响应校验： 若远端 PutObject 响应缺失必需的校验和、格式非法或仍带有分段 -N 后缀，代理节点直接报错，不会将其包装成合法的整对象结果。由于报错时远端写入可能已经落盘，针对版本化桶重试前应先检查目标端实际生成的版本。

Object Lock 头部类型与时间精度

代理节点通过类型化的 LegalHold 客户端选项转发法律保留状态，确保请求发送标准的 x-amz-object-lock-legal-hold 请求头，而非误转为 x-amz-meta-* 用户元数据。对象保留期（Retention）时间戳完整保留亚秒级精度，不再截断为整秒。目标端继续独立执行权限认证与桶级 Object Lock 校验。

返回实际提交的目标写入身份

CopyObjectResult XML 响应与 ObjectCreated:Copy 事件均直接采用目标端本次写入返回的键名、逻辑大小、ETag、精确 VersionID 与修改时间。代理节点既不在本地伪造修改时间，也不通过后续不带版本号的 HEAD 请求二次读取（避免并发写入下读到其他版本的元数据）。当请求指定了源 versionId 时，源版本响应头继续标识所选中的源版本。

源码与测试索引

• 实现源码： cmd/object-handlers.go、cmd/object-handlers-common.go（PR #157、PR #159、PR #163、PR #177、PR #179）
• 回归测试： cmd/object-copy-federation*_test.go、cmd/object-federation-time_test.go
• 关联记录： SSE-C 副本完整性 · Object Lock 复制排序 · 组件版本矩阵

10 - 复制可靠性：删除完成、MRF 可见性与 resync 取消

本文记录随 Server 20260916 交付的三轮复制可靠性修复的问题分析、方案取舍与验收结论：

• 第一轮（PR #162，合并为 d1105bbb）： 修复 #153、#152 与 #137，分别涉及请求入口的操作分类、后台恢复队列的可观测性以及任务取消生命周期。
• 第二轮（PR #196，提交 0c61128d2）： 修复复制工作协程（worker）的删除出口、外层状态聚合与持久化 MRF 标记恢复路径（见第二轮小节）。
• 第三轮（提交 eb4f5e5b3、254b19ac0 与 358ab38fb）： 修复指定版本清除（purge）的磁盘写回与仲裁语义、删除标记自愈元数据保留，以及清除后排队创建任务的过期复核（见第三轮小节）。

整体判断与系列边界

本系列修复遵循同一工程准则：在拥有对应不变量的最小模块边界内修复已复现的缺陷，复用现有后台恢复机制，并用确定性测试验证收敛。

这一系列此前已分别闭合另外两项复制不变量：

• #136 / PR #138 修复了计数完整性：先接收并累加最后一个结果，再持久化终态，不再依赖一分钟一次的周期性刷新。
• #139 修复了结果真实性：仅当目标端本次复制请求实际成功时才计入成功，不再因目标端已有同名对象而误判。
• #137 修复了取消与资源生命周期：取消指令下达后，目录遍历器（walker）、工作协程与结果收集器均能及时退出，且已终止的旧任务不会覆盖新任务状态。

复制请求是否有权使用内部特权语义，由鉴权前不做 I/O，Header 不产生权限定义；跨存储池的 Object Lock 权威状态选择由 #133 跟踪并在 #178 中修复，详见多池对象一致性。

#153：先分清复制删除标记，还是永久删除版本

报告与复现为什么不完全相同

原议题报告称生命周期管理（ILM）与复制共同触发了持续的 HTTP 405 请求风暴，并建议将删除标记探测返回的 405 一律视作完成。源码核查与本地复现表明，这一归因并不准确，直接采纳该补丁会破坏删除一致性。

以 450dcb848 为基线，测试启动两个本地构建的 SILO 服务端实例，配合 mcli 与 minio-go 客户端进行验证。排查发现：mcli 即使只删除单个对象键，也会调用批量 DELETE 接口；而批量删除的分类逻辑原本就是正确的。 因此必须直接发送单对象 S3 DELETE 请求才能触发故障路径。

如果只检查远端版本是否消失，就会漏掉源端 xl.meta 残留的 PENDING 状态。本地实验复现了首次 purge 的分类错误、完成状态误写以及一次多余的 HEAD 探测；但由于现有的 scanner/heal 与 resync 已经按 purge 状态走正确分支，并不会产生持续的 405 风暴。

一处分类修正为什么足够

永久删除一个已有的删除标记时，对象层会同时返回 DeleteMarker=true 和非空的 VersionPurgeStatus：前者表示被操作版本的对象类型，后者表示当前正在执行永久清除，二者并不矛盾。

旧版单对象删除处理函数仅检查 DeleteMarker，直接将版本 ID 填入 DeleteMarkerVersionID。复制完成后，工作协程随之更新了普通的 ReplicationStatus，而非待完成的 VersionPurgeStatus。DeleteObject 处理函数中的修复逻辑如下：

if objInfo.DeleteMarker && objInfo.VersionPurgeStatus.Empty() {
    dmVersionID = objInfo.VersionID
} else {
    versionID = objInfo.VersionID
}

这一判断条件与批量删除、scanner/heal 及 resync 的既有逻辑完全对齐，无需调整磁盘存储格式或新增后台恢复任务；历史遗留的 PENDING 记录仍由现有的 scanner/heal 清除路径自动回收。

为什么不把 405 一律视为成功

对带版本号的对象发送 HEAD 请求收到 HTTP 405，仅说明“目标端存在该版本的删除标记”。对于复制删除标记，这代表目标端已就位，可按幂等成功处理；但对于永久删除该版本，405 恰恰说明目标端的删除标记尚未清除。

如果在收到 HEAD 405 时直接写入 VersionPurgeComplete，源端就会清理本地元数据，而目标端仍残留本应删除的标记版本。同理，远端返回的 403、405、503 等错误均代表删除未完成，必须按失败重试处理。

追溯提交历史可以看到，仅按 DeleteMarker 分类的逻辑源于上游 2020-11-19 的提交。2023-07-10 的优化将入队判断条件从 dsc.ReplicateAny() 改为检查返回对象的复制状态与 PENDING 清除状态，但保留了仅按 DeleteMarker 赋值的分支；2025-04-02 的提交又在该处将 Pending 枚举替换为 replication.VersionPurgePending。

#152：让有界 MRF 队列的丢弃行为可见

MRF（Most Recent Failures）队列用于暂存近期失败的复制任务，以便后台快速重试。该队列设有明确容量上限：mrfSaveCh 容量为 100000，单条任务最大重试次数 mrfRetryLimit 为 3；当 RetryCount > mrfRetryLimit 或通道已满时，队列会淘汰该条目。源对象及其待复制状态仍保留在磁盘上，被内存队列淘汰的条目后续由后台 scanner 扫描并重新发起恢复。

此前的缺陷在于：TotalDroppedCount 与 TotalDroppedBytes 虽在内部原子递增，却未写入两处管理统计快照，也未注册到 Prometheus v2/v3 指标中。使用容量为 1 的确定性测试夹具可以稳定复现：1 条任务成功入队，20 字节的通道溢出条目与 30 字节的超限重试条目被淘汰后，内部计数为 2 / 50，而管理接口仍返回 0 / 0。

选定的最小改动

1. 在两处管理统计快照中原子读取并填充现有的丢弃计数。
2. 在 Prometheus v2 与 v3 中注册并导出对应的累计计数器。
3. 在重试超限与 MRF 通道已满这两个实际丢弃点记录去重警告，使用固定的日志消息与去重键，避免因计数值变化使日志去重失效。普通工作队列溢出转入 MRF 时并未丢弃任务，不在该处触发丢弃告警。
4. 普通对象复制、自愈与删除路径统一按 (bucket, objectName) 计算工作协程哈希，保证同一对象的操作路由到同一个 worker。

这组指标统计服务端启动以来的累计丢弃量，重启后归零。操作数按队列条目计数，同一对象的多次失败会重复累加；字节数统计已知的对象大小，删除条目记为零字节。运维监控应关注其增长速率，并结合复制积压量与目标站点健康状态综合判断。

本次修复保持原有队列容量与重试次数上限不变，由有界队列控制内存占用，由后台 scanner 承担最终兜底恢复。

#137：绑定单次运行的 resync 取消生命周期

一个共享 token 无法取消一组多桶任务

原实现在取消 resync 时，仅向全局共享通道写入一个不带任务标识的 token。而一次站点级 resync 可能涵盖多个桶（最多 10 个桶并发执行），分发器（dispatcher）与多个工作协程又会竞争消费同一个通道。这会导致只有单个桶停止、无关任务误消费取消信号，或者残留的 token 错误中止后续发起的新任务。

此外还存在两处阻塞死锁：从目录遍历器 Walk 的输出通道读取时未监听取消信号；向已满的 worker 通道发送任务时同样未监听取消信号。一旦 worker 先行退出，dispatcher 就会永久阻塞在无人接收的通道上。同时，Walk 直接复用了父级 context，函数提前返回时无法通知底层的遍历协程退出。

状态管理同样存在漏洞：站点级 updateState 修改了栈上局部变量却未写回 map；桶级 Canceled 分支处理缺失；已取消任务的延迟收尾（finalizer）还可能将状态重新覆盖为 Completed。

注册、取消与状态使用同一个写入边界

修复后，每个 resyncBucket 任务在等待并发槽位之前先创建专属的 context.WithCancelCause 并完成注册。注册与 cancelResyncID 共用 resyncer 的状态互斥锁：

• 注册时校验复制目标仍然有效、resync ID 仍然匹配，并立即检查当前是否已处于取消状态。
• 取消时先将同一 resync ID 下所有处于 Pending 或 Started 的记录标记为 Canceled，随后逐一取消已注册的对应 context。
• 已注册但仍在等待并发槽位的任务能立即收到取消信号；取消发生后才尝试注册的任务也会直接读到已取消状态并退出。
• Walk、任务分发、worker 执行与结果发送全程监听当前运行专属的 context；不同 resync ID 之间互不干扰，也不会在通道中残留取消 token。

站点级启动与取消的配置准备阶段由专用操作锁串行化；即使部分桶的目标配置更新失败，已启动任务的取消动作仍会照常执行。桶级收尾函数与进度更新均会核对当前目标与 resync ID，自动忽略已被移除、替换或取消的旧任务结果；站点级状态正确写回 map，Canceled 终态不会再被迟到的 Completed 覆盖。

成功与失败的收尾顺序不同

任务收尾必须严格保持 #136 建立的契约——待结果收集协程处理完最后一条结果后再持久化终态：

正常完成：关闭 worker 输入 → 等待 worker 退出 → 排空结果通道
          → 持久化终态 → 归还并发槽位 → 取消专属 context 并注销

失败/取消：先取消 context 解除阻塞 → 等待 worker 与结果收集器退出
          → 持久化对应终态 → 归还并发槽位 → 注销

如果在正常完成路径上先取消 context 再等待 worker，尚未处理完的任务就会被提前中断，导致原本成功的运行变成 Failed。最终实现通过单一 defer 调用 finish，按固定顺序完成清理，无需额外引入 sync.Once。

借助 WithCancelCause，代码能够区分用户主动取消与服务关闭导致的父级 context 中断：用户取消记录为 Canceled；父级中断则不会将未跑完的任务误记为 Completed；若任务在等待并发槽位期间遇到服务关闭，则保留原有的 Pending 状态，以便重启后自动恢复。

取消终态与恢复任务也必须受保护

在检查 context 状态与落盘保存终态之间仍可能并发到达取消请求。因此 markStatus 在持有状态锁时，若发现内存状态已变为 Canceled，即使收尾流程此前计算出的结果是 Completed，也必须保持 Canceled；同时拒绝旧 resync ID 覆盖新任务的状态。

若某个桶在站点级取消到达前已完成并落盘，最终状态会记录为该桶 Completed、站点整体 Canceled。锁内状态检查确保已进入 Canceled 状态的任务不会被迟到的完成信号改写为 Completed。

在重启恢复路径上，loadResync 原本在启动后台恢复协程后立即执行 defer cancel()。核查 SILO 的分布式共享锁实现确认，该 cancel() 会直接终止合并后的 leader context，导致恢复协程被立即取消。修复方案引入 WaitGroup，保持该 context 存活至所有恢复协程退出；当节点失去 leader 身份时，底层 context 仍会按预期触发取消。此外，从磁盘加载历史状态时也不会覆盖内存中更新的启动或取消状态。

设计审查与复杂度取舍

针对基线复现与备选方案的评审结论汇总如下：

此外，低频的 resync 启动操作在状态锁内完成配置读写，与终态落盘保持同一锁边界；活跃任务注册表直接复用包含 resyncBefore 的 resyncOpts 作为键。

验收证据与可复验入口

所有修复均遵循“先在未修改基线上编写失败回归测试，再提交生产修复”的流程。新增测试直接驱动生产环境处理函数、纠删码存储层、Prometheus 指标注册表与 resyncBucket 完整流程。

固定提交上的回归测试文件：删除标记、MRF 可见性、取消生命周期。复现与验证命令：

go test ./cmd -run '^(TestReplication|TestReplicateDeleteMarker|TestResync|TestSiteResync)' -count=1
go test -race ./cmd -run '^(TestReplication|TestReplicateDeleteMarker|TestResync|TestSiteResync)' -count=1
go test ./cmd -run '^TestResyncCancel' -count=100
go test ./... -count=1 -timeout=30m

后续维护原则

复制与 resync 的回归测试需分别断言五项独立不变量：操作类型判定准确、队列淘汰可观测、单对象复制结果真实、终态计数完整、取消后协程与并发槽位完全释放。

第二轮（2026-09-16）：worker 侧 purge 分类与持久 MRF 恢复

第一轮在 HTTP 请求入口修正了删除分类（#153）、公开了 MRF 队列丢弃计数（#152）并闭合了 resync 取消生命周期（#137）。第二轮——PR #196，提交 0c61128d2，集成验证记录 aea3882c9——深入到后台复制链路，修复了 worker 自身的删除出口、外层状态聚合，以及删除标记的持久化 MRF 恢复路径。

第二轮排查出的遗留缺陷

• 旧形态任务被整体跳过。 当任务的 VersionID 为空、DeleteMarkerVersionID 非空、目标端创建状态为 COMPLETED 且清除（purge）状态为 PENDING 时，目标侧的“创建已完成”早退分支会直接跳过该任务，导致永不发出 DELETE 请求。
• 仅修复内层目标函数会导致外层状态误报。 外层状态聚合原本以 VersionID 与创建状态为键；若仅放行内层函数，执行失败的旧形态清除任务会被外层汇总为 COMPLETED，触发 ObjectReplicationComplete 事件并跳过持久化 MRF 入队。
• 持久化 MRF 恢复路径丢弃了所有删除标记的 405 响应。 重放磁盘 MRF 中针对删除标记版本的条目时，本地读取会返回真实的删除标记元数据与 MethodNotAllowed 错误；原错误处理分支直接将其丢弃，导致删除标记无法通过持久化 MRF 恢复。
• 状态覆盖与重复发送。 失败的清除操作会覆盖已成功的 resync 标记，已完成的清除操作被重复发送，而尚未就绪的 HEAD 探测也会无条件覆盖创建状态。
• 多目标空状态解析错误会破坏创建元数据。 当磁盘上的删除标记仅含创建元数据、而内存任务携带清除状态时，正则解析会将两个空的目标状态误判为 Pending；随后的已删除标志守卫会将整个创建元数据块重写为带新时间戳的空记录。

根因在于三处缺失：首先，worker 缺少任务级的清除判定（社区 PR #184 提出的按单目标判定谓词存在缺陷，复合清除状态经该分支处理后永远无法收敛为 COMPLETE，但 Julien Laurenceau 的问题排查与提案为本轮修复提供了重要参考）；其次，MRF 恢复路径缺少识别合法删除标记 405 响应的准入条件；最后，删除任务未携带重试计数，导致 mrfRetryLimit 上限在删除路径上形同虚设。

第二轮修复方案

• 统一出口的清除判定。 新增 isVersionPurge()（当 VersionID 非空，或 DeleteMarkerVersionID 非空且携带复合清除状态时为真），同时驱动内层单目标执行函数与外层状态聚合。清除路径退出时仅更新 VersionPurgeStatus，并将 ReplicationStatus 留空（存储层将其视作“不修改创建复制状态”）。
• 三字段清空守卫。 在清除路径上显式清空创建复制相关的三个状态字段，彻底阻断多目标空状态在落盘时触发正则误判的可能。
• 发送规范的永久删除请求。 清除操作统一携带显式 versionId 与 ReplicationDeleteMarker=false，不再执行前置 HEAD 就绪探测（权限校验直接由 DELETE 请求完成），同时防止网络丢包重试在无版本回退路径上意外重建删除标记。
• MRF 恢复的 405 身份校验。 重放 MRF 收到 MethodNotAllowed 时，仅当返回对象确系删除标记、桶名/对象名/版本号完全匹配且修改时间非零时，才重新入队调度恢复。
• 有界重试预算。 删除任务新增重试计数器，在全部三个持久化 MRF 入口（聚合失败、获取锁失败、内存队列满回退）递增并受 mrfRetryLimit 约束；超过上限淘汰后，仍可由后台 scanner 重新发起自愈。
• 审计与事件状态兼容映射。 仅在统计与事件通知边界将 COMPLETE 映射为 COMPLETED，复用既有常量定义。

405 的准确含义

对于创建操作（将删除标记复制到目标端），对目标标记版本发起 HEAD 收到 405 意味着目标标记已经存在，可视作幂等完成。对于清除操作（永久删除指定版本），MRF 恢复阶段探测本地版本收到带完整标记身份的 405 意味着本地标记仍在、尚待清除；清除操作本身的成败完全取决于远端 DELETE 请求的响应，DELETE 返回 403、405 或 503 均计为真实失败。空版本或 null 版本的标记返回的是 ObjectNotFound 而非 405，不会进入该分支。

实现边界

旧形态内存任务不会跨重启持久化，当前代码也已不再生成该形态，保留其兼容分支主要作为防御性保护。未配置远端客户端的目标站点仍仅记录日志；单目标级 resync 覆盖部分清除状态属于既有行为，不在本轮修改范围内。同系列可靠性修复中的标签排序与副本元数据归一化，另见复制标签排序与副本元数据归一化。

第三轮（2026-09-16）：指定版本清除、标记 heal 与过期的排队创建

第二轮确保了 worker 的清除出口如实反映执行结果。第三轮——提交 eb4f5e5b3、254b19ac0 与 358ab38fb，随 Server 20260916（40220bd836cbd066ca424fa4dc5dbb90057fb55a，配合 silo-pkg 6f27ee6）发布——进一步修复了指定版本清除在底层磁盘上的写回与仲裁逻辑，以及排队中的创建任务在版本清除之后乱序执行的问题。该问题由三站点容器集群测试（三个站点，每站点 4 进程 16 盘，EC 12+4）暴露：一个已被永久清除的删除标记在两个目标站点上死灰复燃，而源站点却仍返回正常的数据版本。

第三轮排查出的遗留缺陷

• 清除操作反而会在缺盘上创建待删标记。 查找层为了标记版本可见性，将待清除版本打上了已删除标志；而清除写回路径把该标志当成了“写入删除标记”的落盘指令。结果原本没有该标记的磁盘反而被写入了新标记，使清除了一半的磁盘组在反复重试中来回翻转、无法收敛。
• 过早确认版本缺失。 读取路径只要看到半数磁盘报告版本不存在，就判定该版本已缺失；导致清除重试直接返回 204 成功，而实际上仍有最多一半的磁盘残留着该删除标记。
• 自愈（heal）删除标记会抹掉其复制元数据。 自愈路径在重建删除标记时传入了空的元数据映射。修复后的删除标记丢失了原有的复制与清除状态，重新退化为待复制状态，随后被当作全新创建的标记再次复制到远端。
• 排队中的创建任务在清除完成后延迟执行。 针对处于 pending 状态的删除标记，每次 GET/HEAD/LIST 请求、后台 scanner 以及 MRF 都会入队一个携带当时标记快照的创建任务；来自多个前端节点的任务在单对象复制锁前排队串行执行。在复现时序中，用户的永久清除请求先在两个目标站点完成确认；约 85 毫秒后，排队中的创建任务携带相同的 VersionID 与原始修改时间抵达两个目标站点。由于目标站点此时已无该版本，且请求报文中没有任何字段能区分“首次创建”与“过期的乱序创建”，两个目标站点各自重新创建了 16/16 份删除标记，而源站点为 0/16 份。

第三轮修复方案

• 单点判定清除意图（isVersionPurge）。 仅当请求携带合法的显式 VersionID，不含创建删除标记、前缀匹配、数据迁移、免版本控制、过期或生命周期转换选项，且复制状态为“清除已完成”、“无复制状态”或“可信副本请求”之一时，才判定为永久清除。清除路径绝不设置创建删除标记的落盘标志，并将“磁盘已完成物理删除”与“磁盘确认版本不存在”两类响应合并计入成功票数。仅当实际删除了磁盘上存储的删除标记时，响应才标识为删除标记；此前清除仍处于 pending 状态的数据版本则按正常数据版本返回。
• 确认版本缺失必须满足写仲裁多数（N/2+1）。 当重试清除在查找阶段发现版本缺失时，会重新读取每一块磁盘。若明确报告“版本不存在”的磁盘不足 N/2+1 块，则按写仲裁不足返回失败；只要任意磁盘仍残留副本，就触发 MRF 自愈。离线、损坏或读取报错的磁盘绝不计入“版本不存在”票数。多存储池层对查找阶段跳过的存储池执行同样的多数派核查，副本接收端则按版本号跨存储池解析清除请求。
• 自愈删除标记保留完整持久化元数据。 自愈路径完整复制删除标记原有的持久化元数据表，仅剔除自愈、数据迁移与分层相关的临时操作键。类型化状态生成逻辑仅用于不带存量元数据的新建写入，且不再伪造时间戳。
• 发送前在复制锁内复核源端状态。 删除复制 worker 在向远端发送创建请求前，先在对象复制锁内重读源端对应版本。若该版本已不存在、不再是删除标记或已进入清除流程，则判定该排队任务已过期并直接丢弃，不修改源端状态；若重读因临时故障无法得出确定结论，则交由 MRF 重试，而不直接视为版本缺失。

证据与边界

在两组三站点分批故障恢复测试（涵盖源站点重启与不重启、单个目标站点分两批恢复上线）中，集群均在约 15 秒内完成收敛，并在随后 450 秒的观测窗口内保持完全一致。过期排队创建乱序复现用例在未合入修复的 main 分支上稳定复现失败，合入修复后在单盘与 16 盘纠删码夹具上全部通过。

源端复制锁内的发送前复核无法拦截已经发往网络的数据包，也无法拦截其他站点重放的创建请求；彻底消除这一跨站点乱序窗口需要在接收端持久化清除记录或引入单调序号，已由 #217 独立跟踪。此外，若某次清除刚达成多数派确认、所有服务端进程随即同时崩溃，此前离线磁盘上残留的少数派副本最多会保留七个后台扫描周期，在此期间所有前端读取仍一致返回正确的数据版本。

11 - FULL_OBJECT 校验和复制：在初始化上传时保留类型

Issue #254 报告了一类复制故障：使用 FULL_OBJECT CRC32 或 CRC32C 校验和的分片上传对象在源端可正常上传和读取，但复制到目标端并在最后调用 CompleteMultipartUpload 时会因 400 BadDigest 失败。Denis Babchuk（@botdeniska）提交的 PR #255 补回了出站复制请求遗漏的校验和类型头。

该补丁于 2026 年 10 月 24 日以 6d890fc86 合入主干并随 Server 20261026 发布，共修改 5 行生产代码（含 2 行注释） 并新增 257 行回归测试。

故障现象

当分片上传对象的校验和类型记录为 FULL_OBJECT、算法为 CRC32 或 CRC32C 时，启用桶复制或站点复制会出现以下现象：

• 原始分片上传在源端成功完成，源端版本可正常读取。
• 复制发送端将所有分片传往目标端后，目标端在 CompleteMultipartUpload 阶段返回 400 BadDigest。
• 源端对象复制状态停留在 FAILED，目标端无法生成该版本的完整副本。
• 后续每次复制重试（包括对 FAILED 版本执行 HeadObject 触发的重入队）都会重新传输全部分片字节，并在完成阶段再次因同一错误失败。

分片 CRC64NVME 对象不受影响，因为接收端默认将 CRC64NVME 解释为 FULL_OBJECT；普通单次 PUT 与分片 COMPOSITE 上传也正常。此外，对受影响的分片 FULL_OBJECT 对象执行服务端 CopyObject 后再复制，会触发下文所述的另一条故障路径。

根因：仅转发算法无法区分校验和类型

对于分片 CRC32 和 CRC32C，同一算法支持两种截然不同的对象级校验和计算方式。设 P1 ... Pn 为各分片的字节内容，|| 表示字节拼接：

即便分片上传只有一个分片，这两种方式算出的摘要也通常不同。仅转发算法名称与摘要值，不足以还原校验和语义。

复制发送端代码中的完整故障链路如下：

1. putReplicationOpts() 调用 getCRCMeta() 构造对象校验和请求头。旧实现保留了摘要值和 x-amz-checksum-algorithm，但丢弃了 x-amz-checksum-type。
2. replicateObjectWithMultipart() 将这些选项传给目标端的 NewMultipartUpload。当算法为 CRC32 或 CRC32C 且未指定类型时，目标端默认将该分片上传初始化并持久化为 COMPOSITE。
3. 发送端传完各分片后，再次通过 getCRCMeta() 构造完成阶段的对象级校验和头，其中携带的摘要仍是源端的整对象（FULL_OBJECT）CRC。
4. 目标端的CompleteMultipartUpload 校验逻辑读取初始化时持久化的 COMPOSITE 类型，将收到的整对象 CRC 与“分片 CRC 的复合 CRC”进行比对，因摘要不匹配返回 BadDigest。

核心不变量：复制必须在初始化与完成两个阶段同时保留校验和的算法、摘要值与类型解释方式，使目标端按与源端一致的规则执行完整性校验。

历史演进与上游回归来源

上游 MinIO 于 2025 年 8 月 22 日在 PR #21535 中合入提交 4ea6f3b06，从 getCRCMeta() 中删掉了校验和类型转发。在那之前，getCRCMeta() 会无条件转发所有校验和的类型；但直接回退到无条件转发又会破坏普通单次 PUT 的 SHA 校验和复制（见下文）。

此前 SILO 针对分片完成阶段做过三项相关修复，均处于不同链路环节：

最小修复实现

在 getCRCMeta() 复制已识别的校验和摘要与算法之后，新增三行判断：

if isMP && cktype.CanMerge() && cs[xhttp.AmzChecksumType] == xhttp.AmzChecksumTypeFullObject {
    meta[xhttp.AmzChecksumType] = xhttp.AmzChecksumTypeFullObject
}

三个条件分别约束了精确的转发范围：

• isMP：解码自已落盘校验和的分片元数据标记（不要求当前对象的 ETag 一定是带 -n 的分片格式）。
• cktype.CanMerge()：复用既有算法能力判断，仅匹配支持将分片 CRC 合并为整对象 CRC 的算法（CRC32、CRC32C 与 CRC64NVME）。
• cs[xhttp.AmzChecksumType] == xhttp.AmzChecksumTypeFullObject：仅当源端持久化类型确为 FULL_OBJECT 时才转发，绝不改动 COMPOSITE 对象。

由于分片复制的初始化阶段（NewMultipartUpload）与完成阶段（CompleteMultipartUpload）共用 getCRCMeta()，这一处修改同时补齐了两个阶段的请求头。逐分片上传请求读取的是不含对象级类型的分片校验和映射，其请求头保持不变；CRC64NVME 则显式携带与其默认行为一致的 FULL_OBJECT。

为什么不能转发所有已存类型？

普通单次 PUT 上传的 SHA1 或 SHA256 对象，在内部存储和读取元数据中同样会标记为 FULL_OBJECT。但在 S3 请求侧，getContentChecksum() 解析器会拒绝为不可合并算法（如 SHA1、SHA256）显式指定 x-amz-checksum-type: FULL_OBJECT。

若无条件转发所有已存类型，单次 PUT 的 SHA1/SHA256 对象在复制时反而会被接收端拒绝。通过 isMP && cktype.CanMerge() 收窄条件后，分片 CRC 请求得以恢复，同时普通单次 PUT 与 COMPOSITE 上传的既有请求头完全不受影响。

CopyObject 自动恢复单次 PUT 复制路径

对分片 FULL_OBJECT 对象执行服务端 CopyObject 后，生成的新对象不再带有 -n 分片 ETag（!objInfo.isMultipart()），但其底层校验和元数据仍保留分片 FULL_OBJECT 标记。由于 FULL_OBJECT 摘要本身就是完整对象字节的 CRC，通过单次 PutObject 传输到目标端后依然完全有效。

putReplicationOpts() 中原本就包含针对该场景的路由分支：

if !objInfo.isMultipart() && cs[xhttp.AmzChecksumType] == xhttp.AmzChecksumTypeFullObject {
    isMP = false
}

修复前，由于 getCRCMeta() 丢掉了 x-amz-checksum-type，上述条件永远为假，导致 CopyObject 生成的对象被错误路由到单分片 Multipart 复制路径并同样触发 BadDigest。在 getCRCMeta() 补回类型后，这段既有路由逻辑自动生效：此类对象直接通过单次 PutObject 完成复制，无需额外编写 Copy 专用分支或重算校验和。

备选方案取舍

验证与实机验收

在合入前的基线 aafe4f888 上运行新增回归测试：FULL_OBJECT CRC32/CRC32C 复制稳定复现 BadDigest，CopyObject 用例在路径选择断言处失败（got true, want false）；应用补丁后全部通过。

入库的单元测试与集成测试包含 8 个请求头表驱动用例（含逐分片请求头检查）和 8 个双版本桶 API 集成用例，验证复制路径选择与两端校验和元数据一致性。

独立实机验收启动两个单盘 SILO 服务端实例，通过 mcli 配置站点复制，实测 12 个端到端用例：

全部 12 个用例均达到源端 COMPLETED、目标端 REPLICA；独立计算的校验和摘要与类型、版本 ID、ETag、对象大小及目标端下载字节均与源端完全一致。

可复现测试命令：

go test ./cmd -count=1 -v \
  -run '^(TestGetCRCMetaChecksumType|TestReplicateObjectChecksumTypes)$'
go test ./cmd ./internal/hash -count=1 -timeout 10m \
  -run 'Replicat|Checksum|CRC|Multipart'
MINIO_API_REQUESTS_MAX=10000 CGO_ENABLED=0 \
  go test -tags kqueue,dev ./... -count=1 -timeout 30m

PR 检查（Go CI、DCO、VulnCheck）与合并提交检查（Go CI、VulnCheck）全部通过。

升级与运维要点

• 升级复制源端：该修复作用于复制发送端构造的请求头。仅升级目标端无法补回被源端丢弃的 x-amz-checksum-type；在双向（active-active）复制拓扑中，两端站点均作为发送端，需同时升级。贡献者在 PR #255 中的混合版本测试验证了已修复源端可向未修复 SILO 目标端正常复制，而未修复源端向已修复目标端复制仍会失败。
• 覆盖路径：桶复制、站点复制与批量复制（batchReplicationOpts()）均通过 putReplicationOpts() 构造请求头，因此统一获得修复。SSE-C 加密对象继续通过 X-Minio-Replication-Ssec-Crc 传递加密校验和元数据。
• 存量 FAILED 版本恢复与回滚：本次修改不涉及配置项、磁盘元数据格式或 API 变更。此前因该问题停留在 FAILED 状态的对象版本在源端保有完整的校验和元数据，升级源端后，触发复制重试或 resync 即可完成同步；回滚旧版本不会影响已落盘的目标端副本。

12 - Alias 区域：小配置改动的兼容性边界

2026-10-23 决策：mcli PR #44 已在 91006a587 合入 main。我们接受按 alias 配置区域的方案，保留小范围生产实现并补充回归覆盖。本文记录当时的设计决定。该能力已包含在正式发布的 mcli 20261109 中；以下配置边界按该版本源码复核。

原始补丁和测试由 mr javad seydi 贡献，解决的是上游 issue #5268 所报告的配置能力缺口。

缺少的究竟是什么

原始报告中的内部 S3 服务不实现 GetBucketLocation，调用时返回 501 Not Implemented。SDK 在发送普通对象请求前，先尝试发现桶的区域；发现失败，对象请求也就无法执行。用户向 alias JSON 加入 "region": "us-west-1" 后仍然无效：旧配置结构没有这个字段，会直接忽略它。

访问本身已有绕过办法。MC_REGION 和 AWS_REGION 可以设置 SDK 区域并跳过发现。只访问一个端点时，环境变量已经足够：

MC_REGION=us-west-1 mcli cp example.txt archive/bucket/example.txt

真正缺少的是按 alias 持久保存区域。进程级覆盖值无法在同一条命令中表达两个 alias 各自不同的区域，也不会随 alias 导出。这次新增字段填补了该缺口。它属于新增配置能力，不能把此前未受支持的 alias 字段被忽略说成既有功能回归。SILO 本身实现了 GetBucketLocation，原始报告也不能证明 SILO 服务端缺少这个接口。

最小且完整的配置链

原始生产补丁只改四个文件，新增 13 行、删除两行：

优先级为：

MC_REGION > AWS_REGION > alias.region > SDK 自动发现

第一个非空值生效。alias 区域缺失或为空时，保留原有发现路径；JSON null 也按空值接受。既有环境变量仍然优先。同名 MC_HOST_<alias> 环境 alias 继续整体替换文件 alias，因此不会继承文件中的区域。

缓存修改是正确性的一部分。两个 alias 可以共用端点和凭据，却分别指定不同区域。如果缓存仍只识别旧身份，第二个 alias 就会复用第一个已经固定区域的 SDK 客户端。把最终生效区域纳入键，才能阻止这种错误复用；当环境变量把两者覆盖成同一区域时，仍可共享客户端。SDK 和缓存使用同一个解析函数，避免两套优先级发生偏差。

SDK 已经支持显式区域，接通现有配置即可，无需 fork SDK、为某个服务增加 501 特判、引入依赖或升级配置版本。遇到发现错误就静默猜测区域，反而会掩盖配置错误，让签名行为更难解释。

固定区域意味着什么

非空区域会固定 SDK 使用的区域，跳过桶区域发现，并可能绕过 SDK 的区域纠正重试路径。它不是“先试这个区域，再发现真实区域”的提示。现有两个环境变量本来就具有同样的强制语义。相关实现见 SDK 的显式区域路径和区域纠正条件。

一个 alias 访问多个区域的桶时，这个区别尤其重要。应留空以使用自动发现，或为不同区域建立独立 alias。端点或服务区域变化时，也要同步更新固定配置。错误区域还会影响生成的签名：share upload 可能生成直到使用时才失败的 POST 表单；share download 会先执行 Stat，因此可能更早失败。

升级后哪些行为可能变化

补丁不会为旧 alias 自动填写区域。旧 CLI 正常生成的配置通常没有该字段，普通升级会保留原有区域发现和环境变量覆盖行为。例外需要分别说明，不能用一句“向前兼容”概括。

最后一种情况很容易漏掉。旧程序只读新配置不会擦除磁盘文件，保存才会，即使用户改的只是另一个 alias。再次升级无法恢复丢失字段。降级前应备份配置；必须混用新旧客户端时，使用独立配置目录。因此，这项改动兼容正常旧配置的升级；对本次验证的前一版本，降级后格式可读，但语义不完整，写回也有损。

更实际的升级意外，是自动化模板一直写着默认区域，或用户早先试填后忘记清理。非字符串值属于更边缘的错误输入。这些风险不足以成为继续忽略新字段的理由，但值得用户检查已有自定义 JSON。

如何配置和维护

对于包含这项改动的客户端，把下面内容保存为 archive.json，替换端点、凭据和实际区域：

{
  "url": "https://s3.example.com",
  "accessKey": "REPLACE_WITH_ACCESS_KEY",
  "secretKey": "REPLACE_WITH_SECRET_KEY",
  "api": "S3v4",
  "path": "auto",
  "region": "us-west-1"
}

chmod 600 archive.json
mcli alias import archive archive.json
mcli stat archive/existing-bucket

导入文档是单个 alias 对象，不是完整的 version 10 配置。Import 会替换目标 alias，轮换凭据时应包含完整的预期配置；导入对象不含 region，就会清除已有区域。Export 命令保留该字段，可以用来检查，但其输出也包含凭据。

alias set 没有 --region 参数。它会重建 alias 并清掉该字段，连接探测也不会继承已保存的区域。因此，启用新能力后，用 alias set 轮换凭据的脚本需要调整。alias list 包括 JSON 输出都不显示区域。这是初版明确的管理边界；CLI 支持可以单独改进，无需扩大本次生产补丁。

建桶另有设置。mb --region 继续使用自己的默认值 us-east-1，alias 区域不会替代它。例如，预期创建在 us-west-1 时，应执行 mcli mb --region us-west-1 archive/new-bucket。固定的客户端配置应与建桶位置一致。

回归覆盖与取舍

正式版本中的区域回归测试通过实际配置 loader 和拒绝 GetBucketLocation 的 HTTP 测试服务，检查固定区域下的 Stat/Put、签名区域、环境变量优先级及客户端缓存隔离。它验证了配置到 SDK 的完整链路，不代表所有第三方 S3 服务都兼容。维护的正式组合是 SILO、SILO Console、mcli 与 silo-pkg；对原厂 MinIO/MC 保持尽最大努力兼容。

这项改动通过 SDK 已有接口解决按 alias 保存区域的需求，正常旧配置仍保留发现行为。运维人员需要管理的边界是固定区域的强制语义、alias 重建和旧客户端写回；新增 CLI 参数可单独评估。

13 - IAM 策略重载：锁粒度、请求取消与超时预算隔离

提交 1b5477f3d（pgsty/silo#251）解决了 KMS/KES 响应缓慢时的两类级联故障：

1. 鉴权缓存锁争用：ListPolicies 与 ListPolicyDocs 在保留 IAM 写操作串行锁（writeMu）的前提下，将慢速的后端策略读取与解密移出内存鉴权缓存锁（store.lock()），避免管理员列举策略时阻塞普通用户的 S3 读写请求。
2. 全链路取消传播与超时预算隔离：将调用方的请求 context.Context 贯通至 IAM 配置解密、SSE-S3 列表密钥解封以及底层的 KES.Decrypt 调用；同时将底层存储 RPC 超时严格限制在存储读取阶段，确保耗时超过 30 秒的合法慢查询不会被误杀。

两种故障表象与对应机制

在排查 pgsty/silo#251 时，受控复现实验将 KES 慢响应下的服务端异常拆解为两条独立机制：

1. 当管理员在 KES 响应缓慢时执行策略列表查询，查询本身耗时数秒，而普通用户访问无关对象的 GET、HEAD、PUT 请求也随之停滞。
2. 当客户端中途放弃并断开 SSE-S3 对象列表请求（需解密对象元数据的 ListObjects）后，服务端仍继续向 KES 发起后续对象的密钥解密请求。

缩小锁粒度（A）与贯通取消信号（B）互为补充：释放缓存锁保证正常 S3 流量在慢速管理查询期间畅通无阻；贯通取消信号则确保客户端断开后立即停止无效的 KMS 解密请求。

锁耦合与取消断点的形成原因

ListPolicies 和 ListPolicyDocs 会从后端存储重新加载全部持久化策略，并替换内存中的策略映射表。原实现从调用 store.lock()（即 IAMCache 写锁）开始，一直持锁直到所有策略文档读取并解密完毕。在对象存储 IAM 后端上，每个加密策略文档都可能触发一次独立的 KES 解密请求。由于所有普通 S3 请求在鉴权阶段都需要获取同一个 IAMCache 的读锁，管理端列举策略时的数秒 KES 延迟会直接阻塞数据面的全部对象读写。

与此同时，请求取消链路在三个位置发生了断裂：

1. IAM 配置解密在调用 KMS 时使用了与 HTTP 请求无关的后台 Context；
2. SSE-S3 列表路径（UnsealObjectKeys）调用了不接收 context.Context 参数的单对象辅助函数 UnsealObjectKey；
3. KES 客户端适配器最终使用 context.Background() 调用 Decrypt。

由于最底层被硬编码替换为 context.Background()，即便顶层 HTTP 处理器传入了请求 Context，出站 KES 请求也无法感知客户端断开。

A：释放鉴权缓存锁，保留写入串行顺序

IAM 子系统中的两把锁承担着不同的职责：

• 鉴权缓存锁（store.lock() / store.rlock()）：保护普通 S3 鉴权在每个请求上读取的内存映射表。
• IAM 写串行锁（writeMu）：串行化管理端 IAM 写入与整表缓存替换，防止并发修改交错覆盖。

修复方案 A 在加载策略期间继续持有 writeMu 以保证写入次序，但在执行慢速后端读取与 KMS 解密时释放鉴权缓存锁：

获取 IAM 写串行锁 (writeMu) 与鉴权缓存锁 (store.lock)
  仅释放鉴权缓存锁
  使用调用者 Context，将策略读取并解密至私有 map
  重新获取鉴权缓存锁
  再次检查加载结果与调用者 Context 取消状态
  若成功且未取消，补齐内置策略并发布完整替换结果
释放鉴权缓存锁与 IAM 写串行锁 (writeMu)

在私有 map 加载和解密期间，普通 S3 鉴权可以继续并发读取已提交的缓存快照，只有其他管理端 IAM 写操作会在 writeMu 上排队。之所以不在加载期间同时释放 writeMu，是因为若完全放开并发，较早启动但较晚结束的慢速列表可能用旧快照覆盖期间刚提交的策略更新或删除。

缓存替换仅在后端加载成功、且重新获取缓存锁后再次确认 ctx.Err() == nil 时才会发布。若仅在重新加锁前检查取消，就会漏掉等待缓存锁期间发生的取消事件。一旦发布前遇到后端读取错误、部分加载或请求取消，原有的内存策略映射表及其更新时间均保持不变。

后台定期刷新同样遵循这一合并与撤销规则。回归测试直接驱动具体的 IAMObjectStore 刷新路径，与策略更新、策略删除以及持久化 IAM 撤销并发执行验证。

2026 年 11 月单条目按需加载扩展（07ce95dfd、00270e9f6、c78ef6a6f、bb31c2618）： 单个用户、组和策略的按需加载（Lazy Load）同样在存储读取期间释放鉴权缓存锁以保持已缓存 S3 鉴权可用，按 key 通过 singleflight 合并并发未命中，并在读取存储前记录 loadedAt，防止在途慢速读取覆盖更新的缓存版本或删除墓碑。

B：将取消信号贯通至 KMS 与 KES

受影响的两条解密调用链现在全程保留调用方的 context.Context：

IAM / 配置请求
  -> 对象后端或 etcd 配置解码器
  -> 配置解密 (携带请求 ctx)
  -> KMS.Decrypt(ctx, ...) -> KES.Decrypt(ctx, ...)

SSE-S3 列表请求
  -> UnsealObjectKeys(ctx, ...)
  -> 接收 Context 的内部单密钥辅助函数
  -> KMS.Decrypt(ctx, ...) -> KES.Decrypt(ctx, ...)

为了避免改动其他不具备请求 Context 的调用点，原有的单对象入口 UnsealObjectKey 保持原函数签名不变，列表路径改调内部新增的带 Context 辅助函数。

在列表循环迭代、历史回退分支以及最终缓存发布边界上均增加了取消检查。特别是当 IAM 解密因请求取消而中断时，加载器会立即返回，不再启动针对旧版密文的附加认证数据（AAD）兼容回退重试；而对于未取消的正常请求，旧密文 AAD 回退、密文格式、密钥顺序以及非取消类的 KES 错误映射均保持不变。

R1：将超时预算严格限制在原存储操作范围内

第一版修复候选在实现 A 时直接复用了 withIAMStorage 辅助函数来释放缓存锁。withIAMStorage 最初在 9 月 15 日的撤销持久化提交（709d50a916）中引入，用于为单条记录的存储读写、分布式锁等待和清理操作施加 30 秒超时保护。将其直接套用到策略全量列举上，相当于给原本没有总时长限制的策略列表额外加上了 30 秒整批硬上限。

边界测试直接暴露了这一回归反例：

• 在修复前的基线版本上，包含 61 个加密策略的慢查询在 32.74 秒后正常返回 HTTP 200；
• 在第一版修复候选上，同一查询在 31.22 秒后因 30 秒超时到期而返回 HTTP 503。

然而，仅移除外层的 withIAMStorage 包装对于 etcd 后端仍然不够。etcd 存储实现在调用 Get RPC 时会派生一个 30 秒的子 Context。旧代码的解密逻辑忽略了传入的 Context；当修复 B 将 Context 真正贯通到解密调用后，如果直接把这个 30 秒的 etcd 读取子 Context 传给后续解密，就会让原本只约束 Get RPC 的截止时间继续约束读取完成后的 KMS 解密。一旦遇到“快速 etcd 读取 + 32 秒慢速 KES 解密”的场景，请求就会在解密阶段因超时失败。

修正方案 R1 在策略文档与策略映射加载路径上，将调用方的请求总预算与单次 etcd 读取预算明确分离：

由于 etcd 读取 Context 是调用方请求 Context 的子级，若调用方本身设置了更短的超时，读取依然会立即响应取消；而在 etcd 读取完成后，解密操作继续受调用方剩余预算约束——当调用方允许更长等待时间时，超过 30 秒的慢查询依然能够成功返回。

备选方案与取舍

相对于受测基线 a07d655dc，最终生产代码改动涉及 8 个文件（新增 83 行、删除 29 行）及 5 个测试文件，不涉及线协议、密文格式或权限模型变更。

实测对比与回归测试契约

在相同进程级实验夹具下，基线版本 a07d655dc、第一版候选与最终实现 1b5477f3d 的实测对比如下：

在构造回归测试时，还处理了 KES 客户端的两处实现细节：

1. KES SDK 不可取消的退避休眠：KES SDK 在重试时可能执行最多两次、每次最长 999 ms 且不监听 ctx.Done() 的休眠。2 秒的测试观察窗口不足以覆盖 300 ms 请求超时加上两次退避休眠；将观察窗口调整为 3 秒后，可稳定验证取消后绝不发起任何新的解密请求。
2. 周期性 DescribeKey 探针：在持续 32 秒的真实长耗时测试中，后台会触发合法的周期性 DescribeKey 请求，模拟 KES 夹具需同时响应该接口。

持久化回归测试入口位于：

• cmd/iam-policy-reload_test.go
• cmd/iam-policy-refresh_test.go
• cmd/iam-policy-budget_test.go
• cmd/kms-cancellation_test.go

运维边界说明

• 并发 IAM 管理写入仍按序排队：由于策略重载期间保留了 writeMu 以维护写入顺序，其他管理端 IAM 写操作（如创建或删除策略）仍需等待当前正在执行的策略列表完成或取消；普通 S3 数据面鉴权则完全不受阻塞。
• KES SDK 退避期间的本地返回延迟：取消信号会立即终止正在进行的出站 KES 请求并阻止后续密钥解密或 AAD 回退启动；但如果取消发生时 KES SDK 恰好处于不可打断的退避休眠（最长 999 ms）中，本地函数会在该次休眠结束后返回。

工程复盘要点

1. 复用辅助函数时必须审视其全部副作用：为复用锁释放逻辑而直接调用 withIAMStorage，会连带引入原本不存在的 30 秒整批超时上限。
2. 修复 Context 传播时须逐层核对子 Context 的生命周期：当原先忽略 Context 的底层函数开始真正遵守 Context 时，上层为单步 RPC 创建的短生命周期子 Context（如 etcd 读取超时）如果未及时切回父 Context，就会误伤后续步骤。
3. “能取消”与“慢查询能成功”必须成对验证：取消测试只能证明请求能提前终止，必须配合超过单步后端预算（> 30 秒）的正向慢查询测试，才能防止超时范围扩大造成的回归。

相关设计文档：

• 持久化 IAM 撤销
• 请求头读取超时
• KES 与 OpenBao 集成

14 - LDAP 长 DN：恢复登录可用性并守住 IAM 撤销安全边界

Server PR #250（合入提交 d43adc0f2，已随 Server 20261026 发布）修复了 LDAP 用户在规范化可分辨名称（Distinguished Name，DN）超过对象存储 IAM 后端单路径分量 255 字节上限时无法登录的问题，同时严格保留了对真实存储故障与持久化 IAM 撤销记录的 Fail-Closed 错误传播。

原始问题报告、初版补丁（9faeb7a11）及长 DN 回归测试由社区贡献者 @910patin 提交。在合并前的设计复核中，维护者进一步收窄了错误分类守卫条件，确保完整路径超限（PATH_MAX）或多字节 Unicode 文件名读取失败绝不会掩盖磁盘上已有的撤销墓碑记录。

问题背景与故障影响

在企业目录服务中，合法的 LDAP 账号常带有较长的 DN，尤其是当姓名与多级组织单元（ou=）包含中文、俄文等非 ASCII 字符时。即使某个用户完全通过 LDAP 用户组（Group）获取权限、既不需要直接绑定个人策略也没有本地父身份记录，SILO 的登录与鉴权流程仍会尝试读取这些可选的个人 IAM 记录。

在对象存储 IAM 后端上，规范化后的 DN 会直接作为目录名或文件名分量拼接到存储路径中。一旦该分量超过文件系统单分量上限（255 字节），底层读取就会抛出文件名过长错误（ENAMETOOLONG / ObjectNameInvalid）并向上传播，导致原本完全合法的 LDAP 登录、STS 临时凭证签发以及服务账号加载直接失败。

为什么 DN 规范化会让非 ASCII 名称膨胀三倍

DN 标识完整的目录条目（例如 cn=张三,ou=研发,dc=example,dc=com）。根据 RFC 4514 §2.4，特定语法字符必须转义，其余字节允许使用 \xx（反斜杠加两位十六进制数字表示一个字节）格式转义。虽然 RFC 4514 允许直接保留普通 UTF-8 字符，但上游 go-ldap 库的 DN.String() 序列化器选择将所有非 ASCII 的 UTF-8 字节逐字节转义为 \xx。

SILO 的 NormalizeDN 先解析 LDAP 服务端返回的 DN，再调用 DN.String() 生成统一的规范化字符串：

由于每个 3 字节汉字都会展开为 9 个 ASCII 字节，原本仅 141 字节的 UTF-8 DN 在序列化后膨胀到了 381 字节。

这条查询结果规范化逻辑由上游 MinIO 于 2024 年 3 月 27 日在 minio/pkg efb73fa5（配套 MinIO PR #19358，作者 Aditya Manthramurthy / @donatello）中引入，目的是强制使用 LDAP 目录返回的权威 DN 作为身份标识，防止用户输入的拼写变体（例如将普通句点输入为 Unicode 变体句点）被当成不同的本地身份。

登录回归是如何形成的

对象存储 IAM 后端使用如下路径存放用户级记录：

config/iam/users/<normalized-DN>/identity.json
config/iam/policydb/sts-users/<normalized-DN>.json

主流 POSIX 文件系统对**单个斜杠分隔的路径分量（NAME_MAX）**限制为 255 字节。在 sts-users/<normalized-DN>.json 中，5 字节的 .json 后缀与规范化 DN 共用同一个文件名分量预算：250 个 ASCII 字节加 .json 刚好 255 字节，251 个字节加后缀即达到 256 字节并触发超限。

两处历史实现细节进一步加剧了症状的隐蔽性：

1. checkPathLength 在 Unix 上漏计反斜杠：SILO 的路径长度预检查函数 checkPathLength 在 Unix 系统上会跳过反斜杠（\）字符。复现样本中 271 字节的转义 DN 被 checkPathLength 算成了 197 字节，从而绕过预检查，直到真正访问操作系统文件系统时才报错。
2. 结果随祖先目录是否存在而变化：如果 config/iam/users/ 前缀目录尚未在磁盘上创建，操作系统内核在解析父目录时就会直接返回 ENOENT（文件不存在），根本不会走到后面的超长 <normalized-DN> 分量——此时登录反而返回 HTTP 200 成功。一旦集群中曾经写入过任何用户记录、使 config/iam/users/ 目录落盘存在，内核就会继续解析超长子分量并返回 ENAMETOOLONG，导致同一用户的登录立刻变成 HTTP 500。

修复方案：仅将确定无法落盘的纯 ASCII 超长分量归类为不存在

修复集中在对象存储 IAM 的共享底层读取函数 loadIAMConfigBytesWithMetadata 中。函数首先按原流程尝试读取；仅当读取返回错误，且同时满足以下三个条件时，才将该错误归类为 errConfigNotFound（记录不存在）：

1. 底层错误为 errFileNameTooLong 或 ObjectNameInvalid（含标准包装错误）；
2. 完整对象键通过常规的桶名与对象名合法性校验（isValidBucketName 与 isValidObjectName）；
3. 至少存在一个按 / 分隔的路径分量完全由 ASCII 字符构成（utf8.RuneCountInString(component) == len(component)），且字节长度超过 255（len(component) > 255）。

由于超过 255 字节的纯 ASCII 路径分量在对象存储后端从一开始就不可能写入成功，磁盘上绝不可能存在对应的历史记录。将其转换为 errConfigNotFound 后，上层调用者即可安全进入既有的“无此可选记录”分支——例如继续执行 LDAP 认证并通过用户所属的 LDAP 组策略完成授权——既不会凭空授予任何默认权限，也不会跳过对可存储身份的父版本撤销检查。

写入、删除、etcd IAM 后端以及全局对象路径长度检查均保持不变。核心生产代码仅在 cmd/iam-object-store.go 中新增 25 行（配套新增 318 行回归测试），正常读取路径零额外开销。

为什么要收窄初版补丁的错误分类范围

初版 PR 将任何语法合法键上的 ObjectNameInvalid / errFileNameTooLong 统统归类为 errConfigNotFound。在合并前的设计复核中，我们构造了两个具体反例，证明“读取报长度错误”并不总能推出“该记录从未在磁盘上存在过”：

1. 完整路径超限（PATH_MAX）掩盖已落盘的真实撤销记录：假设管理员先撤销了一个各路径分量均不超过 255 字节的合法身份（撤销墓碑已成功落盘），随后在 macOS 等环境上将数据目录挂载或迁移到了层级更深的父目录之下。此时相对路径下的各个分量依然合法，但完整绝对路径触发了系统的总路径长度上限而导致读取失败。如果把这类错误也吞成 errConfigNotFound，就会直接掩盖磁盘上真实存在的撤销墓碑，让已被撤销的身份重新通过检查。限定检查单个 / 分量 len(component) > 255 后，完整路径超限仍会按 Fail-Closed 向上报错。
2. 按字符数计长的多字节 Unicode 文件名（如 macOS APFS/HFS+）：不同文件系统对 255 上限的定义并不相同。在 macOS 实验探针中，由 100 个汉字 界 组成的单个路径分量虽然占用 300 个 UTF-8 字节（len(component) == 300，但字符数仅为 100），却能够在 macOS 文件系统上成功创建并落盘。如果仅凭 len(component) > 255 就断定记录不可能存在，就会把这类已经落盘的多字节 Unicode 记录误判为不存在。加上 utf8.RuneCountInString(component) == len(component) 限制后，该规则仅对纯 ASCII 分量（天然涵盖所有 \xx 转义后的 DN）生效，而在任何平台上 256 个以上 ASCII 字符都无法存入单分量上限为 255 的文件系统中。

由此确立了严格的安全边界：只有被证明在物理上绝无可能写入成功的路径分量，才允许走 errConfigNotFound 分支；任何可能已经存在但当前无法读取的撤销记录，一律保持报错拒绝。

备选方案与取舍

测试验证矩阵

运维边界与配置建议

• 读取与写入的能力边界：本次修复恢复了长 DN 用户的登录与只读查询路径，但对象存储 IAM 后端依然不支持写入单路径分量超过 255 字节的文件。直接向规范化后超过 250 字节的个人 DN 绑定策略（写 sts-users/<DN>.json）或写入父身份版本墓碑（写 users/<DN>/identity.json）仍会因文件名超限而失败。
• 推荐使用 LDAP 组授权：在使用对象存储 IAM 后端的集群中，对于包含中文或长路径的 LDAP 用户，应通过绑定到 LDAP 组（Group）的策略进行授权（确保组 DN 规范化后不超过 250 字节），避免直接向超长个人 DN 绑定独立策略。
• 无需数据迁移：升级无需执行任何磁盘数据迁移。切勿通过手动删除 .minio.sys/config/iam/ 下的目录来规避路径报错；多站点升级请遵循 IAM 升级与恢复手册。

15 - 复制标签排序：修订时间戳、墓碑与复活

随 SILO Server 20260916（40220bd836cbd066ca424fa4dc5dbb90057fb55a）发布的 PR #193（修复提交 03027727d）与 PR #196（修复提交 680eac66e），修复了对象标签在跨桶复制中保持顺序的两项缺陷：SSE-KMS 目的端复制静默丢弃标签修订时间戳（R4），以及空标签值（删除操作）缺失修订时间戳导致延迟到达的复制事件将已删除标签“复活”（R5）。

共同模型：标签值与其修订时间戳共同构成单一状态

对象标签在复制时通过请求头 X-Minio-Source-Tagging-Timestamp 传递内部修订时间戳（在 xl.meta 中存储为 x-minio-internal-tagging-timestamp）。接收端在对象写锁保护下通过 reconcileStoredObjectTags 执行排序规则：入站复制的标签状态仅在其修订时间戳严格新于目标端已存时间戳时才胜出。

本组两项缺陷均以“丢失修订时间戳而非丢失标签值”的方式破坏了这一规则：

• R4（PR #193）： 在写入 SSE-KMS 加密目标端时丢弃了入站时间戳，导致较新的标签更新在存储层对账中输给陈旧的已存状态。
• R5（PR #196）： 使空标签值（即删除标签）完全不携带修订时间戳，导致复制协议无法表达“在时刻 $T$ 已删除标签”——网络中迟到的旧复制事件因此能够重新恢复客户端早已删除的标签。

R4：SSE-KMS 目的端复制丢弃标签修订时间戳

故障形态： 发往 SSE-KMS 加密目的端的可信复制 COPY 请求返回 HTTP 200 OK，对象密文加密正确，明文 GET 读取也完全正常——但目的端对象的标签及其时间戳却停留在旧值。由于 HTTP 请求返回成功，不会触发任何告警或 MRF 重试。存储层对账函数 reconcileStoredObjectTags 在对象写锁内比较修订时间戳时，因入站时间戳丢失而直接判定存量旧状态获胜。

触发范围： 不仅限于携带显式 SSE-KMS 请求头的调用；当目的端桶配置了桶级默认 KMS 加密或集群开启了全局自动加密时，均会进入同一代码分支，因此即便请求中不含任何 KMS 请求头也会触发该缺陷。

根因追溯： PUT 类请求的选项构造函数在解析出可信来源标签时间戳并存入 ObjectOptions 后，SSE-KMS 分支重新构造并返回了另一个 ObjectOptions 结构体字面量——该字面量复制了 MTime、ETag、复制信任标志与两个 Object Lock 时间戳，唯独漏掉了 ReplicationSourceTaggingTimestamp。这一遗漏最早可追溯至上游提交 c4373ef290（2021 年）；2026 年初的一次 Object Lock 修复向该结构体字面量补齐了两个保留期/法务锁定时间戳，但依然漏掉了标签时间戳。

修复（03027727d）： 在 SSE-KMS ObjectOptions 字面量中补齐 ReplicationSourceTaggingTimestamp 字段传递。回归测试覆盖了全部目的端加密方式（无加密、SSE-S3、带与不带 key context 的 SSE-KMS、SSE-C）$\times$ 可信/不可信来源 $\times$ 缺失/有效/畸形时间戳的完整组合矩阵，以及在单盘和 16 盘纠删码后端上以 1–3 纳秒间隔执行的 50 次有序签名 COPY+GET 循环验证。

相近代码观察： 同一个 SSE-KMS ObjectOptions 字面量还遗漏了 ProxyRequest 与 Speedtest 选项字段（全局自动加密下 speedtest PUT 会丢失该标志），该问题作为独立跟进项单独记录，不混入本次复制修复。

R5：空标签值无修订时间戳，导致已删标签被延迟事件复活

故障形态： 基线测试在真实存储与函数级测试中暴露出 9 项具体回归表现：

1. 成功的 DeleteObjectTagging 从不生成新的修订时间戳，因此迟到的可信元数据 COPY 只需携带旧标签快照即可将已删标签重新写回。
2. 携带空标签状态的较新 COPY 被接收端忽略——空字符串被解释为“未提供标签变更”而非“已清空标签”。
3. 首次副本 PUT 虽然解析了来源标签时间戳，却未将其持久化写入磁盘元数据。
4. 当源端与目标端可见标签值相等（或均为空）时，发送端将其折叠为“无需复制”；由于 HEAD 响应不暴露内部标签修订时间戳，更新的删除或重加操作不可见，无法恢复正确顺序。
5. 排队中的复制事件在完成回调时会将快照中的旧标签写回本地元数据，直接覆盖已提交的删除操作——且在无时间戳保护下，复活的旧标签还会继承删除操作的较新修订状态。

根因： 标签值与其修订时间戳（包括空值的时间戳）共同构成一个完整状态。旧协议只能表达非空状态：DeleteObjectTagging 从不生成修订时间戳、发送端仅在非空分支附带时间戳、接收端也仅在非空分支执行对账判断。

修复（680eac66e）：

1. 每次标签变更均生成单调递增修订： PutObjectTagging 与 DeleteObjectTagging 处理器无条件生成单一的 UTC RFC3339Nano 修订时间戳，无论该对象当前是否命中复制规则。存储层在写锁内强制保证单调性：若新生成的本地修订不严格新于已存修订，则将其推进至 $\text{stored} + 1\text{ ns}$；多池后端则跨所有存储池计算出严格大于全部池副本的统一修订值。
2. 发送端传输删除墓碑（tombstone）： 空标签值同样携带其已记录的修订时间戳；对于从未设置过标签的对象（空值且无修订记录）绝不伪造时间戳；若磁盘上已记录的时间戳格式畸形，则按失败关闭（fail-closed）处理，不作静默修补。
3. 接收端对账墓碑状态： 复制 COPY 在重建元数据前先捕获存量标签与时间戳对，使带时间戳的空值作为可胜出的有效状态进入 reconcileStoredObjectTags。内部重复版本抑制（412 PreconditionFailed）仅对严格更新的可信来源标签修订放宽（客户端显式指定的 If-Match 与 If-None-Match 依然严格执行）。多段上传完成（CompleteMultipartUpload）从已持久化的 upload 元数据读取标签顺序；复制删除确认回调不再将快照标签写回本地；普通 SSE-C 密钥轮换则会从复制的加密元数据中剥离旧标签时间戳，防止其覆盖新生成的本地修订。

运维可见变化与升级要求

• 时间戳相等时统一判定存量胜出： 在不带版本（unqualified）及显式 null 版本的 COPY 请求上，当入站时间戳与已存时间戳相等时统一保留存量状态（旧逻辑在未限定版本路径上曾让入站请求胜出平局）。
• 携带 X-Amz-Tagging-Directive: REPLACE 且无标签的普通 COPY： 现在会按 S3 规范真正清空目的端标签，而不再沿用旧默认路径将源对象标签复制过去。
• 复制两端必须协同升级： 旧版本对端仍会丢弃空值修订头，新发送端发出的删除墓碑对旧接收端不可见（关于同步包含的 IAM 变更，请参阅 IAM 与复制升级指南）。
• 显式 resync/heal 期间每个带修订记录的对象增加一次元数据 COPY： 当目的端配置了桶级默认 KMS 或全局自动 KMS 加密时，该元数据 COPY 会实际重写对象数据，执行大批量重同步时需据此评估 I/O 预算。
• 固有边界： 历史已丢失或被覆盖的删除时间戳无法自动重建，需从权威源端发起一次新的显式标签写入以重新收敛；带标签过滤条件的复制规则仍按删除后的（空）标签状态评估目标资格；跨站点逐跳排序依赖站点间的时钟同步（NTP），畸形的已记录时间戳会使发送端构造持续失败并经由 MRF 重试，直至被新的合法标签变更替换。

评估并否决的候选方案

• 为空值且无修订记录的对象从 ModTime 合成墓碑： 会使每个从未打过标签的普通对象都获得标签修订，叠加显式同步时的强制元数据复制后，会导致每个对象在每一跳都触发额外的元数据 COPY。
• 仅在标签值为空时传输修订时间戳： 提案者在代码评审中撤回了该方案——在“时刻 $T_1$ 设为 X $\to$ 时刻 $T_2$ 删除 $\to$ 时刻 $T_3$ 重新设为相同值 X”的序列下，若非空时省略时间戳会丢失 $T_3$ 的重加修订（已由回归测试 TestTaggingRepeatedValueNeedsRevisionDelivery 固定该反例）。
• 扩展 HEAD 协议返回内部标签修订： 当前固定的 minio-go 元数据提取器会丢弃内部响应头，修改协议契约收益有限，且当修订不同时最坏情况仍需执行一次元数据 COPY。
• 引入分布式因果时钟或在底层提交时重新生成时间戳： 墙钟时间戳配合写锁内的 $+1\text{ ns}$ 单调护栏已是无需修改存储格式的最小正确修复。
• 仅做单池内的单调护栏： 普通读取仅返回单池对象信息，若只在单池内维护单调性，发送端可能发出落后于其他存储池的旧修订；因此必须跨池计算统一的最高修订值。

验证

R4 回归测试覆盖了加密模式 $\times$ 信任状态 $\times$ 时间戳矩阵，以及单盘与 16 盘纠删码后端上的有序序列；R5 额外包含多存储池标签删除回归测试，PR #196 的全部 11 项 CI 检查均已通过。

升级摘要见组件版本矩阵；阻止归一化副本元数据被重新注入的姊妹修复见副本元数据归一化。相关设计记录：复制标签排序 · 副本元数据归一化 · 请求头超时防护 · 副本元数据审计手册。

16 - SILO Server 20260903 发布前复审

本文记录 SILO 20260903（RELEASE.2026-09-03T13-18-01Z，对应提交 9b11dc9469e650815b775cb47b039610644f5da4，候选复审提交 6e112d1856d4f3655f30fc81ee47e9f43d50d8f3，对比基线 RELEASE.2026-08-06T00-00-00Z 即 3be10fcc1a44f6620ded0bd303461f9d688cca23）的发布前工程复审：第二轮复审发现了哪些遗漏缺陷、修复边界如何收窄，以及发布门禁如何组织。后续九月与十月版本的修复见复制可靠性、Server 20260916 与 Server 20261018。

为什么需要第二轮审查

第一轮实现修复了大多数已知问题并通过了现有测试。第二轮复审进一步检查各安全不变量在所有合法协议形态与异常状态下是否严密：

• 同一条不变量能否被另一种合法的请求格式（wire representation）绕过？
• 鉴权前的快路径是否仍会触发磁盘 I/O 或修改内存状态？
• 元数据存在但加载失败时会发生什么？
• 两条各自正确的“读-改-写”路径是否共享同一个串行化边界？
• 请求头清洗是否保留了完整的 SigV4 流式签名状态？
• 验收记录对应的是最终代码树，还是此前的中间提交？
• 复杂的防御逻辑对应的是已复现的故障，还是仅停留在假想场景？

第二轮复审在首轮实现之上定位出多处真实缺陷，并将每项修复与验收结论严格收窄到具体的不变量与代码提交。

分领域复审结果

定义候选的四条不变量

信任只在鉴权后推导一次

看似内部专用的请求头本质上仍是客户端输入。请求必须先以原始签名形态通过既有鉴权路径，随后处理函数才能综合以下四项条件推导复制特权：

1. 唯一且精确匹配的复制标记；
2. 非匿名的已认证身份；
3. 目标资源上的 s3:ReplicateObject 或 s3:ReplicateDelete 权限；
4. 仅限副本（replica-only）语义所要求的副本状态。

推导结果存入私有请求上下文；后续剥离内部请求头仅作为面向旧调用链的纵深防御，而非权限来源。

这一顺序至关重要：SigV4 签名可能覆盖这些请求头，若在鉴权前剥离，合法的复制请求就会因 SignatureDoesNotMatch 被拒绝。此外，清洗后的克隆请求必须与原请求共享 Trailer 映射，因为流式上传的校验和会在请求体读取完毕后通过 trailer 到达。

完整的接收端信任模型见鉴权前不做 I/O，Header 不产生权限。

共享记录只有一个写边界

桶策略、生命周期、服务端加密（SSE）、标签、配额、复制、Object Lock、版本控制与 CORS 在逻辑上各自独立，但在存储层同属一条桶元数据记录。按字段拆分的互斥锁无法保护整条记录的“读-改-写”周期。

修复方案没有引入重型的事务层，而是统一收敛到单一的元数据写锁：

acquire metadata.lock
  load or reuse current record
  mutate the requested field
  parse/normalize the complete record
  persist atomically
  publish the in-memory record
release metadata.lock

该锁不涉及对象数据 I/O，生命周期严格限制在单次桶元数据操作内。元数据迁移与自愈同样会替换整条记录，因此也必须受该锁保护。站点复制的接收端仅合并发生变更的字段，防止远端较旧的快照覆盖本地其他配置。

区分 CORS 加载失败与桶不存在

CORS 热路径必须明确区分以下四种状态：

表中第二行是保留失败桶集合的原因。预签名 URL 由签名本身完成授权，可在不经过桶策略求值的情况下访问私有对象；此时桶级 CORS 配置就是浏览器跨源访问的唯一边界。如果丢弃加载失败状态并回退到宽松的全局 CORS 配置，这一隔离边界就会失效。

该集合仅在真实桶加载失败时记录，规模受实际桶数量约束，并通过 noteLoadFailure 与 clearLoadFailure 两个辅助函数维护。成功加载、删桶、陈旧桶清理、刷新、重置与并发加载均已补齐测试覆盖。

按解析后的 XML 语义归一化 Object Lock

任何合法且处于启用状态的 Object Lock 配置都要求开启版本控制。XML 空白字符、元素顺序以及是否包含默认保留规则（Default Retention）都不会改变这一语义。因此，状态归一化必须在解析 XML 之后执行，而不能通过与单一标准 XML 进行字节比对来判断。

开启 Object Lock 后的版本控制状态固定为纯粹的 Enabled；暂停状态（Suspended）与前缀排除扩展均与 Object Lock 不变量冲突，会在配置更新、读回和磁盘重载时自动剥离。

复杂度审计

发布前复审专门排查了过度设计、重复逻辑、缺乏威胁模型的防御性代码，以及陈旧的兼容机制。

因保护已复现故障而保留

• 单一元数据锁： 确定性的跨配置类型并发测试已复现更新丢失。
• CORS 删除墓碑（tombstone）： 缺少墓碑记录时，站点复制无法区分“配置已删除”与“从未配置”。
• CORS 加载失败状态： 预签名 URL 提供了已通过认证但绕过桶策略的具体反例。
• 两级复制信任判定： 普通复制与副本密文/SSE 透传具有不同的请求特征与权限要求。
• 鉴权后清洗请求头： 在 SigV4 验签前剥离请求头会破坏合法的签名请求。
• 多存储池与 null 版本边界测试： 单池常规路径无法覆盖它们捕获到的跨池状态选择缺陷。

删除或收窄的复杂度

• CORS 失败集合的修改统一收口到 noteLoadFailure 与 clearLoadFailure。
• 站点复制导入路径改为仅应用变更字段，不再整条覆盖可能过期的记录。
• 删除废弃的加密辅助函数、无调用的事件目标函数与死代码分支。
• 兼容性守卫不再逐一枚举所有导出的源码符号，改为保护实际对外暴露的路由及冻结的协议/配置表面。
• 移除旧的 wait_pipe 静态检查豁免，并以 gomodguard_v2 替代已弃用的配置。
• 动态超时测试不再从并行测试包中调用全局 rand.Seed。
• 服务端依赖从临时 silo-go 分叉切回经审查的上游兼容 minio-go 版本。

刻意没有引入

• 不引入通用的元数据事务框架；
• 不引入第二套 CORS 缓存或无界的负缓存；
• 不新增公开的“可信复制”请求头；
• 不设置让服务端发布受制于后续 Console 或文档站发布的跨仓库门禁；
• 不在候选版本中塞入半成品的条件删除契约；
• 不在缺少专项收敛测试的前提下重写继承的站点复制状态寄存器。

延期事项，以及为什么严重度不同

证据

完整验收树

全量本地验收基于提交 ebac0ca73bbf251b070bb6df4d8005015841f901：

• 完整的 cmd 与 internal 测试套件通过；
• 完整的 cmd 并发竞态套件（-race）耗时 365.448 秒，全部通过；
• 静态检查（lint）：0 告警；
• 品牌重命名/兼容性守卫与生成文件检查通过；
• govulncheck 扫描无可达漏洞；
• 六种 make verify 部署拓扑验收：174 PASS / 0 FAIL。

前两次运行 make verify 在拉取 mcli 时因网络代理与环境准备中断，并非测试用例失败。最终通过的运行使用了本地固定校验和的 mcli 二进制，保留访问 GitHub 的出站代理、对 localhost 绕过代理，并将 GNU 工具链置于 PATH 首位。

验收后的候选

全量验收之后唯一的代码改动是 84e1580a4：在按需重载桶元数据成功后清除对应的 CORS 加载失败标记。随后的候选合并未改动业务代码，6e112d185 仅更新了 Helm Chart 发布元数据与文档。最终候选提交通过了以下门禁：

• git diff --check；
• CORS 与 Object Lock 定向 go test -race；
• 品牌重命名与兼容性守卫（rebrand-guard）；
• 生成文件一致性检查；
• 静态检查（lint）0 告警；
• Helm Chart 语法检查、默认与可选模板渲染、Chart 打包，以及七类资源的旧版升级身份守卫。

Go、No-Go 与发布门禁

代码结论：GO

两轮复审确认的代码缺陷在候选版本中均已闭合。各项修复直接作用于对应不变量所在的模块边界，保留的防御机制均有可复现的故障反例支撑。

生产发布门禁

在正式发布 RELEASE.2026-09-03T13-18-01Z 前，候选版本依次通过了七道发布门禁：

1. 候选提交推送至远端并完成代码审查；
2. 远端 CI 与测试发布流水线在最新提交上全部通过；
3. 预发布标签精确指向经审查的 Chart 7.0.2、Server 0903 与 Client 0903 代码树；
4. 构建产物、校验和、SBOM、构建证明（attestation）与签名 RPM 包全部通过校验；
5. 正式发布与容器镜像流水线完成 classic 与 distroless 两种镜像的构建与推送；
6. 匿名下载与镜像拉取验证通过；
7. 基于正式标签更新发布说明并完成文档站部署。

20260903 部署注意事项

升级至 20260903 时需满足以下部署前提：

• 在同一维护窗口内完成分布式集群所有节点的同步升级；
• 在启用桶级 CORS 配置前，先升级站点复制组内的全部成员；
• 核对并更新涉及 s3:DeleteObjectVersion 及用户/组状态启停权限分离的 IAM 策略。

重启与读回验证（2026-09-11，#116）

后续的 #116 专项验收（2026-09-11 执行）测量了集群在有界重启窗口内的写入确认与读回一致性，验证方法涵盖四个要点：

• 确认台账。 每次返回成功的 PUT 都写入带版本的唯一对象键，并在收到响应时立即记录 VersionId、字节数与 SHA-256。后续读回按精确的 VersionId 获取对象并同时校验三项指标，防止早期确认的写入被后续写入静默覆盖。
• 读回时机。 数据探针（canary）写入成功后，分别在 15 秒、30 秒和 60 秒经由所有对端节点周期性重读；最终检查同时覆盖单节点中断期间写入的对象及其重新加入集群后写入的对象。
• 禁用重试掩盖。 每次探针操作设置 60 秒硬超时（涵盖连接建立、请求发送、响应体读取与等待间隔），并关闭客户端 SDK 自动重试，防止恢复窗口内的短暂失败被客户端重试掩盖。
• 容器拓扑。 单机运行四个拥有独立网络标识的 Linux/arm64 容器，每节点挂载一块盘（EC 2+2）；tmpfs 卷由占位容器在整个停机窗口内保持挂载；四个节点以 10 秒宽限期并行优雅停止，随后并行启动。

管理接口就绪不代表数据面就绪。 原始测试记录对比了 0806、0903 与当时的 main 修复构建。main 构建在重启后 2.461 秒通过管理接口检查，但随后又经过 14.489 秒才完成首次数据探针读写。在该启动窗口内，admin/health 探针无法反映数据面状态，滚动升级脚本必须验证实际的数据面读写，而不能依赖固定时长的等待。

后续各项修复的交付状态见组件与源码矩阵。

17 - 多池覆盖亲和：为何最终没有采纳 #245

2026 年 10 月 24 日决定：不合并本次测试的多池覆盖亲和补丁（PR #245）。 该方案解决了跨池覆盖遗留旧副本的空间占用问题，但无论完整策略还是仅限普通无版本覆盖的收窄策略，都未能在性能测试中达到可接受的权衡。两个实验分支（codex/healthy-pool-affinity 与 codex/unversioned-pool-affinity）已保留归档，服务端 main 分支保持原状。

Denis Babchuk 提出的思路是：覆盖已有对象时，优先写回已存放该对象的池。代码评审发现并修复了请求级写 quorum 判断缺陷，收紧了健康池判定规则，并通过了功能验证。但随后的性能实测改变了结论：完整策略使深版本历史的写入成本翻倍；第二版排除版本桶后，普通小对象覆盖写入仍有明显退化。

后续的多池删除修复（#257）已于 10 月 24 日独立合并：在保留按容量加权分配的前提下，先清理非权威池中的旧副本，再删除决定当前读取结果的权威副本，防止删除中途报错导致旧值暴露。

问题背景：跨池覆盖会在旧池留下过时副本

假设无版本对象 reports/latest.json 位于池 A，下一次 PUT 将新内容写入池 B。后续读取仍会选出池 B 中最新的逻辑对象，但池 A 中的旧物理副本会继续占用磁盘空间——普通覆盖写成功后，并不会跨池清理其他池里的旧副本。

基线代码在查找到可读的既有对象后，仍会再次进入按剩余容量加权的选池流程。视各池使用率不同，反复覆盖同一个 key 最终可能在两个池中都留下池级记录（xl.meta）。

这一行为源于如下历史演进：

• 上游 MinIO issue #21087 报告单池上传可能绕过最小剩余空间阈值；2025 年 7 月 19 日合入的 PR #21115（83b2ad418b）为可读旧对象的覆盖写也强制执行了容量选池，从而丢掉了原有的原池亲和性。
• SILO issue #199 与 PR #207 修复了跨池当前逻辑对象的条件写校验，同时保留了按容量加权的分配策略。
• 池迁移通过独立机制防止旧内容覆盖新内容及删除标记丢失，详见多池对象一致性。

覆盖亲和的空间收益主要集中在多池部署下对同一批无版本 key 的高频覆盖。单池部署不存在跨池重复；新 key 仍需按容量跨池分配；版本桶则必须保留所有历史版本，集中到单个池并不会减少需保存的数据量。

原始 PR 的设计方案

提案复用了现有的对象查找和锁边界：若最新可读对象已存在，则在满足写 quorum 和硬空间阈值的前提下优先选择其所在池；新 key 继续按容量加权分配；当原对象所在的纠删码组无法接受写入时，先排除该池再从其余池中分配。

生产代码修改集中在 cmd/erasure-server-pool.go（新增 73 行、删除 3 行，附带 331 行放置测试），作用于进入共享选池路径的 PUT 和分片上传初始化。

选池过程涉及两条容量规则：

• 软分配预留（15% reserve）：存在可用替代池时，分配器会过滤掉使用率超过约 85% 的池，优先填充较空的池。
• 硬空间检查（hasSpaceFor）：结合写入大小、单盘容量及 diskFillFraction（0.99）执行硬性门槛检查。

当原池健康且有足够空间时，亲和策略会绕过软分配预留，同时保留硬空间检查。代价是在集群扩容后，既有热点 key 会继续留在较满的旧池中更新，而不会随覆盖写自动迁移到新池。

如果只是简单删掉“已有对象重新选池”的分支，就会丢失 83b2ad418b 引入的容量检查与故障回退。仅检查剩余空间同样不够：当某个纠删码组仍有足够在线盘读取旧对象、但在线盘数已不足以写入新对象时，选池必须提前识别；由于选池发生在消费上传流之前，一旦不可重放的请求体被消费，写入失败后无法无代价地换池重试。

正确性评审与实现改进

写 quorum 必须按本次请求计算

原始 helper 对所有写入一律按 STANDARD 存储类推算写 quorum。双池受控测试暴露了使用 REDUCED_REDUNDANCY（RRS）覆盖时的回归：

由于校验片越少、数据片越多，RRS（EC:2）实际需要 14 块在线盘才能写入，而原始预检查按 EC:4 只要求 12 块写盘，误判原池可写，最终在写入阶段因盘数不足返回 InsufficientWriteQuorum（映射为 HTTP 503）。基线代码通过 85% reserve 过滤掉已用 90% 的原池，路由到健康的第二池并全部成功；原始 PR 在两个原池位置 × 两种入口的 4 个场景（重复 3 轮共 12 次尝试）中全部失败。

PUT 的内部 MaxParity 选项还会触发反方向的误判：实际允许使用 EC:8 的写入被按 EC:4 评估，导致不必要的跨池迁移。

仅优先选择完全健康的原池，并明确回退规则

改进后的实现将请求的存储类和 PUT MaxParity 一并传入选池逻辑，严格对齐写入路径的 availability / capacity 校验片计算规则（包括数据片与校验片相等时额外要求的写盘数），并保持分片初始化的既有 parity 语义：

健康度与容量检查共享同一次组级 DiskInfo 快照：只有在线、查询成功且总容量为正的磁盘才计入可用写盘；DiskInfo 调用失败的磁盘一律按不健康处理。

回归测试同步覆盖了请求级 parity、已知坏盘、降级组、扫描次数、异构组大小、最新对象选取以及既有分片上传会话，并为分片上传回退测试配置了独立的初始对象（避免前置 PUT 先一步把最新副本迁走而削弱测试前置条件）。

第二版设计：仅对普通无版本覆盖启用

第一轮性能测试暴露出深版本历史的元数据重写放大后，第二分支（codex/unversioned-pool-affinity）将亲和范围收窄至普通无版本覆盖写：

资格判定同时检查桶的版本控制配置与请求选项：启用了版本控制但配置了排除前缀的桶，或处于版本暂停（Suspended）状态、带有混合历史版本的桶，均继续使用基线分配器。

各阶段功能验证

定向回归测试筛选正则为：

^(TestPoolsOverwrite|TestPoolsMultipartOverwrite|TestSinglePoolOverwrite|TestPoolsConditionalPut|TestSinglePoolConditionalPut|TestPoolsMultipartCondition)

性能测试环境与指标定义

两轮基准测试均在 m3 主机上执行（AMD Ryzen AI MAX+ 395，32 逻辑 CPU，61 GiB 内存，Linux 7.0.0-38，单块 CT2000P310SSD8 NVMe SSD，XFS 文件系统）。两个存储池各使用该 XFS 文件系统上的 16 个目录（共 32 个目录，单池单纠删码组，默认 EC 12+4）。

基线与候选分支均使用 Go 1.27.3（linux/amd64，CGO_ENABLED=0）编译。服务端绑定 CPU 4–11（GOMAXPROCS=8），客户端绑定 CPU 12–15（GOMAXPROCS=4），通过 minio-go v7.4.1 走本机回环 HTTP 压测。

• 吞吐（operations/s）：每秒完成的对象操作数（分片上传每次操作含初始化、2 个分片上传及完成请求）。
• P50 / P99：取各轮运行 50 / 99 分位延迟的中位数。
• CPU 成本：每完成一次操作消耗的服务端 CPU 时间。
• 块 I/O：取自 /proc/PID/io 的进程级读写字节数。
• 活动桶空间：对象数据文件、元数据与目录占用之和（不含临时目录）。

第一轮结果：完整策略导致深版本历史写入显著退化

第一轮对比完整候选分支（0aa870115d7d）与基线（789a2327ba8c），共执行 54 次测量运行（完成 243,718 次操作，0 失败）。基础矩阵每项运行 3 对 15 秒测试，新 key 与 4 KiB 覆盖追加 2 对 60 秒长测，单对象版本测试固定写入 4,000 个新版本，另在存量双副本数据上执行 4 轮 ABBA 二进制切换测试：

普通 4 KiB 覆盖的两对 60 秒长测分别下降 30.7% 和 21.8%，此前三对 15 秒短测也全部下降；但每次操作的 CPU 时间反而从 5.85 ms 降至 5.33 ms，单次块写入保持在约 128 KiB。

单对象 4,000 版本测试下降 30.8% 的原因则非常直接：池内 xl.meta 保存了该池内所有版本的元数据（以及小对象的内联数据），每次新增版本都要重新序列化并整文件重写 xl.meta。基线按容量分配将 4,000 个版本大致均分到两个池（每池约 2,000 个版本），而亲和策略将全部 4,001 个版本集中写入同一个池，导致每次 PUT 重写的 xl.meta 体积翻倍：

• 单次写入 CPU 耗时：26.61 ms → 39.29 ms
• 单次写入块读取：12.20 MiB → 24.42 MiB
• 单次写入块写入：12.27 MiB → 24.49 MiB（4,000 次写入上传正文共约 15.6 MiB，累计块写入从 47.9 GiB 增至 95.7 GiB）
• 4,001 版本最终活动数据量：两版均为约 48.90 MiB
• 最后 1,000 次写入平均延迟：18.4 ms → 28.5 ms

集中历史版本既不能节省空间，又让更新成本随版本深度成倍放大，因此第二版直接排除了版本桶写入。

第二轮结果：排除了版本放大，但无版本小对象覆盖依然退化

第二轮对比收窄版（codex/unversioned-pool-affinity）与同一基线（789a2327ba8c）。测试前设定的准入线为：普通覆盖吞吐损失不超过 5%，P99 延迟增长不超过 10%，且 P50 与排除范围场景无实质退化。

四个场景每版各运行 5 次（AB/BA 交替，常规场景预热 5 秒、测量 60 秒，版本对照场景固定写入 4,000 次，每轮重建服务与数据目录，关闭性能分析器插桩）：

在核心的 4 KiB 普通覆盖场景中，五对运行的吞吐变化分别为 +11.9%、−14.9%、−1.4%、−10.3%、−12.8%（配对中位数变化 −10.3%，两版中位数比值 −5.7%，P50 上升 14.4%）。基线自身在 141.4–202.6 次/秒之间波动（变异系数 13.0%），收窄版为 146.3–176.6 次/秒，未能满足“吞吐损失 ≤ 5%”的准入线。

收窄范围确实消除了版本历史重写放大：单版本块写入为 12.272 → 12.268 MiB，块读取为 12.201 → 12.197 MiB，CPU 为 26.98 → 27.26 ms（版本对照项中五对均为后运行的二进制更快，而未改逻辑的新 key 对照项逐对波动达 −44.3% 至 +15.3%，反映出共享单盘测试环境的顺序波动）。

固定初始数据布局的恢复对照测试

新建数据集测试中，两种策略会随运行逐步写出不同的磁盘目录布局。为排除布局演化差异，追加的 8 轮夹具测试在每轮运行前恢复完全相同的初始数据快照——“每 key 单池副本（共 256 条记录）”或“每 key 双池副本（共 512 条记录）”——每次恢复后静置 30 秒，再预热 5 秒、测量 60 秒：

单份副本初态的两对运行分别为 −0.9% 和 −23.5%；而双份副本初态的两对运行分别下降 −22.6% 和 −26.5%，P50 暴涨 +111.9%，P99 上升 +36.9%，且磁盘上原有的 512 份记录一份也不会减少。对于已经积累了跨池旧副本的存量集群，这意味承担显著的写入性能退化却无法立即回收任何空间。

根因定位与 I/O 路径实验

阶段计时显示，新增的健康检查每次仅耗时 0.014–0.016 ms，远小于对象查找（毫秒级）和纠删码写入（数十毫秒级）。第二轮 4 KiB 覆盖的单次 CPU 时间从 5.75 ms 降至 5.36 ms，吞吐却反而下降，说明瓶颈来自存储路径上的 I/O 与调度等待。

Go 执行跟踪（execution trace）显示系统调用等待集中在 RenameData → writeAllInternal → write 以及读取和 goroutine 调度等待。

随后我们做了一项局部 I/O 实验：将小元数据写入（约 791 字节，小于 4 KiB 对齐粒度，CopyAligned 会自动关闭 O_DIRECT）从 Linux O_DSYNC 路径改走 writeAllDirect（实际等价于缓冲写加独立 fdatasync）。“收窄亲和 + I/O 修改”五轮正式运行均值达到 179.4 次/秒（对比基线 167.9 次/秒，+6.9%，P99 −1.5%，逐对波动 −19.2% 至 +35.9%）。但在两对同时给基线和候选分支都加上该 I/O 修改的对照实验中，“基线 + I/O 修改”达到 212.5 次/秒，“收窄亲和 + I/O 修改”为 185.2 次/秒（中位数差值 −12.8%，逐对 +37.7% 与 −49.1%）。由于修改小元数据同步写路径会影响全局存储引擎，且开启后亲和分支依然落后于同条件基线，该构建覆盖补丁未被采纳。

收益与代价汇总

在双池新建数据集测试中，256 个普通 4 KiB key 结束时的池内记录数从 512 份降至 256 份，活动数据逻辑体积从 6.18 MiB 降至 3.09 MiB；1 MiB 场景记录数从 128 份降至 64 份，体积从 171.56 MiB 降至 85.78 MiB。

从集群稳态看，若逻辑数据中有比例为 $f$ 的对象会在双池间产生第二份副本，消除额外副本可节省的总体空间比例为 $f / (1 + f)$（例如当 $f = 10%$ 时约节省 9.1%）。单次请求的写入量则不会减半：两版在 4 KiB 覆盖下的单次进程块写入均为 128 KiB 左右。

最终决定与后续重启条件

1. 完整亲和方案（codex/healthy-pool-affinity）：因集中版本历史导致 xl.meta 重写 I/O 翻倍、4,000 版本写入吞吐下降 30.8% 且无空间收益而否决。
2. 无版本收窄方案（codex/unversioned-pool-affinity）：虽消除了版本历史放大，但在普通 4 KiB 覆盖上仍存在 −5.7%（配对中位数 −10.3%）的新数据吞吐退化，且在存量双副本恢复测试中出现 −24.5% 的吞吐退化（P50 +111.9%）而否决。

因此，我们决定保持主线分配器行为不变，归档两轮基准测试证据（第一轮 54 次运行 / 243,718 次操作；第二轮 53 次运行 / 495,745 次操作）。后续若重新评估该问题，应先采集生产环境的真实旧副本空间占比并在多块独立物理盘拓扑上压测，再权衡是采用后台旧副本清理还是显式可选的放置策略。

源码与证据索引

公开参考资料：PR #245、上游容量修复 PR #21115、多池对象一致性，以及基线存储实现 cmd/erasure-server-pool.go、cmd/xl-storage-format-v2.go 与 cmd/xl-storage.go。

18 - 副本元数据归一化：可信复制不得重新注入什么

随 SILO Server 20260916（40220bd836cbd066ca424fa4dc5dbb90057fb55a）发布的 PR #194（修复提交 4fcdf37ce，合并提交 9f3037e941，采纳并保留 Mikhail Khadarenka 在 PR #187 中的实现），修复了可信复制接收端在恢复副本内部元数据时重新调用宽松请求头提取器、导致仅用于传输的 aws-chunked Content-Encoding 标记与 GHSA 已脱敏的用户元数据重新回流至落盘对象中的回归缺陷。

问题根因

普通 S3 PUT 路径在落盘前会对请求元数据执行归一化处理：从 Content-Encoding 中剥离仅用于流式传输分帧的 aws-chunked 标记，并删除 GHSA-76wf-9vgp-pj7w 缓解措施要求剔除的 X-Amz-Meta-X-Amz-Unencrypted-Content-Length 与 X-Amz-Meta-X-Amz-Unencrypted-Content-Md5 用户元数据键。

然而，当可信复制接收端为副本写入恢复内部复制元数据时，却以开启“允许复制（allowReplication）”标志的方式重新运行了同一个通用宽松提取器——把原始 HTTP 请求中的全部标准请求头与所有 X-Amz-Meta-* 用户元数据重新覆盖回已归一化的元数据映射表中。结果在可信副本写入路径上，服务端可能落盘并在后续 GET/HEAD 响应中返回：

• Content-Encoding: aws-chunked（按 AWS SigV4 流式传输规范绝不能作为对象元数据持久化的纯传输编码），或未经拆分的 aws-chunked,gzip 整串（正确落盘值应为 gzip）；
• 上述两个在普通写入中已被 GHSA 缓解措施剔除的 X-Amz-Meta-X-Amz-Unencrypted-Content-* 用户元数据键；
• 对于未携带独立 PAX 头的 Snowball 归档条目：意外继承外层归档请求的 Content-Type、Cache-Control、Expires 与用户元数据。

底层对象数据字节本身并未受损，但持久化的 xl.meta 元数据被污染。该回归由 56fa63bfd（2026-04-15，针对 CVE-2026-34204 的复制请求头信任边界加固）引入——该提交的认证与信任边界保护本身完全正确并予以保留。

修复方案

提交 4fcdf37ce 仅修改 cmd/handler-utils.go，删除了布尔双模式辅助函数，将普通请求头提取与副本内部字段恢复彻底拆离：

• 普通提取器无条件跳过所有复制专用内部键；
• 新增专用副本提取器（extractReplicationMetadata），仅遍历复制头到内部头的映射表，且仅恢复 6 个复制域专用字段：
  1. SSE-C 密封密钥材料（x-minio-internal-server-side-encryption-ssec-key），
  2. SSE-C 密封算法（x-minio-internal-server-side-encryption-ssec-seal-algorithm），
  3. SSE-C 初始向量 IV（x-minio-internal-server-side-encryption-ssec-iv），
  4. 加密多段上传标记（x-minio-internal-encrypted-multipart，空值标记按键存在性生效），
  5. 实际逻辑对象大小（x-minio-internal-actual-size），
  6. SSE-C 校验和恒等映射；
• 副本提取器绝不重新读取标准受支持请求头（如 Content-Encoding、Content-Type 等）或 X-Amz-Meta-* 用户元数据。

修复后各请求编码对应的落盘结果如下：

注：aws-chunked, gzip（逗号后带空格）仍存储带前导空格的 gzip，gzip, aws-chunked 仍存储整串；这两者属于普通 PUT 路径既有的解析现状，由测试按现状固定断言。

运维可见变化

• 可信 Snowball 归档条目： 可信 Snowball 条目不再继承外层归档请求的普通元数据。当条目不含 PAX 记录时，不再继承外层 Content-Type、Cache-Control、Expires 与用户元数据；当含有 PAX 记录时，也不再继承条目自身未声明的外层字段。条目自身的 minio.metadata.* 依然生效，6 个复制域专用字段仍作用于已授权条目，归档的存储类型（Storage Class）仍正常继承。（仓库内置批量生产端调用 PutObjectsSnowball 时虽发送自动解压标记，但外层请求并不标记为可信副本，因此未受该继承路径影响。）
• GHSA 脱敏键： 在副本元数据恢复时不再写回两个未加密长度/MD5 元数据键，与普通 PUT 行为完全一致。
• 不变边界： 身份认证、权限门禁与复制信任语义保持不变；普通 PUT 提取路径逐字节等价。

为什么升级服务端不会自动修复存量污染对象

升级至 SILO Server 20260916 会立即阻断新写入对象的元数据污染，但不会后台扫描或改写磁盘上的存量对象。运维中需注意两点影响：

1. 权威源端仍被污染时的反复同步： 若权威源对象仍带有被污染的元数据（例如来自早期的双向复制回流），在与已归一化的目标副本比对时会持续检测到元数据差异，导致在自愈（heal）或重新同步（resync）中反复触发元数据复制。务必先修复权威源端的对象版本，再让下游副本收敛。
2. 普通 S3 自 COPY 的局限性： 普通 S3 向自身发起 CopyObject 并非通用的存量修复 API，因为它在版本化桶中会生成新版本或更新时间戳，而不会原地改写指定历史 versionId 的元数据。

只读副本元数据审计手册提供了可执行的存量清单扫描工具与分类规则，用于在改动前盘点受影响的对象版本。

存量元数据修复方案设计原则

针对审计手册识别出的历史受污染对象，制定修复流程时应遵循以下安全边界：

• 构建包含所有非当前历史版本的完整清单（不能仅扫描最新版本）；
• 通过比对可信源版本或独立校验和来核验真实内容编码——绝不凭被污染的响应头猜测，也绝不因为头部写有 gzip 就盲目执行解压重传；
• 优先处理权威源端的精确版本，再让副本自动收敛；保留不可变清单与元数据备份，在小批量验证并演练回滚后再推广；
• 修复操作必须保持版本 ID 与当前版本关系、Object Lock 保留期与法务锁定、对象标签、复制状态及加密上下文不变；对缺乏受支持修复路径的对象保持原状，严禁直接手动编辑磁盘上的 xl.meta 文件。

已知范围边界

• 浏览器 POST 表单上传路径（cmd/bucket-handlers.go）直接调用底层提取器，原本即未对 aws-chunked 执行编码归一化；该路径不属于复制接收端，作为独立跟进项记录。

验证

回归测试（TestExtractReplicationMetadata*、TestAPIReplicaContentEncoding、TestAPISnowballReplicaContentEncoding 以及开启 -race 的复制信任与 SSE-C 往返测试）在真实单盘与 16 盘纠删码后端上覆盖了映射表、6 个复制恢复字段与普通路径等价性（共 64 个 HTTP 叶级用例：44 个对照通过，20 个缺陷用例在修复前失败、修复后通过，外加 16 个辅助函数单元测试）。

升级摘要见组件版本矩阵；姊妹修复见复制标签排序。相关设计记录：复制标签排序 · 副本元数据归一化 · 请求头超时防护 · 副本元数据审计手册。

19 - 为 SILO 提供多语言支持

Eduardo Andrade Machado 的 Console PR #83 提供了巴西葡萄牙语翻译。siyahkut 在 silo#277 中请求土耳其语。这两项贡献推动 Console 扩展为可配置的十语言界面。

**截至 2026-11-09 的状态：**十语言界面、审校后的译文、逐语言压缩、静态全量加载和长期缓存已合入 Console main，并随 Console 2.7.0 发布。最终复核保留了紧凑标签要求，并检查了相关控件在手机、平板和桌面宽度下的显示。源码合入、打标与正式产品发布仍是不同阶段。

决定

每种翻译语言生成一个预压缩 JavaScript 资源，全部词典静态导入，各自通过内容哈希独立缓存。 分包不意味着懒加载。应用加载完成后，切换语言同步完成，不再请求网络，离线也能切换。

九份翻译词典逐语言执行 gzip -9 后合计 555,105 字节，合并压缩则为 549,712 字节：分包只增加 5,393 字节，约 1%。这个体积对管理控制台可以接受。我们承担包括英文用户在内的首次下载成本，换取无需语言加载状态、超时、重试和迟到响应协调的简单实现；独立文件则让单种译文更新后能复用其他语言的缓存。

英文始终是默认语言，也是唯一的缺词回退语言。中文由第一方维护，必须完整。其他语言更新期间可以暂时回退英文。只翻译界面，服务端消息和日志内容原样展示。本次决策覆盖 Console，不扩展为服务端、命令行工具或整套文档的多语言工程。

为什么增加语言

管理控制台要求用户理解访问策略、保留设置、复制和危险操作。熟悉的语言有助于理解这些控件，也能让更多运维人员使用产品。葡萄牙语和土耳其语已经有具体的社区贡献或需求；统一注册表可以让后续语言沿同一条路径接入。

持续成本比增加一个菜单项更大。英文文案变更需要补译，存储术语需要保持一致，长文本和 RTL 文字影响版面。如果译文把保留或删除警告的意思翻反，危害比清晰的英文回退更大。词典条目齐全并不能证明语言质量合格。

因此，设计需要限制范围、区分维护承诺，并自动检查结构问题。安装和运行 SILO 不需要新增翻译服务、下载模型或访问外部运行时依赖。

已定决策

1. 先合并 #83，再提交维护者调整，保留原作者署名。
2. 统一使用下拉语言菜单，并提供 KBar 语言命令。
3. 支持英语、中文、法语、德语、俄语、西班牙语、巴西葡萄牙语、日语、阿拉伯语、土耳其语。
4. 默认英文，不探测浏览器语言，保留用户显式选择。
5. 中文覆盖率阻断 CI，其他语言报告覆盖率。
6. 全部词典启动时加载，构建产物按语言分包并预压缩，通过内容哈希与长期缓存独立复用。
7. 阿拉伯语同时实现 RTL 布局，协议数据仍从左到右展示。

原有设计

英文原文就是词典 key。原中文词典分为 zh、zhHelp、zhScreens，合并优先级为外壳文案 > 功能页面 > 帮助。原先所有用户都会下载登录页和 Console 包中的中文词典。

保留英文原文 key，可以直接得到可读的回退文案，也无需仅为引入消息 ID 而重写数千处调用。代价是修改英文措辞就意味着迁移 key：审查时必须有意识地更新词典，不能把英文润色视为与翻译无关的改动。

代码中还有数字/日期格式、链接、间隔和语言按钮的专用分支。五处数量显示按英文单复数选择，不能覆盖俄语、阿拉伯语的复数规则。

PR #83

贡献包含 2,249 个词条和葡语专用的异步加载器，将双语切换改为英语 → 中文 → 葡语循环。翻译工作值得接纳，但选择器和加载方式需要成为通用能力，不能持续增加葡语专用分支。因此先合并 #83、保留贡献者原始提交，再调整注册表和界面。

原加载器在功能页面词典失败时，可能已注册公共词典却不通知已挂载组件。最终静态实现彻底消除了这类失败路径，同时删除 catalogRevision、首屏等待、重试状态和葡语专用加载器。贡献中的组件文案回归测试保留，改为验证同步切换与离线行为。

体积与打包

测量口径

以下数据来自 2026-11-09 的生产构建，基于完成译文及紧凑标签复核后的 Console 提交 b0371b6。未来文案变化后需要重新测量。十种可选语言对应九份翻译词典：英文直接使用源码 key，不需要重复词典。KB 按 1,000 字节、MB 按 1,000,000 字节计算。

九个生产词典资源压缩前合计 1,863,188 字节。生产流水线固定使用 fflate 0.8.3、level: 9、mtime: 0，得到 568,470 字节。优化后的完整嵌入 GUI 为 2,357,925 字节，相对合入葡语 PR 后的 1,905,708 字节增加 452,217 字节（23.7%）。这里统计的是嵌入 Web 资源，不是整个 Go 可执行文件。

登录首屏 JavaScript 合计 794.08 KB gzip，预算为首屏依赖图 850 KB、全部语言数据 630 KB、每个分包 350 KB。检查器会累加所有语言包，要求每个语言包都属于首屏静态依赖图，同时执行单包上限；不能靠拆成多个小文件绕过体积限制。

合成一包，还是每种语言一包

对比保持生产源码、压缩混淆方式和静态导入不变，只调整构建分组：全部词典一个组，或者每个语言目录一个组。每个语言组都包含 chrome、help、screens 三部分。然后分别用本机 gzip -n -9 命令和现有固定版本压缩器处理生成的 JavaScript。

相同压缩级别不保证不同实现输出相同字节。系统命令用于对比，固定生产压缩器用于保证不同构建主机上的结果可复现。两种实现得到相同的打包结论，因此不需要为此更换压缩器。

合并文件并不会自动消除跨词典重复的所有英文 key。DEFLATE 只能引用前面 32 KiB 窗口内的文本，而单种语言的完整词典远大于这个窗口。这解释了为什么不能预设跨语言合并会带来巨大压缩收益；上表给出了实际构建的结果。参见 RFC 1951 第 2 节。

缓存收益与请求代价

另一次构建只修改了一句土耳其语 UI 译文。分包后，只有土耳其语语言资源的哈希变化，其他八个保持不变；合并时，整个语言包的哈希变化。若浏览器保留了有效缓存，这次修订后需要下载的语言数据按生产压缩器计算约为 63 KB，而不是 562 KB。入口模块也可能变化，因此这不是整个应用更新流量的比较。如果所有语言一起修改，独立复用的收益也会明显下降。

代价是冷启动多八个请求。全部语言仍在应用使用前下载和初始化；分包不会减少首次传输总量、词典内存分配或 JavaScript 解析工作。高延迟 HTTP/1.1 连接可能放大额外请求的成本。本轮测量证明的是字节体积与哈希稳定性，没有测出加载时间或内存占用的改善。

独立缓存还需要明确的服务端策略。早期合并语言包的实现设置了 Content-Encoding: gzip 和 Vary: Accept-Encoding，但没有明确的长期 Cache-Control。现已落实以下策略：

• 对确实存在、带内容哈希且与用户无关的 JavaScript 和 CSS 资源设置 Cache-Control: public, max-age=31536000, immutable。
• HTML 入口设置 Cache-Control: private, no-cache，重新验证以发现新资源名称。不存在的资源路径回退到 HTML 时不会继承长期缓存；API 的缓存策略继续由各自处理器控制。
• 构建时预压缩，服务时直接发送已有 gzip 内容。.js.gz 是采用 HTTP 内容编码的 JavaScript 资源，不是要求用户手动解包的归档文件。

这一策略遵循带版本资源的 HTTP 缓存原则。使用实际 Go 静态资源处理器的浏览器检查确认：首次访问加载九个生产语言文件，刷新时九个全部复用缓存；十种语言可离线切换，并保留未保存输入。该资源检查的 API 响应使用受控测试数据，不是整套 SILO 部署的验收测试。

为什么仍然全量加载

约 0.57 MB 的压缩词典对当前 Console 可以接受。随应用加载全部词典，可以消除切换语言时的另一组失败路径：无需协调部分词典到达、加载提示、首屏宽限时间、重试循环和过期响应。应用加载完成后也能离线切换语言。这不意味着首次加载前即可离线使用 Console，也不意味着存储操作不再依赖服务端。

成本依然存在：英文用户会下载可能永远不用的翻译，所有用户都要解析并保留这些词典。如果以后语言语料显著增长、首屏依赖图超过预算，或目标网络与设备的实测发现问题，再讨论选择性加载。当前仅为了更小的字节数，还不足以引入这套运行时复杂度。

设计

范围

翻译静态 UI 文案、帮助主题、控件无障碍名称、日期和数字格式、图表图例前缀。服务端错误、日志、审计、Trace、健康报告数据、对象名称、路径、配置标识符、策略 JSON 和 RSS 内容保持原样。文档站仍为中英双语：中文使用中文链接，其他语言回退英文链接。

语言注册表

src/i18n/locales.ts 管理 LOCALES 与 CATALOGS。元数据记录语言自称、BCP 47 标签、方向和维护级别。CATALOGS 的类型为 Record<Lang, Dictionary>，新增注册语言后，类型检查会要求补上词典映射。

这里的可配置是源码中的构建配置，不是管理后台设置，也不是远程语言包服务。组件从注册表读取菜单、格式和方向，避免继续增加语言专用的条件分支。例如：

tr: { label: "Türkçe", tag: "tr", dir: "ltr", tier: "maintained" },

已有 zh 偏好不变。早期测试版的 pt 映射为 pt-BR；未知或未启用的值回退英文。未完成的语言可以通过 enabled: false 从菜单排除，但隐藏菜单项本身不会从构建中移除静态导入。

词典布局

每种语言在 src/i18n/locales/<id>/ 下保留 chrome.ts、help.ts、screens.ts。这三个文件用于组织翻译，不代表加载阶段。字面量 TypeScript 格式保留译者注释，支持静态校验。合并优先级仍为 chrome > screens > help。

加载

每种语言的三个部分全部静态导入。浏览器在应用启动时加载这些 JavaScript 依赖，渲染和后续语言切换不用等待另一轮语言请求。没有语言请求 API、Promise 缓存或启动计时器。共享下拉菜单也静态导入，因此应用首次加载完成后，第一次点击菜单即可离线选择语言。既有路由拆包，以及编辑器、图表、PDF 等大型组件的加载方式，与语言切换相互独立。

格式与链接

组件读取注册表中的格式化标签和站点语言字段。整句模板决定标点和间隔。MDS ControlLabelsProvider 提供 Actions 标题，删除 CSS 生成中文的做法。

语言菜单

登录、匿名页面和 Console 复用地球按钮与下拉菜单。每项用语言自称，并带对应 lang、dir；标记当前语言，键盘选择后将焦点还给按钮。KBar 提供同一组语言命令。

十种语言继续循环切换，会迫使用户经过多个看不懂的界面才能找到自己的语言。下拉菜单允许直接选择，也能随语言数量增长。使用语言自称，即使当前界面陌生，用户也能认出目标语言；无需用国旗代表语言。

复数

tn(count, one, other) 使用 Intl.PluralRules。多形式译文放在英文复数 key 下，包含该语言使用的全部类别。缺词时按英文规则选择英文原文，不将俄语或阿拉伯语规则应用到英文回退文案。

字体

中文和日语避免拉丁大写字距，阿拉伯语使用正常字距。非拉丁文字依靠系统回退字体，不增加字体下载。德语标题和控件允许断词。

紧凑措辞是界面要求。提高准确性时，不能把已经解决的长标签溢出问题带回来。例如，西语 Tiempo activo、法语 Temps actif 和葡语 Tempo ativo 保留 Uptime 的时长含义；纠删码健康标签可用 EC 缩写；生命周期过期标签仍需指明历史版本。应在真实指标卡和表单中审核这些文案，不能只看词典表格。

从右到左布局

间隔、对齐、边框和移动抽屉改用逻辑 CSS 属性。方向图标、标签页方向键和开关滑块随 RTL 改变。对象路径、桶名、ARN/JSON、策略编辑器和原始 Trace/日志数据保持 LTR。图表与物理视口坐标不做机械镜像。

维护分级与检查

中文完整覆盖是硬门槛。其他词典缺词时报告并回退英文，暂时的缺词不阻断无关发布，但仍需要持续审校和修正，所有词典也都必须通过结构校验。审校后的词典每种语言三部分合计 2,252 个词条，对应 2,235 个不同的 key；这是 key 覆盖统计，不是语言熟练程度证明。

两级翻译维护策略反映维护责任。核心团队承诺中文完整，其他语言通过贡献持续演进，不暗示团队有能力亲自保证每种语言的母语质量。英文是唯一回退语言，法语缺词时不会突然显示中文。

占位符错误、空译文、复数类别错误、重复或错分段 key、无效语言标签、注册表与目录不匹配都会导致校验失败。原有中文孤立词条和重复项基线是历史例外，不允许扩充以掩盖回归。

翻译生产

新增词典采用 AI 辅助草稿，再按术语、UI 上下文和危险操作说明校对。术语表覆盖核心存储与访问控制概念，审核重点包括否定关系、权限、不可逆操作、保留期限、占位符和协议标识符。完整覆盖不等于母语审校，AI 复核也不能证明已经达到这一标准。首轮审核与随后的紧凑标签复核已完成，较长帮助段落继续接受修正。

贡献指南说明了 i18n:report：导出缺词及中文参考、源码位置；以及 i18n:rename：在词典间迁移经过确认的英文 key 改动。翻译工具和服务不是构建或运行时依赖。

版面检查

真实语言在 350、768、1440 像素宽度检查登录页和密集的站点复制表单。额外覆盖键盘操作、偏好持久化、所有语言离线切换、未保存表单、RTL 抽屉/标签页，以及日志和路径原文不变。

同样的三种宽度也覆盖每种语言的真实指标行组件和批量生命周期对话框。检查拒绝标签与数值重叠、字段文字裁切或横向溢出，并保留紧凑指标布局，为后续译文调整守住版面约束。

开发专用 en-XA 将文案拉长约 40%，ar-XB 检查 RTL。两者不进入公开菜单或生产词典。词典校验、类型检查、全量前端单元测试和生产包预算共同补充浏览器验收。

考虑过的替代方案

按语言懒加载曾在评估中实现，维护者选择静态方案后将其移除。独立 gzip 文件仍然保留了以后调整加载方式的自然边界，不必现在就引入相关状态。

交付

PR #83 已保留原始历史合并，初版十语言实现与嵌入 GUI分别提交。最终交付包含审校译文与紧凑布局检查、逐语言资源与缓存策略，以及重新生成的嵌入 GUI。

最终源码通过 789 项前端单元测试、Go API 测试、类型检查、格式检查、未使用代码检查和生产包预算。词典修订既要进入 TypeScript 文件，也必须进入实际发布的 GUI。

验收覆盖缺词回退、占位符和复数、语言偏好持久化、首次加载后的离线切换、未保存表单、阿拉伯语布局、原始数据不变，以及只修改一种语言后的缓存复用。双语设计记录由伴生站点承载；源码合入、生成资源、文档发布和产品发布仍是不同交付事项。

20 - Multipart 提交失败可能让上传卡死

本记录说明在下一版本地验收中发现的一个缺陷。它在 69fcf50cd 上能复现，继承自上游 MinIO。目前还没有对应的 GitHub issue。

**状态：**已分析并复现。起草过一版修复，但对抗评审认为它对本版风险太大，予以否决。修复推迟到下一版，与存储操作的完成确认（fencing）一起做。下一版把它列为已知问题。

简短回答

CompleteMultipartUpload 没有达到写 quorum 时，这个上传可能变得无法使用，即使之后所有盘都恢复正常：

• 再次 Complete 返回 503；
• 用同一个 upload ID 重新上传分片返回 503；
• ListParts 列不出任何分片。

上传会一直保持这个状态，直到过期清理把它删掉，客户端只能新建上传、重新发送所有分片。如果 rename 成功的盘数超过校验盘数，已上传的数据甚至无法重建。还有一种变体：某块盘执行了 rename，但应答丢失，重试会返回 404 NoSuchUpload，客户端可能把它理解成“之前的 Complete 已经成功”。

这个缺陷不影响已提交的对象。受损的是进行中的上传，而且只在提交时恰好遇到盘故障时发生。

把分片移回、恢复上传元数据的小修复能让复现测试通过，但它会和迟到的存储操作、以及过期上传清理发生竞争。在这些竞争下，它可能发布一个没有数据的对象，或者把一块没有分片的盘算作写入成功。那会把一个可用性缺陷变成数据缺陷，所以不进本版。

**临时办法：**如果 Complete 返回 503，并且在集群恢复正常后仍然失败，就中止这个上传，重新上传对象。

定性

何时发生

Complete 原地把上传 rename 成对象。以 4 块盘、EC 2+2（写 quorum 3）为例，下列情况会触发：

• rename 在 2 块盘上失败，在另外 2 块上成功（权限错误、盘满、盘故障）；
• 一块盘离线，另一块盘上 rename 失败；
• 一块盘执行了 rename 但应答丢失，另一块盘上 rename 失败。

如果只有一块盘的 rename 失败，quorum 仍然达到，提交成功。如果失败的盘不止一块，但上传仍保留在足够多的盘上，那么第一次重试会返回 400 InvalidPart，只有重新上传分片才行。

根因

行号对应下一版的本地集成；69fcf50cd 上是同一条代码路径。

1. 提交之前，Complete 在每块盘上删除每个已完成分片的 part.N.meta（cmd/erasure-multipart.go:1663-1678、:1725）。这时还不知道提交能否达到 quorum。
2. 提交调用纠删层的 renameData，把上传目录 rename 成对象（:1734）。在每块盘上，xlStorage.RenameData：
   • 用合并后的对象 xl.meta 覆盖上传的 xl.meta（cmd/xl-storage.go:2900）；
   • 把上传的数据目录（包含所有分片）移进对象（:2926）；
   • 把 xl.meta 也移过去（:2965）；
   • 删除上传目录（:2989-2996）。
3. 没达到写 quorum 时，撤销步骤在 rename 成功的盘上调用 DeleteVersion(UndoWrite)（cmd/erasure-object.go:1140-1167），把这个版本的数据目录，也就是上传的分片，移进回收站（cmd/xl-storage.go:1387-1412）。没有任何东西被移回 .minio.sys/multipart。

结果是，上传只留在 rename 失败的那些盘上，而且那里保存的是合并后的对象元数据，不是上传自己的元数据。这些盘不够写 quorum，所以 PutObjectPart 和 Complete 返回 503；所有盘上都没有 part.N.meta，所以 ListParts 什么也列不出。

来源

• 上游 #9377（4915433bd，2020 年）把原来“把上传 rename 回去”的撤销，换成了丢弃数据的版本删除。在此之前，失败的 Complete 可以重试。
• 上游 #15346（f939d1c18，2022 年）引入了 part.N.meta，以及在 rename 之前删除它。
• 把合并后的元数据写回源目录，来自 2d58a8d86（2020 年）。

方案

方案 A：撤销步骤把分片移回

只对 multipart 来源：在原有的 DeleteVersion(UndoWrite) 之前，先把数据目录 rename 回上传目录。这是必要的，但单靠它不够：分片元数据已经在所有盘上被删掉，上传元数据也已被移走或覆盖。

方案 B：等调用方决定之后再删上传目录

某块盘上 rename 成功时，上传目录已经空了，推迟删除省不下任何东西。而且这需要改存储 RPC，所有节点都要升级。不采用。

方案 C：用仍保留上传的盘重建上传

数据可能已经没了，分片 ETag 也丢了；而且少数盘上的残留，无法和一次已经成功的 Complete 或 Abort 留下的残余区分开，可能导致同一个上传被提交两次。不采用。

方案 D：把 part.N.meta 保留到提交之后

这会改变成功路径，崩溃后还会在对象目录里留下分片元数据；而且仍然需要方案 A 和元数据恢复。不采用。

方案 E：返回 NoSuchUpload，或者直接中止上传

这不是修复。S3 客户端重试 Complete 时收到 NoSuchUpload，会理解为“可能已经成功”。

起草的修复，以及为什么暂缓

起草的修复是方案 A 加上 Complete 中的恢复步骤：保存每块盘上上传的元数据；提交失败时，在每块盘上先用 CheckParts 检查分片是否齐全，再重写每个 part.N.meta，最后重写上传的 xl.meta。代码约 45 行，只改失败路径，不改存储 RPC 和格式，复现测试的所有用例都能通过。

对抗评审否决了它进入本版：

• **迟到的 rename 可能发布一个空对象。**远端 rename 可能先暂存对象元数据，在移动数据之前停住，而调用方此时已经看到了错误。恢复步骤把上传元数据写回去之后，迟到的 rename 继续执行，就会把它当作对象发布：大小为零，没有分片。迟到的撤销同样可能删掉一次成功的重试，因为它只按复用的版本 ID 匹配。
• **过期上传清理不取锁。**它可能在 CheckParts 通过之后删掉一个已过期的上传。恢复步骤的写入随后会重建一个只有分片元数据的数据目录，重试时可能把这块没有分片的盘算作写入成功。
• 空上传会丢失零长度的分片文件，恢复步骤没有重建它们。
• **恢复步骤不理会锁丢失，还可能在持锁期间运行很久：**分布式锁丢失后它仍继续写；分片成千上万的上传意味着每块盘成千上万次持久化写入。
• **数据移走之后的明确失败，仍会让上传卡住：**一块盘如果在移动分片之后、提交元数据之前失败，它既不会被撤销，也不会被恢复。

前两条会把可用性缺陷变成数据缺陷。它们都来自同一个缺失的保证：调用方无法判断一个返回错误、或者已被放弃的存储操作到底有没有执行完。这个缺口已经针对所有写路径单独跟进。

完整的修复需要什么

• 在复用上传路径之前，先能对每块盘上的 RenameData 和撤销操作做 fencing，或确认其结果；
• 过期上传清理与恢复步骤互斥，并在写完分片元数据之后重新校验；数据目录在最后一次校验之后绝不能被重建；
• 空上传的零长度分片文件；
• 锁丢失时取消、总时间预算，以及有上限的并行写入；
• 恢复已明确失败、但数据已被移走的那些盘，或者明确收窄修复范围。

后续修复的代价与兼容性

起草的做法不改存储 RPC 和盘上格式，只有协调节点运行新逻辑。存储操作的 fencing 可能改变这一点，因为它需要盘按代际报告或拒绝操作。相关设计归入存储操作完成确认的单独跟进。

验证

一个确定性的单元测试在 4 块盘、EC 2+2 的纠删集上，上传 5 MiB 和 1 MiB 两个分片，制造盘故障后执行 Complete，再恢复这些盘，然后要求：ListParts 列出两个分片；直接重试和重新上传后的 Complete 都成功；内容一致；没有哪块盘持有对象元数据却缺少分片。在 69fcf50cd 和本地集成上，所有用例都失败：

进程级验收在 69fcf50cd 和下一版上，以同样的结果复现了桶目录只读和盘离线两种情况。

顺带发现的相关缺陷

• 已上传、但没有列入 Complete 清单的分片，会被移进对象的数据目录，成为孤立文件。上游从 2022 年起就存在。
• 当足够多的盘因为权限错误导致提交失败时，Complete 返回 403 而不是 503，客户端可能不会重试。

两者都列入下一版跟进。

评审记录

• 对抗评审第 1 轮：否决进入本版，理由见起草的修复，以及为什么暂缓。评审还纠正了本记录的几处说法：起草的修复并不充分，遗留竞争被低估了，“已提交的对象不会丢失”也说得太宽，因为撤销步骤里还有那个更早的缺口。

参考

• 上游 #9377、#15346
• 局部视图不能把存在的对象报成不存在

21 - 局部视图不能把存在的对象报成不存在

本记录说明在下一版本地验收中发现的一个缺陷。下一版的本地集成和 69fcf50cd 上都能复现。目前还没有对应的 GitHub issue。

**状态：**修复已通过对抗评审（附若干小意见，均已采纳），并已在本地分支实现。尚未合并或发布。

简短回答

刚重启的节点，或者短暂与部分节点断开连接的节点，只能看到纠删集里的一部分盘。如果它能看到的盘上，对象元数据分属两个修订版本，而哪个版本都凑不够读 quorum，GET 和 HEAD 就会对一个存在的对象返回 404 NoSuchKey。

数据不会丢失，也不会被删除。但 S3 客户端、缓存和复制都把 404 当作确定结论：备份工具可能把这个 key 记成已删除，缓存可能存下这个否定答案，条件写入可能基于一个错误的“不存在”做决定。从这样的局部视图出发，正确的回答是 503 SlowDownRead，客户端会重试。

修复只改 cmd/erasure-object.go 一个文件，新增 37 行、改动 2 行：

• 只有纠删集里每块盘都应答了，元数据不一致才判为“不存在”；
• 版本合并找不到达到 quorum 的版本、且有盘没有应答时，持有版本的盘报告读 quorum 错误，而不是“不存在”。

在足够多的盘应答、且每块应答的盘上都没有这个 key 时，仍然返回 404。所有盘都应答的情况下，行为不变。在这种视图下执行的删除、复制和维护操作，现在会失败并重试，而不是把对象当作不存在；代价与兼容性列出了这些情况。

定性

何时发生

两个条件必须同时成立：

1. 一次写入在写 quorum 上提交，但没有写到所有盘，而且改动了元数据 quorum 会比较的字段。恢复、转储、恢复副本到期、覆盖未开版本控制的对象都属于这类。写入时离线的盘保留旧版本，直到 heal。
2. 某个节点通过局部视图读取：它至少能连上一半的盘，但连上的盘分属两个版本，没有哪个版本达到读 quorum。8 块盘、EC 4+4 时，能看到 4 或 5 块盘的节点就可能遇到。

发现它的那次验收：4 个节点，每个节点 2 块盘，EC 4+4。节点 1 和节点 2 同时重启。经节点 1 发起的 t1 恢复只提交到 8 块盘中的 6 块，因为当时还连不上节点 2 的盘。节点 2 只能连上自己的两块盘（未恢复）和节点 4 的两块盘（已恢复）。经节点 2 的 GET 和 HEAD 返回 404。69fcf50cd 上也出现了同样的失败。

根因

行号对应下一版的本地集成；69fcf50cd 上是同一条代码路径。

1. 启动时连不上的盘，在节点的纠删集里留空（cmd/erasure-sets.go:420），不到 1 秒后重连一次，此后每 15 秒一次（:287-290、:349）。
2. getObjectFileInfo 里，没有应答的盘保持 errDiskOngoingReq（cmd/erasure-object.go:792, 820），quorum 统计忽略这个错误（:57）。
3. 版本合并和 objectQuorumFromMeta 接受 8 块盘中的 4 个应答（cmd/erasure-object.go:659-661、cmd/erasure-metadata.go:560）。
4. findFileInfoInQuorum 只对远端版本把转储字段算进哈希（cmd/erasure-metadata.go:346）。恢复副本不是远端版本，所以 2 个已恢复副本和 2 个未恢复副本分成两组，每组 2 个，低于读 quorum 4，返回 InsufficientReadQuorum{RQInconsistentMeta}（:386）。
5. getObjectFileInfo 把这个错误转成 errFileNotFound（cmd/erasure-object.go:1007-1016），API 返回 NoSuchKey。

未开版本控制的对象被覆盖时，还有第二条路径通向同样的 404：没有版本达到合并 quorum 时，pickLatestQuorumFilesInfo 把所有应答过的盘都标记为“不存在”，包括持有对象的盘（cmd/erasure-object.go:661-668）。

与 tier 无关。tier 连接被拒绝会映射成 XMinioBackendDown（HTTP 400），不会是 NoSuchKey；而且读取在到达 tier 之前就已经失败。

来源

• RQInconsistentMeta 转“不存在”来自上游 #20522（dc86b8d9d）。它的提交说明假定“所有盘都给出了足够的应答”，代码却没有检查。
• 只对远端版本哈希转储字段来自上游 #19165（c599c11e7）。
• 合并失败后把所有盘标记为“不存在”来自上游 d48002271。

方案

方案 A：只有所有盘都应答，才把元数据不一致转为“不存在”

补上缺失的前提：每个位置都必须是元数据，或者是明确的“没有这个文件、版本、卷，或元数据损坏”。这修复恢复和转储造成的分裂。新增 15 行、改动 2 行。

方案 B：局部视图下合并失败时，保留读 quorum 错误

合并找不到版本、且有盘没有应答时，持有版本的盘报告 errErasureReadQuorum，而不是 errFileNotFound。这修复未开版本控制对象的覆盖路径。新增 20 行。

方案 C：对所有转储版本都哈希转储字段

这会把已恢复和未恢复的副本合成一组，再由下标顺序决定返回哪一个。它不覆盖未开版本控制对象的覆盖，还会改变 #19165 之后的 heal 判断。不采用。

方案 D：让 /minio/health/cluster 反映本节点自己的视图

集群检查按各节点自报的本地盘计数，所以本节点还连不上部分节点时，它也可能报告“健康”。改它不能消除 404（任何局部视图都会触发），还会改变编排系统依赖的语义。对这个缺陷不采用。

方案 E：启动后更快地重连盘

只能缩小窗口。可以作为单独的改动。

修复方案

在 cmd/erasure-object.go 中同时采用方案 A 和 B：

• 新增辅助函数 allDrivesAnswered(errs)：每个位置都是 nil，或 errFileNotFound、errFileVersionNotFound、errFileCorrupt、errVolumeNotFound 之一时为真。这些都是盘给出的明确答复。元数据损坏也算作答复，是因为它已不可用，而不是因为它证明对象从未存在。请求仍在进行、盘缺失或故障、盘未格式化、访问错误、传输错误、context 被取消，都不算答复；
• getObjectFileInfo 中，RQInconsistentMeta 的转换要求 allDrivesAnswered；
• pickLatestQuorumFilesInfo 中，合并以“不存在”失败、且不是所有盘都应答时，xl.meta 中持有可读版本的盘得到 errErasureReadQuorum。

为什么充分且必要

• **充分。**把局部视图变成 404 的两条路径，现在都要求所有盘都应答过。否则读取保留 quorum 错误，API 返回 503。
• **必要。**只有方案 A，未开版本控制对象的覆盖仍会 404（路径 B）；只有方案 B，恢复和转储仍会 404（路径 A）。缺任何一半，复现测试都会失败。
• **最小。**不改存储 RPC、元数据哈希和健康检查语义，悬挂对象清理删除的东西不多也不少。真正不存在的 key，或所有盘都应答的对象，回答都不变。

代价与兼容性

• 代价：只在错误路径上多遍历一次错误数组，没有额外 I/O。
• S3：S3 承诺强读后写一致性，所以 NoSuchKey 必须意味着 key 不存在。503 SlowDown 是 SDK 会重试的临时错误码。
• 混合版本：改动只在处理请求的节点本地生效。滚动升级期间，旧节点在这种状态下仍返回 404，已升级节点返回 503，不需要协调。
• 有意的行为变化：某些盘离线时被删除的未开版本控制对象，如果从一个“旧副本和已删除副本恰好一样多”的视图读取，在节点重连或 heal 之前返回 503 而不是 404。从这个视图看，两种历史无法区分。
• 多池（依据代码推断）：读 quorum 错误被视为“对象在这个池里”，所以某个节点处于局部视图时，PUT 不会再在另一个池里创建重复对象。
• 其他经过这种视图读取的操作，现在返回 503 并重试，而不是把对象当作不存在：
  • 多池下删除一个副本以这种方式分裂的未开版本控制对象（deleteObjectFromAllPools），以前可能走受保护的盲删路径；
  • CopyObject 读取源对象，以及标签和元数据更新；
  • decommission 和 rebalance，会重试或报告这个对象，而不是把它当作缺失而跳过。

遗留限制

• 在写 quorum 上提交的带版本覆盖，通过这样的局部视图仍可能读到旧版本。这是上游既有行为，不在本次范围内。

• 永久损坏的盘。 errDiskNotFound 算作没有应答的盘。因此在有一块永久坏盘的纠删集中，元数据分裂、且没有任何修订达到 quorum 的对象不再返回 404：

  • GET 和 HEAD 持续返回 503；
  • 在开启版本控制或版本控制暂停的桶中，它的 DELETE 返回 InsufficientWriteQuorum，dangling 对象清理也因为缺盘而拒绝执行；
  • 在未开版本控制的桶中，它的 DELETE 仍可走盲删。

  更换这块盘之后，纠删集的每块盘都会重新应答。但这本身并不能恢复这个对象：只有足够多的存活盘对它的元数据达成一致并持有它的数据时，heal 才能重建它。否则，一旦每块盘都应答，这次不一致的读取可能变成“不存在”。恢复步骤：更换这块盘，等盘的 heal 完成，然后读取该对象并列出它的版本加以确认；不要假定它已经恢复。

• /minio/health/cluster 可能在节点连上所有对端盘之前就报告健康。验收脚本应改为经每个节点探测一次写和读。

验证

一个确定性的单元测试构建 8 块盘、EC 4+4 的纠删集和内存 tier，在隐藏两块盘的情况下提交恢复、转储或覆盖，再通过只有 4 块盘的视图读取：

恢复、转储和未开版本控制的覆盖三种情况，断言返回读 quorum 错误、HTTP 503。带版本的覆盖可以返回旧版本，但不能报告为不存在。撤掉修复后这三种情况都失败；只保留方案 A 时，未开版本控制的覆盖仍然失败。

修复后约 100 个相关测试通过，覆盖读 quorum、悬挂对象、恢复、列举和删除标记清除。

评审记录

• 对抗评审第 1 轮：批准，附若干小意见。评审逐一核对了判断条件对盘位上每种可能错误的处理、版本合并的所有调用方，以及悬挂对象清理。小意见已全部采纳：测试改为断言 503，而不只是“不是 404”；本记录补充列出了会失败而不是把对象当作不存在的降级删除、复制和维护操作，也不再把元数据损坏当作对象不存在的证据。

参考

• 上游 #20522、#19165
• 恢复副本：过期的是副本，不是对象

22 - 两阶段原生恢复

本文覆盖 issue #284，以及 #281 第一版原生恢复防护带来的两处回归；那些防护记录在恢复副本：过期的是副本，不是对象中。本文基于 main 69fcf50cd 和下个版本的集成分支评估。这个设计取代 #281 防护中私有 upload 的部分，其余部分保留。

状态： 设计经六轮审查通过，实现经两轮审查通过，已在下个版本的集成分支上本地提交。尚未合并或发布。

简短结论

原生恢复（对已转储版本发起 POST ?restore）会从 tier 下载该版本，并写出一份本地副本。两个问题来自这次写入如何加锁，以及副本放在哪里：

• 读写要等待下载结束（#284）。 在有多个池的部署中，已发布的代码在整个下载期间持有对象写锁。#281 的第一版防护让单池也这样做，以免下载期间设置的 legal hold 被覆盖，并且把"对象锁被占用"当作"有恢复正在运行"。于是在恢复一个旧版本时，同一个 key 的所有 GET、HEAD 和写入，包括对其他版本的读取，都要等待下载结束。
• 失败的普通上传会卡住。 同一批防护把恢复数据放在一个用私有标记隐藏的分段上传里。普通上传的完成操作在暂存元数据之后失败时，这个标记就无法再区分两类上传。此后该普通上传对所有调用方都返回 InvalidUploadID，一小时内也无法中止。

下一个版本分两个阶段恢复：

1. 不持对象锁暂存。 worker 把 tier 副本纠删编码写入该版本所在纠删集的 tmp 卷，写法与 heal 写入它重建的分片相同。该 key 上的其他请求不必等待。
2. 短暂持有对象锁提交。 worker 重新读取该版本，确认它的尝试仍拥有该版本、暂存的内容仍是该版本的内容，然后逐盘发布副本。发布没有达到写 quorum 时，先在同一次持锁期间尝试收敛；这一轮没能理顺的，之后在重新取得的锁下重试，重试用尽或进程崩溃后仍可能留下未解决的状态。

判断是否有恢复正在运行的，改为每个版本一把的恢复锁，而不是对象锁。分段上传完成回到 main 上的代码，普通上传的行为与 #281 防护之前相同。

定性

根因

两处回归都来自 #281 第一版防护的两个选择：

• 恢复复用了公开的分段上传命名空间。 恢复 upload 与普通 upload 的唯一区别，是 xl.meta 中的一个键。完成操作会删除这个键，而失败的完成操作会在 upload 目录里留下合并后的对象元数据。发生这种失败之后两者无法再区分，只能隐藏所有已暂存的 upload，普通 upload 也在其中。
• 下载期间持有对象锁，而且这把锁代表 worker。 POST 根据对象锁是否被占用，推断是否有恢复在运行。因此在给 worker 另一种表明自己存活的方式之前，无法缩短这把锁的持有时间。

设计

先恢复锁，再对象锁

每个版本有一把恢复锁 R，它是系统桶下按桶名、对象名和版本 ID 命名的分布式锁。POST 先取 R，最多等待两秒，再取对象锁 O，持有到登记完它的尝试为止。新的尝试把 R 移交给 worker，worker 在整个运行期间持有它。除此之外没有任何路径取 R，所以不存在持有 O 时等待 R 的情况：顺序总是先 R 后 O。

R 只是存活提示，不保证排他。分布式锁的刷新失败按节点离线处理，所以在网络分区期间，第一个 worker 仍在运行时，另一个节点可能取得 R。因此正确性只依赖提交在 O 下所做的核验：被取代的 worker 会发现它的尝试已不再拥有该版本，于是什么也不写。它的暂存只属于它自己，不会干扰新的 worker。

在等待时间内取不到 R 的 POST，会不加锁地读取各盘：各盘显示该版本正在恢复时返回 409 RestoreAlreadyInProgress，没有显示或无法判断时返回可重试的错误。它从不启动第二个 worker。

在对象锁之外暂存

worker 在持有该尝试所指版本的池、以及对象哈希到的纠删集中暂存。它读取 tier 数据流，按版本各分段的大小切分，确认它们的总和等于对象大小，并按该版本自己的纠删布局把每个分段写到 tmp/<id>/<data dir>/part.N，使用与分段上传和 heal 相同的流式 bitrot 哈希。暂存期间不持有对象锁。

在所有分段的写入中逐盘跟踪：

• 某块盘在任一分段的写入、编码或关闭时出错，就被排除，之后不再为它创建写入器；
• 提交之前，对每块剩余的盘运行 CheckParts，每个分段都必须报告成功，所以 tmp 卷被移走、又被后续写入重建的盘也会被排除；
• 剩余的盘少于写 quorum 时，暂存失败，该尝试清除自己的标记，客户端可以重新发送 POST。

不做内联：恢复副本总是使用新的数据目录。

在对象锁下提交

随后 worker 取 O，等待时间与普通操作一样有界。取不到时，它清除自己的标记并删除暂存。在 O 下，它重新解析池（必须仍是暂存所在的池），读取该版本的权威修订，然后核验：

标签、retention、legal hold 和复制状态在下载期间可以变化。提交采用它在 O 下读到的修订中的这些字段，因此下载期间已确认生效的保护会保留。在按 ID 指定的版本之上出现更新的删除标记，不会让恢复停止；只有版本本身消失才会。

逐盘发布

提交在每块持有权威修订、且保留了暂存的盘上发布。它像 heal 一样直接调用该盘的 RenameData，从不经过纠删层的 rename：后者对被替换版本的回滚可能删掉新的数据目录，却留下指向它的元数据。每块盘写入的是提交在该盘上读到的版本，换上新的数据目录、已完成的恢复状态，以及在所有盘上相同的恢复字段。内联数据标记会被删除，因为更早的恢复可能把它留了下来。

副本达到写 quorum W 时提交成功：

• 被替换的数据目录只在返回了它的盘上删除，并且只有当这些盘返回的都是同一个目录时才删；否则留给废弃数据清理；
• 有盘没有拿到副本时，该版本以规范化的版本 ID（null 版本为 null）排入 MRF heal，由 heal 把这些盘修到已恢复的修订。

未达写 quorum 时的收敛

确认拿到副本的盘少于 W，或者某个结果不确定时，worker 在仍持有 O 时收敛该版本，之后再做有限次数的内存重试，每次重试都重新取 O。只有这个 worker 知道每块盘在提交前持有什么（Sᵢ）、提交在那里写了什么（Pᵢ），以及收敛会写什么（Vᵢ）。每一轮都先读取每块盘上的条目，要求每一条都等于其中之一：

• 出现任何其他内容就停止收敛：两次持锁之间有人改过该版本，例如密钥轮换、标签更新、新的尝试或 heal；不写入任何东西，并记录错误；
• Pᵢ 出现在 W 块或更多盘上，说明提交其实已经成功，例如响应丢失；该版本排入 heal，修复其余的盘；
• 其他情况下，worker 把 Vᵢ 写到每块持有该版本的盘上。Vᵢ 是不带任何恢复字段和内联标记、并使用旧数据目录的修订。此后该版本处于未恢复状态，新的 POST 可以再次恢复它。内容仍在 tier 上。

收敛不删除任何数据目录；不再被引用的目录留给废弃数据清理。重试用尽或某一轮停止时，worker 记录 restore publication did not converge，并附上桶、对象、版本、尝试和数据目录。

多池下的废弃数据清理

在把数据目录移入位置和改名 xl.meta 之间，某块盘上会短暂存在一个尚无元数据引用的目录。单池时，废弃数据清理本来就取同一锁域的对象锁。多池时，它只取各池所属集的锁，而这把锁与 O 并不互斥。现在多池时的废弃数据清理像 heal 一样取池层的对象锁，因此不会删掉提交已经移入位置的目录。每次 PUT 的 rename 也有同样的窗口，同一个改动一并关闭了它。

分段上传回到 main

分段上传完成中的恢复例外、私有 upload 标记、第一版设计的提交锁，以及 null 版本 Object Lock 检查中的恢复例外，都已移除。单池的完成操作重新先取 upload 锁、在提交之前才取对象锁，与 main 相同；多池时先取对象锁。暂存之后完成失败的普通 upload 的行为重新与 main 一致：重新上传分段后可以完成，也可以立即中止。Multipart 提交失败可能让上传卡死中描述的继承来的失败路径保持不变。

能力协议 2

旧服务器不取恢复锁，不在对象锁下核验尝试，提交方式也不同。因此只有集群中每台服务器都明确回答支持协议 2 时，才运行原生恢复：

• 处理 POST 的服务器询问每个对等节点，肯定的回答最多缓存十秒；只要有对等节点没有确认，就返回 503 ServiceUnavailable，不写入任何东西；
• 排队中的 worker 在开始前再问一次，因为恢复排队期间某台服务器可能被换成了旧二进制；开关关闭时它清除自己的标记；
• 无法连上的对等节点会阻止原生恢复（errNativeRestorePeerUnreachable，b8ebaffd2）：503 ServiceUnavailable 响应会单独指出不可达的服务器，与滚动升级协议不匹配（errNativeRestoreUnsupported）区分开，因为无法证明不可达的对等节点已经停止，它可能仍在对同一个版本运行旧的恢复。

两阶段恢复的设计文档写的是只有 POST 检查这个开关。代码在 worker 中也会检查，本文以代码为准。

为什么方案充分且必要

充分。 恢复只在提交时、在 O 下、通过上述核验之后才写入该版本，而只有拥有该版本的尝试能通过核验。下载期间，它不持有任何会让其他请求等待的东西。除剩余限制中的排除项外，发布的每种结果都落在三种状态之一：副本达到写 quorum；每块持有该版本的盘都是未恢复修订；或者记录日志后停止，不写入任何东西。

必要。

• 没有恢复锁，对象锁就仍要代表 worker，下载期间无法释放。
• 没有逐盘的合格性跟踪和 CheckParts，tmp 卷被重建的盘可能在缺少分片的情况下参与提交。
• 没有 O 下的核验，被取代的 worker、被替换的版本或已改变的布局都可能被发布。
• 不逐盘调用 RenameData，纠删层的回滚可能删掉被替换版本的新数据，而元数据仍指向它。
• 没有收敛，未达写 quorum 的发布会留下一个可能读不出来的版本。在 12 块盘、8 个数据分片加 4 个校验分片的集上，7 块盘发布成功就构成元数据读 quorum，但分片不足以重建数据。
• 废弃数据清理不取池层的锁，多池清理可能在元数据写入之前删掉已发布的数据目录。

代价与兼容性

• 普通请求。 GET、HEAD、PUT 和分段上传不取恢复锁，不做能力检查，也不多读任何东西。恢复在下载期间不再阻塞该 key 上的其他请求。多池时，scanner 的废弃数据检查改取池层的对象锁，而不是各池所属集的锁。
• 提交。 它在持有 O 期间重新读取版本元数据，并对每块盘调用一次 RenameData。这段时间随版本元数据的大小、分片数和盘数以及磁盘延迟增长，不随下载时间增长。它没有固定的毫秒上限。
• 恢复路径。 提交前对每块合格的盘做一次 CheckParts，恢复锁的刷新，以及在提交之前占用一份编码后副本的 tmp 空间。
• 重复的 POST。 对正在恢复的版本再次发送的 POST，最多等待两秒恢复锁，然后返回 409 RestoreAlreadyInProgress。
• 残留。 收敛或失败的 rename 留下的目录等待废弃数据清理；崩溃的 worker 留下的暂存等待过期 tmp 清理或重启。两者都不会阻塞之后的恢复。
• 格式。 不改变存储格式或公开 API。唯一新增的 RPC 是能力询问。版本元数据中的尝试键是内部键，旧二进制会保留它而不读取。

升级、回滚与降级

• 升级。 旧版本的服务器不会回答支持协议 2，所以在每台服务器都运行本版本之前，POST 返回 503。旧版本留下的、没有尝试 ID 的标记，由下一个拿到恢复锁的 POST 接管。对于各集使用不同主机的单池，锁域修复要求的排空重启仍然适用。
• 降级或回滚之前， 停止发起新的恢复，并等运行中的 worker 结束。旧二进制不认识恢复锁，开关也拦不住已经降级的服务器。
• 检查每台服务器的日志中是否有 restore publication did not converge，降级前逐一修复其中列出的版本。这条日志只是正面证据：进程在重试途中退出时不会留下记录。
• 现有工具无法证明不存在发布分裂。 heal 演练不能作为证明：它在检查可用分片是否足够之前就返回了，所以发现不了"已恢复的盘占多数、分片却不足以重建"的情况。只读的检查工具属于下文协调者崩溃的后续工作。
• 降级之后，残留的进行中标记在旧二进制上会返回 409，与上游相同。

剩余限制

• 协调者在发布途中崩溃。 运行 worker 的服务器在发布途中崩溃，或者收敛重试用尽时，该版本可能留下分裂：部分盘已恢复，部分盘未恢复。没有任何机制会自动收敛它。在人工修复或后续能够检测并收敛这种分裂的修复上线之前，该版本可能读不出来，POST 也可能失败。main 在任何写入途中崩溃时都有同样的风险。
• 迟到完成的存储调用。 调用方已经因超时或错误返回之后，服务端的存储 RPC 仍可能在执行，即使提交仍持有 O 也是如此，它可能在核验或收敛之后才落盘。所有写入路径都有这一限制；为存储 RPC 加 fencing 是单独的事项。少数盘上迟到落盘的副本，只有当未恢复修订达到 heal 对恢复字段要求的 quorum 时，才会被 heal 修回。
• 假定 tier 不可变。 提交相信远端名称和远端版本相同时字节也相同，与所有 tier 读取的前提一样。外部写入者覆盖未开版本控制的 tier 对象，不在保护范围内。
• 暂存丢失。 服务器重启会移走它的 tmp 卷，过期 tmp 清理会删除旧目录。下载期间受影响的盘会被排除在提交之外。只有剩余的合格盘少于写 quorum 时，暂存才会失败，这时可以重新发送 POST。协调服务器重启会结束它的尝试。
• 重启。 收敛和标记重置的重试在内存中运行。重启之后，版本保持进行中状态，直到之后的 POST 接管。

验证

两个问题的回归测试在之前的集成 head 上失败，其中分段上传的测试在 main 上也通过：

• TestRestoreDownloadKeepsKeyAvailable：暂停旧版本的下载期间，对该 key 热版本的 GET、HEAD、PutObjectTags 和 PUT 都按时完成，覆盖一个池和两个池、单段对象和分段对象；
• TestMultipartFailedCommitRetriesLikeMain：完成操作暂存元数据后失败，客户端重新上传分段后可以完成，或者中止。

故障注入测试覆盖整个协议：

• TestRestorePublicationBelowQuorumReverts 和 TestRestorePublicationBelowWriteQuorumOnWideSet（8+4 上 12 块盘中 7 块发布成功会回退；把阈值放宽到 W-1 时该测试失败）；
• TestRestorePublicationUncertainCommits（响应丢失）、TestRestoreConvergenceRetries 和 TestRestoreConvergenceStopsOnOtherWrites；
• TestRestoreRemovesOldDataDirOnlyWhenUnanimous、TestRestoreDropsStaleInlineMarker 和 TestRestorePublishedRevisionAcrossExpiry；
• TestRestoreStagingDropsRecreatedTmp：在 4 块盘的集上，暂存期间 tmp 卷被重建的一块盘被排除，恢复成功；有两块这样的盘时，什么也不发布；
• TestRestoreSecondPOSTWhileRunning、TestRestoreTargetDeletedDuringDownload 和 TestRestoreTierNotFoundClearsMarker；
• TestCheckAbandonedPartsTakesPoolsLock 放置一个未被引用的数据目录，确认它在持有对象锁期间保留、之后被删除；没有池层锁时该测试失败；
• TestRestorePartialCommitQueuesNullVersionHeal：提交漏掉非当前 null 版本的一块盘时，以 null 排入 heal，并把它修回。

私有 upload 标记的 13 个测试，以及从客户端完成恢复 upload 的 TestNativeRestoreConcurrentCompletion，随那个设计一起删除。4 个测试按新语义改写，其中锁域的恢复测试现在卡住的是提交，而不是下载。本地完整的 go test -tags kqueue,dev -p 4 ./cmd/... ./internal/... 套件、恢复、分段上传、锁域和废弃数据测试的竞态选集、go vet 和 golangci-lint 都通过。

本地通过记录使用 kqueue,dev 标签。最终提交在 Ubuntu CI 上的无标签命令 CGO_ENABLED=0 MINIO_API_REQUESTS_MAX=10000 go test ./cmd/ -count=1 -timeout 30m 尚待验证；本地带标签的结果不能替代该项验收。

审查记录

参考

• Issue：#284
• 恢复副本：过期的是副本，不是对象（#281）
• 大型单池集群的锁域
• Multipart 提交失败可能让上传卡死：本设计保持与 main 相同的分段上传失败路径
• Heal 演练不能删除数据
• 上游多池恢复锁：minio/minio#20495

23 - Console 的桶配额：列表显示与数值校验

本文覆盖 silo-console#72（在 Web Console 中设置的配额在桶列表里显示为短横线）和 silo-console#73（创建桶表单的数值校验）。评估基于修复之前的 Console 源码 3d264aea9，以及修复提交 a85665814 至 5a34232e7。

状态： 已随 Console 2.6.0 发布。修复提交已合入 Console main（PR #74，合并提交 3d1dd56eb，2026-11-04），之后又有数值相关的后续修复（PR #79）。Console v2.6.0 已在 f8ab14669 发布，SILO main 已内嵌 v2.6.0（e24831f53）；尚无已打标的 SILO Server 发布包含该内嵌更新。

简短结论

两份报告都属实，且都不影响已存储的数据或配额的执行。

• #72 是显示缺陷。 自 Console 开始写入新的 Size 字段（2025-09-16）起，在 Web Console 中设置的配额以 size 存储，旧的 quota 字段为零。桶列表处理程序和列表界面只读 quota，所以什么都不显示。服务器对配额的执行是正确的。
• #73 是输入校验缺陷，其中有一种情形会影响写入。 parseInt(getBytes(...)) 会把 868 Ei 及以上的任何数量变成 1 字节配额；服务器接受并执行它，该桶随后拒绝所有非空写入。其余情形是误拒绝或缺少检查：0.5 Gi 被拒绝，切换单位不会重新校验，保留期有效值既不检查是否为整数，也没有限制在 32 位范围内。

两个缺陷都不是 SILO 引入的。#72 来自 SILO 所派生的社区 Console 分支：它的配额写入端在 2025-09-16 改变了，列表读取端没有跟着改。#73 是 2020 至 2022 年间 minio/console 的原有代码。SILO 在下文列出的所有内嵌 Console 的发布中都带着这两个缺陷，而且 Console v2.5.0 的列表改版保留了过时的读取方式。

修复很小：桶列表与 Summary 使用同一个配额读取函数，创建与编辑表单共用同一套换算与边界检查。

定性

何时发生

#72。 创建一个桶，用 mcli quota set 设置配额，它写入旧的 quota 字段，列表可以显示。在 Console 中打开该桶，修改配额并保存。Console 写入 size，服务器存储的配置中 quota 为零。此时管理 API 对 110 GiB 配额返回 size=118111600640, quota=0。Summary 页面优先使用 size，显示 110 GiB；列表读取 quota，显示短横线。在创建表单中设置的配额同样如此。

#73。 打开启用配额的创建桶表单。

1. 输入 1000 并选择 Ei。表单把它换算成字符串 1.152921504606847e+21，parseInt 在 e 处停止并返回 1，请求携带 amount: 1。
2. 输入 0.5 并选择 Gi。parseInt("0.5") 为 0，所以表单把字段标记为无效，尽管输入模式允许两位小数。
3. 输入 1000 和 Gi，然后把单位改为 Ei。切换单位不会重新校验，先前的有效状态保留，无需再次输入就能走到情形 1。
4. 启用保留期并输入 1.5 或 3000000000。输入通过 valueAsNumber 读取，唯一的检查是 NaN 或小于 1，而 API 模型是有符号 32 位整数。

已有桶的配额编辑器使用同样的 parseInt(getBytes(...)) 换算；保留期编辑器同样缺少整数与上界检查。

根因

#72。 在修复之前的源码中，桶列表响应由 getAccountBuckets（api/user_buckets.go 第 409 至 414 行）构造，它复制 bucket.Details.Quota.Quota，忽略 Size。列表界面随后只渲染 details.quota.quota：v2.5.x 中是 BucketsTable.tsx 第 387 至 390 行，更早的版本是 BucketListItem.tsx 第 144 行。而单个桶的配额处理函数 getBucketQuota（api/user_bucket_quota.go 第 118 至 125 行）已经优先使用正的 Size，否则回退到 Quota。对同一份配置，两个读取方使用了两套规则。

服务器没有改变表示方式。它按客户端写入的内容存储和返回配置，执行时先看 Size 再看 Quota（cmd/bucket-quota.go 中的 getBucketQuotaSize；上游 MinIO 的最后一个 master 也是同样的优先顺序）。madmin-go 的结构自 2023 年 8 月起就把 Quota 标为已弃用，并带有 Size。mcli quota set 仍然写旧的 Quota 字段，所以命令行设置的配额在列表中显示正常。

#73。 创建表单有四个相互独立的缺口：

• addBucketThunks.ts 第 80 行发送 parseInt(getBytes(quotaSize, quotaUnit, true))。getBytes 把数字转成字符串返回，而 JavaScript 对 1e21 及以上的数字使用指数形式。
• addBucketsSlice.ts 第 122 行在 parseInt(state.quotaSize) === 0 时拒绝该字段。下一行的输入模式后来放宽到允许两位小数，parseInt 检查却保留了下来。
• setQuotaUnit（第 133 行）只保存单位，不触及 invalidFields。
• setRetentionValidity（第 170 至 183 行）和 SetRetentionConfig.tsx（第 87 行）只检查 NaN 和 < 1。

在服务器端，配额请求接受任何非负数量并存为 Size。存储的大小为 1 时，enforceQuotaHard 会拒绝所有一字节及以上的写入（uint64(size) >= quotaSize，cmd/bucket-quota.go）。

行为的来源

溯源依据 Console 的提交历史。上游项目 minio/console 如今已无法公开访问。SILO Console 所派生的社区延续项目 georgmangold/console 仍然可以访问。pgsty/silo-console 的 main 派生自它的提交 feff71e48（2026-04-16），这就是派生点。下列提交都在 pgsty/silo-console 的 main 上；PR 编号指提交原本所在的仓库。派生点之前的 Console 发布标签中，只能取得社区的 v1.7.7 及之后的标签，所以更早的提交不给出 minio/console 的首个发布标签。

#72：写入端改变后被遗留的读取端

缺陷需要倒数第二行：2025-09-16 之前 Console 写的是旧字段，列表能读到。6c54a55d5 就是表示方式的改变，它只更新了两个读取端中的一个。这不是服务器或 madmin-go 的改动：madmin-go 自 2023 年 8 月起就同时带有两个字段，服务器对它们的存储与执行也没有因此改变。SILO 没有引入这个缺陷。

SILO 改了什么。 从派生点到修复之间，没有 SILO 提交改动列表处理程序或配额写入端。SILO 的 Web 改版（23ae6e8e6，Console v2.0.0）和 2611a4d11 的列表重建重写了列表界面，并沿用了旧的读取方式。v2.0.0 至 v2.4.2 的列表只是不显示配额；v2.5.0 和 v2.5.1 的新表格列显示短横线，读起来像“没有配额”，使缺陷明显到被人报告。这个改动放大了可见症状，没有改变原因。

包含该缺陷的 Console 发布。 写入端的改变和过时的读取端同时存在于 georgmangold/console v1.9.0 与 v1.9.1，以及 SILO 的每个 Console 标签，v2.0.0 至 v2.5.1。SILO 的首个 Console 标签是 v2.0.0（2026-08-04）。写旧字段的 Console 发布，直到 minio/console v1.7.6 和社区 v1.8.1，都没有这个缺陷。

内嵌了此类 Console 的 SILO Server 发布（取自 Server go.mod 中 replace github.com/minio/console 一行）：

Server main 分支的 go.mod 现已指向 Console v2.6.0（e24831f53），但尚无已打标的 Server 发布包含该修复。Server 标签 20260304、20260323 和 20260330 内嵌的是写入端改变之前的 Console 构建，不受影响。

#73：minio/console 的原有代码

这些都在社区分支和 feff71e48 中。修复之前触及相同文件的 SILO 提交（23ae6e8e6、14b1c2de2、2611a4d11）改的是链接目标、翻译和命令预览，没有改动校验或换算。SILO 既没有引入也没有放大 #73。它存在于每个 Console 发布，因而存在于每个内嵌 Console 的 SILO Server 发布。

仅凭推理、未执行：main 一线的历史。2020 至 2022 年这些提交对应的 minio/console 首个发布标签无法取得，所以只给出提交主题和日期。

方案选项

选项 1：列表和详情共用一个配额读取函数

把“先 Size 后 Quota”的规则放进一个函数，列表处理程序和 getBucketQuota 都调用它。两个读取方始终一致，API 模式不变。

选项 2：让写入端同时发送两个字段

同时写 Quota 和 Size 能让旧读取端重新工作，但会为一个使用方重新引入已弃用字段，而其他工具写入的配额仍会让列表出错。否决。

选项 3：让界面也读取 size

列表响应模型只有 quota。让浏览器再读一个字段，会把规则复制到第三处。否决。

选项 4：用一个函数校验数量，到处使用

一个函数把文本数量和单位换算成字节数，并拒绝 1 到 2^63 - 1 之外的值。创建表单、配额编辑器和 thunk 都调用它，切换单位时重新校验。保留期增加整数和 1..2147483647 的检查。

选项 5：交给服务器拒绝

服务器接受任何非负的 Size，包括 1。这个错误值本身是合法配置，服务器无法区分它与有意设置。不能只靠它，保留作为负数的后备防线。

建议的修复

选项 1 加选项 4，在分支的六个提交中（都在 PR #74 内）：

1. a85665814 提取 bucketQuotaSize，并同时用于列表处理程序和 getBucketQuota：正的 Size 优先，否则用 Quota。处理程序的 JSON 测试覆盖现代、旧式、冲突、空、零和 nil 值。配额写入与模式不变。
2. 35cf4aae7 让配额编辑器保留精确的字节值，未变化时跳过保存，换算前先校验，并在 API 端拒绝负数。
3. fb2c9e71c 完整解析字节值并限制显示单位，大数字在显示时不再出现指数形式。
4. d878dbf88 新增 addBucketValidation.ts，包含 getQuotaBytes 和 isValidQuota。数量必须符合两位小数的模式，换算为大于零且小于 2^63 的有限整数，切换单位时重新校验。创建 thunk 在发送前再检查一次。
5. 9fb0b0627 与 5a34232e7 要求保留期有效值在创建表单、其 thunk 和保留期编辑器中都是 1 到 2147483647 的整数。前者还让 API 拒绝小于等于零的保留期有效值。

分支上还有两个无关的显示提交（API 请求图表与 syscall 速率标签），不属于这两个问题。

PR #74 之后已在 main 上的后续修复。 它们改进同一处代码，不在该分支内：

• 2b18ff854（#75）用整数运算缩放小数配额，并拒绝浏览器写入 8 PiB 及以上的值，因此不会再发送不精确的值。
• 4da296098（#76）把其余 calculateBytes 与显示路径改用同一个有界解析器。
• 9107a8281（#77、#78）在创建桶之前校验配额和保留期。此前 makeBucket 容忍配额调用失败并返回成功，所以桶可能在没有所请求配额的情况下被创建。

为什么充分且必要

对 #72 充分。 列表处理程序和单桶处理程序现在调用同一个函数，所以两个字段的任何组合下它们都一致，包括 mcli 写入的旧式配额和 Console 写入的新式配额。界面读取处理程序返回的 quota 值，无需改动。

对 #73 充分。 所有把文本变成配额数量的路径现在都经过同一个有界换算：0.5 Gi 变成 536870912，868 Ei 及以上在变成 1 之前就被拒绝，切换单位会重新校验。保留期检查封住了两个表单中小数和超范围的情形。thunk 检查防止过期的表单状态。

必要。 没有共用的读取函数，列表响应的任何新使用方都会重犯同样的错误。没有在换算前校验，对数字字符串使用 parseInt 对任何大值都不安全。

刻意不包含。 以下内容不在本记录的修复之内：

• 任意 64 位精度：在分支上，小数数量经由 JavaScript 数字换算，所以 7 Ei 这样的值会以 8070450532247929000 发送，而不是 8070450532247928832。这由 silo-console#75 跟踪，之后在 main 上通过拒绝此类写入处理；
• 其余的 calculateBytes 用法，由 silo-console#76 跟踪，之后在 main 上处理；
• 三个复制带宽表单，换算模式相同，在 PR #74 中由单独的提交（facbf3bab）修复；
• 服务器：配额的存储、执行和管理 API 都不改。

成本与兼容性

• 不改 API 模式、服务器或 madmin-go。列表响应保留字段名 quota，只是它携带的值现在是有效配额。
• 服务器上已有的配额，无论旧式还是新式，都不变。旧式配额照旧显示；原先被隐藏的新式配额现在显示。
• 以前被接受、现在被拒绝的输入是 868 Ei 及以上的数量（原本等于 1 字节）以及非整数或超范围的保留期。以前被拒绝、现在被接受的是小于一的小数，如 0.5 Gi。
• 已经用 1 字节配额创建的桶保持原样，见剩余限制。
• 回滚到旧版 Console 即恢复旧行为，无需迁移。

剩余限制

• 已被设成 1 字节配额的桶仍然被阻止写入。 用 mcli quota info ALIAS/BUCKET 查找（大小为 1 字节即是迹象），然后设置期望的配额，或用 mcli quota clear ALIAS/BUCKET 清除。
• 尚未进入已打标的 Server 发布。 独立版 Console 2.6.0 已包含该修复，且 SILO main 已内嵌 v2.6.0（e24831f53）。在下一个 SILO Server 发布推出之前，直到 20261026 的已打标 SILO Server 发布内嵌的 Console 界面仍有这两个缺陷。
• 大配额仍用 mcli。 在 main 上，浏览器拒绝写入 8 PiB（2^53 字节）及以上的配额，因为 JSON 数字只在此范围内是精确的（#75，由 2b18ff854 关闭）。分支顶端允许到 2^63，但经由 JavaScript 数字换算。
• 窄屏。 现有的响应式布局在 1200 px 以下隐藏桶列表的配额列；Summary 仍显示配额。

验证

在 Console 仓库中，对修复分支顶端 5a34232e7 实际执行（未在之后的 main 上重跑）：

• Playwright unit 项目。 e2e/bucket-quota.unit.ts、e2e/bucket-retention.unit.ts、e2e/add-bucket-numeric.unit.ts 和 e2e/size-format.unit.ts：49 个测试全部通过。覆盖 1000 Ei 与 8 Ei 被拒绝、0.5 Gi 写成 536870912 字节、切换单位会重新校验、未变化的配额不写入，以及保留期边界。
• Go 测试。 go test -mod=readonly ./api -run 'Quota|Retention|AccountBuckets|ListBuckets' 通过（现代、旧式、冲突、空、零和 nil 配额的列表与详情响应）。
• 换算缺陷本身。 对修复前公式的一个小脚本给出：1000 Ei 为 "1.152921504606847e+21"，其 parseInt 为 1；867 Ei 是 999582944494136300000，868 Ei 是指数形式，所以 1 字节的情形从 868 Ei 开始。parseInt("0.5") === 0 为真。
• 合并后的结果（来自报告，此处未重跑）。 issue 讨论报告合并后的改动在真实的 SILO、mcli 与 Console 环境中验证过（用 mcli 设置 100 GiB，在 Console 中改为 110 GiB，列表、详情与 mcli 一致为 118111600640 字节；创建时的 0.5 GiB 配额恰好存为 536870912 字节）。

仅凭代码推理、此处未执行：

• 服务器对 1 字节 Size 的执行（cmd/bucket-quota.go）；
• API 对 8 Ei 至 867 Ei 的超范围数量的拒绝，以及 32 位模型对小数或超范围保留期的拒绝；
• 没有任何 Server 发布包含修复，依据 go.mod 历史；
• 派生点之前的历史，依据提交主题和日期。

参考

• Issue：silo-console#72、silo-console#73
• 修复：PR #74，合并提交 3d1dd56eb
• 写入端改动：georgmangold/console#28
• main 上的后续修复：silo-console#75（64 位精度，2b18ff854）、silo-console#76（calculateBytes，4da296098）、PR #79（创建时校验）
• 发布页面：Console 2.6.0、Console 2.5.1、SILO 20261026

24 - Heal 演练不能删除数据

本文覆盖 Jasper Bernhardt（@dihmandrake）提交的 PR #280 中与演练（dry run）相关的部分，基于 main 69fcf50cd 评估。同一个 PR 还让深度扫描并发校验一个对象的各块盘。这项优化另行评审，不在本文范围内。该 PR 尚未运行 CI。

状态： 修复已通过审查，已在本地提交。它已和下个版本的其他修复放在同一个集成分支上一起测试：带 kqueue,dev 标签的本地完整测试套件、本地执行的 CI 竞态检测选集，以及针对修复之间相互作用的对抗性审查，全部通过。尚未合并或发布。

简短结论

缺陷属实，是 SILO 从上游 MinIO 继承来的。mc admin heal --dry-run 的说明是"只检查数据，不做修改"。在 main 上，只要一个对象版本的 xl.meta 没有读 quorum，演练 heal 仍会执行悬空对象清理：如果缺少元数据的盘全部回答"不存在"、且数量多于该版本的校验块数，deleteIfDangling 就会向每块可用的盘发出删除该版本的请求：仍持有该版本、且删除成功的每块盘都会失去它（连同数据目录），heal 随后报告对象不存在。运维人员为评估受损集群而运行演练，结果销毁的恰恰是他们正在调查的那些对象的最后几份元数据。

对象 heal 的修复是 PR #280 中五行的提前返回：演练中遇到元数据 quorum 失败时，heal 在清理之前返回 quorum 错误，以及一个根据观察到的盘状态构造的集合级结果。真实 heal 不受影响。它应进入下一个版本，与并行校验改动拆开交付，并保留贡献者署名。

我们的审计还发现了第二处演练写操作。PR #280 没有涉及它，本修复把它一并覆盖。 在多节点部署中，桶 heal 只向远端节点发送桶名和 remove 标志。没有演练标志，这些节点执行的就是真实的桶 heal：在缺少桶目录的盘上创建桶目录，或者在所有池中都找不到该桶时删除空的桶目录。它不删除对象，但演练不应改变任何东西。修复在对端消息中加入演练标志，并让远端处理函数遵守它，使远端节点走与本地节点相同的演练返回。改动是四行功能代码，加一个构造对端消息的小辅助函数，以及一个回归测试。

PR 中第二处与演练相关的改动，是在分片校验没有成功时，把盘报告为 unknown 而不是 ok。这是报告层面的改动，不是安全修复。如果只对演练生效，演练和真实 heal 会对同一块盘给出不同的报告。它可以留给一个同时修正两种模式的改动。

定性

触发条件

需要同时满足三个条件：

1. 带 DryRun 的 heal 对某个对象版本进入 healObject。heal 遍历会逐个版本分别 heal。
2. objectQuorumFromMeta 失败：读错误归约后，有结果的盘不足一半；或者没有哪个校验块数（parity）得到足够多可读副本的一致报告。一个 parity 需要的一致副本数，等于它所对应的读 quorum，对普通对象就是数据块数。例如，一个 EC 3+1 的版本只有两份可读副本时，虽然有一半的盘作答，仍然会失败。
3. isObjectDangling 判定该版本悬空。此时还没有做任何分片检查，因此判定要求：
   • 至少有一份有效的 xl.meta；
   • 每块出错的盘都回答"文件不存在"或"版本不存在"。任何其他错误（盘离线、元数据损坏、桶目录缺失、超时）都会否决这个判定。heal 读取元数据时会一并读取小对象的数据，所以对于没有内联的小对象，即使 xl.meta 还在，缺失的分片文件也会表现为"不存在"；
   • 对象版本：缺少元数据的盘数多于该版本的校验块数，也就是元数据副本少于数据块数。删除标记：超过一半的盘上没有它。

举例来说，四块盘、EC 2+2。一个 1 MiB 的对象在三块盘上丢失了 xl.meta，这三块盘上的分片文件仍在。在 main 上，对该对象运行演练 heal，会把该版本从第四块盘（唯一还存有其元数据的地方）上删除，并报告"对象不存在"。

降级集群。 离线的盘回答 errDiskNotFound，这个错误会否决悬空判定。因此一块正常离线的盘会阻止清理，而不是导致清理；这一点我们已经验证过。判定只统计回答"不存在"的盘，并且无法分辨它们为什么这样回答。有些盘回答"不存在"，但它们的回答并不权威：

• 一块已更换的盘：桶目录已经建好，但还没有收到这个对象；
• 一块丢失了 xl.meta、但分片文件仍在的盘。isObjectDangling 的源码注释承认，这种情况原则上是可以恢复的。

而这正是运维人员会去运行演练的场景。这个规则对真实 heal 是否合适，是另一个继承下来的策略问题；演练根本不应该应用这个规则。

根因

healObject 把 opts.DryRun 读入 dryRun，并在任何修复写入之前返回，代码注释原文是：“After this point, only have to repair data on disk - so return if it is a dry-run”。处理元数据 quorum 失败的分支位于更前面，它调用 deleteIfDangling 时没有检查 dryRun。

deleteIfDangling 自己也无法检查。它接收的是 ObjectOptions，其中没有演练字段；它还被 GET、HEAD、CopyObject、PutObjectMetadata 和 PutObjectTags 路径共用，这些路径按设计就会清理悬空版本。它还直接从纠删集合获取盘，所以调用方无法限制它会碰到哪些盘。

healObject 中另一处 deleteIfDangling 调用，在处理无法修复对象的分支里。它位于演练返回之后，是安全的。

行为的来源

溯源

由上游 MinIO 引入，不是 SILO 引入的。 两个缺陷都来自上游提交，这些提交都是 SILO 分叉点（27742d469，2025-12-03）的祖先。它们存在于分叉前最后一个上游发布 RELEASE.2025-10-15T17-29-55Z、已归档的上游 master，以及从 RELEASE.2025-12-03T12-00-00Z 到 RELEASE.2026-10-26T00-00-00Z 的每一个 SILO 发布中。我们检查了每个 tag：healObject 中第一次 deleteIfDangling 调用位于演练返回之前，远端桶 heal 的消息不带演练标志。没有任何 SILO 提交引入、扩大或缩小这两个缺陷。

对象 heal。 上游曾经有这道保护。它的 purgeObjectDangling 只在 if !opts.DryRun && opts.Remove 时删除，来自 db2155551（#9159，2020-03-19，RELEASE.2020-03-19T21-49-00Z）。随后两处改动分阶段拆掉了它，第三处把结果留在了 healObject 中：

桶 heal。 2024 年 1 月之前，按纠删集的桶 heal 会遵守 DryRun。节点级桶 heal 在 e31081d79（#18612，2024-01-10，RELEASE.2024-01-11T07-46-16Z）中取代了它。它的远端调用只发送桶名和 remove 标志，远端 handler 用这两个值构造 heal 选项。同一调用的本地实现会检查 DryRun，所以只有本地节点遵守。ff80cfd83（#18951，2024-02-02，RELEASE.2024-02-04T22-36-13Z）把调用迁到 grid，仍只带这两个值。上游 master 上这个缺口依然存在。

SILO 的改动。 分叉之后，SILO 对 heal 函数、cmd/peer-s3-client.go、cmd/peer-s3-server.go 以及 cmd/peer-rest-server.go 中的 heal handler 所做的改动：

SILO 没有改动 deleteIfDangling、isObjectDangling、remotePeerS3Client.HealBucket 或 HealBucketHandler，也没有在这条路径上增加任何演练保护。PR #280 仍处于开放状态，带有对象 heal 的保护；桶 heal 的部分只是本记录提出的方案。

证据。 提交的祖先关系、首个发布、两个缺陷在每个 tag 上的存在，以及这些函数中没有 SILO 改动，都用 git 核对过。2022 年各步骤的行为（先是演练加 --remove，之后是单独的演练）来自对改动的阅读，没有在那些版本上运行。当前行为由验证一节中的测试复现。

方案比较

方案 1：在 healObject 中提前返回

这是 PR #280 的做法。当 objectQuorumFromMeta 失败且设置了 dryRun 时，healObject 用观察到的错误构造 defaultHealResult，连同 quorum 错误一起返回。改动只有一个函数中的五行，只影响演练，真实 heal 的行为与现在完全一致。它的局限是只保护这一个调用点：将来如果别处有演练路径调用 deleteIfDangling，需要自己的保护。

方案 2：把演练标志传入 deleteIfDangling

给 deleteIfDangling 增加一个参数或一个 ObjectOptions 字段，让它在演练中只做判定、不做删除。它还可以向报告返回"将会清理"的判定。代价是六个调用方都要改动，其中四个是对象读取和元数据更新路径，根本没有演练的概念。而且将来的调用方同样可能忘记传这个标志，就像可能忘记提前返回一样。为这点稳健性付出这么多改动并不划算；“将会清理"的报告应该归入演练报告的重新设计。

方案 3：集中式保护

让演练 heal 使用只读包装的盘，这样任何写入都会失败。这是唯一能从结构上防住将来失误的方案。但 StorageAPI 有几十个方法，deleteIfDangling 从纠删集合而不是从调用方获取盘，而桶 heal 的缺口位于对端 RPC 层，这样的包装也覆盖不到。作为发布修复，它的范围太大。

同一思路的廉价版本适用于测试。PR 的合成测试盘内嵌一个 nil 的 StorageAPI，任何测试未预期的写操作都会 panic。回归测试保留这种写法。

远端节点上的桶 heal

要阻止远端节点在演练中写入，有两种办法：

• 传递标志。 在对端消息中携带演练标志，并在远端处理函数中遵守它。这样远端节点会走与本地节点相同的提前返回。消息形态、处理函数和错误归约都不变；将来演练桶报告补全后，远端节点也能报告自己的状态。
• 跳过调用。 让 S3PeerSys.HealBucket 在演练时不调用远端节点。这在滚动升级期间也能防住旧节点，但放弃了将来演练报告中远端的那一半，还要在分发逻辑中加一个演练特例。

我们选择传递标志。修复之前，每个节点的行为本来就等同于标志为 false。升级期间，混合版本的集群不会比现在更差；所有节点都运行修复后，缺口即被关闭。

关于报告改动

在演练的深度扫描中，如果一块盘的元数据读取成功，但分片校验因为缺失或损坏以外的原因没有成功，PR 会把它报告为 unknown。这些原因包括：检查过程中盘离线、卷缺失、超过截止时间、被取消、访问被拒绝。在 main 上，两种模式都把这块盘报告为 ok，修复决策也会忽略这些结果。

PR 只改了演练模式。它自己的测试对同一状态，期望演练给出 unknown、真实 heal 给出 ok。mc admin heal 在给对象着色、以及按在线盘数给对象分组时，只统计 ok 的盘。于是同一个对象在演练中会显得比随后的真实 heal 中更糟。

把未经校验的盘报告为 ok 确实是一个准确性问题：一次完整性审计可能对它根本没检查过的数据报告"干净”。但这个问题两种模式都有，而且它既不删除也不修改数据。应该同时修正两种模式，包括 heal 序列根据同样的盘状态推导出的"quorum loss"说明。

建议： 本次发布中，对象 heal 采用方案 1，桶 heal 采用传递标志；推迟报告改动。

修复方案

修复分两部分。第 1 部分是 PR #280 中贡献者的改动，第 2 部分来自维护者的审计。

第 1 部分：对象 heal 在悬空清理之前返回

代码。 原样采用 PR #280 在 healObject 中的第一处改动：

readQuorum, _, err := objectQuorumFromMeta(ctx, partsMetadata, errs, er.defaultParityCount)
if err != nil {
	if dryRun {
		// A metadata quorum failure must not delete dangling data in dry-run.
		return er.defaultHealResult(FileInfo{}, storageDisks, storageEndpoints,
			errs, bucket, object, versionID), err
	}
	m, derr := er.deleteIfDangling(ctx, bucket, object, partsMetadata, errs, nil, ObjectOptions{
		VersionID: versionID,
	})
	// 其余不变

演练中，集合级结果把每块盘的读错误映射为盘状态，例如缺少 xl.meta 的盘为 missing。这次调用传入的是 FileInfo{}，所以结果的大小为零，校验块数和数据块数取默认值。返回的错误就是 objectQuorumFromMeta 返回的错误，经过 toObjectErr 转换：多数盘回答"不存在"时为版本或对象不存在；多数副本损坏时为损坏错误；或者为读 quorum 不足。真实 heal 在报告 quorum 失败之前仍会丢弃各盘的错误，与现在一致。

这些信息并不都能到达管理报告。当每个池都回答"不存在"时（这是悬空的常见情形），erasureServerPools.HealObject 会用一个空条目替换各集合的结果，所以报告中只有"不存在"错误，没有逐盘状态，这与 main 在清理之后的表现相同。只有错误是其他类型时（例如元数据损坏或读 quorum 不足），观察到的盘状态才会出现在报告中。读 quorum 不足也涵盖一部分悬空版本：一个 EC 3+1 的版本有两份可读副本、两个"不存在"回答时会被判定为悬空，修复后它的演练报告读 quorum 不足，并带有全部四块盘的状态。

测试。 采用 PR 中不依赖并行校验的三个测试及其辅助代码：

• TestNativeAuditDryRunPreservesFaults 使用合成盘，覆盖元数据 quorum 失败、元数据损坏、分片缺失或损坏、内联数据损坏，以及没有 quorum 的删除标记；
• TestNativeAuditDryRunPreservesDanglingFiles 使用真实盘：从四块盘中的三块删除 xl.meta，检查演练不改动任何文件；
• TestNativeAuditNonDryRunStillDeletesDangling 是对照组：不带 DryRun 的相同场景仍会走到清理。

三处小改动：

• TestNativeAuditDryRunPreservesFaults 把删除计数断言放到报告断言之前，这样在未修复的代码上，失败信息会直接指出删除；
• 对每种 quorum 情形，它断言转换后的错误（版本不存在，或损坏错误），取代原来针对 errFileNotFound 的检查——经过 toObjectErr 之后，那个检查不可能失败；
• 合成盘去掉了 CheckParts 桩，它只被 PR 中并行校验和报告相关的测试使用。

第 2 部分：远端节点在桶 heal 中遵守演练标志

代码。 在 peerS3BucketDeleted 旁边新增键 peerS3BucketDryRun = "dry-run"。remotePeerS3Client.HealBucket 通过一个小编码函数构造消息并加入这个键，HealBucketHandler 把它读入 madmin.HealOpts.DryRun：

// peer-s3-client.go
func healBucketPeerMSS(bucket string, opts madmin.HealOpts) *grid.MSS {
	return grid.NewMSSWith(map[string]string{
		peerS3Bucket:        bucket,
		peerS3BucketDeleted: strconv.FormatBool(opts.Remove),
		peerS3BucketDryRun:  strconv.FormatBool(opts.DryRun),
	})
}

// peer-rest-server.go，HealBucketHandler
dryRun := mss.Get(peerS3BucketDryRun) == "true"
res, err := healBucketLocal(context.Background(), bucket, madmin.HealOpts{
	Remove: bucketDeleted,
	DryRun: dryRun,
})

设置了 DryRun 时，healBucketLocal 本来就会在任何 MakeVol 或 DeleteVol 之前返回，所以它不需要改动。RPC 处理函数、它的注册和返回类型也都保持不变。

测试。 TestPeerHealBucketDryRun 启动两个 grid 管理器，在其中一个上注册对端处理函数，再从另一个调用 remotePeerS3Client.HealBucket。这样请求会经过真实的客户端、grid 连接和处理函数，作用于一个四块盘的集合，其中一块盘上的桶目录已被删除。两次演练请求（一次带 Remove，一次不带）既不能重建缺失的目录，也不能删除空目录。随后两个对照组证明测试场景能走到这两种写操作：一条不带演练键的消息（旧节点发送的形态）会重建目录；一次带 Remove 的真实 heal 会删除空目录。该测试不使用任何新增标识符，因此能在 main 上编译，并在第一个演练断言处失败。

其他对端 heal 调用。 我们逐一检查过，没有一个存在同样的缺口：

• format heal 只从协调节点保存 format.json，并且只在它自己的演练检查之内保存。它会先用常规的存储初始化打开各块盘，而这一步发生在演练检查之前，见剩余限制。在当前代码中，管理 heal 序列不会把 format heal 入队；
• 后台 heal 状态调用是只读的；
• 管理 heal 请求只有在凭 token 轮询已有序列时才会被代理到其他节点，从不用于启动序列。

交付

• 把演练改动和上述测试拆成独立的提交和 PR，与并行校验改动分开。后者需要单独评审（慢盘上的 I/O 并发和取消处理），也需要单独的 CI。
• 保留贡献者署名。生产代码改动与贡献者已签署 DCO 的提交完全一致，但测试是经过调整的子集，所以拆分后的提交是维护者提交，附带 Jasper Bernhardt 的 Co-authored-by 标注，并引用 PR #280。
• PR #280 随后继续承载并行校验；如有需要，也可以承载一个同时覆盖两种模式的报告改动。
• PR 说明中写明，实现和测试由 AI 编写，贡献者无法独立确认其正确性。演练改动足够小，维护者已按下文所述独立验证；本文依据的是这些验证，而不是 PR 自身的说法。
• 第 2 部分作为单独的维护者提交，放在同一个 PR 中交付。它不含贡献者代码，贡献者署名保留在第 1 部分上。

为什么方案充分且必要

我们审计了管理演练 heal 可能修改数据的每一个位置：

heal 路径本身不会向 MRF 入队；只有上面的桶元数据加载可能入队。被执行的清理在盘以外唯一的副作用，是一条 DeleteDanglingObject 审计记录，只在配置了审计日志时写入。

充分性。 两部分都到位、且所有节点都运行修复后，管理演练 heal 不再执行 heal 自身的写操作：对象 heal 在清理之前返回；桶 heal 在每个节点上（而不只是协调 heal 的那个节点）都在 MakeVol 和 DeleteVol 之前返回。heal 修复逻辑之外，还有两处继承下来的影响，列在剩余限制中：全站列举时的桶元数据加载，以及直接调用 format heal 时的盘初始化。

必要性。

• 在演练中，quorum 失败分支是唯一一处在演练返回之前执行的对象 heal 写操作。没有第 1 部分，清理就仍然可达。
• 远端桶 heal 是管理演练能走到的另一处 heal 写操作。没有第 2 部分，多节点部署中的每个远端节点在演练时仍会修复桶目录。
• 报告改动对安全不是必需的。

有意排除的范围：

• checkObjectWithAllParts 中的并行校验；
• unknown 报告改动；
• 真实 heal 和读路径的悬空清理策略。

代价与兼容性

• 不改变 API、配置、指标、存储格式或依赖。真实 heal 不变。
• 桶 heal 的对端消息新增一个可选键 dry-run。这个消息是字符串映射，grid 编解码会解出收到的每一个键，所以接收方不认识的键会被原样携带并忽略。我们验证过：带新键的消息能完整往返编解码，旧处理函数也能接受它。没有新增 RPC 处理函数，也没有处理函数的版本变更。
• 滚动升级：
  • 新节点调用旧节点。 旧节点忽略这个键，执行真实的桶 heal，与现在完全相同。
  • 旧节点调用新节点。 消息中没有这个键，新节点读到 false，执行真实的桶 heal，与现在完全相同。
  • 只有在所有节点都运行修复之后，演练桶 heal 才不再改动桶目录；混合版本的集群任何时候都不会比现在更差。
• 演练结果的变化如下：
  • 悬空版本不再被删除；
  • 在集合级，各盘报告观察到的状态，而不是 ok。只有错误不是"不存在"时，管理报告中才能看到这些状态，因为当每个池都回答"不存在"时，池聚合会丢弃集合结果；
  • 返回的是经过转换的 objectQuorumFromMeta 错误，而不是清理之后的结果；
  • 演练不再产生 DeleteDanglingObject 审计记录；
  • 远端节点不再改动桶目录，演练桶报告中远端的部分现在也和本地部分一样是空的。
• 回滚即恢复旧行为，两个方向都不需要迁移。

剩余限制

• 混合版本集群。 在所有节点都运行修复之前，演练桶 heal 仍会让旧节点创建缺失的桶目录或删除空的桶目录。发布说明应写明：只有升级完成后，演练才不再改动桶目录。
• 全站演练会加载桶元数据。 它的桶列举会填入创建时间。对于元数据不在缓存中的桶，这是一次普通的元数据加载，与服务器在启动时和定期刷新时尝试的加载相同（每轮刷新在上一轮结束 15 分钟后开始）：它可能把旧版桶配置文件迁移进 .metadata.bin，并为缺失的 .metadata.bin 副本入队 MRF 修复。它不触及对象数据。服务器自己的加载也会做出同样的改动，但迁移或修复何时完成没有保证。让演练列举跳过创建时间即可避免这次加载，这属于后续工作。
• format heal 在演练检查之前初始化各块盘。 打开盘时可能创建内部目录并迁移旧的 format.json。在当前代码中，管理 heal 序列不会把 format heal 入队，所以管理演练不会走到这里。要让 format 检查只读，需要只读的盘初始化。
• 演练桶 heal 不报告盘状态。 healBucketLocal 在把观察到的状态附加到结果之前就返回。修复后，这在每个节点上都成立，而不只是本地节点，所以演练给出的桶摘要没有逐盘细节。在演练返回之前填入观察到的状态，属于报告的后续改动。
• 过去的演练无法撤销。 如果在本修复之前曾对受损对象运行过演练 heal，被它清理掉的版本已经不存在了。如果配置了审计日志，它们会以 DeleteDanglingObject 记录出现，其 caller 标签指向 heal 代码。
• 演练不会提示"将会清理"。 修复后，一个悬空版本在管理报告中要么表现为一个没有盘状态的"不存在"错误（每个池都回答"不存在"，池聚合丢弃了集合结果），要么表现为带有盘状态的读 quorum 不足错误。两种情况下，集合结果本身的大小都为零、校验块数为默认值。它不会被标注为真实 heal 将要删除的对象。“将会清理"的判定可以放进报告的后续改动。
• 未经校验的盘仍被报告为 ok，两种模式都是如此，直到报告的后续改动完成。
• 真实 heal 的悬空清理策略不变。 它统计的"不存在"回答，可能来自并不权威的盘。重新审视这个策略是另一项工作。

验证

所有运行都用 go test -run 只选相关测试，参数为 -p 2，标签为 kqueue,dev。下文的"main"指一个位于 69fcf50cd、只加入了新测试文件的一次性 worktree。

已执行：main 上的缺陷。

• 在合成盘上（四块中有三块回答"版本不存在”）运行演练 HealObject，会向每块盘发出 DeleteVersion 调用，对象版本和删除标记都是如此。
• 把其中一块盘改为离线后，真实 heal 一次也不调用，这证实了离线否决。
• 在真实盘上，演练 heal 删除了最后一份幸存的 xl.meta。
• 把只含桶名和 remove 标志的消息（即 main 的远端客户端为演练请求发送的形态）交给对端处理函数，它会重新创建缺失的桶目录；本地 healBucketLocal 带 DryRun 时不会。PR #280 的改动对此没有影响。

已执行：提交的测试。

• 在 main 上：
  • TestNativeAuditDryRunPreservesFaults 的元数据 quorum 和删除标记子测试在删除断言处失败；元数据损坏子测试在报告断言处失败：那里的清理被否决了，但 main 把每块盘都报告为 ok；
  • TestNativeAuditDryRunPreservesDanglingFiles 失败：演练之后，持有最后一份 xl.meta 的盘上，对象目录已经不存在；
  • TestPeerHealBucketDryRun 能编译，并在第一个演练断言处失败：远端节点重建了缺失的桶目录；
  • 对照组通过：TestNativeAuditNonDryRunStillDeletesDangling，以及分片缺失、分片损坏和内联数据损坏三个子测试。
• 应用修复后，以上测试全部通过，-race -count=3 也通过。
• 对 TestPeerHealBucketDryRun 的变异检查：客户端编码函数漏掉这个键时测试失败，处理函数忽略这个键时测试也失败。
• 新测试与已有的 TestHealing*、TestHealObject*、TestHealCorrectQuorum、TestHealLastDataShard、TestHealEmptyDirectoryErasure、TestIsObjectDangling 和 TestFreeVersionHealObjects 在同一进程中以 -race -count=2 一起运行，全部通过。已有的 TestPeer*、TestErasureHeal 和 grid 包测试在不启用 race 检测时也通过。TestErasureHeal 在 race 检测下会在 ring buffer 中 panic，在 main 上同样如此，与本修复无关。
• gofmt 和 go vet ./cmd 都没有报告问题。

已执行：对抗性评审。

• 带上新键的消息能完整往返 grid 编解码，main 的处理函数接受并忽略它：重建缺失目录，并删除空目录。这就是"新节点调用旧节点"的情形。
• 同时存在于两个池中的对象仍会经过两个池进行 heal；健康的第二个池仍会在聚合中胜出。
• 每个对端都返回空的演练结果时，归约不会报错；扇出过程改写 Remove 和 Recreate，但保留 DryRun。
• 桶元数据缓存为空时，全站演练会迁移一份旧版桶配置，并为缺失的 .metadata.bin 副本入队 MRF 修复，main 和修复后都是如此。让列举跳过创建时间可以同时避免这两者。
• 直接调用的 HealFormat 演练会重建缺失的 .minio.sys/config 目录，main 和修复后都是如此。
• 在管理层，一次悬空演练报告一个带"不存在"错误的空条目；在集合层，同一次调用报告三块 missing 盘。一个有两份可读副本的 EC 3+1 版本报告读 quorum 不足，并带有四块盘的状态，而 main 会清理它。
• 全站演练序列会 heal .minio.sys/config 中的对象。修复后，一个悬空的配置对象会保留它最后一份 xl.meta。

根据代码推断，未执行：

• 只有管理 heal API 会设置 DryRun；
• main 的远端客户端只发送这两个字段；
• 没有其他对端 heal 调用会丢掉这个标志；
• mc admin heal 如何使用盘状态；
• 上游历史。

未运行：

• 完整的 ./cmd 测试；
• 远端 CI；
• 实际部署的多节点集群和混合版本升级。对端测试使用真实的 grid 连接，但两个管理器位于同一个测试进程中；
• 端到端的 mc admin heal --dry-run；
• 并行校验相关的测试。

集成验证。 这个修复已摘取到下个版本的同一个集成分支上，位于 #278 和 #281 之后，与锁域、#259、#285、delete-all 和 Console 的修复放在一起。所有摘取都没有冲突。在该 head 上，完整的 go test -tags kqueue,dev -p 4 ./cmd/... ./internal/... 套件通过，CI 的竞态检测选集和覆盖全部新测试的竞态选集也都通过。针对组合的对抗性审查没有发现缺陷，锁域、清理路径以及清除与恢复之间的交互都用实际执行的探针检查过。

本地通过记录使用 kqueue,dev 标签。最终提交在 Ubuntu CI 上的无标签命令 CGO_ENABLED=0 MINIO_API_REQUESTS_MAX=10000 go test ./cmd/ -count=1 -timeout 30m 尚待验证；本地带标签的结果不能替代该项验收。

审查记录

参考

• 贡献者 PR：#280
• 评估基线：69fcf50cd
• 上游历史：minio/minio#14053、minio/minio#14273、minio/minio#15954、minio/minio#18612
• 相关：对象自愈、mc admin heal

25 - 大型单池集群的锁域

本文覆盖在审查恢复副本修复（恢复副本：过期的是副本，不是对象）时发现的锁域缺陷，评估基线为 main 上的 69fcf50cd。目前尚未提交 issue。

状态： 修复已通过审查，已在本地提交。它已和下个版本的其他修复放在同一个集成分支上一起测试：带 kqueue,dev 标签的本地完整测试套件、本地执行的 CI 竞态检测选集，以及针对修复之间相互作用的对抗性审查，全部通过。尚未合并或发布。

简短结论

锁域分裂是真实的，继承自上游 MinIO，并且只在一个池中的各纠删集并不使用相同主机时才存在。按自动布局，这意味着单池有 18 台或更多主机；不超过 17 台主机时，每个集都包含所有主机，锁组完全相同。

在这样的池里，DELETE、批量删除、CopyObject 以及 upload ID 守卫使用的对象锁，取自第一个纠删集的 locker。PUT、分片上传完成、标签/保留/法定保留/元数据更新、恢复（restore）、转储（transition）和修复（heal）使用的锁，取自键所哈希到的集的 locker。对于哈希到主机与第一个集不同的集的键，两把锁永远不会相遇，所以这些操作之间并不互斥。xlStorage 自身没有按键的串行化：RenameData、DeleteVersion、UpdateMetadata、WriteMetadata 都是读出 xl.meta、在内存中修改、再写回。