解决 Harbor 推送 S3 报错 412 Precondition Failed

在云原生环境中，使用 Harbor 对接对象存储（如 AWS S3、MinIO、Ceph RGW、Aliyun OSS 等）是常见的做法。然而，在推送大镜像时，有时会遇到 412 Precondition Failed 错误，导致推送失败。本文将详细分析该问题的原因并提供解决方案。

问题现象

当尝试使用 docker push 向 Harbor 推送镜像时，进度条走到最后可能会失败，并提示类似以下的错误信息：

1

error parsing HTTP 412 response body: invalid character '<' looking for beginning of value: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error><Code>PreconditionFailed</Code><Message>At least one of the pre-conditions you specified did not hold</Message><Condition>If-Match</Condition><RequestId>...</RequestId><HostId>...</HostId></Error>"

或者在 Harbor 的 registry 组件日志中看到：

1

level=error msg="response completed with error" err.code="unknown" err.detail="s3aws: PreconditionFailed: At least one of the pre-conditions you specified did not hold\n\tstatus code: 412, request id: ..."

原因分析

HTTP 412 错误表示“前提条件失败”。在 Harbor (Docker Registry) 与 S3 交互的上下文中，这通常与 Multipart Upload（分段上传） 和 Copy Object 操作有关。

Docker Registry V2 协议在处理镜像层（Layer）上传时，为了提高效率，会使用 S3 的 Multipart Upload API。当一个 Layer 上传完成后，Registry 可能会尝试将其移动（Copy）到最终的存储路径。在 Copy 操作中，S3 允许客户端通过 x-amz-copy-source-if-match 头提供源对象的 ETag，以确保源对象在复制过程中未被修改。

问题的根源通常有以下几点：

1. S3 兼容性问题：某些非 AWS S3 的存储实现（如旧版本的 MinIO、Ceph RGW 或其他网关）计算 ETag 的方式可能与 AWS S3 标准不完全一致，特别是在涉及 Multipart Upload 产生的文件时。Registry 预期的 ETag 与存储后端实际返回的 ETag 不匹配，导致校验失败。
2. 分段大小问题：如果分段大小（Chunk Size）设置不当，可能导致 ETag 计算差异。
3. 反向代理干扰：如果在 Harbor 和 S3 之间有 Nginx、Cloudflare 等代理/WAF，它们可能会修改请求头或响应头（如去除 ETag），导致校验失败。

解决方案

以下按推荐程度列出解决方案。

方案一：调整 Harbor 存储配置

这是最直接有效的修复方法。我们需要调整 Harbor Registry 的 S3 存储驱动配置，增大分段阈值，或者显式指定分段大小。

1. 如果你是通过 Helm Chart 部署

修改 values.yaml 文件，找到 persistence.imageChartStorage.s3 部分，添加或修改以下参数：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

persistence:
  imageChartStorage:
    type: s3
    s3:
      region: "us-east-1" # 根据实际情况填写
      bucket: "your-bucket"
      # ... 其他配置 ...
      
      # 关键配置：调整分段上传阈值和块大小
      # 建议设置为 32MB 或更大 (单位：字节)
      multipartcopychunksize: 33554432 
      multipartcopythreshold: 33554432

然后执行 helm upgrade 更新 Harbor。

2. 如果你是通过 docker-compose 部署

编辑 harbor.yml (或者 common/config/registry/config.yml，取决于你的版本和挂载方式)。如果是 harbor.yml，通常没有直接暴露这些高级参数，你可能需要直接修改生成的 common/config/registry/config.yml 文件，然后重启 registry 容器。

在 config.yml 中：

1
2
3
4
5
6
7
8
9

storage:
  s3:
    accesskey: "..."
    secretkey: "..."
    region: "..."
    bucket: "..."
    # 添加以下两行
    multipartcopychunksize: 33554432
    multipartcopythreshold: 33554432

修改后重启 Harbor：

1

docker-compose restart registry

原理解释： 默认情况下，Registry 可能会使用较小的 chunk size。将其增大（例如 32MB），可以减少分段数量，甚至对于小于 32MB 的层直接使用单次上传，从而规避 Multipart Upload 的 ETag 问题。

方案二：检查并禁用 Cloudflare 等代理缓存

如果你的 Harbor 域名使用了 Cloudflare 代理（开启了橙色云朵），Cloudflare 可能会对上传请求进行处理，或者缓存行为导致 ETag 丢失/改变。

建议：

1. 在 Cloudflare DNS 设置中，将 Harbor 域名设置为“仅 DNS”（灰色云朵）。
2. 或者在 Cloudflare 规则中，为 Harbor 路径关闭缓存和性能优化特性。

方案三：检查 S3 后端兼容性

如果你使用的是 MinIO 或 Ceph：

1. MinIO：确保 MinIO 是较新的版本。早期版本的 MinIO 在处理 Multipart Copy ETag 时存在已知问题。
2. Ceph RGW：检查 Ceph 的配置，确保兼容 S3 V4 签名。

在 Harbor 配置中，确保启用了 V4 签名：

1
2
3

storage:
  s3:
    v4auth: true

方案四：禁用重定向（如果不影响性能）

某些情况下，Registry 会尝试将客户端重定向到 S3 的预签名 URL 进行直接上传。如果客户端与 S3 之间的网络有问题，或者 S3 的 CORS 配置不正确，也可能导致怪异的错误（虽然通常不是 412）。

你可以尝试禁用重定向，让流量全部经过 Harbor Registry：

1
2
3

storage:
  redirect:
    disable: true

注意：这会增加 Harbor 服务器的带宽压力。

验证修复

修改配置并重启 Harbor 后，再次尝试推送镜像：

1

docker push your-registry.com/project/image:tag

如果推送成功，说明问题解决。

总结

412 Precondition Failed 是 Harbor 对接 S3 时的一个经典兼容性问题。通过调整 multipartcopychunksize 和 multipartcopythreshold 通常能解决 90% 的此类问题。作为 SRE，在对接非标准 AWS S3 存储时，应特别留意这些高级配置项。