镜像拉取慢怎么办给 Docker 和 Kubernetes 配一个能用的国内镜像源【免费下载链接】public-image-mirror很多镜像都在国外。比如 gcr 。国内下载很慢需要加速。致力于提供连接全世界的稳定可靠安全的容器镜像服务。项目地址: https://gitcode.com/GitHub_Trending/pu/public-image-mirror镜像拉取慢怎么办这几乎是每个国内开发者的日常。public-image-mirror 项目就是一个面向国内用户的国内镜像源它把 gcr.io、quay.io、docker.io 等国外仓库统一映射到国内可访问的地址用最简单的镜像加速方式解决镜像同步与拉取难题。这篇教程把原理、选型和配置一次讲透。先讲一个你多半经历过的下午周五下午你照着教程部署一套开源监控系统命令敲下去docker pull quay.io/prometheus/alertmanager:latest然后终端沉默了。进度条每几十秒跳一格你从应该快好了等到要不重试一下。按 CtrlC 再来一次还是老样子。换网络、开代理、问同事折腾一个多小时最后发现问题根本不在网速而在镜像仓库本身——源站远在海外链路绕、带宽小慢是常态超时也是常态。这类问题集中在 gcr.io、quay.io、ghcr.io、registry.k8s.io 这些仓库。它们承载着大量 Kubernetes 生态组件却又恰恰是国内访问最慢的一批。你需要的不是更好的网络而是一个离你更近的货源。镜像加速的底层逻辑一个快递中转站先搞清楚一个概念docker pull 拉下来的镜像不是单个文件而是一组分层数据blob加一份索引manifest。这个细节后面避坑会用到先记住分层和索引两个词。把海外源站想象成原厂仓库国内加速站就是一个快递中转站你下单docker pull中转站先看自己有没有现货有现货直接从国内节点发货速度自然快没现货中转站替你去海外原厂进货进完再发给你。整个过程你拿到的包裹和原厂完全一致——镜像的所有哈希值sha256与源站严格相同中转站不改动任何内容只是替你多跑了一趟路。public-image-mirror 正是这个机制它只是源仓库的 Mirror采用懒加载模式你第一次拉某个镜像时触发回源同步之后同一镜像再次被拉取就直接命中缓存。示意图如下一句话总结原理你在国内下单中转站在国内发货货源从海外补齐。三条路线横向对比先选型再动手动手之前先看看市面上解决镜像拉取慢的主流路线想清楚自己属于哪种场景再抄配置。路线你要做的事拉取速度维护成本适合谁自建私有仓库Harbor 等搭服务、配代理、管证书、续磁盘内网环境下最快高需长期维护企业、镜像吞吐量大的团队第三方公共加速站改一行配置可能随时失效看运气高峰期排队低但不可控临时应急public-image-mirror加前缀或改一行配置稳定覆盖仓库广极低个人开发者到企业均适用三个选项的本质区别自建私有仓库等于在自家机房开一个备货仓库内网访问最快但进货回源、库存存储、盘库清理都要自己负责第三方公共加速站是别人家的中转站零维护但货源和带宽都不受你控制public-image-mirror介于两者之间中转站是公共的、有人维护的你只需把拉取地址指向它。企业还可以把它作为自建缓存的上游两边叠加。结论先行个人和中小团队直接用本项目即可企业用户建议在公网加速之上再叠一层内网缓存第五步会给到完整方案。递进式实操从第一条命令到生产可用第一步确认环境先确认 Docker 装好且能正常调用docker version作用检查 Docker 客户端与守护进程版本。预期输出显示 Client 和 Server 两段版本信息Server 段正常输出即代表守护进程在运行。再确认你要拉的镜像在项目支持范围内。根目录的 allows.txt 是白名单按仓库/命名空间列出了所有支持同步的镜像grep -i gcr.io allows.txt作用在白名单里查找 gcr.io 相关条目。预期输出列出 gcr.io 开头的白名单规则。没搜到也没关系去 Issue 区提一个申请即可。第二步最小可用示例——加前缀public-image-mirror 最推荐的用法是增加前缀在原始镜像地址最前面加上m.daocloud.io/。拿一个 gcr 镜像举例原地址是gcr.io/google-samples/hello-app:1.0改成docker pull m.daocloud.io/gcr.io/google-samples/hello-app:1.0作用从国内加速站拉取原本托管在 gcr.io 的镜像。预期输出显示Pulling from m.daocloud.io/gcr.io/google-samples/hello-app正常情况下几十秒内完成而不是干等。再试一个更常见的 docker.io 镜像两种写法都行。加前缀docker pull m.daocloud.io/docker.io/library/nginx:latest或使用前缀替换docker.io 对应 docker.m.daocloud.iodocker pull docker.m.daocloud.io/library/nginx:latest作用两种写法都指向同一个国内加速地址。预期输出秒级完成拉取命中缓存的层直接显示 Pull complete。部分主流仓库还支持前缀替换映射规则维护在 README 的表格里比如 gcr.io 对应 gcr.m.daocloud.io、quay.io 对应 quay.m.daocloud.io、registry.k8s.io 对应 k8s.m.daocloud.io。规律就一条任何镜像地址前面加m.daocloud.io/就是加速后的地址。临时拉镜像套个前缀即可不用改任何全局配置。第三步给 Docker 永久换源每次手写前缀太累可以让 Docker 全局走加速。编辑/etc/docker/daemon.json修改前后对比// 修改前 { registry-mirrors: [] }// 修改后 { registry-mirrors: [https://docker.m.daocloud.io] }作用把 docker.io 的拉取请求统一转发到加速站。说明这里用的是 docker.io 的前缀替换地址只对 docker.io 生效。gcr、quay 等其他仓库配这个不生效要靠加前缀或下面的 containerd 方案。改完重启 Dockersystemctl restart docker作用让新配置生效。预期输出重启无报错。再用docker info确认Registry Mirrors 一栏应出现加速站地址。第四步为 Kubernetes 配置国内镜像源K8s 集群的运行时大概率是 containerd配置方式和 Docker 不同。在/etc/containerd/certs.d/docker.io/hosts.toml里写入server https://docker.io [host.https://docker.m.daocloud.io] capabilities [pull, resolve]作用让 containerd 拉取 docker.io 镜像时优先走加速站。说明capabilities 里的 pull 和 resolve 必须保留用不到 push 就省略。重启 containerd 后ctr images pull docker.io/library/nginx:1.27这类命令会自动命中加速站。用 kubeadm 装集群的话还可以把系统组件镜像源一并换掉apiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration imageRepository: k8s.m.daocloud.io dns: imageRepository: k8s.m.daocloud.io/coredns作用让 kubeadm 从国内镜像源拉取 kube-apiserver、coredns 等系统组件避开 registry.k8s.io 的慢链路。用 kind 做本地开发也有现成参数kind create cluster --name dev --image m.daocloud.io/docker.io/kindest/node:v1.22.1作用创建集群时直接从加速站拉取节点镜像。预期输出控制台显示节点镜像拉取进度比直连原站快得多。第五步企业场景自建镜像缓存代理团队里多台机器反复拉同一个镜像时可以在内网架一个缓存代理。项目 docs/local-cache/ 目录下有完整的 Docker Compose 配置核心就两段镜像本身从加速站拉容器通过 proxy 回源到 m.daocloud.io相当于在内网复制了一个备货仓库services: registry: image: m.daocloud.io/docker.io/library/registry:3 restart: unless-stopped ports: - 8888:8888 volumes: - cache-data:/var/lib/registry configs: - source: registry-config target: /etc/docker/registry/config.yml configs: registry-config: content: | storage: filesystem: rootdirectory: /var/lib/registry http: addr: :8888 proxy: remoteurl: https://m.daocloud.io ttl: 2160h volumes: cache-data: {}作用启动一个带代理能力的本地 Registry回源指向 m.daocloud.iottl 设为 90 天缓存有效期。说明这是精简版配置完整版含 storage.delete 等项以仓库 docs/local-cache/README.md 为准。启动服务docker compose up -d作用后台启动缓存代理。预期输出容器状态为 Up8888 端口开始监听。之后内网机器拉镜像在原始地址前加你的IP:8888/前缀即可docker pull 192.168.1.10:8888/docker.io/library/nginx:latest作用从内网缓存拉取命中后不消耗外网流量。说明第一台机器首次拉取会触发回源后续机器全部命中内网缓存速度接近瞬时。进阶技巧五个少有人提的细节固定 tag 优于 latestsha256 优先。latest 是可变标签镜像一变缓存就要重新同步。能用nginx:1.27就别用nginx:latest追求可复现直接nginxsha256:xxx。固定地址的缓存命中率更高拉取更快。批量拉取排到凌晨。加速站是公开服务白天高峰排队严重。项目文档明确建议把拉取任务放在北京时间凌晨 01 点到 07 点这个窗口内同步几乎不排队。缓存寿命只有 30 天。加速站缓存过期即清空再次拉取需重新回源。偶尔才用的镜像首次拉取会慢一些属正常现象。别把 gcr 配进 Docker 的 registry-mirrors。Docker 的 registry-mirrors 只对 docker.io 生效。gcr、quay 的加速要走加前缀或用 containerd / Podman 的 per-registry mirror。第一次拉取慢不等于失败。懒加载机制下冷门镜像首次拉取要触发后台回源多等一两分钟正常第二次就快很多。想提前焐热缓存闲时手动 pull 一遍常用镜像即可。避坑手册症状、原因、对策症状原因对策报 404提示 manifest unknown 或 blob unknown缓存过期blob 保留 30 天或 tag 刚更新换固定 tag 重试稍等再拉确认镜像在白名单内latest 标签内容是旧的加速站对 manifest 有约 1 小时缓存改用明确版本号紧急时换 sha256 地址高峰时段拉取特别慢公共加速站排队拥挤拉取任务挪到凌晨 01–07 点或自建内网缓存提示镜像不在支持范围项目是白名单制冷门镜像需申请去 Issue 区提交镜像申请附完整地址Docker 换了源gcr 还是慢registry-mirrors 只作用于 docker.iogcr/quay 用m.daocloud.io/前缀或配置 containerd 的 per-registry mirror对照表格查一遍大多数加速没生效的疑问都能自己解决。⚠️最后说几句镜像拉取慢的本质是物理距离问题不是玄学。public-image-mirror 做的事很朴素把国外镜像仓库原样搬一份到国内可访问的地址你只管改拉取地址。个人用套前缀就够团队用叠一层内网缓存K8s 用containerd 配 per-registry mirror。三档方案按需选择每一档都能落地。✅需要更多资料时这些入口都在项目里项目仓库需要完整文档或参与贡献执行git clone https://gitcode.com/GitHub_Trending/pu/public-image-mirror即可拿到全部内容白名单与限流说明根目录 allows.txt 列出了所有支持同步的镜像范围内网缓存部署docs/local-cache/ 目录下有完整的 Docker Compose 配置同步状态与服务监控README 中给出了同步队列状态页和服务状态监控页的入口社区求助白名单外的镜像需求或配置疑问去 Issue 区提问即可。如果这篇文章帮到了你不妨把配置命令分享给身边同样被镜像问题折磨的同事。关键词清单核心关键词镜像加速、国内镜像源、镜像同步长尾关键词镜像拉取慢怎么办、Kubernetes 配置国内镜像源、自建镜像缓存代理、Docker 换源教程【免费下载链接】public-image-mirror很多镜像都在国外。比如 gcr 。国内下载很慢需要加速。致力于提供连接全世界的稳定可靠安全的容器镜像服务。项目地址: https://gitcode.com/GitHub_Trending/pu/public-image-mirror创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
