企业官网建设流程全解析

public-image-mirror 镜像加速实战：3 步配置，把卡死的 docker pull 提速 10 倍

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

周五晚上 10 点，发布群又弹出一行红字：Failed to pull image "gcr.io/google-samples/hello-app:1.0": context deadline exceeded。这已经是今晚第三次了。Pod 卡在 ImagePullBackOff，节点和 gcr.io 之间那条漫长的国际链路，把一次本该 1 分钟的拉取拖成了半小时起步，上线窗口眼看着就要错过。你需要的不是更好的网络，而是一个"在国内就能取到货"的镜像仓库。public-image-mirror 就是干这个的：它把 gcr.io、quay.io、registry.k8s.io 这些海外仓库的镜像同步到国内节点，你只需改一下镜像地址，拉取速度就能从几 KB/s 提升到 MB/s 级别，适合所有受困于国外镜像下载慢的 Docker 和 Kubernetes 用户。下面这篇实战指南会带你从一条命令开始，把加速配置一步步接到 Docker、kubeadm 和你的内网环境里。

先花 1 分钟搞懂它到底是什么

本节解决什么问题：在动手之前，先让你明白它为什么快，这样后面排错时心里有底。

把 public-image-mirror 想象成一个国内高速中转仓。海外仓库是原厂，你直连取货要跨越整条国际链路，慢而且容易断；中转仓把货提前备在国内，你只需要到仓自提。它和普通缓存的区别在于三个关键机制：

• 懒加载：镜像不是提前全量搬过来，而是你第一次拉取时才从上游同步，所有 sha256 与源仓库完全一致。
• 缓存有时效：内容只保留 30 天，过期后要重新同步；Manifest 内存缓存 1 小时，意味着 tag 更新后最多 1 小时才会同步到加速站。
• 白名单准入：项目通过 allows.txt 白名单管理可同步的镜像，拉不到的镜像先查它。

这套设计让加速站"按需取货"，你拿到手的东西和原厂一模一样，而不是二次打包的假货。

量化对比：以拉取 gcr.io/google-samples/hello-app:1.0 为例：

差距不是几倍，而是数量级的。

动手前的环境检查清单

开始之前先花 30 秒确认三件事：

• ✅ Docker 版本在 20.10 以上，老版本对 registry 兼容性略差。
• ✅ 本机能正常访问 m.daocloud.io 域名，ping m.daocloud.io通即可。
• ✅ 准备一个明确版本号的镜像做测试，别拿 latest 当小白鼠。

为什么强调版本号：latest 是可变 tag，加速站对它有一小时的同步延迟，用来验证容易得出"内容不对"的错误结论，后面我们会专门讲这个坑。

第一步：一条命令验证加速通道

本节解决什么问题：只花 1 分钟，确认这条加速通道在你的网络环境里真的通。

docker pull m.daocloud.io/docker.io/library/nginx:1.27

再对比一次直连拉取，感受一下差距：

docker pull docker.io/library/nginx:1.27

为什么先做这一步：加前缀（m.daocloud.io/+ 完整原始地址）是这套方案里最通用的写法，适用于 gcr.io、quay.io、registry.k8s.io 等所有被支持的仓库。先验证它，你就确认了"这条路本身通不通"，之后再折腾各种配置才有意义。

地址有两种写法，别混用：

常见的前缀替换对照（完整列表见项目 README）：

验证是否生效，除了看下载速度，更严格的做法是对比镜像摘要：

docker image inspect m.daocloud.io/docker.io/library/nginx:1.27 --format '{{.RepoDigests}}'

拿到的 digest 和官方源一致，说明你拉到的就是原厂正品。

进阶：把加速从"手改地址"升级成"自动生效"

本节解决什么问题：让 Docker、kubeadm 和整个内网自动走加速通道，不用再逐个改镜像地址。

场景一：单机 Docker

编辑/etc/docker/daemon.json，之后所有docker pull都自动转发：

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

然后重启：sudo systemctl restart docker。

这里有个高频误区 ⚠️：registry-mirrors 只对 docker.io 官方源生效，不要把 gcr.m.daocloud.io 这类站点填进去——每个加速域名只服务自己的源站，填错了不生效，pull 还是会走海外。

场景二：Kubernetes 集群

安装 kubeadm 时直接指定国内镜像仓库，一条配置就够：

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

用 kind 建测试集群同理，指定镜像即可：

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

已经在运行的集群，可以用 repimage 这类 Webhook 工具，自动改写所有新建 Pod 的镜像地址，不用改任何 yaml 和 helm 包。

场景三：企业内网缓存

如果团队人多、机器多，建议在内网部署一个 registry 代理（文档见项目内 docs/local-cache/ 目录）。它把 m.daocloud.io 当作上游，内网机器再把它当镜像源。这样只有一台机器出外网流量，其余机器全部走内网拉取，几百台节点也能做到秒级拉取。

疑难杂症：配置没问题，为什么还是慢

本节解决什么问题：遇到"拉取慢、内容不对、报 404"三连，逐个对症下药。

症状一：高峰期拉取依旧慢

加速站也有高峰。服务在凌晨 01-07 点（北京时间）最空闲，其他时间段经常非常拥挤。把 CI 批量拉取、镜像预热这类任务挪到闲时，是成本最低也最有效的优化。

症状二：latest 标签拉下来的内容和官方对不上

原因就是前面说的：Manifest 有一小时内存缓存，tag 更新后要等约一小时才同步。官方推荐的 tag 优先级是：@sha256:精确摘要 > 明确版本号 > latest。这也是环境检查里让你别用 latest 的原因。

症状三：报 404 或者首次拉取特别慢

缓存内容只保留 30 天，长时间没人拉取的镜像过期后需要重新同步；而首次同步本身就是"实时去上游取货"，比命中缓存时慢是正常的。排查时可以到官方同步队列状态页看一眼该镜像是否正在同步，同时确认它是否在 allows.txt 白名单内——白名单外的镜像，加速站不会同步。

一个通用的排错顺序：凡是改完配置没生效的，先确认重启了对应服务（docker 改了 daemon.json 要 restart）；再对比 digest 确认拿到的是正品；最后才考虑是不是白名单或同步延迟的问题。

现在动手：3 步行动清单

1. 跑通一条命令：docker pull m.daocloud.io/docker.io/library/nginx:1.27，确认通道可用。
2. 按场景接入：单机改 daemon.json，集群改 kubeadm 配置，企业级部署内网缓存。
3. 记住两个时间参数：Manifest 同步延迟 1 小时、缓存保留 30 天，排错时先对表。

完整白名单、前缀替换表和本地缓存文档都在仓库里，需要源码时执行git clone https://gitcode.com/GitHub_Trending/pu/public-image-mirror，重点看 allows.txt 和 docs/local-cache/ 目录；项目自带的 hack/ 校验脚本可以帮你验证镜像地址规则是否匹配。🚀

镜像拉取慢这件事，大多数时候不是玄学，只是缺一条国内通道。public-image-mirror 用最朴素的命名映射解决了它——不修改代码、不改镜像内容，只改地址。下次再看到 ImagePullBackOff，你已经知道答案了。

关键词：public-image-mirror 镜像加速、docker pull 国内加速、gcr.io 镜像加速、kubeadm 安装镜像加速、Kubernetes 镜像拉取慢、Docker registry-mirrors 配置

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