rpardini/docker-registry-proxy

概述

Docker Registry Proxy 是一个基于 Nginx 的 Docker 缓存代理工具，通过 HTTPS_PROXY 机制和 CA 证书拦截 Docker 流量，实现对任意容器镜像仓库的集中认证管理和镜像缓存。它能缓存大型镜像层数据以节省带宽和拉取时间，并可选择性缓存清单请求以避免仓库的拉取速率限制。

0.6.5 版本：2025年2月更新以应对"第二次Docker危机"

Docker 公司宣布将于2025年3月1日实施新一轮政策调整（后推迟至4月），引发了对本项目的关注。此次更新包含依赖项升级、https://github.com/rpardini/docker-registry-proxy/actions/workflows/test.yaml%E6%B7%BB%E5%8A%A0%E3%80%81PR%E5%90%88%E5%B9%B6%EF%BC%88%E5%8C%85%E6%8B%AC%E9%95%BF%E6%9C%9F%E9%9C%80%E6%B1%82%E7%9A%84%60DISABLE_IPV6=true%60%EF%BC%89%E5%8F%8A%E6%96%87%E6%A1%A3%E6%9B%B4%E6%96%B0%E3%80%82%E6%84%9F%E8%B0%A2%E6%89%80%E6%9C%89%E8%B4%A1%E7%8C%AE%E8%80%85%EF%BC%8C%E6%9C%AC%E9%A1%B9%E7%9B%AE%E5%B0%86%E6%8C%81%E7%BB%AD%E7%BB%B4%E6%8A%A4%E3%80%82

新特性：通过缓存避免DockerHub拉取速率限制

自2020年11月2日起，DockerHub开始实施拉取速率限制，主要表现为拉取时出现toomanyrequests错误。许多Kubernetes集群会触发此限制，且难以配置imagePullSecrets和imagePullPolicy。

本代理可通过设置环境变量ENABLE_MANIFEST_CACHE=true来缓存DockerHub限制的清单请求，并可通过其他参数进行精细调整。结合集中式认证注入功能（0.3x版本起支持），这是缓解集群压力、同时节省带宽和时间的有效方案。

注意：默认配置下启用清单缓存会使部分标签不可变，需谨慎使用。相关环境变量说明如下：

dockerfile
# 清单缓存层级。默认禁用，以保持0.4/0.5版本行为。
# 设置为true时启用以下环境变量配置。
# 启用后对所有仓库生效，不仅限于DockerHub。
# *_REGEX为正则表达式片段，具体用法见entrypoint.sh（Nginx ~ location，PCRE语法）。
ENV ENABLE_MANIFEST_CACHE="false"

# "主要"层级默认缓存频繁使用/滥用标签10分钟。
# - 使用:latest标签发布到生产环境的用户应将其加入正则表达式
# - 受速率限制但不介意清单过时的用户应增加此处缓存时间
ENV MANIFEST_CACHE_PRIMARY_REGEX="(stable|nightly|production|test)"
ENV MANIFEST_CACHE_PRIMARY_TIME="10m"

# "次要"层级默认匹配包含3个数字或点的标签，以匹配大多数显式版本化标签。
# 缓存60天，与清单引用的大型二进制层缓存时间一致，使其 effectively 不可变。
# 确保不受此影响；可收紧正则表达式或扩大主要层级范围。
ENV MANIFEST_CACHE_SECONDARY_REGEX="(.*)(\d|\.)+(.*)(\d|\.)+(.*)(\d|\.)+"
ENV MANIFEST_CACHE_SECONDARY_TIME="60d"

# 不匹配上述主要或次要层级的清单的默认缓存时长。
# 默认配置下，:latest和其他常用标签将使用此值。
ENV MANIFEST_CACHE_DEFAULT_TIME="1h"

镜像版本说明

• :latest 和 :latest-debug 标签为不稳定版本，从master分支构建，仅支持amd64架构
• 生产稳定版为 0.6.5，支持多架构（amd64/arm64），详见https://github.com/rpardini/docker-registry-proxy/tree/0.6.5

镜像托管地址

• DockerHub: rpardini/docker-registry-proxy:<version>
• GitHub Container Registry: ghcr.io/rpardini/docker-registry-proxy:<version>
• 0.5.x版本起，两个地址的镜像内容完全一致
• 若已触发DockerHub速率限制无法拉取代理镜像，可使用GHCR地址

代理服务器部署与使用

基本要求

• 部署在网络位置靠近Docker客户端的主机（高带宽、同VPC等）
• 暴露3128端口到网络
• 映射卷/docker_mirror_cache用于存储缓存镜像（默认最大32GB）
• 映射卷/ca用于存储CA证书（跨重启保留，安全敏感）

环境变量说明

部署示例

简单模式（无认证，全缓存）

bash
docker run --rm --name docker_registry_proxy -it \
       -p 0.0.0.0:3128:3128 -e ENABLE_MANIFEST_CACHE=true \
       -v $(pwd)/docker_mirror_cache:/docker_mirror_cache \
       -v $(pwd)/docker_mirror_certs:/ca \
       rpardini/docker-registry-proxy:0.6.5

DockerHub认证

Docker Hub认证需注意：

• hostname 应为 auth.docker.io
• username 应为普通用户名（非***）

bash
docker run --rm --name docker_registry_proxy -it \
       -p 0.0.0.0:3128:3128 -e ENABLE_MANIFEST_CACHE=true \
       -v $(pwd)/docker_mirror_cache:/docker_mirror_cache \
       -v $(pwd)/docker_mirror_certs:/ca \
       -e REGISTRIES="registry.k8s.io gcr.io quay.io your.own.registry another.public.registry" \
       -e AUTH_REGISTRIES="auth.docker.io:dockerhub_username:dockerhub_password your.own.registry:username:password" \
       rpardini/docker-registry-proxy:0.6.5

GitLab认证

GitLab可能使用不同的域名处理认证，类似DockerHub使用auth.docker.io，GitLab使用其主域名。若GitLab部署在git.example.com，仓库在reg.example.com，需同时将两者加入REGISTRIES，并使用主域名进行认证。

bash
docker run  --rm --name docker_registry_proxy -it \
       -p 0.0.0.0:3128:3128 -e ENABLE_MANIFEST_CACHE=true \
       -v $(pwd)/docker_mirror_cache:/docker_mirror_cache \
       -v $(pwd)/docker_mirror_certs:/ca \
       -e REGISTRIES="reg.example.com git.example.com" \
       -e AUTH_REGISTRIES="git.example.com:USER:PASSWORD" \
       rpardini/docker-registry-proxy:0.6.5

Google容器仓库（GCR）认证

GCR认证需使用_json_key作为用户名，密码为服务账户JSON内容。因JSON包含空格和冒号，需修改分隔符：

bash
docker run --rm --name docker_registry_proxy -it \
       -p 0.0.0.0:3128:3128 -e ENABLE_MANIFEST_CACHE=true \
       -v $(pwd)/docker_mirror_cache:/docker_mirror_cache \
       -v $(pwd)/docker_mirror_certs:/ca \
       -e REGISTRIES="registry.k8s.io gcr.io quay.io your.own.registry another.public.registry" \
       -e AUTH_REGISTRIES_DELIMITER=";;;" \
       -e AUTH_REGISTRY_DELIMITER=":::" \
       -e AUTH_REGISTRIES="gcr.io:::_json_key:::$(cat servicekey.json);;;auth.docker.io:::dockerhub_username:::dockerhub_password" \
       rpardini/docker-registry-proxy:0.6.5

Kind集群环境

Kind节点是Docker容器，需将代理加入同一网络：

bash
docker run --rm --name docker_registry_proxy -it \
       --net kind --hostname docker-registry-proxy \
       -p 0.0.0.0:3128:3128 -e ENABLE_MANIFEST_CACHE=true \
       -v $(pwd)/docker_mirror_cache:/docker_mirror_cache \
       -v $(pwd)/docker_mirror_certs:/ca \
       rpardini/docker-registry-proxy:0.6.5

创建集群后配置节点：

bash
#!/bin/sh
KIND_NAME=${1-kind}
SETUP_URL=http://docker-registry-proxy:3128/setup/systemd
pids=""
for NODE in $(kind get nodes --name "$KIND_NAME"); do
  docker exec "$NODE" sh -c "\
      curl $SETUP_URL \
      | sed s/docker\.service/containerd\.service/g \
      | sed '/Environment/ s/$/ \"NO_PROXY=127.0.0.0\/8,10.0.0.0\/8,172.16.0.0\/12,192.168.0.0\/16\"/' \
      | bash" & pids="$pids $!" 
done
wait $pids

Docker客户端配置

Docker Desktop for Mac

详见专用文档。

Linux客户端/Kubernetes节点

假设代理部署在主机192.168.66.72，可通过curl http://192.168.66.72:3128/ca.crt获取CA证书。

在每台Docker主机上执行以下步骤（适用于Ubuntu Xenial/Bionic/Focal等systemd系统）：

bash
# 添加Docker代理环境变量
mkdir -p /etc/systemd/system/docker.service.d
cat << EOD > /etc/systemd/system/docker.service.d/http-proxy.conf
[Service]
Environment="HTTP_PROXY=http://192.168.66.72:3128/"
Environment="HTTPS_PROXY=http://192.168.66.72:3128/"
EOD

# Ubuntu: 添加CA证书到系统信任根
curl http://192.168.66.72:3128/ca.crt > /usr/share/ca-certificates/docker_registry_proxy.crt
echo "docker_registry_proxy.crt" >> /etc/ca-certificates.conf
update-ca-certificates --fresh

# CentOS: 添加CA证书到系统信任根
# curl http://192.168.66.72:3128/ca.crt > /etc/pki/ca-trust/source/anchors/docker_registry_proxy.crt
# update-ca-trust

# 重启Docker
systemctl daemon-reload
systemctl restart docker.service

测试验证

清理本地镜像后拉取测试：

bash
# 清理所有未运行镜像（谨慎操作）
docker system prune -a -f

# 首次拉取（应显示MISS）
docker pull registry.k8s.io/kube-proxy-amd64:v1.10.4

# 再次清理后拉取（应显示HIT）
docker system prune -a -f
docker pull registry.k8s.io/kube-proxy-amd64:v1.10.4

观察代理日志，首次拉取应显示大量MISS，再次拉取应显示HIT。

开发与调试

使用-debug版本镜像进行调试：

bash
docker run --rm --name docker_registry_proxy -it \
       -e DEBUG_NGINX=true -e DEBUG=true -e DEBUG_HUB=true -p 0.0.0.0:8081:8081 -p 0.0.0.0:8082:8082 \
       -p 0.0.0.0:3128:3128 -e ENABLE_MANIFEST_CACHE=true \
       -v $(pwd)/docker_mirror_cache:/docker_mirror_cache \
       -v $(pwd)/docker_mirror_certs:/ca \
       rpardini/docker-registry-proxy:0.6.5-debug

• DEBUG=true：启用客户端与缓存层之间的mitmweb代理（端口8081）
• DEBUG_HUB=true：启用缓存层与DockerHub之间的mitmweb代理（端口8082）
• DEBUG_NGINX=true：启用nginx调试日志

注意事项

• 经过代理拉取的私有镜像对所有可访问代理的客户端可见，需注意安全
• ALLOW_PUSH默认关闭，推送功能需显式启用
• 不同操作系统配置方式不同：Linux较简单，Mac详见专用文档，Windows详见专用文档
• Docker官方仓库仅支持DockerHub镜像缓存，不支持其他仓库（如quay.io、gcr.io等），这是本项目的核心优势

待办事项

• Docker-for-Mac配置说明
• Docker-for-Windows配置说明
• 测试quay.io认证（缺乏访问权限）
• 通过Docker构建ARG隐藏mitmproxy构建代码
• "开发办公室"代理场景（支持开发者共享代理节省带宽，解决推送冲突）