2026 年 8 月 Docker 国内镜像加速配置指南：别只改 registry-mirrors

docker pull 一直转圈、kubectl apply 后 Pod 卡在 ImagePullBackOff、群晖里装个小工具也「下载中」——很多人第一反应是「镜像源又挂了」，把地址塞进 daemon.json 的 registry-mirrors 再重启。有时能好一会儿，换台机器、进集群、拉 ghcr.io 就又失败。

其实更常见的问题是：用法选错了。

• registry-mirrors 只是优先尝试；失败时 Docker 会自动回退官方 registry-1.docker.io，而且管不了 GHCR、GCR、registry.k8s.io。
• 更稳妥：在镜像名里写上轩辕域名（公共登录域或个人专属域），让每次 pull / Compose 都走明确路径。
• K8s / K3s 读的是节点上的 containerd（或 K3s 配置），不会读你笔记本 Docker Desktop 里的 daemon.json。

跨云、本机、NAS、多仓库场景，建议用轩辕镜像专业版：个人中心查看镜像账户 / 密码与专属域名。

轩辕镜像专业版：

https://xuanyuan.cloud
https://xuanyuan.cloud/recharge

加速只解决「能不能稳拉」。EMQX、Kafka、phpMyAdmin、ERPNext 等怎么部署，可到技术博客跟做（250+ 篇）：

https://xuanyuan.cloud/blog

⚠️ 本文仅限学习研究，请勿违规使用。专属域名前缀以个人中心为准。建议收藏。

一、先对号入座：哪种报错？

四句话结论：

1. 命令行拉 Hub：默认 docker pull docker.xuanyuan.run/<路径>（一次性 docker login）
2. 免登录 / NAS / GUI：主专属域 你的前缀.xuanyuan.run/<路径>（不要对专属域 login）
3. GHCR → 前缀-ghcr.xuanyuan.run；K8s → 前缀-k8s.xuanyuan.run（禁止对这类域 login）
4. registry-mirrors 只作兼容，不作为首选

新手总览：

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

二、8 月加速方式怎么选？

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

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

轩辕镜像专业版（推荐）

• 覆盖 Docker Hub、GHCR、GCR、registry.k8s.io 等（见映射表）
• 适配 Linux、Desktop、K8s、NAS、信创
• 新人 ¥2.9 起，50GB ¥8（以充值页为准）
• 凭据：个人中心 → 用户信息 → 镜像仓库信息（与网站登录密码相同）

https://xuanyuan.cloud
https://xuanyuan.cloud/recharge

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

docker pull docker.xuanyuan.me/nginx:latest

无需登录，仅 Docker Hub，有限流，不建议生产。对比说明：

https://xuanyuan.cloud/faq/free-vs-pro

开通路径：注册 → 充值 → 复制专属域名 / 镜像账户密码 → 按第三节拉取。

三、推荐用法：镜像名里写轩辕域名

*** 表示你的专属前缀，以个人中心为准。

3.1 仓库映射（务必看后缀）

只换前缀，/ 后面的路径和 tag 不要改。

多仓库教程总览：

https://xuanyuan.cloud/usage/mirror-tutorial

Hub / GHCR / K8s 分篇（复制打开）：

https://xuanyuan.cloud/usage/mirror-tutorial/docker-hub
https://xuanyuan.cloud/usage/mirror-tutorial/ghcr
https://xuanyuan.cloud/usage/mirror-tutorial/k8s

3.2 命令行默认：公共登录域

分步截图：

https://xuanyuan.cloud/usage/login

# 已登录可跳过（看 ~/.docker/config.json 里有没有 docker.xuanyuan.run）
grep -q '"docker.xuanyuan.run"' ~/.docker/config.json || \
  docker login docker.xuanyuan.run

docker pull docker.xuanyuan.run/library/nginx:1.27
docker pull docker.xuanyuan.run/library/alpine:3.20

注意：

• Windows CMD：密码不要加双引号（会导致 401）
• PowerShell 示例：Write-Output "镜像密码" | docker login -u 镜像账户 --password-stdin docker.xuanyuan.run
• 出现 402 → 去充值，不要反复 login

3.3 免登录：主专属域（NAS / GUI 友好）

https://xuanyuan.cloud/usage/nologin
https://xuanyuan.cloud/faq/exclusive-domain

# 把 myprefix 换成个人中心主专属前缀
docker pull myprefix.xuanyuan.run/library/nginx:1.27

不要对专属域执行 docker login（群晖 GUI 尤其容易踩坑）。

3.4 关于 registry-mirrors

只能改加速地址、改不了镜像名时，可作兼容；须知失败会回退官方。平台说明：

https://xuanyuan.cloud/usage/linux
https://xuanyuan.cloud/usage/desktop
https://xuanyuan.cloud/faq/registry-mirrors-not-working

生产与脚本更推荐上面的显式域名 pull。

四、按场景复制官方教程地址

登录还是专属域？ → https://xuanyuan.cloud/usage/login 、 https://xuanyuan.cloud/usage/nologin
Linux 未装 Docker → https://xuanyuan.cloud/usage/linux
Linux 已装 Docker → /usage/linux
Docker Desktop    → https://xuanyuan.cloud/usage/desktop
Compose           → https://xuanyuan.cloud/usage/docker-compose
K8s containerd    → https://xuanyuan.cloud/usage/containerd
K3s               → https://xuanyuan.cloud/usage/k3s
Podman            → https://xuanyuan.cloud/usage/podman
群晖            → https://xuanyuan.cloud/usage/synology
威联通            → https://xuanyuan.cloud/usage/weiliantong
极空间            → https://xuanyuan.cloud/usage/jikongjian
其他          → https://xuanyuan.cloud/install/linux， https://xuanyuan.cloud/usage/harbor
部署业务组件       → https://xuanyuan.cloud/blog

五、Linux 一键安装 Docker

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

说明页：

https://xuanyuan.cloud/install/linux

装好后仍建议按第三节用显式域名拉取。

六、Compose：image 写完整轩辕域名

教程：

https://xuanyuan.cloud/usage/docker-compose

services:
  web:
    image: docker.xuanyuan.run/library/nginx:1.27-alpine
    ports: ["8080:80"]
    volumes: [./html:/usr/share/nginx/html:ro]
    depends_on: [cache]
    restart: unless-stopped
  cache:
    image: docker.xuanyuan.run/library/redis:7.4-alpine
    ports: ["6379:6379"]
    volumes: [redis-data:/data]
    command: ["redis-server", "--save", "60", "1"]
    restart: unless-stopped
volumes:
  redis-data:

mkdir -p html && echo '<h1>ok</h1>' > html/index.html
# 公共登录域且未登录时先执行：docker login docker.xuanyuan.run
docker compose up -d
curl -s http://127.0.0.1:8080/

若有 GHCR 镜像，把 image 写成：你的前缀-ghcr.xuanyuan.run/组织/应用:标签（不要 login 该域）。

七、拉取自检（复制即用）

grep -q '"docker.xuanyuan.run"' ~/.docker/config.json || docker login docker.xuanyuan.run
docker pull docker.xuanyuan.run/library/alpine:3.20 && echo "OK" || echo "FAIL"

# 免登录专属域（替换 myprefix）
# docker pull myprefix.xuanyuan.run/library/alpine:3.20

失败时按第一节查 FAQ，不要默认改回官方短名硬拉。

轩辕只支持公开镜像 pull，不支持 push、不支持私有仓库透传 PAT：

https://xuanyuan.cloud/faq/docker-push-not-supported
https://xuanyuan.cloud/faq/private-registry-not-supported

八、技术博客：拉通之后照着部署

https://xuanyuan.cloud/blog

跟做前先保证第七节自检通过；教程里的镜像名也建议改成轩辕域名形式。

九、生产 Checklist（精简）

十、FAQ

Q1：为什么不推荐只改 daemon.json？
mirrors 失败会回退官方，且不管 GHCR/K8s。见：

https://xuanyuan.cloud/faq/registry-mirrors-not-working

Q2：本机 Docker 加速了，K8s 还是 ImagePullBackOff？
节点要配 containerd / K3s；K8s 官方仓用 前缀-k8s.xuanyuan.run：

https://xuanyuan.cloud/usage/containerd
https://xuanyuan.cloud/usage/k3s

Q3：能对 xxx-ghcr.xuanyuan.run login 填 GitHub PAT 吗？
不能。专属域禁止 login；私有 GHCR 也不在支持范围：

https://xuanyuan.cloud/faq/private-registry-not-supported

Q4：429 / 402？

https://xuanyuan.cloud/faq/429-rate-limit-error
https://xuanyuan.cloud/faq/traffic-exhausted-error
https://xuanyuan.cloud/recharge

连通性 / 401 / manifest（常用）：

https://xuanyuan.cloud/faq/docker-cannot-connect-xuanyuan-domain
https://xuanyuan.cloud/faq/unauthorized-error
https://xuanyuan.cloud/faq/manifest-unknown-error
https://xuanyuan.cloud/faq/no-matching-manifest-architecture
https://xuanyuan.cloud/faq

总结

1. 别只改 mirrors——优先 docker.xuanyuan.run/...（登录一次）或主专属域免登录
2. GHCR / K8s 看后缀——-ghcr、-k8s，别混用主专属域，别对专属域 login
3. 分平台打开官方 Usage——第四节地址可直接复制
4. 落地——拉通后去技术博客跟做部署

立即开始：

https://xuanyuan.cloud
https://xuanyuan.cloud/recharge
https://xuanyuan.cloud/usage/login
https://xuanyuan.cloud/usage/nologin
https://xuanyuan.cloud/agents.md
https://xuanyuan.cloud/blog

完整长文（含分发标题与更细表格）见官网博客版，可搜索站内「2026 年 8 月 Docker 国内镜像加速」，或打开技术博客首页查找最新镜像源专题。

欢迎收藏，配置与套餐以官网为准。拉取慢、超时、ImagePullBackOff 时，按本文换成显式轩辕域名再试。