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 探针无法反映数据面状态，滚动升级脚本必须验证实际的数据面读写，而不能依赖固定时长的等待。

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