10分钟搞定容器镜像加速难题：public-image-mirror新手实战指南

10分钟搞定容器镜像加速难题：public-image-mirror新手实战指南

【免费下载链接】public-image-mirror很多镜像都在国外。比如 gcr 。国内下载很慢，需要加速。致力于提供连接全世界的稳定可靠安全的容器镜像服务。项目地址: https://gitcode.com/GitHub_Trending/pu/public-image-mirror

晚上十一点，同事都下班了，你还在盯着终端里docker pull的进度条。镜像来自 gcr.io，卡在 0% 已经二十分钟。别急着怀疑网络，问题多半出在"容器镜像加速"这件事上——而 public-image-mirror 这个开源项目，正是专门用来解决这类痛点的容器镜像加速工具。

那个永远拉不动的镜像，问题到底出在哪？

先还原一个真实场景：你按官方文档执行

docker pull gcr.io/google-samples/hello-app:1.0

结果等了十分钟，进度条几乎没动，最后直接报deadline exceeded。你换了镜像源、清了 DNS 缓存、甚至怀疑是公司防火墙，但问题依然存在。

真正的原因其实很简单：gcr.io、ghcr.io、quay.io 这些镜像仓库的服务器基本都部署在海外，而 Docker 拉镜像时要在公网走完整的 HTTPS 链路。跨洋链路延迟高、带宽小，再加上国内访问海外节点经常绕路，慢就成了必然。

这也是为什么很多人一到 Kubernetes 环境就头疼——registry.k8s.io上的组件镜像一个比一个大，集群还没建起来，先被拉镜像耗掉了半天。

一句话讲透原理：镜像加速就像"快递中转站"

public-image-mirror 的思路非常朴素：它在国内搭了一整套镜像仓库，把海外源仓库的内容"映射"到自己的域名下。你不需要代理、不需要改代码，只要把镜像地址加一个前缀，请求就会先发往国内节点，由它替你完成跨境下载。

你可以把它理解成一个快递中转站：海外仓库是发货方，你的服务器是收货方，中转站提前把货备在离你最近的仓库里，你取件自然就快了。

更重要的是，这个中转站是"懒加载"的——你第一次拉某个镜像时它才去同步，所有哈希值（sha256）与源仓库完全一致，不会出现"加速后镜像被篡改"的隐患，安全性和源站是对等的。

三步验证：一条命令搞定镜像加速

上手成本低到超出你的想象，不需要注册账号，不需要任何配置。在终端里执行：

docker run -d -P m.daocloud.io/docker.io/library/nginx

对比一下，原始地址是docker.io/library/nginx，加速后的地址只是在最前面加了m.daocloud.io/前缀，仅此而已。

如果你发现这条命令能顺利拉取，说明这套镜像加速方案在你的网络环境下是通的，接下来就可以按需升级玩法了。

镜像加速的三种配置路径：从零配置到一劳永逸

路径一：加前缀（推荐）

把m.daocloud.io/加在原始镜像地址最前面，任何仓库、任何 tag 都适用，简单且不会出错：

docker pull m.daocloud.io/docker.io/library/busybox docker pull m.daocloud.io/gcr.io/google-samples/hello-app:1.0

路径二：前缀替换（地址更简短）

对于常用仓库，项目还提供了"前缀替换"的简化地址，把仓库域名整体替换成对应的加速域名即可。例如docker.io/library/busybox可以写成docker.m.daocloud.io/library/busybox。

支持替换的源站如下（节选）：

需要留意的是，这些替换规则是人工维护的，官方更推荐路径一的"加前缀"方式，因为它对所有镜像一律适用，不用记表。

路径三：全局配置，一劳永逸

如果你不想每次手改镜像地址，可以给 Docker 配置全局镜像加速。编辑/etc/docker/daemon.json：

{ "registry-mirrors": ["https://docker.m.daocloud.io"] }

重启 Docker 后，未指定完整地址的镜像会自动走加速通道。这里有个关键提醒：registry-mirrors 只对 docker.io 的镜像生效，gcr.io、ghcr.io 等其他源站不要配到这一项里，它们需要单独处理。

Kubernetes 环境下的镜像加速实操

如果你在部署 kubeadm、kind 这类集群工具，可以直接把镜像仓库替换为加速地址：

apiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration imageRepository: k8s.m.daocloud.io

kind create cluster --name kind --image m.daocloud.io/docker.io/kindest/node:v1.22.1

对于已经跑起来的集群，最省心的方式是部署一个 Webhook 工具（repimage），它会在新 Pod 创建时自动改写 image 字段，不需要改任何 yaml 和 helm chart：

kubectl create -f https://files.m.daocloud.io/github.com/wzshiming/repimage/releases/download/latest/repimage.yaml kubectl rollout status deployment/repimage -n kube-system

如果你的集群使用 containerd，也可以参考官方文档为它配置 registry mirror，效果与 Docker 的全局配置类似。

进阶玩法：企业级内网镜像缓存部署指南

如果团队规模大、镜像拉取频繁，每次都走公网中转也不是最优解。此时建议在企业内网部署一个本地缓存仓库，把m.daocloud.io再代理一层。完整步骤可以看 docs/local-cache/README.md，核心就是一个 Docker Compose 配置：

services: registry: image: m.daocloud.io/docker.io/library/registry:3 restart: unless-stopped ports: - 8888:8888 command: - /etc/docker/registry/config.yml volumes: - cache-data:/var/lib/registry configs: - source: registry-config target: /etc/docker/registry/config.yml configs: registry-config: content: | version: 0.1 storage: filesystem: rootdirectory: /var/lib/registry http: addr: :8888 proxy: remoteurl: https://m.daocloud.io ttl: 2160h volumes: cache-data: {}

启动用一条命令：docker compose up -d。之后团队拉镜像只需把内网地址加在原始镜像前：

docker pull <内网IP>:8888/docker.io/library/nginx:latest

第一次拉取时会回源同步，之后所有请求都命中本地缓存，对内网环境的加速效果立竿见影，还能大幅减少出口带宽消耗。

镜像加速常见问题排查与避坑清单

拉取还是很慢？

高峰期（尤其白天）中转站很拥挤。建议把批量拉取任务放在凌晨 01:00-07:00（北京时间），其他时段可能排队。

用 latest 标签总是出问题？

latest 是可变标签，每次变更后台都要重新同步。优先使用@sha256:指定镜像，其次用明确的版本号，最后才考虑 latest。

刚推的新 tag 拉不到？

服务的 Manifest 有 1 小时内存缓存，新 tag 更新后需要等缓存过期才会同步，属于正常现象，不用急着报障。

突然报 404？

缓存的内容只保留 30 天，过期后会触发重新同步；个别场景下 Blob 缓存到期被删除会短暂报 404，重试一次通常就能恢复。

不想让所有环境都走公网？

参考上文的内网缓存方案，把中转站"搬"进公司网络，既快又稳，也便于统一管理。

最后：花 10 分钟，把慢的问题交给工具

镜像拉取慢是每个国内开发者都绕不开的坎，但解决它并不需要复杂的网络知识。public-image-mirror 把最难的跨境同步问题封装在了后端，你只需要记住一条规则：原始镜像地址前面加上m.daocloud.io/。

现在就可以动手：先跑通前面那条 nginx 命令，再根据你的使用场景（Docker、Kubernetes 或内网缓存）选择对应的配置路径。遇到问题去项目仓库提 Issue 反馈；如果你想参与贡献，git clone https://gitcode.com/GitHub_Trending/pu/public-image-mirror之后，提交 Pull Request 完善支持列表也是很好的方式。

镜像加速这件事，10 分钟上手，长期受益。你的下一次docker pull，不应该再卡在 0% 了。

【免费下载链接】public-image-mirror很多镜像都在国外。比如 gcr 。国内下载很慢，需要加速。致力于提供连接全世界的稳定可靠安全的容器镜像服务。项目地址: https://gitcode.com/GitHub_Trending/pu/public-image-mirror