企业官网建设流程全解析

如何修复 ImagePullBackOff：DaoCloud public-image-mirror 镜像加速实践

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

DaoCloud public-image-mirror 是一个容器镜像加速方案：它把白名单内的海外公共镜像同步到国内节点 m.daocloud.io，解决镜像拉取超时和 ImagePullBackOff 问题。适用于在国内服务器上部署 docker.io、gcr.io、ghcr.io 等海外镜像（例如 dify-plugin-daemon、k8s 组件、ollama）的工程师。

先说结论：只改镜像地址的前缀

整个方案的机制很朴素：这是一个纯 Mirror 服务，所有镜像的 sha256 与源仓库保持一致（懒加载同步），你只需要把原镜像地址前面加上m.daocloud.io/前缀，其余命令、yaml、部署流程一律不动。以 dify-plugin-daemon 为例：

• docker.io/langgenius/dify-plugin-daemon:latest→m.daocloud.io/docker.io/langgenius/dify-plugin-daemon:latest

替换后拉取耗时从直接访问源站的 30 分钟以上、成功率不足 60%，降到 1–3 分钟、成功率 99% 以上。有团队在反复部署 dify 插件服务的场景中，仅替换镜像地址这一项改动，就把单次部署时间从半小时压到 3 分钟以内。

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

gcr、docker.io 等公共镜像仓库托管在海外，国内直连受延迟和带宽影响，慢和失败是常态。public-image-mirror 针对这个问题做了三件设计上的事：

• 简洁的名称映射：统一前缀规则，不需要改业务侧的任何配置；
• 白名单驱动：新增镜像只改 allows.txt 数据文件，不改代码，当前白名单约 1300 行，覆盖 docker.io 全量（docker.io/*）及其他多个源站；
• 稳定同步：后端每天检查同步情况，缓存内容保留 30 天，过期后重新同步。

最小上手路径：验证白名单，然后替换地址

确认镜像是否在同步白名单

先确认目标镜像路径在 allows.txt 内。该文件支持通配符（*匹配单层、**匹配多层），可以直接检索：

grep "langgenius" allows.txt # docker.io/langgenius/*

如果想用脚本精确判断，仓库提供了 hack/verify-allows.sh（注意传参不带 tag）：

bash hack/verify-allows.sh allows.txt docker.io/langgenius/dify-plugin-daemon echo $? # 输出 0 表示允许同步，1 表示不在白名单

脚本需要在本地拿到仓库文件，可以先把仓库克隆下来：

git clone https://gitcode.com/GitHub_Trending/pu/public-image-mirror

把原地址替换成 m.daocloud.io 前缀

确认允许后，替换前缀直接拉取或运行：

docker run -d --name dify-plugin-daemon \ m.daocloud.io/docker.io/langgenius/dify-plugin-daemon:latest

容器状态为 Running 即完成。如果你手上只有一个简写（比如langgenius/dify-plugin-daemon），可以用 hack/correct-image.sh 自动补全为完整引用（补上docker.io/和:latest）：

bash hack/correct-image.sh "langgenius/dify-plugin-daemon" # docker.io/langgenius/dify-plugin-daemon:latest

备选：整域替换的 registry 前缀

除了加前缀，部分源站还支持"前缀替换"（人工配置，覆盖面较小，官方更推荐加前缀方式）。常见映射：

• docker.io→docker.m.daocloud.io
• gcr.io→gcr.m.daocloud.io
• ghcr.io→ghcr.m.daocloud.io
• registry.k8s.io→k8s.m.daocloud.io
• quay.io→quay.m.daocloud.io
• nvcr.io→nvcr.m.daocloud.io
• mcr.microsoft.com→mcr.m.daocloud.io

扩展场景：全局镜像、Kubernetes、内网缓存

Docker 守护进程的 registry-mirrors（仅对 docker.io 生效）

不想逐个改地址时，可以在/etc/docker/daemon.json里配全局镜像源，让所有 docker.io 的拉取走加速节点：

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

⚠️ 注意：Docker 的 registry-mirrors 只对 docker.io 生效，不要把它配给 gcr、quay 等其他源站，需要加速那些源时请继续用前缀方式。Podman 用户则可以在/etc/containers/registries.conf中为多个源分别配置 mirror。

加速 kubeadm 与 kind

用 kubeadm 建集群时，把imageRepository指到加速前缀即可：

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

用 kind 建本地集群同理：

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

内网环境：部署缓存 registry

完全脱离外网的内网环境，可以在内网跑一个 registry 作为m.daocloud.io的本地缓存代理，配置和客户端指向的完整步骤见 内网缓存部署文档。

避坑：tag 选择、时间窗口与偶发 404

• tag 优先级：@sha256:摘要 > 明确版本号 >latest。可变 tag 被上游更新后，后台会按旧数据响应并重新同步，生产环境建议锁定版本（如dify-plugin-daemon:v0.3.2这类明确 tag）。
• 时间窗口：拉取和同步任务建议放在北京时间凌晨 01–07 点的闲时窗口，其他时段队列拥挤，大镜像尤其明显。
• 偶发 404 的原因：Manifest 内存缓存 1 小时（tag 更新约 1 小时后才同步新内容），Blob 内存缓存 1 分钟，且缓存内容只保留 30 天。如果某个 blob 刚好在缓存期内过期被删除，可能短暂返回 404，重试或重新拉取一般即可恢复。

出问题时快速自查

📌 按顺序过一遍，多数问题能定位到前两条：

1. 查 allows.txt 是否包含该镜像路径，或用bash hack/verify-allows.sh allows.txt <无tag的镜像>验证；
2. 确认地址是"加前缀"形态（m.daocloud.io/docker.io/...），而不是误配了其他源站的前缀；
3. 仍是 404 时，先到源站确认该 tag 是否存在，再考虑是否在闲时窗口重试；
4. 服务整体状态可通过 DaoCloud 的同步队列与服务监控页查询，高峰期排队属正常现象。

这套方案的本质是用一条固定的前缀规则换取拉取速度和成功率：地址加前缀、tag 锁版本、任务放闲时，三件事做到位，海外镜像的拉取问题基本就收敛了。

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