Distribution项目S3存储清理功能升级适配指南

背景介绍

在Distribution项目（原Docker Registry）从2.8.3版本升级到3.0.0-rc.1版本的过程中，用户发现使用S3存储后端进行垃圾回收时出现了连接问题。这个问题特别出现在使用非AWS标准的S3兼容存储服务（如某些分布式文件系统）的场景下。本文将深入分析问题原因并提供解决方案。

问题现象

当用户从2.8.3版本升级到3.0.0-rc.1版本后，执行registry垃圾回收命令时出现以下错误：

failed to garbage collect: failed to mark: s3aws: RequestError: send request failed
caused by: Get "http://registry.10.44.1.12:8333/?list-type=2&max-keys=1000&prefix=docker%2Fregistry%2Fv2%2Frepositories%2F&start-after=": dial tcp: lookup registry.10.44.1.12 on 172.17.0.1:53: no such host

关键问题在于新版本尝试将bucket名称作为子域名拼接在regionendpoint前，导致DNS解析失败。

技术分析

S3 API访问模式

AWS S3 API支持两种访问方式：

1. 虚拟主机风格：http://bucket-name.s3.region.amazonaws.com/key-name
2. 路径风格：http://s3.region.amazonaws.com/bucket-name/key-name

在Distribution 3.0.0-rc.1版本中，当使用自定义regionendpoint时，默认采用了虚拟主机风格的访问方式，这会导致：

• 尝试将bucket名称作为子域名
• 对于非AWS标准的S3服务（如某些分布式文件系统、MinIO等），这种访问方式通常不支持

版本差异

2.8.3版本中，无论是否设置regionendpoint，都默认使用路径风格的访问方式，因此能够正常工作。而3.0.0-rc.1版本改变了这一行为，导致兼容性问题。

解决方案

配置调整

在storage.s3配置部分添加以下参数：

storage:
  s3:
    forcepathstyle: true
    v4auth: true
    secure: false
    rootdirectory: /

其中最关键的是forcepathstyle: true，它强制使用路径风格的访问方式，保持与旧版本的兼容性。

参数说明

1. forcepathstyle：强制使用路径风格访问S3 API
2. v4auth：使用AWS签名版本4（推荐启用）
3. secure：是否使用HTTPS（根据实际环境配置）
4. rootdirectory：存储根目录（默认为/，显式声明更清晰）

最佳实践

对于使用非AWS标准S3服务的用户，在升级到Distribution 3.0.0及以上版本时，建议：

1. 提前测试：在测试环境验证垃圾回收功能
2. 明确配置：显式声明forcepathstyle参数
3. 版本过渡：保留旧版本配置与新版本配置的对比文档
4. 监控验证：升级后密切监控存储操作是否正常

总结

Distribution项目3.0.0版本对S3存储后端的访问方式进行了优化，但在自定义S3服务场景下需要特别注意访问风格的配置。通过明确设置forcepathstyle: true参数，可以确保升级过程的平滑过渡，保持与各类S3兼容存储服务的良好兼容性。