企业官网建设流程全解析

public-image-mirror 容器镜像加速服务：原理、配置与避坑指南

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

在国内网络环境下，从 docker.io、gcr.io、ghcr.io 等境外仓库拉取容器镜像，速度往往很慢甚至完全不可达。public-image-mirror 是一个公开的容器镜像加速服务，它把境外镜像仓库的内容以懒加载方式同步到国内节点，你只需要在镜像地址前加一个前缀，就能完成镜像加速。本文说明它的工作原理、支持的仓库范围，以及 Docker、Podman、Kubernetes 和内网缓存等场景的具体配置方法。

工作原理：按需同步的镜像缓存

这个项目不是“提前把所有镜像搬回来”的静态仓库，而是源仓库的 Mirror：

• 按需取回：首次拉取某镜像时才去源仓库获取并缓存（懒加载机制）。
• 哈希一致：所有镜像的 hash(sha256) 与源保持一致，校验结果不变。
• 缓存保留 30 天：过期后内容会被清掉，下次需要重新同步。
• 同步有延迟：Manifest 内存缓存 1 小时，源站 tag 更新后最多要 1 小时才会反映到镜像侧；Blob 内存缓存 1 分钟。

也就是说：第一次拉取某个镜像时速度取决于回源情况，之后同一内容的拉取都会很快。

快速开始：加一个前缀就能拉镜像

最短路径是给原始镜像地址加上m.daocloud.io/前缀：

docker.io/library/busybox → m.daocloud.io/docker.io/library/busybox

跑一条命令即可验证链路是否可用：

docker run -d -P m.daocloud.io/docker.io/library/nginx

这条命令不需要修改任何客户端配置，也能随时还原，适合先做一次最小验证。前缀方式适用的仓库范围比下面的替换域名更广，具体以仓库内的白名单文件 allows.txt 为准。

支持哪些仓库，前缀方式和前缀替换有什么区别

项目提供两种命名方式：

• 增加前缀（推荐）：m.daocloud.io/+ 原始镜像地址。地址结构不变，适合写进脚本和 CI。
• 前缀替换：把源站域名换成对应的加速域名。这套映射是人工维护的，需要新增源站时要向项目提需求。

一条必须记住的规则：只有 docker.io 对应的域名可以放进 Docker 的registry-mirrors。每个源站的内容互不相同，把 gcr 或 ghcr 的域名配进全局 registry-mirrors，会导致 docker.io 的镜像拉取失败。

场景化配置

如何给 Docker 配置全局镜像加速

编辑/etc/docker/daemon.json，只加入 docker.io 的加速域名：

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

然后重启 Docker 服务。此后不带前缀的docker pull都会优先走镜像，不用改任何业务命令。

如何给 Podman 配置镜像源

在/etc/containers/registries.conf中添加（rootless 模式也可以写在~/.config/containers/registries.conf）：

[[registry]] location = "docker.io" [[registry.mirror]] location = "docker.m.daocloud.io"

与 Docker 不同，Podman 允许为 docker.io 之外的源站配置 mirror，比如gcr.io、ghcr.io、quay.io、registry.k8s.io，按上表逐条添加对应的*.m.daocloud.io域名即可。

Kubernetes 集群怎么用镜像加速

kubeadm 安装：修改 ClusterConfiguration 中的imageRepository，并指定 CoreDNS 的镜像仓库：

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

kind 本地集群：创建集群时直接指定镜像地址：

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

存量集群：如果不想改动任何 yaml 或 Helm chart，可以部署 repimage 这个 Webhook 组件，它会自动把所有新建 Pod 的 image 改写成镜像地址，不用动现有清单。节点使用 Containerd 作为运行时时，可参考 Containerd 官方的 hosts 配置文档配置 registry mirror；用 kubespray 安装的场景则可以使用containerd_registries_mirrors选项。

内网环境如何部署本地镜像缓存

拉取方在内网、无法直连公网时，可以先在一台能出网的机器上部署一个本地缓存 registry，让它反向代理到m.daocloud.io。部署方式是运行一个registry:3容器，关键配置有三点：

• proxy.remoteurl指向https://m.daocloud.io，ttl控制缓存保留时长
• 容器对外暴露 8888 端口
• Docker 客户端在daemon.json里用insecure-registries指向<registry-ip>:8888

之后就像用m.daocloud.io加前缀一样，把本地 registry 地址当前缀即可，例如：

docker pull <registry-ip>:8888/docker.io/library/nginx:latest

完整的 docker-compose 文件和说明见 docs/local-cache/README.md。安全上要注意：本地缓存默认是 HTTP 服务、依赖insecure-registries才能访问，只能对内网开放，不要暴露到公网。

如何加速 Ollama 镜像拉取

CPU 版本直接拉加速源镜像：

docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama docker.m.daocloud.io/ollama/ollama

GPU 版本需要先安装 Nvidia Container Toolkit，再给同一条命令加上--gpus=all参数。容器启动后，实验阶段还可以用ollama run ollama.m.daocloud.io/library/deepseek-r1:1.5b这样的方式通过加速源拉取模型（内测中）。

能力边界：能做什么，不能做什么

• 能做：按懒加载方式加速拉取公开镜像，哈希与源一致，每天检查同步情况。
• 不能做：它不是私有镜像托管，也不替代源仓库存储；私有镜像和不在白名单内的镜像不在覆盖范围。
• 白名单机制：服务按白名单工作，allows.txt 即当前允许的仓库与镜像清单，清单外的镜像无法经此拉取，有需求可向项目提 Issue。
• 限流：高峰期非常拥挤且有并发限制，官方建议把批量拉取任务放在闲时（北京时间 01:00–07:00）。
• 排查窗口有限：同步队列状态页只保留一小时的同步记录，拉取失败后应尽快排查。

另有一个相关项目做二进制文件加速（public-binary-files-mirror），下载软件包、二进制这类非镜像场景可以一并了解。

常见坑与排障

• latest 拉到旧内容：Manifest 内存缓存 1 小时，源站更新 latest 后，镜像侧最多 1 小时仍可能返回旧数据并触发后台重新同步。生产环境建议优先用@sha256:摘要，其次用明确版本号 tag，最后才考虑 latest。
• 偶发 404：Blob 到期删除时若正处在 1 分钟内存缓存窗口内，可能报 404，重新拉取一般即可恢复。
• 配了 mirror 却没生效：检查是否把非 docker.io 的域名放进了 Docker 的registry-mirrors，这是最常见的配错。
• 拉取明显变慢：先确认是否处于高峰期，批量任务挪到凌晨会快很多。
• 拉取失败但镜像存在：对照 allows.txt 确认镜像是否在白名单内；不在清单内的，只能继续走原始地址或先提需求。
• k8s.gcr.io 地址失效：该源站已迁移到 registry.k8s.io，配置应改用k8s.m.daocloud.io。

行动建议

1. 先用前缀方式对你最常用的 1～2 个镜像做一次验证，不改配置、随时可回退。
2. 团队普遍拉取慢时，再配置 Docker 或 Podman 的全局镜像，记住只放 docker.io 对应的域名。
3. 有内网需求时，按 docs/local-cache/README.md 部署本地缓存，并把insecure-registries指向该 registry。
4. 把清单里的 latest 逐步替换为明确版本号或@sha256:摘要——这比追求更快的镜像通道更稳定，也更容易定位问题。

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