镜像仓库的层别堆本地盘：用 RustFS 给 Docker Registry 当 S3 后端

自己跑一个 Docker Registry，默认配置下镜像的层和清单全写在仓库主机的本地文件系统上。单机玩玩没问题，一旦你想横向扩几个仓库节点、或者不想因为主机盘坏了就丢镜像，本地盘就成了单点。Docker Registry（distribution 项目）原生支持 S3 存储驱动，把层和清单直接写成对象丢进 RustFS 桶，仓库本身变成无状态，扩节点就是多起几个实例指同一个桶。镜像数据从主机盘搬到对象存储，主机的生命周期就和数据解耦了。

Registry 把镜像拆成什么存

一个镜像由若干层（layer）和一个清单（manifest）组成。层是镜像文件系统的差分，清单记录层之间的顺序和配置摘要。Registry 用 S3 驱动时，每个层和配置都作为对象存进桶的 docker/registry/v2/ 之下，清单和标签指向这些 blob 的链接。仓库主机上不再保留镜像数据，真正的字节都在 RustFS 里。这也是它能横向扩展的根本原因：节点无状态，多个 Registry 实例共享同一个桶，谁挂了换一个起来照样能拉。

官方指南用 registry:2 配合 rustfs/rustfs-x86-musl:v2.3.1 验证通过。下面这套做法就是把你已经跑着的 Registry 指向你已经有的 RustFS。桶要提前建好，驱动不负责建桶。

一组环境变量把层指到 RustFS

S3 驱动完全用环境变量配置，不用碰 YAML。最关键的是 REGISTRY_STORAGE_S3_REGIONENDPOINT，它把 AWS SDK 指向 RustFS，而不是真的 AWS。漏掉这一项，仓库会把请求发往真实的 AWS 端点，推送必然失败。

bash 复制代码

docker run -d --name registry -p 5000:5000 \
  -e REGISTRY_STORAGE=s3 \
  -e REGISTRY_STORAGE_S3_ACCESSKEY=<your-access-key> \
  -e REGISTRY_STORAGE_S3_SECRETKEY=<your-secret-key> \
  -e REGISTRY_STORAGE_S3_REGION=us-east-1 \
  -e REGISTRY_STORAGE_S3_BUCKET=registry-demo \
  -e REGISTRY_STORAGE_S3_REGIONENDPOINT=http://<your-rustfs-endpoint>:9000 \
  registry:2

REGISTRY_STORAGE=s3 打开 S3 驱动，下面四个字段才生效：桶名决定对象落在哪个桶，区域虽然对 RustFS 不校验但这一栏不能为空，端点是请求真正发往的地址，凭证是访问这个桶的钥匙。确认 v2 API 已就绪只需一句：

bash 复制代码

curl -s -o /dev/null -w "%{http_code}\n" http://localhost:5000/v2/

返回 200 说明仓库进程起来了，但还不能证明层真的落进 RustFS，那一步要靠后面推完镜像再 rc ls 确认。

推一张镜像进去，层真的落桶了

给任意本地镜像打个仓库标签推上去，层和清单就写进 RustFS：

bash 复制代码

docker pull alpine:3.20
docker tag alpine:3.20 localhost:5000/rustfs-demo/alpine:3.20
docker push localhost:5000/rustfs-demo/alpine:3.20

在 RustFS 这边用 rc ls 看桶，能找到镜像的链接对象，每个 _layers 链接都指向同一桶内的 blob：

bash 复制代码

rc ls rustfs/registry-demo/docker/registry/v2/repositories/rustfs-demo/alpine/ -r | head -4

这说明镜像数据本身在 RustFS 里，不在仓库主机上。同一个层如果多个镜像都用到，在桶里只存一份 blob，链接复用，所以对象存储侧的去重是天然的。删掉本地镜像再拉一次，层从 RustFS 回来，链路就闭环了。

桶里的目录结构值得记一下：_repositories 下按镜像名分目录，每个镜像的 _layers 存层链接、_manifests 存清单和标签引用、_uploads 是进行中的上传临时区。理解这个布局，出问题时你才能直接进桶判断某个层到底在不在，而不是只能靠 registry 的 API 报错猜。也正因为层是内容寻址的，删掉某个标签不会立刻删掉底层 blob，真正释放空间要等垃圾回收跑完，这点和本地文件系统删文件立刻释放不一样。

多节点共享一个桶

因为数据全在桶里，起第二个 Registry 实例、指同一个 REGISTRY_STORAGE_S3_BUCKET 和 REGIONENDPOINT，就能直接读同一批镜像。前面加一层负载均衡，仓库就从单机变成了可横向扩展的服务。删除本地副本再从仓库拉一次验证：

bash 复制代码

docker rmi localhost:5000/rustfs-demo/alpine:3.20
docker pull localhost:5000/rustfs-demo/alpine:3.20

对象存储给了镜像层持久性和跨节点共享，但有一点要记住：Registry 自己不会回收那些已经没有标签引用的层，也就是垃圾对象。长期运行后桶里会积累无人引用的 blob，需要定期跑 Registry 的垃圾回收（registry garbage-collect）来释放空间，这部分运维不能因为换了存储后端就忘了。

多实例共享桶时还要注意一致性假设：Registry 对 S3 后端默认按最终一致来设计读写，而 RustFS 提供强一致读取，所以推完立刻拉一般不会遇到幽灵层。这层假设在你换用其他最终一致的存储时要重新评估，否则可能出现刚推送完却拉不到的窗口。也不是所有场景都该上对象存储，如果你只是单机开发验证、镜像量很小，本地文件系统反而更简单，少了端点可用性和凭证管理这两层依赖。对象存储真正的价值在横向扩展、跨节点共享和持久性，量起来之后这些才划算。

RustFS 当前稳定版是 1.0.4（2026-10-25），覆盖 Registry 需要的这些 S3 操作。官方 GA 基准里 4KiB 小对象 PUT 大约能到 MinIO 的 2.3 倍，镜像层多为几 MB 到几十 MB，上传靠的是稳定大块吞吐，这一层 RustFS 不拖后腿。控制台在 /rustfs/console/ 路径下，进去能直接翻 docker/registry/v2/ 前缀确认层到位。

几个最容易踩的点

端点必须显式设 ：漏掉 REGISTRY_STORAGE_S3_REGIONENDPOINT，仓库会把请求发往真实的 AWS，推送失败且 digest 为 unknown；
桶要提前建好 ：驱动不负责建桶，桶不存在会报 InvalidAccessKeyId 或被拒绝，先 rc mb；
凭证只认环境变量 ：这个驱动不读 AWS 凭证链，必须老老实实通过 REGISTRY_STORAGE_S3_ACCESSKEY 和 SECRETKEY 传进去；
多实例配置要一致 ：重启后拉取报 manifest unknown，多半是两个实例的桶名或端点没对齐；
垃圾回收别漏 ：层落进对象存储后，无人引用的 blob 不会自动消失，定期 garbage-collect 才有干净的空间。

接好之后，Registry 主机可以随意起停扩缩，镜像全在 RustFS 桶里一个地方管，垃圾回收按你自己的节奏来。

官方把 Docker Registry 接进 RustFS 的完整步骤在 Docker Registry 集成指南里，包含推送、拉取与对象验证的示例命令。需要 UI、RBAC 或复制能力时，可以看同一目录下的 Harbor 指南，生产凭证的创建方式看访问密钥管理。