public-image-mirror容器镜像加速 Mirror 的完整使用指南——前缀映射、白名单机制与 K8s/Docker 加速实战【免费下载链接】public-image-mirror很多镜像都在国外。比如 gcr 。国内下载很慢需要加速。致力于提供连接全世界的稳定可靠安全的容器镜像服务。项目地址: https://gitcode.com/GitHub_Trending/pu/public-image-mirror很多镜像源仓库如 gcr.io位于海外国内直接拉取速度慢、稳定性差。public-image-mirror 项目通过“简洁的名称映射 懒加载同步”的方式提供一个只读的容器镜像 Mirrorm.daocloud.io让docker pull、Kubernetes 节点拉取、Ollama 模型下载等场景都能就近加速。读完本文你将掌握两种加速前缀的用法与差异、支持前缀替换的 11 个源站对照表、镜像白名单allows.txt的匹配规则、Docker/Containerd/Podman/K8s 各类客户端的完整配置方法以及内网二级缓存 registry 的部署方案。一、背景、目标与项目定位项目的出发点很直接很多镜像都在国外比如 gcr国内下载很慢需要加速。为此项目设定了几个设计目标见 README简洁有效加速这些包的方法是一个简洁的名称映射不需要额外的客户端插件易于扩展添加新的包新的镜像仓库/命名空间不需要修改后端代码只维护白名单文件稳定可靠、更新实时每天检查同步情况配合队列与状态监控保证同步进度可观测。需要明确的是项目边界——此项目仅是源镜像仓库Registry的 Mirror它不存储自定义内容只做透明代理与缓存所有 hashsha256均与源仓库保持一致懒加载机制缓存的内容只保留30 天过期后会需要重新同步Manifest 内存缓存 1 小时所以 tag 被更新后约 1 小时之后才会同步新的内容Blob 内存缓存 1 分钟在此期间如果 blob 到达 30 天期限被删除会导致拉取时报 404。理解这四点缓存语义非常关键它解释了“为什么 latest 拉到的可能是旧数据”“为什么刚过期的镜像会短暂 404”这类现象也是后文“镜像引用优先级”最佳实践的理论基础。项目后端基于 OpenCIDN ocimirror 实现运营侧还有两个观察入口值得关注同步队列状态页仅保留一小时的同步记录另外还有一个 Docker 镜像服务的状态监控页。白名单与限流的公开讨论、以及使用问题的咨询入口均维护在项目上游的 Issue 区。二、加速原理名称映射 懒加载public-image-mirror 本质上是一个“命名空间镜像器”你在拉取时把源站地址替换成 Mirror 地址Mirror 服务发现本地没有对应内容时就去源仓库拉取并缓存下来首次拉取即“懒加载”后续命中缓存的请求直接返回。由于所有 sha256 与源保持一致从缓存拉到的镜像内容可以逐字节信任其一致性。这种设计带来两个工程后果首次拉取可能仍然较慢要回源热缓存后的拉取才真正快可变 tag如latest存在最长 1 小时的 Manifest 缓存延迟即源站 tag 更新后Mirror 侧约 1 小时才响应新数据。因此对生产部署项目给出的镜像引用优先级是建议优先使用sha256:指定镜像其次使用明确版本号的 tag最后才考虑latest这种可变 tag——其变更后会响应旧数据并且后台会重新同步。另外由于服务共享且高峰拥挤官方建议将批量拉取任务放在闲时即北京时间凌晨 01:00–07:00其他时间段非常拥挤。三、快速开始最小可用示例一行命令即可通过 Mirror 拉取并运行 Docker Hub 官方 nginx 镜像docker run -d -P m.daocloud.io/docker.io/library/nginx这里体现的是核心用法在原始镜像地址docker.io/library/nginx前加上m.daocloud.io/前缀。四、使用方法两种前缀写法4.1 增加前缀推荐方式在完整源地址前面统一加m.daocloud.io/例如docker.io/library/busybox | V m.daocloud.io/docker.io/library/busybox优点是规则统一、无脑通用对任意源站都成立因此项目推荐使用添加前缀的方式。4.2 源站前缀替换对支持的镜像仓库也可以直接把源站域名替换为对应的*.m.daocloud.io子域例如docker.io/library/busybox | V docker.m.daocloud.io/library/busybox4.3 支持前缀替换的 Registry 对照表不推荐优先使用前缀替换的映射规则是人工配置的有新需求需要提 Issue。完整对照表如下源站替换为备注docker.elastic.coelastic.m.daocloud.iodocker.iodocker.m.daocloud.iodhi.iodhi.m.daocloud.iogcr.iogcr.m.daocloud.ioghcr.ioghcr.m.daocloud.iok8s.gcr.iok8s-gcr.m.daocloud.iok8s.gcr.io 已被迁移到 registry.k8s.ioregistry.k8s.iok8s.m.daocloud.iomcr.microsoft.commcr.m.daocloud.ionvcr.ionvcr.m.daocloud.ioquay.ioquay.m.daocloud.ioregistry.ollama.aiollama.m.daocloud.io实验内测中用法见下文“加速 Ollama DeepSeek”一个重要的使用约束这里每一个源站的内容都是不同的不要把 docker.io 之外的站点配置给 Docker 的registry-mirrors。Docker 的registry-mirrors只会对docker.io未指定域名时的默认仓库生效把gcr.m.daocloud.io这类子域填进去是无效甚至有害的。五、白名单机制allows.txt 与校验脚本Mirror 并非对全网镜像无差别加速而是由一份白名单文件 allows.txt共 1300 余行控制哪些“源站 命名空间/仓库”允许被同步。白名单条目有三种形式精确仓库docker.io/library/nginx——仅该仓库一级通配*docker.io/ollama/*——匹配该命名空间下的一级仓库不跨/递归通配**gcr.io/**、docker.io/*兜底整源——匹配前缀下的任意深度路径。例如文件中同时存在docker.io/*覆盖 Docker Hub 全量一级仓库以及大量更细粒度的docker.io/namespace/*条目、ghcr.io/**之外的单仓库条目、quay.io、mcr.microsoft.com/**、public.ecr.aws/...等。从 allows.txt 的实际内容看白名单覆盖 Docker Hub、GitHub Container Registry、gcr.io / k8s 相关源、quay.io、MCR、AWS public ECR、Oracle/Canal 等源站的常用开源镜像。仓库的 hack 目录提供了维护与校验这份白名单的脚本其逻辑与上述条目语义一一对应值得细读1. hack/verify-allows.sh判断某个镜像是否命中白名单# 用法hack/verify-allows.sh allows.txt image核心函数check_allowshack/verify-allows.sh#L7-L30的匹配规则function check_allows() { local file$1 local image$2 if [[ ${image} *: ]]; then # 带 tag/digest 的引用一律先剥掉再匹配 return 1 fi while read line; do if [[ ${line} *** ]]; then # ** 递归通配纯前缀匹配 if [[ ${image} ${line%\*\*}* ]]; then return 0 fi elif [[ ${line} ** ]]; then # 单 * 一级通配前缀匹配后剩余部分不允许再出现 / if [[ ${image} ${line%\*}* ]]; then if [[ ${image#${line%\*}} ! */* ]]; then return 0 fi fi elif [[ ${line} ${image%\:*} ]]; then # 精确仓库匹配比较时去掉 tag 部分 return 0 fi done ${file} return 1 }注意细节传入的 image 若包含:tag 或 digest会直接判否因为白名单里登记的都是“仓库路径”而非“仓库:tag”*分支中! */*的检查正是实现“docker.io/ollama/*不匹配docker.io/ollama/sub/repo”的语义。2. hack/fmt-image-match.sh白名单归一化与去冗余format函数hack/fmt-image-match.sh#L37-L53会扫描全文件把被*/**通配条目覆盖的精确条目删掉、去掉重复行并排序。check_match与check_match_more两个内部函数实现的匹配逻辑与verify-allows.sh同源。3. hack/verify-image-match.sh格式校验# 备份原文件 → 用 fmt 脚本格式化备份 → diff 比对不一致则说明白名单存在可归一化的冗余 cp $1 $1.bak $(dirname ${BASH_SOURCE})/fmt-image-match.sh $1.bak diff -c $1 $1.bak rm $1.bak4. hack/correct-image.sh用户输入的镜像名归一化guess_image函数hack/correct-image.sh#L3-L34演示了“把用户随手写的镜像名补全为标准形式”的完整规则链非常适合作为理解 Docker 镜像引用语法的参考image${image// /} # 去掉空格 image${image#\/}; image${image%\/} # 去掉首尾 / # hub.docker.com/r/ 或 registry.hub.docker.com/r/ 前缀 → 归一为 docker.io/ if [[ -z ... ]]; then return; fi if [[ ${image} ! */* ]]; then imagelibrary/${image}; fi # 官方库补 library/ if [[ ${image%%/*} ! *.* ]]; then imagedocker.io/${image}; fi # 首段无点 → 补 docker.io if [[ ${image} ! *:* ]]; then image${image}:latest; fi # 无 tag → :latest从源码结构看这套脚本服务于白名单的日常维护与提交前校验新增镜像只需在 allows.txt 追加一行仓库路径或命名空间通配无需改动任何服务代码——这正是 README 中“添加新的包不需要去修改代码”目标的具体落地。六、内网缓存部署二级 Mirror Registry如果你的机器在内网/离线环境或希望把热点镜像沉淀在公司内README 的“最佳实践”章节详见 docs/local-cache/README.md给出了基于 Docker 官方registry的本地缓存代理方案在机房内起一个registry:3配置proxy指向上游https://m.daocloud.io形成“内网 registry → m.daocloud.io → 源站”的二级缓存链。6.1 完整部署步骤步骤 1准备环境——确保已安装 Docker 和 Docker Compose。步骤 2创建docker-compose.yml内嵌 registry 配置缓存 TTL 为 2160h 90 天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: delete: enabled: true filesystem: rootdirectory: /var/lib/registry http: addr: :8888 proxy: remoteurl: https://m.daocloud.io ttl: 2160h volumes: cache-data: {}配置要点proxy.remoteurl指定上游为https://m.daocloud.io即本 Mirror 的“加前缀”入口因此本地缓存天然继承“源站 命名空间”的完整路径语义proxy.ttl: 2160h是本地缓存有效期 90 天storage.delete.enabled: true允许通过 DELETE API 清理过期缓存层。步骤 3启动服务docker compose up -d步骤 4配置 Docker 客户端——在/etc/docker/daemon.json中添加本机 registry 走 HTTP需声明为 insecure{ insecure-registries: [your-registry-ip:your-registry-port] }然后重启 Docker 服务systemctl restart docker6.2 用法此时your-registry-ip:your-registry-port/已成为m.daocloud.io/的本地缓存代理。就像对m.daocloud.io加前缀一样只需在原始镜像地址前加上本地 registry 前缀即可。例如拉取docker.io/library/nginx:latestdocker pull your-registry-ip:your-registry-port/docker.io/library/nginx:latest七、加速 Kubernetes7.1 加速安装 kubeadm在ClusterConfiguration中把imageRepository和 DNS 组件仓库指向k8s.m.daocloud.ioapiVersion: kubeadm.k8s.io/v1beta3 kind: ClusterConfiguration dns: imageRepository: k8s.m.daocloud.io/coredns imageRepository: k8s.m.daocloud.io ...注意对应关系源站registry.k8s.io的前缀替换域名是k8s.m.daocloud.io旧的k8s.gcr.io对应k8s-gcr.m.daocloud.iok8s.gcr.io 本身已被迁移到 registry.k8s.io。7.2 加速安装 kindkind 的节点镜像来自 Docker Hub 的kindest/node直接用“加前缀”方式即可kind create cluster --name kind --image m.daocloud.io/docker.io/kindest/node:v1.22.17.3 加速所有 PodWebhook 方式不改 YAML推荐第三方工具 repimagewzshiming/repimage不修改 yaml、helm 等清单仅通过 Webhook 自动改写所有新建 Pod 的 image 地址使用本 mirror。部署命令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第二条命令等待 kube-system 下 repimage Deployment 滚动完成。7.4 加速 ContainerdContainerd 官方通过hosts.md文档的 registry host 命名空间机制/etc/containerd/certs.d/源站/hosts.toml为每个源站单独配置 mirror 指向对应的*.m.daocloud.io子域如果使用 kubespray 安装 containerd可以配置其文档中的containerd_registries_mirrors参数来批量声明源站到 mirror 的映射。八、加速 Docker / Podman 客户端8.1 加速 Docker添加到/etc/docker/daemon.json{ registry-mirrors: [ https://docker.m.daocloud.io ] }再次强调Docker 的registry-mirrors仅对 docker.io 生效不要把 docker.io 之外的源站gcr、ghcr 等的 mirror 配置填进这里那些源站应通过“加前缀”或 Containerdhosts.toml方式加速。8.2 加速 Podman添加到/etc/containers/registries.confrootless 模式也可以添加到~/.config/containers/registries.conf[[registry]] location docker.io [[registry.mirror]] location docker.m.daocloud.io与 Docker 不同Podman 支持为 docker.io 之外的 registry 也配置 mirror例如[[registry]] location gcr.io [[registry.mirror]] location gcr.m.daocloud.io [[registry]] location ghcr.io [[registry.mirror]] location ghcr.m.daocloud.io [[registry]] location quay.io [[registry.mirror]] location quay.m.daocloud.io [[registry]] location registry.k8s.io [[registry.mirror]] location k8s.m.daocloud.io语法细节可参考 Podman 官方 registries.conf 文档。九、加速 Ollama DeepSeek9.1 加速安装 OllamaCPU 版docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama docker.m.daocloud.io/ollama/ollamaGPU 版先安装 Nvidia Container Toolkit再运行docker run -d --gpusall -v ollama:/root/.ollama -p 11434:11434 --name ollama docker.m.daocloud.io/ollama/ollama9.2 加速使用 DeepSeek-R1 模型实验内测中registry.ollama.ai的加速域名ollama.m.daocloud.io目前为实验内测。在上述 Ollama 容器已启动的前提下可通过加速源拉取 DeepSeek 相关模型注目前 Ollama 官方源的下载速度已经很快也可以直接使用官方源。# 使用加速源 docker exec -it ollama ollama run ollama.m.daocloud.io/library/deepseek-r1:1.5b # 或直接使用官方源下载模型 # docker exec -it ollama ollama run deepseek-r1:1.5b十、运营信息、注意事项与项目生态白名单与限流服务的白名单策略与限流信息在项目上游以公开 Issue 形式维护使用前可先确认目标镜像是否受保护拉取时机建议将批量拉取放在北京时间凌晨 01:00–07:00 的闲时白天高峰非常拥挤缓存生命周期30 天未命中的缓存会被清理清理窗口内可能遇到短暂的 404Blob 内存缓存 1 分钟所致tag 更新后有约 1 小时的 Manifest 缓存延迟镜像引用规范sha256:摘要 明确版本 tag latest问题咨询疑问统一走项目上游 Issue 渠道姊妹项目除镜像加速外DaoCloud 还有配套的“二进制文件加速”项目public-binary-files-mirror即本文 repimage 部署命令中files.m.daocloud.io所服务的二进制文件镜像二者常被一起使用——一个解决镜像问题一个解决静态文件/二进制下载问题。小结public-image-mirror 的用法可以浓缩为三句话能加前缀就加m.daocloud.io/客户端 mirror 配置只给 docker.io内网场景再叠一层 registry proxy 指向 m.daocloud.io。配合 allows.txt 白名单核对目标镜像、遵循 sha256 优先的引用规范与闲时拉取策略即可在生产环境中稳定获得镜像加速收益。【免费下载链接】public-image-mirror很多镜像都在国外。比如 gcr 。国内下载很慢需要加速。致力于提供连接全世界的稳定可靠安全的容器镜像服务。项目地址: https://gitcode.com/GitHub_Trending/pu/public-image-mirror创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考