Docker镜像加速器搭建 [yanWiki]

本页面只读。您可以查看源文件，但不能更改它。如果您觉得这是系统错误，请联系管理员。
====== Docker镜像加速器搭建 ======

搭建 Docker Registry Mirror（镜像加速器服务器）的核心是部署带代理缓存功能的私有 Registry，本质是让私有 Registry 拉取并缓存官方镜像，供本地 / 内网 Docker 客户端使用，从而提升拉取速度。以下是基于 Docker 官方 Registry 镜像 + 缓存配置的完整搭建步骤。

===== 环境准备 =====

**服务器要求**

 - 一台可联网的 Linux 服务器（推荐 CentOS/Ubuntu），已安装 Docker 和 Docker Compose。
 - 开放 5000 端口（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 字段显示你的服务器地址，即为配置成功。

===== 测试 Mirror 功能 =====

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 挂载目录，里面存储了：

  * 普通列表项目镜像的分层数据（blobs）；

  * 普通列表项目镜像的元数据（manifests）；

  * 普通列表项目Registry 的存储索引（registry.db）。
这些数据是平台无关、可移植的（只要 Registry 版本一致），复制后新的加速器服务器可直接复用已有缓存，无需重新从 Docker Hub 拉取镜像。

**查看缓存大小**

```
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、**版本兼容**：

  * 普通列表项目低版本 Registry（如 2.7）的数据可迁移到高版本（如 2.8+），但高版本数据不能回退到低版本；

  * 普通列表项目建议所有服务器统一使用 registry: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、关键步骤：停止原服务 → 打包数据 → 传输 → 解压并修复权限 → 启动新服务。