内网环境拉取Docker Hub镜像有多痛苦，经历过的人都知道：要么直接超时，要么慢到怀疑人生。给每台服务器逐个配置镜像加速器看似能解决一部分问题，但加速器地址经常失效，而且每个节点各自拉取，缓存无法复用。更合理的做法是在内网自建一台Registry，以pull-through-cache（穿透式缓存）模式运行，所有机器统一从它拉取镜像。第一次访问时它去上游回源，之后相同的镜像层就直接命中本地磁盘缓存，整个内网只需要回源一次。本文详细讲解这套方案的搭建与配置过程。
一、搭建pull-through-cache模式的Registry
Docker官方的registry镜像本身就支持代理模式，原理很简单：当客户端请求的manifest或blob不在本地时，Registry会自动向上游（默认是Docker Hub）发起请求，把结果落盘后再返回给客户端。整个过程对客户端完全透明，用法和普通仓库没有区别。
先准备一个配置文件，比如放在/etc/docker/registry/config.yml，核心配置如下：
version: 0.1
log:
fields:
service: registry
storage:
cache:
blobdescriptor: inmemory
filesystem:
rootdirectory: /var/lib/registry
delete:
enabled: true
http:
addr: :5000
headers:
X-Content-Type-Options: [nosniff]
proxy:
remoteurl: https://registry-1.docker.io
username: your-dockerhub-username
password: your-dockerhub-password其中proxy.remoteurl是整个配置的灵魂，指定上游仓库地址。username和password是可选的，如果你的Docker Hub账号是免费个人版，建议配上，因为匿名拉取的限流非常严格（大约每6小时100次按IP计算），配了账号后限流额度会宽裕不少。如果是企业版用户，还可以用token方式认证。
然后一条命令把服务跑起来：
docker run -d --restart=always \ --name registry-proxy \ -p 5000:5000 \ -v /etc/docker/registry/config.yml:/etc/docker/registry/config.yml:ro \ -v /data/registry:/var/lib/registry \ registry:2
这里把数据目录挂载到/data/registry，缓存都落在这个目录，重启容器不会丢数据。delete.enabled: true要记得打开，否则后面想清理缓存时会发现删除API被禁用。
二、客户端配置与常见坑
Registry跑起来之后，客户端不需要装任何特殊工具，只要把镜像地址指过来就行。这里有一个非常容易踩的坑：代理模式下Registry默认以HTTP方式提供服务，而Docker daemon默认要求HTTPS，直接docker pull myregistry.local:5000/nginx会报证书错误。
解决办法有两个。图省事的话，在客户端的/etc/docker/daemon.json里把仓库地址加入insecure-registries：
{
"registry-mirrors": [],
"insecure-registries": ["myregistry.local:5000"]
}改完执行systemctl restart docker生效。但要注意这个方式对非localhost地址在新版Docker中可能会有额外限制，而且明文传输在生产环境不够安全。更推荐的做法是前面挂一层Nginx做HTTPS终结，给仓库配一个正式证书，客户端就完全不需要额外配置，直接像用官方仓库一样使用。
Nginx的关键配置如下：
server {
listen 443 ssl;
server_name myregistry.local;
ssl_certificate /etc/nginx/certs/registry.crt;
ssl_certificate_key /etc/nginx/certs/registry.key;
# 镜像层可能很大，禁止Nginx缓冲请求体
client_max_body_size 0;
proxy_request_buffering off;
location / {
proxy_pass http://127.0.0.1:5000;
proxy_set_header Host $http_host;
proxy_set_header X-Real-IP $remote_addr;
proxy_read_timeout 900;
}
}这里有两个参数特别关键：client_max_body_size 0取消请求体大小限制（push大镜像层时Nginx默认1M的限制会直接报413错误），proxy_request_buffering off让Nginx流式转发而不是先缓存到本地磁盘，能显著降低推送大层时的延迟和磁盘占用。
三、缓存管理与存储控制
代理缓存用得久了，磁盘会被各种镜像层填满，必须有一套管理手段。首先要能看清楚空间被什么占了，Registry提供了垃圾回收机制配合目录分析来处理这件事。
第一步用registry garbage-collect清理没有被任何manifest引用的孤儿层。完整流程是先通过API删除不需要的manifest，再执行GC：
# 删除一个manifest（digest可从registry API查询） curl -X DELETE \ -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \ https://myregistry.local/v2/library/nginx/manifests/sha256:xxxx # 进入容器执行垃圾回收 docker exec registry-proxy registry garbage-collect \ /etc/docker/registry/config.yml --delete-untagged
注意GC过程中最好暂停写入，否则可能出现误删。稳妥做法是低峰期执行，或者临时把服务切到只读模式（可以在配置里加storage.maintenance.readonly.enabled: true后重启）。
除了GC，还应该监控磁盘增长趋势。可以用一个简单的cron脚本统计/data/registry目录大小，超过阈值就告警；也可以直接用Registry暴露的Prometheus指标（配置http.debug.addr: :5001后在5001端口访问/metrics），里面有上传下载计数和存储相关数据，接入现有的监控体系很方便。
四、让Kubernetes集群统一走代理仓库
如果是K8s环境，逐个节点改daemon.json太分散，更好的方式是修改集群容器运行时的统一配置。以使用containerd的节点为例，编辑/etc/containerd/config.toml，在registry.mirrors段落里为docker.io指定镜像端点：
[plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"] endpoint = ["https://myregistry.local", "https://registry-1.docker.io"]
这样写之后，containerd拉取docker.io的镜像时会优先走你的代理仓库，失败时自动回退到官方源，具备一定的容错能力。改完配置执行systemctl restart containerd。如果用Ansible或节点池镜像统一管理，把这个配置打进基础镜像里，新增节点就自动具备代理能力。
需要说明的是，自建缓存仓库和单纯配置镜像加速器（registry-mirrors）是有本质区别的：加速器只是别人提供的CDN入口，缓存命中与否不受你控制，而且国内可用的公共加速器地址经常变动；自建的pull-through缓存则是你自己的资产，命中率、存储策略、上游选择都由自己决定，还可以顺便代理quay.io、gcr.io等其他源（起多个Registry实例或者用支持多上游的Harbor来做）。如果团队规模较大、镜像种类多，建议直接上Harbor，它的project级别proxy cache功能可以把不同上游源映射到不同项目名下，管理体验比裸Registry好很多。
总体来看，代理缓存仓库的投入成本很低——一台普通的虚拟机加几十行配置，就能换来内网拉镜像速度的质变，同时大幅减少对公网带宽和Docker Hub免费额度的依赖，是非常值得做的基础设施优化。
Docker镜像仓库代理缓存Registry镜像同步修改时间：2026-09-14 08:56:44