搭建 Docker Registry Mirror（镜像加速器服务器）的核心是部署带代理缓存功能的私有 Registry，本质是让私有 Registry 拉取并缓存官方镜像，供本地 / 内网 Docker 客户端使用，从而提升拉取速度。以下是基于 Docker 官方 Registry 镜像 + 缓存配置的完整搭建步骤。
服务器要求
核心原理
客户端请求拉取镜像时，先访问私有 Mirror → 若 Mirror 已有缓存，则直接返回；若无，则从 Docker Hub 拉取并缓存，再返回给客户端。
1、 创建 Registry 配置文件
创建配置目录和 config.yml 文件，配置缓存策略、上游镜像源（Docker Hub）等参数。
# 创建配置目录
mkdir -p /opt/docker-registry/{conf,data}
cd /opt/docker-registry/conf
新建 config.yml 文件，写入以下内容：
version: 0.1
log:
fields:
service: registry
storage:
cache:
blobdescriptor: inmemory # 内存缓存镜像描述信息
filesystem:
rootdirectory: /var/lib/registry # 镜像数据存储路径
http:
addr: :5000 # 监听端口
headers:
X-Content-Type-Options: [nosniff]
proxy:
remoteurl: https://registry-1.docker.io # 上游镜像源（Docker Hub）
username: [你的Docker Hub用户名] # 可选，拉取私有镜像时需要
password: [你的Docker Hub密码] # 可选
health:
storagedriver:
enabled: true
interval: 10s
threshold: 3
注意：
proxy.remoteurl 固定为 Docker Hub 官方地址，不可修改。
若需缓存 Docker Hub 私有镜像，才需要填写 username 和 password；仅缓存公有镜像可省略这两项。（如果使用公共仓镜像，删除username和password这2行。）
2、 编写 Docker Compose 文件
在 /opt/docker-registry 目录下创建 docker-compose.yml，简化部署和管理：
# version: '3' # 在 Compose v2 及以上版本中，这个字段已经不再强制要求，且官方明确该字段会被逐步废弃
services:
registry:
image: registry:2 # 官方Registry 2.x镜像
container_name: docker-registry-mirror
restart: always
ports:
- "5000:5000" # 宿主机端口:容器端口
volumes:
- ./conf/config.yml:/etc/docker/registry/config.yml # 挂载配置文件
- ./data:/var/lib/registry # 挂载数据目录，持久化缓存的镜像
environment:
- REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io # 与配置文件一致，双重保障
3、 启动 Registry Mirror 服务
# 启动服务 docker-compose up -d # 有的linux是执行： docker compose up -d # 查看运行状态 docker-compose ps # 有的linux是执行： docker ps
配置 Docker 客户端使用 Mirror
客户端需要修改 daemon.json，指定搭建的 Mirror 地址，步骤如下：
1、编辑客户端的 /etc/docker/daemon.json：
{
"registry-mirrors": [
"http://[你的服务器IP]:5000", # 替换为 Mirror 服务器的IP或URL和端口
"http://[你的服务器IP]:5000" # 第二台加速服务器
]
}
2、重启 Docker 服务：
sudo systemctl daemon-reload sudo systemctl restart docker
3、验证配置：
docker info
输出中 Registry Mirrors 字段显示你的服务器地址，即为配置成功。
1、在客户端拉取一个未缓存的镜像，例如 nginx:alpine：
docker pull nginx:alpine
2、查看 Mirror 服务器的镜像缓存目录，确认数据已存储：
ls -lh /opt/docker-registry/data/docker/registry/v2/repositories/library/nginx/
若存在相关目录和文件，说明缓存成功。
3、再次拉取 nginx:alpine，速度会显著提升（直接从 Mirror 读取）。
1、配置 HTTPS（推荐）
Docker 默认要求 Registry 使用 HTTPS，若使用 HTTP，需在客户端 daemon.json 中添加 insecure-registries：
{
"registry-mirrors": ["http://[服务器IP]:5000"],
"insecure-registries": ["[服务器IP]:5000"]
}
生产环境建议配置 SSL 证书，将 http 改为 https。
实测不按照上面修改也能正常使用。
2、设置缓存清理策略
Registry 不会自动清理过期缓存，可通过 registry garbage-collect 命令清理：
docker exec docker-registry-mirror registry garbage-collect /etc/docker/registry/config.yml
可添加定时任务（crontab）定期执行。
3、多上游源支持
若需缓存其他镜像源（如阿里云、华为云镜像），可部署多个 Registry 实例，分别配置不同的 proxy.remoteurl。
在 Registry 的 config.yml 配置文件中设置存储配额（storage quota），以此限制镜像缓存的总占用空间，避免服务器磁盘被占满。这个配置需要借助 Registry 的 filesystem 存储驱动扩展参数，结合 quota 相关配置实现，以下是具体的设置方法和完整示例。
一、配置存储配额的核心原理
Registry 的存储配额分为两种核心限制：
1、总磁盘空间配额：限制 Registry 缓存镜像的总占用空间（如 100GB）；
2、单个镜像大小配额：限制单镜像的最大体积（如 10GB）。
配置需写在 storage.filesystem 节点下，且仅对 filesystem 存储驱动生效（这也是我们搭建 Mirror 时的默认驱动）。
二、完整的 config.yml 配置（含配额）
替换 /opt/docker-registry/conf/config.yml 的内容，新增配额相关配置，核心新增字段已标注：
version: 0.1
log:
fields:
service: registry
storage:
cache:
blobdescriptor: inmemory
filesystem:
rootdirectory: /var/lib/registry
# --------------- 新增存储配额配置 ---------------
maxsize: 100GB # 总存储配额（支持 KB/MB/GB/TB，必填）
maxblobsize: 10GB # 单个镜像 blob 最大大小（可选）
# 可选：配置缓存清理的阈值（触发自动清理的条件）
delete:
enabled: true # 开启删除功能（必须开启，否则配额不生效）
http:
addr: :5000
headers:
X-Content-Type-Options: [nosniff]
proxy:
remoteurl: https://registry-1.docker.io
# username: 你的Docker Hub用户名（可选）
# password: 你的Docker Hub密码（可选）
health:
storagedriver:
enabled: true
interval: 10s
threshold: 3
三、关键配置说明
配置项 | 作用 | 示例值
maxsize 限制 Registry 存储目录的总占用空间，达到阈值后无法再缓存新镜像 50GB / 1TB
maxblobsize 限制单个镜像文件（blob）的最大体积，防止超大镜像占用过多空间 5GB / 20GB
delete.enabled 必须设为 true，否则配额限制和垃圾回收命令都无法删除旧镜像（核心） true
四、配置生效步骤
重启 Registry 服务：
cd /opt/docker-registry docker-compose down && docker-compose up -d
五、配额 + 垃圾回收的最佳实践
存储配额只是 “上限限制”，结合定时垃圾回收才能更灵活地管理空间：
1、手动执行垃圾回收（清理未被引用的镜像）：
# 清理悬空镜像（不影响正在使用的镜像） docker exec docker-registry-mirror registry garbage-collect /etc/docker/registry/config.yml
2、配置定时任务（每天凌晨 2 点自动清理）：
# 编辑 crontab 定时任务 crontab -e
添加以下内容：
# 每天凌晨 2 点执行垃圾回收 0 2 * * * docker exec docker-registry-mirror registry garbage-collect /etc/docker/registry/config.yml > /var/log/registry-gc.log 2>&1
注意事项
maxsize 的值需根据服务器磁盘实际可用空间设置（建议预留 20% 余量）；
配额生效后，若空间已满，需先执行垃圾回收释放空间，才能继续缓存新镜像；
该配额仅限制 Registry 自身缓存的镜像，不会影响服务器上的其他 Docker 容器 / 镜像。
总结
配置存储配额的核心是在 storage.filesystem 下添加 maxsize（总空间）和 maxblobsize（单镜像大小），且必须开启 delete.enabled: true；
配额仅为 “上限限制”，需结合垃圾回收命令 / 定时任务，才能主动释放过期缓存空间；
配置后需重启 Registry 服务，配额才能生效。
Docker 镜像加速器的 data 目录（存储缓存镜像的目录）能否复制给其他镜像加速器服务器使用 —— 答案是完全可以，但需要遵循特定的规则和步骤，确保复制后的数据能被新的 Registry 实例正常识别和使用。
核心原理
./data 目录是 Registry 容器的 /var/lib/registry 挂载目录，里面存储了：
查看缓存大小
du -sh /opt/docker-registry/data
复制 / 迁移的前提条件
1、Registry 版本一致：新服务器的 Registry 镜像必须和原服务器一致（推荐用 registry:2 固定版本，避免 latest 导致版本差异）；
2、权限一致：复制后的目录权限需与 Registry 容器的运行用户（默认 root 或 1000:1000）匹配；
3、停止原服务再复制：避免复制过程中数据写入导致文件损坏（核心！）。
完整的复制 / 迁移步骤
1、停止原 Registry 服务（关键）
# 进入原加速器服务器的配置目录 cd /opt/docker-registry # 停止容器（避免数据写入） docker-compose down
2、打包 data 目录
# 打包data目录（保留权限和目录结构） tar -zcvf registry-data.tar.gz ./data
3、传输打包文件到新服务器
用 scp 或 rsync 传输（假设新服务器 IP 为 192.168.1.100）：
scp registry-data.tar.gz root@192.168.1.100:/opt/docker-registry/
4、新服务器准备环境
确保新服务器已创建相同的目录结构（和原服务器的 docker-compose.yml 配置一致）：
# 新服务器创建目录
mkdir -p /opt/docker-registry/{conf,data}
# 解压数据（保留权限）
cd /opt/docker-registry
tar -zxvf registry-data.tar.gz
# 修复目录权限（关键！Registry 容器需读写权限）
chown -R 1000:1000 ./data # 或 chmod -R 755 ./data（简单通用）
5、新服务器启动 Registry
确保新服务器的 docker-compose.yml 和 conf/config.yml 与原服务器完全一致，然后启动：
docker-compose up -d # 检查容器状态 docker-compose ps
6、验证迁移效果
在新服务器的客户端拉取一个原缓存过的镜像（如 nginx:alpine），会发现拉取速度极快（直接读取本地缓存）：
docker pull nginx:alpine
注意事项（避坑关键）
1、禁止在线复制：如果不停止原 Registry 就复制 data 目录，可能导致镜像分层文件（blobs）不完整，新服务器启动后出现「镜像拉取失败」「manifest 不存在」等错误；
2、版本兼容：
3、路径一致性： 新服务器的 docker-compose.yml 中，./data 必须挂载到容器的 /var/lib/registry（和原服务器一致），否则 Registry 找不到缓存数据；
4、清理无效数据：如果迁移后发现部分镜像无法访问，可执行垃圾回收清理无效数据：
docker exec docker-registry-mirror registry garbage-collect /etc/docker/registry/config.yml
总结
1、data 目录（缓存镜像的目录）可以复制给其他镜像加速器使用，核心是保证 Registry 版本一致、停止服务后复制、修复目录权限；
2、迁移后新加速器可直接复用已有缓存，无需重新拉取镜像，大幅节省带宽和时间；
3、关键步骤：停止原服务 → 打包数据 → 传输 → 解压并修复权限 → 启动新服务。