Docker 拉镜像又失败了？7 月国内镜像加速配置一篇说清

2026 年 7 月更新 · 覆盖 Docker、Docker Desktop、K8s containerd、Podman、群晖/威联通 NAS

docker pull 一直转圈、kubectl apply 后 Pod 卡在 ImagePullBackOff、NAS 里拉个 nginx 要半小时——很多人第一反应是「镜像源挂了」，其实更常见的原因是：配错了层级。

Docker 的 registry-mirrors 只管 Docker Hub（docker.io）；K8s 节点读的是 containerd 配置；ghcr.io、registry.k8s.io 还要单独配 mirror。本文按「报错 → 原因 → 配置 → 验证」给出 2026 年 7 月可用的国内加速方案，命令可直接复制。

⚠️ 本文内容仅限学习研究，建议收藏，每月更新。

一、先对号入座：你遇到的是哪种报错？

三句话结论：

• 个人单机、只拉 Docker Hub → 配 registry-mirrors 就够
• K8s / K3s 集群 → 每个节点必须改 containerd
• 要拉 GHCR / K8s 官方仓库 → 用轩辕专业版专属域名（免费源只管 Hub）

二、7 月可用加速源怎么选？

云厂商内网源（仅限自家云服务器）

离开对应云网络，这些地址可能失效，且一般不覆盖 GHCR / K8s 仓库。

轩辕镜像专业版（推荐 · 全场景）

• 注册登录后获得专属域名（如 abc123.xuanyuan.run）
• 覆盖 Docker Hub、GHCR、GCR、registry.k8s.io
• 适配 Linux、K8s、NAS、信创服务器（openEuler / 麒麟等）
• 50GB 流量 ¥7/年起，带 SLA 与在线支持

专业版入口（复制打开）：

https://xuanyuan.cloud

推荐路径：注册 → 个人中心复制专属域名 → docker login → 按下文写入配置。

轩辕镜像免费版（仅体验）

https://docker.xuanyuan.me

无需登录，仅加速 Docker Hub，有限流，不建议生产或团队使用。

免费版说明页（复制打开）：

https://xuanyuan.cloud/free

三、按你的环境选配置路径

还没装 Docker（Linux）
  → 第四节 · 一键安装脚本

已装 Docker，只拉 Hub 镜像
  → 第五节 · Linux daemon.json

macOS / Windows Docker Desktop
  → 第五节 · Desktop 配置

K8s / K3s 集群
  → 第六节 · containerd 多仓库（必做）

Podman
  → 第六节 · registries.conf

群晖 / 威联通 / 极空间 NAS
  → 第八节 FAQ · Q2

四、Linux 一键安装 Docker + 加速

脚本支持 15 种发行版（Ubuntu、Debian、Rocky、openEuler、统信 UOS、深度 Deepin 等），ARM64（鲲鹏/飞腾） 与 x86_64 均可用。

测试环境（快速体验）

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

生产环境（先下载、审阅再执行）

wget https://xuanyuan.cloud/docker.sh -O docker-install.sh
less docker-install.sh
bash docker-install.sh

脚本下载地址（复制备用）：

https://xuanyuan.cloud/docker.sh

开源仓库（可复制审阅源码）：

https://github.com/SeanChang/xuanyuan_docker_proxy

CentOS 7 不支持：已 EOL，请迁移至 Rocky Linux、AlmaLinux 或 CentOS Stream 8+。

安装后验证：

docker --version
docker compose version
docker info | grep -i "registry mirrors" -A 2

五、手动配置 · Linux 与 Docker Desktop

下文 xxx.xuanyuan.run 请替换为你在轩辕个人中心复制的专属域名。免费体验可把地址换成 docker.xuanyuan.me（仅 Hub）。

5.1 Linux · Docker Engine

sudo mkdir -p /etc/docker

cat <<EOF | sudo tee /etc/docker/daemon.json
{
  "registry-mirrors": ["https://xxx.xuanyuan.run"]
}
EOF

sudo systemctl daemon-reload
sudo systemctl restart docker

验证是否生效：

docker info | grep "Registry Mirrors" -A 3
docker pull nginx:alpine

专业版建议先登录仓库（凭据见官网 FAQ）：

docker login xxx.xuanyuan.run

登录说明（复制打开）：

https://xuanyuan.cloud/faq/how-to-pull-images

5.2 macOS / Windows · Docker Desktop

1. 任务栏 / 菜单栏点击 Docker 图标 → Settings
2. 左侧选 Docker Engine
3. 在 JSON 里写入（替换专属域名）：

{
  "registry-mirrors": ["https://xxx.xuanyuan.run"]
}

4. 点 Apply & Restart
5. 终端执行 docker info，确认 Registry Mirrors 已出现

⚠️ 生产环境禁止使用 insecure-registries 跳过证书校验。

六、K8s / containerd / Podman（集群必看）

重点：K8s 节点不会读取 Docker 的 daemon.json。Desktop 配好了，Pod 照样可能 ImagePullBackOff。

6.1 containerd 多仓库配置

containerd config default | sudo tee /etc/containerd/config.toml
sudo nano /etc/containerd/config.toml

在 plugins."io.containerd.grpc.v1.cri".registry.mirrors 下添加（替换专属地址）：

[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
      endpoint = ["https://xxx.xuanyuan.run"]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."ghcr.io"]
      endpoint = ["https://xxx-ghcr.xuanyuan.run"]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."registry.k8s.io"]
      endpoint = ["https://xxx.xuanyuan.run"]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"]
      endpoint = ["https://xxx-gcr.xuanyuan.run"]

保存后重启并测试：

sudo systemctl restart containerd
ctr images pull xxx.xuanyuan.run/library/alpine:3.20
kubectl run test-nginx --image=nginx:alpine --restart=Never
kubectl describe pod test-nginx | grep -A5 Events

生产环境建议 endpoint 配置多个节点做 fallback，避免单点故障。

6.2 nerdctl（自动共享 containerd 配置）

containerd 配好后，nerdctl 无需重复设置：

nerdctl pull nginx:alpine
nerdctl run -d -p 8080:80 --name web nginx:alpine

6.3 Podman

新建 /etc/containers/registries.conf.d/99-xuanyuan.conf：

unqualified-search-registries = ['docker.io']

[[registry]]
prefix = "docker.io"
location = "registry-1.docker.io"
  [[registry.mirror]]
  location = "xxx.xuanyuan.run"

[[registry]]
prefix = "ghcr.io"
location = "ghcr.io"
  [[registry.mirror]]
  location = "xxx-ghcr.xuanyuan.run"

验证：podman pull alpine:latest

七、30 秒自检：加速到底生效没？

把 xxx.xuanyuan.run 换成你的专属域名，在服务器上执行：

DOMAIN="xxx.xuanyuan.run"

echo "=== 显式域名拉取 ==="
docker pull "${DOMAIN}/library/alpine:3.20" && echo "OK" || echo "FAIL"

echo "=== 短名拉取（需 daemon.json mirrors）==="
docker pull alpine:3.20 && echo "OK" || echo "FAIL"

echo "=== 当前 mirrors 配置 ==="
docker info 2>/dev/null | grep -A3 "Registry Mirrors"

Hub OK + Mirrors OK 都通过，说明 Docker 侧配置正常。K8s 还要在每个 Worker 节点单独验 containerd。

八、常见问题

Q1：daemon.json 配了，K8s Pod 还是 ImagePullBackOff？

节点用的是 containerd，不读 Docker 配置。在每个 Worker 上改 /etc/containerd/config.toml，systemctl restart containerd，再 kubectl describe pod <名称> 看 Events。

Q2：群晖 / 威联通 / 极空间怎么配？

1. 登录轩辕专业版，参考官网 NAS 指引
2. 群晖：开启 SSH，在 Docker 注册表或相关配置里填入专属加速地址
3. 威联通：Container Station → 偏好设置 → 注册表
4. 保存后重启容器服务，拉 nginx:alpine 测试

NAS 配置手册（复制打开）：

https://xuanyuan.cloud/usage

Q3：免费源很慢或报 429？

公共免费源有限流。团队开发、CI 流水线、生产环境请用专业版专属节点。

Q4：registry-mirrors 配了，GHCR 还是失败？

正常。mirrors 只管 docker.io。GHCR、K8s 官方仓库须按第六节配 containerd 或 Podman 多仓库，或用专业版全仓库方案。

Q5：openEuler / 麒麟 / 统信 UOS 能用一键脚本吗？

可以。脚本自动识别信创系统与 ARM64，无需手动改源。

Q6：生产环境能直接 bash <(wget ...) 吗？

不建议。应先 wget 下载脚本，审阅源码后再执行，并留存操作记录。

更多错误码（401 / 402 / manifest unknown 等）见 FAQ 大全：

https://xuanyuan.cloud/faq

九、命令速查

十、不同场景怎么选？

安全底线：生产禁止 insecure-registries；密码别写进脚本；.env 别提交 Git。

总结

国内拉镜像失败，多半不是「没源」，而是配错了运行时和仓库层级：

1. Docker Hub → daemon.json 的 registry-mirrors
2. K8s 集群 → 每个节点的 containerd config.toml
3. GHCR / K8s 仓库 → 专业版专属域名 + 多仓库 mirrors

立即开始（复制打开）：

轩辕镜像专业版注册：

https://xuanyuan.cloud

配置使用手册：

https://xuanyuan.cloud/usage

Docker 镜像搜索（可复制 pull 命令）：

https://xuanyuan.cloud/search

常见问题 FAQ：

https://xuanyuan.cloud/faq

containerd 完整多仓库示例、Compose 实战、企业生产 Checklist 等详细内容，请查看官网完整版：

https://xuanyuan.cloud/blog/2026-7-docker

如果你在拉取 Docker 镜像时遇到速度慢、超时、ImagePullBackOff 等问题，可以试试轩辕镜像加速服务。欢迎收藏本文，每月会更新可用性与配置细节。