3分钟解决Docker镜像拉取超时：DaoCloud镜像加速完整指南

3分钟解决Docker镜像拉取超时：DaoCloud镜像加速完整指南

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

public-image-mirror（DaoCloud 公开镜像仓库）解决的是一个很具体的问题：gcr.io、ghcr.io、quay.io 这类部署在海外的镜像仓库，国内直接拉取经常超时或极慢。它的思路很朴素——在镜像地址前加一个前缀，让镜像从国内节点同步缓存后给你下载，你不需要任何账号和付费配置。

为什么国外镜像会拉取超时

先说清它的同步机制，后面几个"坑"都跟这个有关：

• 懒加载：不是把所有镜像提前搬回国内，而是你第一次拉取时才从源仓库同步一份到国内节点；
• 哈希一致：缓存镜像的 sha256 与源仓库保持一致，不会被篡改或"换内容"；
• 缓存 30 天过期：长期不拉取的镜像过期后需要重新同步，所以第一次拉取会明显比第二次慢。

理解了"首次慢、二次快"，你就知道很多超时其实只是冷同步，而不是服务挂了。

选加速方式：加前缀 vs 前缀替换

两种方式都能用，区别在于覆盖范围和适用场景：

常用源站的前缀替换映射（节选自项目 README）：

⚠️ 注意：不要把 docker.io 之外的站点配进 Docker 的registry-mirrors，每个源站内容不同，混配会导致找不到镜像。

3分钟拉取第一张加速镜像

加前缀的用法：把原来的镜像地址原样保留，前面拼上m.daocloud.io/。下面两条命令等价，第二条走国内节点：

# 原地址（国内直连，可能超时） docker pull docker.io/library/nginx:latest # 加速地址（加 m.daocloud.io/ 前缀，其余不变） docker pull m.daocloud.io/docker.io/library/nginx:latest

拉下来之后直接docker run -d -P启动即可，镜像本身和官方完全一致。如果是 K8s 的 YAML，把image:字段按同样方式改前缀就行，其他什么都不用动。

给 Docker 客户端配置全局加速

如果你希望所有docker.io镜像自动走加速节点，而不用改每一条 pull 命令，改一下 daemon 配置即可。编辑/etc/docker/daemon.json，加入registry-mirrors（只放 docker.io 的加速地址），然后重启 Docker 服务生效：

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

sudo systemctl restart docker # 重启使配置生效

这个全局配置只对 docker.io 生效。ghcr.io、gcr.io 等其他源站请继续用加前缀的方式，或参考 Podman 的 registries.conf 写法（Podman 支持为每个源站单独配 mirror，比 Docker 灵活）。

K8s 集群的镜像仓库加速

集群场景常见的三个位置，改法如下：

1. kubeadm 初始化：把集群组件的镜像仓库指到加速节点。在 kubeadm 配置里改两个字段：

apiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration dns: imageRepository: k8s.m.daocloud.io/coredns # CoreDNS 组件镜像 imageRepository: k8s.m.daocloud.io # 其余集群组件镜像

2. kind 本地集群：创建时直接指定 node 镜像的加速地址：

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

3. 存量集群所有 Pod：不想逐个改 YAML 的话，可以部署 repimage 这类 Webhook 组件，自动改写新建 Pod 的 image 地址，业务侧零改动。

另外，企业内网如果对"完全不走外网"有要求，官方提供了本地缓存方案：在内网起一个 Registry 作为m.daocloud.io的二级缓存，细节见 docs/local-cache/README.md。

两个机制：白名单与缓存时效

拉取失败前，先确认这两点：

1. 镜像是否在白名单内

同步范围由仓库根目录的 allows.txt 控制，目前收录 1300 余条仓库规则，docker.io约 1000 条、ghcr.io约 200 条，gcr.io、registry.k8s.io等则是整站放行。想确认某个镜像是否支持，clone 下来查一下最快：

# 把仓库拉到本地，然后 grep 白名单（支持 * 通配规则） git clone https://gitcode.com/GitHub_Trending/pu/public-image-mirror grep "docker.io/nginx" public-image-mirror/allows.txt

不在名单里的镜像会被拒绝同步，需要等维护者添加（项目设计上加仓库不需要改代码）。

2. 缓存时效与 tag 选择

所以 tag 选择的优先级是：@sha256:固定摘要 > 明确版本号 >latest。latest这类可变 tag 变更后后台会重新同步，期间拉到的可能是旧数据，生产环境建议锁死版本。

常见问题排查

• 拉取报 not found / 404：先核对镜像名、仓库、tag 是否拼对；再确认在 allows.txt 白名单内；最后确认不是上面的缓存过期窗口。
• 拉取超时：区分"冷同步慢"和"真失败"——同一镜像第二次拉取如果秒回，说明只是首次同步耗时，把大批量任务挪到闲时执行即可。
• 白名单规则看不懂：仓库 hack/ 目录下有维护者用的校验脚本，如verify-allows.sh可检查某个镜像是否命中白名单规则，排障时可参考其匹配逻辑。

下一步建议

先用加前缀的方式把手头最慢的那几个镜像跑通，确认"首次慢、二次快"符合预期后，再按需配置 Docker 全局 mirror 和 K8s 的 imageRepository。生产环境记得把latest换成固定版本号或 sha256 摘要；有内网部署需求的可以接着看 本地缓存文档。

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