开学季与项目交付高峰叠加，开发机、云主机、家里 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 免费版

bashdocker 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 一键安装

测试环境

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

生产环境（先审阅）

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

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

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

完整步骤：Docker Compose 配置

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

yamlservices:
  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:

bashmkdir -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 ·  技术博客