自建 Docker Registry Mirror：缓存与访问控制

版本范围：原实验基于 registry:2。示例中的 HTTP 与 insecure-registries 只适合受控实验网络，对外入口需配置 TLS、访问限制及必要鉴权。

目标

在外面服务器上搭建一个 Docker Registry Mirror，作为本地 Docker 拉取镜像的中间代理。所有请求先打到这台服务器，由它去 Docker Hub 拉取并缓存，后续相同镜像可直接命中缓存，彻底解决本地网络不稳定、超时的问题。

环境准备

外面服务器一台（能正常访问 Docker Hub）
服务器已安装 Docker
本地 Docker Desktop（或其他 Docker 环境）

一、在外面服务器上部署 Registry Mirror

1. 拉取官方 Registry 镜像

docker pull registry:2

2. 启动 Registry 容器并配置代理上游

docker run -d \
  --restart=always \
  --name registry-mirror \
  -v /opt/registry:/var/lib/registry \
  -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
  -p 5000:5000 \
  registry:2

参数说明：

--restart=always：开机自启，服务保活
-v /opt/registry:/var/lib/registry：挂载本地目录持久化缓存镜像，避免容器删除后缓存丢失
-e REGISTRY_PROXY_REMOTEURL=...：设置上游为 Docker Hub
-p 5000:5000：将容器 5000 端口映射到宿主机 5000 端口（可自定义宿主机端口）

3. 验证容器运行状态

docker ps | grep registry-mirror

正常会看到一行运行中的容器记录。

二、⚠️ 关键一步：开放服务器端口

如果端口没开，本地 Docker 永远连不上！ 务必检查以下两处：

1. 云服务商安全组（阿里云/腾讯云/华为云/AWS 等）

在云服务器控制台 → 安全组（或防火墙）规则中，添加一条 入方向 规则：

协议	端口	源 IP
TCP	5000	0.0.0.0/0（或改为你的固定 IP）

2. 服务器系统防火墙

根据系统执行对应命令放行端口：

Ubuntu（ufw）

sudo ufw allow 5000/tcp
sudo ufw reload

CentOS/RHEL（firewalld）

sudo firewall-cmd --zone=public --add-port=5000/tcp --permanent
sudo firewall-cmd --reload

通用 iptables

sudo iptables -I INPUT -p tcp --dport 5000 -j ACCEPT
## 保存规则（不同发行版命令不同，如 service iptables save 或 iptables-save）

3. 验证端口连通性

在本地机器上测试（PowerShell 或终端）：

Test-NetConnection -ComputerName 服务器公网IP -Port 5000

或

nc -zv 服务器公网IP 5000

显示成功（TcpTestSucceeded: True / Connection succeeded）即表示端口已通。

三、本地 Docker 配置使用该 Mirror

1. 编辑 Docker 配置文件

Windows Docker Desktop：%USERPROFILE%\.docker\daemon.json Linux：/etc/docker/daemon.json

添加或修改 registry-mirrors 字段（如果已有其他镜像源，可以保留或替换）：

{
  "registry-mirrors": ["http://服务器公网IP:5000"]
}

注意：

使用 http://（除非你另外配置了 TLS 证书，自建 Mirror 默认无 HTTPS）
如果希望只使用这一个镜像源，可以移除其他 mirror 地址；否则 Docker 会按顺序尝试

2. 重启 Docker 使配置生效

Windows Docker Desktop：右下角托盘图标 → 右键 → Restart，或在 PowerShell 中：

taskkill /IM "Docker Desktop.exe" /F
Start-Process "C:\Program Files\Docker\Docker\Docker Desktop.exe"

Linux：

sudo systemctl daemon-reload
sudo systemctl restart docker

3. 验证是否生效

docker info

在输出中找到 Registry Mirrors 段落，应显示：

Registry Mirrors:
  http://服务器公网IP:5000/

然后尝试拉取一个镜像测试：

docker pull nginx:latest

如果速度正常且不再超时报错，即代表配置成功。

四、维护与注意事项

查看缓存命中效果

可以在服务器上查看 Registry 容器的日志，观察是否命中缓存（cache 关键字）：

docker logs -f registry-mirror

缓存存储位置

所有缓存镜像保存在宿主机的 /opt/registry（与容器挂载目录对应）。若需清理缓存，直接清空该目录并重启容器即可。

安全建议

如果服务器仅自用，可在安全组中将来源 IP 限制为你的本地固定 IP，避免被他人滥用
生产环境建议配置 HTTPS（绑定域名、使用 Let’s Encrypt 证书），否则 Docker 会报 insecure registry 警告（但功能不受影响）

常见故障排查

拉取时仍然超时：检查服务器是否能正常访问 Docker Hub（在服务器上执行 docker pull hello-world 测试）
本地连接 Mirror 被拒：再次检查安全组和防火墙，确认端口放行且监听正常
拉取提示 “http: server gave HTTP response to HTTPS client”：请确保 daemon.json 中使用的是 http:// 而不是 https://；如果确实想用 HTTPS，需为 Mirror 配置 TLS 证书

这份笔记到此结束，以后遇到网络问题，只需按步骤检查服务器端口和本地配置即可。

缓存范围与维护

Registry pull-through cache 面向其配置的上游，不会自动代理所有镜像仓库。认证镜像的访问范围需单独设计；不要在服务运行期间直接清空挂载目录，清理前先停止相关写入并按版本文档操作。