Docker Mirror Gateway:一个地址搞定所有容器镜像加速
一、前言
拉镜像这件事,难点从来不是「拉」,而是「从哪拉」。加速源今天能用明天 403,GHCR、Quay、K8s 每类仓库还得单独找地址单独配。这个工具就是来收拾这些事的。
在境内拉容器镜像,几乎每个环节都有坑:官方源直连超时;公共加速源随时失效;好不容易配了个快的源,又因为同步滞后拉到了旧版 latest;CI 反复拉同一批镜像,回源带宽白白浪费。
把 registry-mirrors 指向某一个加速地址,只能解决其中一部分问题——而且那个地址一旦挂了,所有机器一起挂。
我把自己这套流程做成了一个自托管的镜像加速网关:Docker Mirror Gateway。它把多个镜像源聚合成一个地址,按健康度和实测速度自动选源,可选本地缓存,一个实例同时服务 Docker Hub、GHCR、Quay、MCR、K8s、GCR、Elastic、NVCR。
- 项目地址:https://github.com/midaug/docker-mirror-gateway
- 开源协议:MIT
- 当前版本:v0.0.2(2026-11-19)
二、解决什么问题
一句话概括:它不是又一个加速地址,而是把「选哪个地址」这件事自动化了。
加速源会挂,那就别只用一个。 一个分组下可以挂多个互为镜像的加速地址,健康检查连续失败自动降级,拉取时逐源重试,切换对客户端无感。
每类仓库都要单独配,那就合成一个入口。 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,排序规则按优先级依次是:
- 健康的上游永远排在失效源之前,失效源只作最后兜底;
- 吞吐高者优先;
- 吞吐相差在
speedTolerance(默认 25%)以内视为持平,此时比较延迟; - 仍持平则比
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. 控制台总览
顶部四个指标卡:上游健康、进行中的拉取、累计出站流量、缓存占用;下方五个子标签页分别是拉取监控、镜像搜索、上游镜像源、分组与路由、接入方式。

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

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

五、下载与安装
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:
|
|
2. Docker Compose
|
|
- 镜像拉取:
http://127.0.0.1:8080/v2/ - 控制台:http://127.0.0.1:8081/(compose 默认只映射到宿主机回环地址)
国内构建镜像时可指定 Go 模块代理:
|
|
3. 本地运行
需要 Go 1.23+:
|
|
不带 -config 时依次查找 ./config.yaml、/etc/docker-mirror-gateway/config.yaml,都没有则使用内置默认配置(仅官方 Docker Hub)。
4. 接入 Docker
编辑 /etc/docker/daemon.json,重启 Docker 后 docker pull alpine:latest 自动走 dockerhub 组:
|
|
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。