Contents

Docker Mirror Gateway:一个地址搞定所有容器镜像加速

一、前言

拉镜像这件事,难点从来不是「拉」,而是「从哪拉」。加速源今天能用明天 403,GHCR、Quay、K8s 每类仓库还得单独找地址单独配。这个工具就是来收拾这些事的。

在境内拉容器镜像,几乎每个环节都有坑:官方源直连超时;公共加速源随时失效;好不容易配了个快的源,又因为同步滞后拉到了旧版 latest;CI 反复拉同一批镜像,回源带宽白白浪费。

把 registry-mirrors 指向某一个加速地址,只能解决其中一部分问题——而且那个地址一旦挂了,所有机器一起挂。

我把自己这套流程做成了一个自托管的镜像加速网关:Docker Mirror Gateway。它把多个镜像源聚合成一个地址,按健康度和实测速度自动选源,可选本地缓存,一个实例同时服务 Docker Hub、GHCR、Quay、MCR、K8s、GCR、Elastic、NVCR。

二、解决什么问题

一句话概括:它不是又一个加速地址,而是把「选哪个地址」这件事自动化了。

加速源会挂,那就别只用一个。 一个分组下可以挂多个互为镜像的加速地址,健康检查连续失败自动降级,拉取时逐源重试,切换对客户端无感。

每类仓库都要单独配,那就合成一个入口。 Hub / GHCR / Quay / MCR / K8s / GCR / Elastic / NVCR 共用同一地址,路径前缀、子域名、自动判定三种路由适配 Docker CLI、containerd、K8s 各种用法。

最快的源未必是最新的。 拉取 latest 这类浮动标签时并发比较各源的构建时间,内容一样才看速度,避免拉到旧镜像。

静态优先级会过期。 吞吐数据来自真实拉取(零成本)加定期探测,谁下载体验好就用谁。

官方源要挂代理,但代理又慢又不能拖累整体。 每个源可以单独配 socks5/http 代理作兜底,加速源直连主力;健康探测与真实拉取走同一个代理,不会出现「探测通过但拉不动」。

CI 反复拉同一批镜像。 可选的 pull-through 缓存,本地磁盘或 S3,blob 边传边校验 sha256。

源挂了没人知道。 分组健康跌破阈值时通过 webhook(飞书、企微、自建服务都能适配)或邮件告警,恢复自动通知。

Nexus / Harbor 太重。 单二进制约 12 MB,只有两个直接依赖,不依赖数据库、Redis 或 JVM,docker compose up 一键起。

三、主要功能

1. 多仓库聚合

一个分组下多个互为镜像的加速地址共享同一入口,已内置 8 个分组、35 个境内公共加速源,开箱即用。配置里给出的初始顺序只是出厂值,运行起来后会按实测吞吐动态重排。

分组 初始源(按序) 实测吞吐
dockerhub sparkcr → 1ms → daocloud → 1panel → 官方 3.4 MB/s
ghcr 南京大学 → sparkcr → dockerproxy → 官方 19 MB/s
quay 南京大学 → sparkcr → dockerproxy → daocloud → 官方 6.8 MB/s
mcr sparkcr → dockerproxy → daocloud → 官方 22 MB/s
k8s 南京大学 → sparkcr → daocloud → dockerproxy → 官方 4.1 MB/s
gcr 南京大学 → sparkcr → daocloud → dockerproxy → 官方 1.6 MB/s
elastic sparkcr → daocloud → 官方 9.0 MB/s
nvcr 南京大学 → sparkcr → daocloud → 官方 30 MB/s

官方源一律放在兜底优先级:通常不可直连,但配上代理后是内容绝对正确的退路。这些都是第三方免费服务,可能限速或下线,健康检查会自动降级,也可以照格式换成自己的源或私有 registry。

2. 按速度选源

默认策略 speed,排序规则按优先级依次是:

  1. 健康的上游永远排在失效源之前,失效源只作最后兜底;
  2. 吞吐高者优先;
  3. 吞吐相差在 speedTolerance(默认 25%)以内视为持平,此时比较延迟;
  4. 仍持平则比 priority。

吞吐来自真实拉取与主动探测两路。小样本(< 64KB)不参与计算,计时只覆盖 body 传输。另外有个 trafficWindow(默认 2 分钟):窗口内处理过成功真实拉取的上游会跳过定时探测——真实流量已经测出延迟、喂了吞吐样本、并由成败维护着健康状态,再发探测请求是纯开销。

3. latest 新旧优先

各加速源同步上游有延迟,最快的源未必有最新的 latest。开启 selection.preferFresh 后,拉取浮动标签时会并发比较各健康上游的镜像构建时间:

  • 各源 manifest digest 完全一致 → 内容相同,直接按速度选,不再下载配置;
  • 否则构建时间新的优先,差异小于 freshnessTolerance 时才比速度;
  • 有效样本少于两个 → 退回速度排序。

探测结果缓存 10 分钟,常见情况下只多花几百毫秒。超过 0.8 秒还没返回的源(例如挂在代理后面的官方源,单次 manifest 就要 1~3 秒)不会拖住这次请求:本次按原策略选源,探测转到后台继续跑,跑完写入缓存,后续十分钟内就能参与比较。版本号标签默认不参与比较。

4. 三种路由方式

解析优先级从高到低:路径首段别名 → 请求 Host → 路由缓存 → 自动判定 → 兜底分组。

方式 示例 适用场景
路径前缀 mirror.example.com/ghcr.io/owner/app:1.0 Docker CLI、CI、临时拉取
域名 ghcr.mirror.example.com/owner/app:1.0 containerd / K8s / 多域名
自动判定 mirror.example.com/owner/app:1.0 单域名且不带前缀

ghcr.io/stefanprodan/podinfo 本身就是合法的 repository 名(允许点号),Docker 不需要额外配置。两个线索都没有时,会并发询问各分组「有没有这个仓库」,结果按 routeTTL(默认 30 分钟)缓存,不存在的仓库走负缓存,后续请求零成本。同名仓库存在于多个源时由 routing.strategy 决胜。响应头 X-Mirror-Gateway-Group 与 X-Mirror-Gateway-Upstream 会标明实际使用的分组和源。

5. 健康检查与故障转移

后台定期探测 /v2/ 与探针镜像的 manifest(验证 token 与拉取链路)。连续失败 failThreshold 次标记不可用,成功一次立即恢复;真实流量中的 5xx / 429 / 超时也计入失败,404 / 401 / 403 不计入。一次拉取中若当前源返回 5xx 或连不上,会立刻尝试下一个源,客户端无感知。

6. pull-through 缓存

默认关闭,需要提速或省回源带宽时再开,后端可选本地磁盘或 S3。blob 用 io.TeeReader 边传边校验 sha256,通过才落盘;客户端中断则丢弃临时文件。manifest 缓存键包含分组名与 Accept 变体,避免不同仓库的同名镜像、多架构清单与单平台清单互相覆盖。tag 有 TTL,digest 永久有效;超过容量上限按最久未访问淘汰到 85%。S3 后端适配 MinIO、OSS、COS、OBS 等兼容服务,blob 校验通过后异步上传,上传慢不影响客户端。

7. 源级代理与安全

每个上游可单独指定 http(s)://、socks5:// 代理或 direct 强制直连,支持认证、密码走环境变量。代理只作用于配置它的那个上游,改不了整个分组的走向——挂了代理的官方源通常比境内加速源慢,只有在 latest 更新或其它源不可用时才会被选中。

安全方面:拉取与管理端口分离(管理端口只绑回环地址),IP 白名单,adminToken;每个源独立选择「配置账号自动认证」或「客户端凭证透传」,默认不透传,公网多域名部署可为官方源开启透传;透传源的拉取不写共享缓存,避免私有内容进入匿名缓存。

8. 监控通知与控制台

分组健康跌破阈值时经模板化 webhook 或邮件告警,恢复自动通知。webhook 协议无关,url 与 body 都是模板,飞书、企业微信或任何自定义协议都能适配;状态变化始终立即通知,持续异常期间按 interval 重发提醒,不刷屏。

四、界面预览

1. 控制台总览

顶部四个指标卡:上游健康、进行中的拉取、累计出站流量、缓存占用;下方五个子标签页分别是拉取监控、镜像搜索、上游镜像源、分组与路由、接入方式。

/images/post/2026112001/dashboard.png

2. 镜像搜索

搜 Docker Hub、Quay 与 MCR,结果带 Star、拉取量、最新版本号与更新时间,任意列可排序,每行还能一键复制拉取命令。

/images/post/2026112001/search.png

3. 资源占用

Go 编译的静态单二进制,无 JVM、无数据库进程;转发大文件走流式零缓冲,内存不随镜像体积增长。这是 docker stats 的实测数据:空载 CPU 0.15%、内存约 19.5 MiB、PIDS 8,小规格 VPS、NAS、树莓派都放得下。

/images/post/2026112001/stats.png

五、下载与安装

1. 直接下载

从 Releases 取对应平台的压缩包,解压即用,提供 Linux(amd64 / arm64 / armv7 / 386)、macOS(Intel / Apple Silicon)、Windows(x64 / ARM64 / x86)。服务端部署推荐 Linux amd64 / arm64;桌面平台产物主要用于本地调试管理命令。

也可以直接用 Docker 镜像 midaug/docker-mirror-gateway,支持 linux/amd64、linux/arm64、linux/arm/v7、linux/386:

1
2
3
4
5
6
7
8
9
docker pull midaug/docker-mirror-gateway:latest

cp config.example.yaml config.yaml   # 先准备配置,再挂载进容器

docker run -d --name docker-mirror-gateway \
  -p 8080:8080 -p 127.0.0.1:8081:8081 \
  -v docker-mirror-gateway:/var/lib/docker-mirror-gateway \
  -v ./config.yaml:/etc/docker-mirror-gateway/config.yaml:ro \
  midaug/docker-mirror-gateway:latest

2. Docker Compose

1
2
3
4
cp config.example.yaml config.yaml   # 从示例配置开始,按需修改 groups 与镜像源
docker compose up -d --build
docker compose logs -f docker-mirror-gateway
curl -s http://127.0.0.1:8081/api/v1/status | jq .groups
  • 镜像拉取:http://127.0.0.1:8080/v2/
  • 控制台:http://127.0.0.1:8081/(compose 默认只映射到宿主机回环地址)

国内构建镜像时可指定 Go 模块代理:

1
docker compose build --build-arg GOPROXY=https://goproxy.cn,direct

3. 本地运行

需要 Go 1.23+:

1
2
3
go run ./cmd/docker-mirror-gateway -config config.yaml
# 或者
make build && ./bin/docker-mirror-gateway -config config.yaml

不带 -config 时依次查找 ./config.yaml、/etc/docker-mirror-gateway/config.yaml,都没有则使用内置默认配置(仅官方 Docker Hub)。

4. 接入 Docker

编辑 /etc/docker/daemon.json,重启 Docker 后 docker pull alpine:latest 自动走 dockerhub 组:

1
2
3
4
{
  "registry-mirrors": ["http://127.0.0.1:8080"],
  "insecure-registries": ["127.0.0.1:8080"]
}

registry-mirrors 只对 Docker Hub 生效;GHCR、Quay 等用路径前缀(Docker CLI)或域名(containerd)。网关只监听 HTTP,需要对外提供 HTTPS 时,TLS 交给反向代理,Caddy 配一个泛域名证书即可,管理后台单独走内网域名并限制来源 IP。

六、技术实现

层 技术
语言 Go 1.23,静态单二进制
直接依赖 gopkg.in/yaml.v3、github.com/minio/minio-go/v7(仅 2 个)
缓存 本地磁盘 / S3 兼容对象存储(minio-go)
配置 YAML,全部字段支持环境变量覆盖
前端 内置控制台,无外部资源
部署 二进制、Docker 镜像、Docker Compose

代码按职责拆在 internal/ 下:registry 处理 registry 协议与拉取转发,server 是 HTTP 层与路由,config 管配置加载,cache 是磁盘 / S3 两套后端,notify 负责 webhook 与邮件,search 做控制台的镜像搜索,activity 记录拉取历史,metrics 输出 Prometheus 指标,access 处理访问控制。

config.example.yaml 里所有字段都带注释,改完重启进程生效;数据目录统一到一个 data.dir,Docker 部署只需挂载这一个目录。健康检查、选源、通知、缓存、访问控制各自独立配置,默认都是保守值——缓存和通知默认关闭,适合先跑起来看一段时间再按需打开。

七、更新日志

1. v0.0.2(2026-11-19)

新增

  • 可选的凭证透传(auth: passthrough),适配公网多域名部署
  • 统一数据目录,拉取监控记录可选落盘,重启不丢

修复

  • 把上游返回的 401、包装成 500 的 404、仓库白名单 403 归类为仓库级策略,不再误判为源故障
  • 健康源都没有对应 manifest 时优先报 404,502 响应补上缺失仓库的上下文
  • 发布前评审与控制台体验改进

2. v0.0.1

首个可用版本:多仓库聚合、按速度选源、健康检查与故障转移、三种路由、镜像搜索控制台。

八、小结

做这个工具的起因很直接:境内拉镜像这件事,每个环节都有坑,而现成的镜像站又都是单点。与其维护一串随时会失效的加速地址,不如把它们交给一个网关来管——健康检查、按速度选源、新旧优先、故障转移都自动化,客户端只需要记住一个地址。

项目还在早期,config.example.yaml 里的公共镜像源仅作示例,生产环境请替换为你有权使用、且服务条款允许的源,并遵守对应仓库的速率与使用政策。有问题或者想要的功能,欢迎到 GitHub 上提 issue。