做开发、搭环境的小伙伴肯定都遇到过这种崩溃时刻：
Docker拉取官方镜像慢到离谱，要么超时报错，要么中途断连，折腾半天连基础镜像都拉不下来，直接拖慢整个开发进度。
其实解决办法很简单——配置专属镜像源！今天给大家带来轩辕镜像源全平台配置教程，覆盖Linux（Ubuntu/CentOS通用）、Windows/Mac版Docker Desktop，甚至Mac专属轻量工具OrbStack，一步一图+命令复制即用，彻底告别镜像拉取卡顿！
📌 前置必备：获取轩辕专属域名
无论哪种系统、哪种Docker工具，配置前都要先获取轩辕专属域名，这是后续所有配置的核心：
- 登录轩辕镜像服务官网：
https://xuanyuan.cloud/； - 点击左侧菜单栏「专属域名」选项；
- 复制生成的专属域名，格式为：***.xuanyuan.run。
下文所有配置中的***.xuanyuan.run，务必替换成你自己的专属域名，否则配置无效！
🐧 Linux系统（Ubuntu/CentOS）配置教程
Linux服务器配置Docker镜像源，支持一键脚本全自动配置和手动命令配置两种方式，新手优先选一键脚本，省心无报错。
方式一：一键脚本配置（推荐，懒人必备）
脚本支持绝大多数Linux发行版，不仅能一键配置轩辕镜像源，还能顺带安装Docker、docker-compose，一行命令搞定所有：
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)
方式二：手动命令配置（自定义可控）
如果想手动管控配置文件，执行以下命令直接写入Docker守护进程配置：
echo '{
"registry-mirrors": ["https://***.xuanyuan.run"]
}' | sudo tee /etc/docker/daemon.json > /dev/null
Step 1：重载守护进程配置
修改配置文件后，先重载systemd守护进程，让系统识别新配置：
systemctl daemon-reload
Step 2：重启Docker服务生效
重启Docker使镜像源配置正式生效：
systemctl restart docker
Step 3：验证配置是否成功
执行以下命令，查看Registry Mirrors是否显示你的轩辕专属域名：
docker info | grep -A 10 "Registry Mirrors"
出现https://***.xuanyuan.run即为配置成功！
🚀 镜像拉取示例（轩辕镜像源）
配置完成后，直接用标准Docker命令拉取即可，默认走轩辕镜像源：
# 拉取MySQL镜像（建议指定版本，避免latest不稳定）
docker pull mysql:8.0
针对ghcr.io、quay.io等非官方仓库，需显性指定轩辕镜像地址拉取：
docker pull ***-ghcr.xuanyuan.run/org/image:tag
🖥️ Docker Desktop（Windows/Mac）配置教程
桌面版Docker操作全靠图形化界面，步骤极简，Windows和Mac端配置流程完全一致，跟着点就行。
Step 1：打开Docker Desktop设置
启动Docker Desktop，点击右上角齿轮形状的设置图标，进入Settings页面。
Step 2：配置Docker Engine
左侧菜单栏选择Docker Engine，在右侧JSON编辑框中，添加/修改以下配置（直接替换原有配置或合并）：
{
"registry-mirrors": [
"https://***.xuanyuan.run"
]
}
关键避坑：registry-mirrors必须加https://，格式错误会导致Docker启动失败！
Step 3：应用配置并重启
点击右下角Apply & Restart，等待Docker自动重启（耗时1-3分钟，耐心等待即可）。
Step 4：验证配置
打开Windows CMD/Mac终端，执行以下命令，查看镜像源是否生效：
docker info
在输出结果中找到「Registry Mirrors」，显示轩辕专属域名即成功。
🚀 桌面端拉取镜像示例
点击Docker Desktop右下角Terminal打开内置终端，执行拉取命令：
# 搜索镜像
docker search ***.xuanyuan.run/nginx
# 拉取指定版本镜像
docker pull ***.xuanyuan.run/nginx:1.25
🍎 Mac专属：OrbStack配置轩辕镜像源
Mac用户嫌弃Docker Desktop占用高、卡顿？推荐用轻量工具OrbStack，配置镜像源同样简单，支持图形化和手动改文件两种方式。
方式一：图形化配置（推荐）
- 点击Mac菜单栏OrbStack图标，选择Settings（快捷键⌘+,）；
- 左侧边栏点击Docker选项；
- 找到Advanced engine configuration；
- 在配置编辑器中添加轩辕镜像源，保存即可。
方式二：手动修改配置文件
打开终端，创建/编辑OrbStack配置文件：
vim ~/.orbstack/config/docker.json
写入以下配置（替换专属域名）：
{
"registry-mirrors": [
"***.xuanyuan.run"
]
}
重启OrbStack生效
- 图形化：菜单栏点击OrbStack图标，选择Restart；
- 终端命令：执行
orb restart。
验证配置
同Linux验证命令，出现轩辕镜像地址即为成功：
docker info | grep -A 10 "Registry Mirrors"
❓ 高频避坑：配置后仍走官方源？
很多小伙伴反馈：明明配了轩辕镜像源，拉取还是报错/走官方docker.io，90%的情况不是配置写错了，而是Docker的正常机制！下面把底层逻辑、高频场景和终极解决方案一次性讲透，适配Docker 20+/24+全版本。
核心逻辑：registry-mirrors不是「强制代理」
你可能误以为配置了镜像源，Docker就会全程走加速源，但事实是：registry-mirrors的核心是「优先尝试」，而非「强制代理」。
Docker完整拉取流程：
docker pull 镜像名
↓
优先请求配置的registry-mirror（轩辕镜像）
↓ 镜像源返回错误/无法访问
自动回退到官方仓库docker.io
↓ 国内网络无法访问官方仓库，请求超时
抛出超时报错
你看到的「访问官方仓库」，其实是Docker尝试镜像源失败后的容错回退，不是配置失效！
5个高频场景：为啥会触发回退机制？
场景1：镜像名称/标签错误，或官方不存在该镜像
轩辕镜像已实时同步Docker Hub，若拉取返回manifest unknown（404），大概率是：
- 镜像名/标签拼写错误（多字、少字、大小写/符号错误）；
- 该镜像/标签在Docker Hub官方已删除/下架。
此时Docker会判定「加速源无此镜像」，自动回退到官方仓库，最终要么404，要么因网络超时报错。
场景2：Docker版本过低（低于20.10+）
Docker Hub和轩辕镜像均采用Registry V2 API，低于20.10的Docker版本对V2接口兼容有缺陷，会误判「镜像不存在」触发回退。
自查命令：
docker version
版本低于20.10.x建议先升级。
场景3：配置确实未正确生效
少数情况是基础配置问题导致镜像源被忽略：
- 修改daemon.json后未重启Docker；
- JSON格式错误（末尾多逗号、括号不匹配）；
- 配置文件路径/权限错误，Docker无法读取。
一键排查配置是否生效：
docker info | grep "Registry Mirrors" -A 3
能看到轩辕镜像地址=配置生效，反之需修复配置文件/重启操作。
场景4：镜像源只对Docker Hub生效，第三方仓库不代理
划重点：registry-mirrors仅对官方docker.io生效！
拉取ghcr.io、quay.io、gcr.io等第三方仓库镜像时，Docker会直接访问原地址，完全不走轩辕镜像。比如：
# 不会走加速源，直接访问官方地址
docker pull ghcr.io/owner/repo:tag
需用轩辕专属加速域名显性拉取：
# ghcr.io专属加速
docker pull ***-ghcr.xuanyuan.run/org/image:tag
# quay.io专属加速
docker pull ***-quay.xuanyuan.run/coreos/etcd:latest
场景5：轩辕专属域名无可用流量
账号流量耗尽时，轩辕镜像会返回402 Payment Required错误，Docker判定「源不可用」后回退到官方仓库，看似「配置无效」，实则是流量问题。
2步快速排查：定位根因
步骤1：显式指定轩辕域名测试
直接用专属域名拉取基础镜像，测试源是否可用：
# 替换为你的专属域名
docker pull docker.xuanyuan.run/library/nginx:latest
- 能正常拉取：源没问题，问题在Docker回退机制；
- 报错：402查流量、404核对镜像名/标签、确认官方是否存在该镜像。
步骤2：确认配置是否加载
执行上文的排查命令，确认轩辕地址已在配置中。
终极解决方案：杜绝回退官方源
✅ 核心方案：显式指定轩辕域名拉取 这是100%规避回退的最优解，Docker会直接请求加速源，完全不碰官方仓库：
| 原始命令 | 轩辕加速命令 |
|---|---|
docker pull nginx:latest | docker pull docker.xuanyuan.run/library/nginx:latest |
docker pull mysql:8.0 | docker pull docker.xuanyuan.run/library/mysql:8.0 |
⚠️ 注意：Docker Hub官方镜像需加library前缀，否则会404。
✅ 补充方案1：第三方仓库用专属加速域名 拉取ghcr/quay/gcr等镜像，必须用对应专属域名，才能走加速通道。
✅ 补充方案2：确保流量充足 提前检查轩辕账号流量，及时充值，避免因402错误触发回退。
✨ 最后总结
- 配置轩辕镜像源后，必须重启Docker使配置生效；
registry-mirrors是「优先尝试」机制，Docker拉取失败会自动回退到官方仓库，并非配置失效；- 想要彻底杜绝回退问题，需显式指定轩辕专属域名拉取镜像，第三方仓库需用对应专属加速域名。
Docker镜像源配置是开发提速的基础操作，轩辕镜像源全平台适配，不管是Linux服务器、Windows/Mac桌面端，还是Mac轻量OrbStack，跟着本文步骤操作，5分钟就能搞定。
