2026 年 8 月 Docker 国内镜像加速配置指南：稳定拉取与部署落地

开学季与项目交付高峰叠加，开发机、云主机、家里 NAS 上同时在拉镜像的情况很常见：docker pull nginx 转圈半小时、kubectl apply 后 Pod 一直停在 ImagePullBackOff、群晖里装个小工具也卡在「下载中」。第一反应往往是「镜像源又挂了」——把搜到的地址塞进 daemon.json 的 registry-mirrors 再重启，有时能好一会儿，换台机器、进集群、拉 ghcr.io 就又失败。

多数情况下，问题不是「没有加速地址」，而是用法选错了：

• Docker 的 registry-mirrors 只优先尝试加速，失败时客户端会自动回退官方 registry-1.docker.io，而且不覆盖 ghcr.io、gcr.io、registry.k8s.io 等仓库。因此官网不把它当作默认推荐方案，详见 mirrors 不生效。
• 更稳妥的做法是：在镜像名里写上轩辕域名（公共登录域或个人专属域），让每次 docker pull / Compose image: 都走明确路径，而不是依赖「写了 mirrors 就一定会加速」。
• Kubernetes / K3s 节点读的是 containerd（或 K3s 自带配置），不会读本机 Docker Desktop 的 daemon.json。集群拉镜像要单独按 containerd / K3s 教程配置。

云厂商内网 mirror（腾讯云、阿里云、华为云等）在同云 ECS 上往往够用，换到本机、另一家云、NAS、CI 就不生效。跨环境、要拉多仓库时，建议注册 轩辕镜像专业版：个人中心可查看镜像账户 / 镜像密码与专属域名；流量在 充值中心 购买——新人使用仅 ¥2.9 起，50GB 仅需 ¥8。仅体验 Hub 可用免费域 docker.xuanyuan.me（免费版与专业版对比）。

加速解决「镜像能不能稳拉下来」。把 Redis、MQTT、数据库管理台、ERP 等真正跑起来，还需要端口、数据卷与验证步骤写清楚的文档。轩辕镜像技术博客 已有 250+ 篇原创部署教程（EMQX、Kafka、phpMyAdmin、ERPNext、Rocket.Chat 等），配好拉取方式后可直接跟做。

本文按官方机器可读规范 agents.md（2026-08-01）整理人类可读的 8 月指南：报错分流 → 选版与域名 → 推荐拉取方式 → 分平台教程链接 → 自检与 Compose → 博客落地。专属域名前缀请以个人中心为准，不要编造；完整分步截图见各条 Usage，报错见 FAQ。

建议收藏本文。

---

一、先诊断：你遇到的是哪类问题？

快速结论：

• 推荐默认：命令行对 Docker Hub 使用 docker pull docker.xuanyuan.run/<路径>（公共登录域，一次性 docker login）
• 免登录 / NAS / GUI：使用个人中心主专属域 ***.xuanyuan.run/<路径>（不要对专属域 login）
• GHCR / K8s 等：必须用带后缀的专属域（如 ***-ghcr、***-k8s），禁止对这类域 login
• registry-mirrors：仅作兼容，不作为首选

新手总览也可读：如何拉取镜像。

---

二、2026 年 8 月可用加速方式

云厂商内网镜像（仅限同云 ECS）

轩辕镜像专业版（推荐）

• 入口：轩辕镜像专业版
• 充值：充值中心 — 新人使用仅 ¥2.9 起，50GB 仅需 ¥8
• 凭据：个人中心 → 用户信息 → 镜像仓库信息（镜像账户 + 镜像密码；与网站登录密码相同，修改见 改密）
• 域名：主专属域 ***.xuanyuan.run（docker.io，免 login）；非 Hub 为 ***-{ghcr\|gcr\|quay\|nvcr\|k8s\|mcr\|elastic\|oracle\|gitlab}.xuanyuan.run
• 规范：agents.md

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

• 地址：docker.xuanyuan.me（不是 .run）
• 说明：无需登录，仅 Docker Hub；勿为免费版生成 GHCR 等专属域命令 → 免费版与专业版

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

---

三、推荐用法：显式域名拉取（优先于 registry-mirrors）

规则摘要来自 agents.md §1–§2。*** 表示你的专属前缀，以个人中心为准。

3.1 上游仓库 → 轩辕域名

多仓库总览：企业仓库镜像教程。

路径规则：只替换 registry 前缀，/ 后的命名空间、镜像名、tag 保持不变。官方短名 nginx:latest 可写成 docker.xuanyuan.run/nginx:latest 或 docker.xuanyuan.run/library/nginx:latest。

3.2 Docker Hub：公共登录域（命令行默认）

分步截图：登录仓库拉取

bash
# 已登录则跳过（凭证在 ~/.docker/config.json）
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
• 仅当用户明确要求海外线路时，将 .run 换成 .dev，且 login 与 pull 必须同域
• 402 是流量问题 → 充值，不要反复 login

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

分步说明：专属域名拉取、专属域名 FAQ

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

MUST NOT 对 *.xuanyuan.run 专属域执行 docker login（尤其群晖 GUI，容易配错）。

3.4 免费版

bash
docker pull docker.xuanyuan.me/nginx:latest

3.5 关于 registry-mirrors（兼容，非首选）

若环境只能改加速地址、无法改镜像名，可参考平台教程中的兼容写法，但须知失败会回退官方源。Linux / Desktop 细节见：

• Linux 配置
• Windows / Mac Docker Desktop
• OrbStack

生产与脚本更推荐第三节的显式域名 pull。

---

四、按场景打开官方配置教程

不要只改一处「万能 mirrors」。按你的环境点进对应文档（含截图与注意项）：

text
你的环境是？
├─ 还不会选登录还是专属域 → /usage/login 与 /usage/nologin
├─ Linux 未装 Docker     → /install/linux（一键脚本）
├─ Linux 已装 Docker     → /usage/linux
├─ Docker Desktop        → /usage/desktop
├─ Docker Compose        → /usage/docker-compose（image 写完整轩辕域名）
├─ K8s + containerd      → /usage/containerd
├─ K3s                   → /usage/k3s
├─ Podman                → /usage/podman
├─ 群晖 / 威联通 / 极空间等 → 下方 NAS 链接（优先专属域，禁止对专属域 login）
└─ 加速通了要部署业务     → https://xuanyuan.cloud/blog

---

五、Linux 一键安装 Docker

官方说明：Linux 一键安装

测试环境

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

生产环境（先审阅）

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

备用地址：

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

装好后仍建议按第三节用显式域名拉取，并完成专业版登录或专属域配置。脚本源码参考：xuanyuan_docker_proxy。

---

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

完整步骤：Docker Compose 配置

多仓库时各用对应专属域后缀；docker.io 可用公共登录域（需已 docker login docker.xuanyuan.run）或主专属域。

yaml
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
  # 若还有 GHCR 镜像，示例（替换 myprefix）：
  # app:
  #   image: myprefix-ghcr.xuanyuan.run/myorg/myapp:v2.0
volumes:
  redis-data:

bash
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/

---

七、拉取自检

bash
# 1) 公共登录域（专业版默认路径）
grep -q '"docker.xuanyuan.run"' ~/.docker/config.json || docker login docker.xuanyuan.run
docker pull docker.xuanyuan.run/library/alpine:3.20 && echo "login-domain OK" || echo "FAIL"

# 2) 主专属域免登录（将 myprefix 换成你的前缀）
# docker pull myprefix.xuanyuan.run/library/alpine:3.20 && echo "exclusive OK"

# 3) 免费版（仅 Hub）
# docker pull docker.xuanyuan.me/alpine:3.20 && echo "free OK"

失败时按第一节表格进入对应 FAQ，不要默认改回官方 docker.io 短名硬拉。服务边界：轩辕只支持公开镜像 pull，不支持 push、不支持私有仓库透传 PAT → 不支持 push、不支持私有镜像。

---

八、轩辕镜像技术博客：配好拉取后照着部署

轩辕镜像技术博客 以 Docker 部署教程 为主（另有安全公告等）。跟做前请先能用第三节方式稳定拉取；教程里的 image / docker pull 建议同样写成轩辕域名形式。

入口：https://xuanyuan.cloud/blog →「Docker部署教程」或搜索产品名。

---

九、企业生产 Checklist

---

十、FAQ

Q1：为什么不推荐只改 daemon.json？
registry-mirrors 失败会回退官方源，且不管 GHCR/K8s。见 mirrors 不生效。请改用第三节域名拉取，或按平台 Usage 配置。

Q2：K8s 配了本机 Docker 加速还是 ImagePullBackOff？
节点走 containerd/K3s，请按 containerd / K3s 配置；K8s 官方镜像域是 ***-k8s.xuanyuan.run，不是主专属域。

Q3：对 ***-ghcr.xuanyuan.run 做 docker login 填 GitHub PAT？
不要。专属域禁止 login；私有 GHCR 本身也不在支持范围 → 私有镜像说明。

Q4：博客教程里的镜像怎么拉？
把官方引用换成第三节的轩辕域名后再 pull / 写进 Compose；先保证第三节自检通过。

Q5：429 / 402？
429 多为限流；402 为流量用尽，前往 充值中心。

更多索引：FAQ 列表 · agents.md

---

总结

• 首选：docker.xuanyuan.run/...（一次性 login）或主专属域免登录；GHCR/K8s 用带正确后缀的专属域
• 慎用：把 registry-mirrors 当唯一手段
• 分平台：打开第四节官方 Usage，勿凭记忆改错配置文件
• 费用：充值 新人 ¥2.9 起，50GB ¥8；免费域仅体验 Hub
• 落地：拉取稳定后到 技术博客 跟做部署

立即开始：注册专业版 · 充值流量 · 登录拉取 · 专属域名 · agents.md · 技术博客