前言

随着 Docker 和云原生技术的发展，越来越多的开发者会使用 Docker Hub、GitHub Container Registry 等海外镜像仓库来部署各种开源项目。

但是对于国内 VPS 用户来说，经常会遇到一个问题：

拉取 Docker 镜像速度非常慢，甚至直接连接失败。

比如我们在国内服务器执行：

docker pull nginx

或者部署一些热门开源项目时，经常因为无法访问海外镜像源，导致镜像下载超时，影响项目部署体验。

虽然现在有很多公共镜像加速服务，但是稳定性、可控性以及镜像缓存策略都无法完全满足自己的需求。

所以今天我开发了一个开源项目 Mirror Relay。

它的思路非常简单：

我们准备一台可以正常访问海外镜像源的 VPS（例如香港 VPS），在上面部署 Mirror Relay 服务。

之后，国内 VPS 不再直接访问 Docker Hub、GitHub 等海外镜像仓库，而是通过 Mirror Relay 进行中转。

第一次请求时，由香港 VPS 从海外镜像源拉取镜像，并缓存到本地；

后续其他服务器再次请求相同镜像时，可以直接从缓存中快速获取，大幅提升 Docker 镜像拉取速度。

简单来说：

国内 VPS → Mirror Relay → 海外镜像源
docker-16-9
通过增加一个镜像中转缓存层，让 Docker 镜像拉取更加稳定、高效。

本期教程我们就来看看如何使用 Docker 部署 Mirror Relay，并搭建属于自己的 Docker 镜像中转缓存服务。

项目图示

web界面显示服务常用信息

拉取镜像的界面显示服务的运行状态

缓存镜像列表展示当前拉取的镜像

开启白名单模式只能自己人使用节省vps的流量等资源

项目简介

自托管 Docker 镜像中继缓存。部署在能访问 Docker Hub 等上游的服务器上，按需拉取并缓存镜像，让无法直接访问上游的服务器也能正常拉取。

✨ 功能特性

功能

功能	说明
多上游代理	Docker Hub、ghcr.io、gcr.io，可在 Web 界面添加更多
按需缓存	只在被请求时拉取，不主动同步
自动清理	磁盘超阈值时 LRU 清理 + Registry GC
白名单	IP/CIDR 级别访问控制，Web 界面动态管理
2FA 验证	TOTP 两步验证，防止密码泄露
暴力破解防护	同一 IP 连续 5 次密码错误自动锁定
管理面板	仪表盘、缓存列表、拉取日志、白名单管理、设置
手动 GC	一键触发垃圾回收
缓存删除	支持删除指定缓存镜像
明暗主题	支持深色/浅色主题切换

管理面板

页面	功能
仪表盘	服务状态、磁盘使用、拉取统计、命中率、各上游缓存大小
缓存列表	查看所有缓存镜像，支持搜索和按上游筛选
拉取日志	最近 100 条拉取记录，命中/透传/拒绝状态，来源 IP
白名单	开关白名单模式，增删 IP/CIDR，批量导入
设置	清理策略、上游管理、2FA 管理、修改密码

白名单

关闭（默认）：所有 IP 可拉取
开启：只有白名单内 IP/CIDR 可拉取，其余返回 403
拒绝的请求会在拉取日志中显示原因（如「IP 不在白名单中」）
支持单 IP（10.0.0.1）和网段（10.0.0.0/24）
批量导入格式：每行一个 IP/CIDR，可用 # 添加备注

10.0.0.1 # 北京服务器
192.168.1.0/24 # 内网段

2FA 两步验证

在「设置」页面点击「启用 2FA」
用 Authenticator App（Google Authenticator、Authy 等）扫描二维码
输入 6 位验证码确认
之后每次登录需要密码 + 验证码双重验证
可在设置页面关闭（需验证当前 2FA 码）

配置

环境变量	默认值	说明
`MAX_DISK_PCT`	80	磁盘使用率阈值（%），超过触发清理
`TARGET_DISK_PCT`	70	清理后目标使用率（%）
`CLEANUP_INTERVAL`	300	清理检查间隔（秒）

以上配置也可在 Web 界面「设置」页面在线修改。

X86/Arm双平台

平台	架构	适用场景
linux/amd64	x86_64	VPS、PC服务器、Intel/AMD
linux/arm64	ARM64	树莓派、Mac M系列、ARM 云服务器

部署方法

使用Docker安装

本教程使用docker的方式安装部署,简单便捷
164b6ac419e23bc5390dc46601a202bf

准备条件

1）一台服务器

我们使用莱卡云VPS来演示，必须选择境外云服务器，支持正常访问dockerhub的vps
需要vps的可以看以下信息，配置尽量选择大点的比如2核心4G内存
莱卡云官网

2）本教程使用到的项目

本教程使用的官方github地址
https://github.com/yyzq-cf/mirror-relay

项目刚创建，如果感觉有用，请帮忙点个stars

3）域名(必须)

根据自己的需求,
1.web界面建议绑定域名
2.中继服务必须配置域名添加ssl证书才能正常使用

VPS部署

一、Docker环境部署

在vps安装docker和docker-compose
Docker官方安装文档（英文）
https://duan.yyzq.eu.org/docker-001
Docker-Compose官方安装文档（英文)
https://duan.yyzq.eu.org/docker-002
Centos安装Docker和Docker-compose（中文）
https://duan.yyzq.eu.org//03
Ubuntu安装Docker和Docker-compose（中文）
https://duan.yyzq.eu.org//04

推荐直接用一键脚本

docker安装脚本

bash <(curl -sSL https://cdn.jsdelivr.net/gh/SuperManito/LinuxMirrors@main/DockerInstallation.sh)

docker-compose安装脚本

curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose && chmod +x /usr/local/bin/docker-compose

二、部署命令

登录我们自己的境外VPS使用root账户执行以下步骤

docker-compose命令

mkdir  mirror-relay ;cd mirror-relay

请自行安装vim编辑器
然后再新建docker-compose.yml

vim docker-compose.yml

services:
  mirror-relay: # 定义 Mirror Relay 服务名称
    image: ywsj/mirror-relay:latest # 使用自己构建的 Mirror Relay 最新版本镜像
    container_name: mirror-relay # 设置 Docker 容器名称为 mirror-relay
    restart: always # 设置容器自动重启，保证服务持续运行
    ports:
      - "5000:5000" # 映射 5000 端口，用于 Docker Registry 镜像代理服务
      - "8080:8080" # 映射 8080 端口，用于 Mirror Relay Web 管理或 API 服务
    volumes:
      - ./data:/data # 挂载当前目录 data 文件夹，用于保存镜像缓存数据
    environment:
      - MAX_DISK_PCT=80 # 设置最大磁盘占用比例，超过 80% 时触发清理机制
      - TARGET_DISK_PCT=70 # 设置清理目标比例，清理后降低到 70% 以下
      - CLEANUP_INTERVAL=300 # 设置缓存清理检查间隔，单位为秒（300秒=5分钟）

注意端口如有冲突自行修改
默认用户名密码
admin
admin123

三、执行容器运行命令

docker-compose up -d #运行容器

docker-compose ps  #查看是否启动成功

正常启动如下所示

docker-compose ps
NAME           IMAGE                      COMMAND                  SERVICE        CREATED         STATUS         PORTS
mirror-relay   ywsj/mirror-relay:latest   "/app/scripts/entryp…"   mirror-relay   5 seconds ago   Up 5 seconds   0.0.0.0:5000->5000/tcp, [::]:5000->5000/tcp, 0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp

查看默认web密码

cat data/.initial_password

四、web界面

打开web页面使用
成功以后需要打开自己相应的端口8080)防火墙就可以web端访问了

主界面

http://ip:8080

输入管理员密码即可登录使用

中继服务

http://ip:5000

绑定域名

接下来就是给中继服务绑定域名和配置SSL证书
绑定域名的教程参考以下内容

绑定域名视频教程

B站

YouTube

绑定域名可以参考
NginxProxyManager
https://duan.yyzq.eu.org//npm-ch

配置好之后是这样的

我们就获得到一个docker中继服务

https://docker.itellyou.cf

然后将需要拉取镜像的国内服务器配置成这个镜像源即可

cd /etc/docker

vim daemon.json

{
  "registry-mirrors": [
    "https://docker.itellyou.cf/"
  ]
 }

重启docker服务生效

systemctl restart docker

注意事项：

如果自己使用建议开启白名单模式，添加自己需要使用的ip即可

有任何问题可以直接留言或者问我
有任何问题可以直接留言或者问我
有任何问题可以直接留言或者问我

欢迎关注我们的微信公众号！

目录CONTENT

我写了一个镜像中转神器！Docker部署 Mirror Relay，解决 Docker/GitHub 拉取镜像难题

前言