先对号入座

docker pull 出问题，症状基本就三类，解法完全不同。先花十秒确认是哪一种，能省掉大量"换了好几个源还是不行"的折腾。

第三类最容易被误判。很多人看到报错第一反应是"源又挂了"，然后一个个换地址试，其实只是把 nginx 写成了 ngnix。

镜像加速不是"翻墙"

这点必须先说清楚，否则后面全是误解。

镜像加速做的事情是：你向加速服务要 nginx:latest，它去上游帮你取回来，再给你。你连的是国内节点，它连的是境外源。整个过程中，你的流量没有"出去"，只是换了个中转站。

所以它有两个天然的边界：

只能加速它代理了的仓库。 这是最关键的一条，也是免费和付费真正的分界线。公共公益入口基本只镜像 Docker Hub（docker.io）；专业版的专属域名则按前缀覆盖了一整排仓库——ghcr.io 加 -ghcr、registry.k8s.io 加 -k8s、quay.io 加 -quay，还有 GCR、NVCR、MCR、Elastic、GitLab。

换句话说，你要装的那个套件，只要有一个基础镜像不在 Docker Hub 上，公共入口就帮不上忙——这不是配置错了，是它根本没那个仓库。

它不改变你本机的网络环境。 配完加速，浏览器该打不开还是打不开，其他软件该慢还是慢。

理解这两条，后面选方案就不会走弯路。

四类方案，2026 年的实际差距

市面上能用的就那么几种，把成本和边界摊开看：

第二列和第三列是要害。100 次/小时听着够用，实际很容易撞：一个镜像按层算请求，docker compose up 拉起五六个服务，一次就吃掉几十次；CI 里并发跑两个构建，基本必撞。撞了之后不是"慢一点"，是接下来几小时都用不了。

说句实在话：自建听起来最"硬核"，但对个人用户基本不划算。Harbor 本身要一台常开的机器、要存储、要定期清理，而且它自己也得从上游拉——上游不通，缓存里没有的镜像照样拉不到。只有镜像种类相对固定、团队规模上来了，自建才回本。

算一笔账：折腾的成本有多高

不谈感受，算三个具体场景：

场景一，家里 NAS 装套件。 一个影视管理套件，镜像 1.2G，公益源跑到一半断流，重试三次才成功，前后四十分钟。这四十分钟你在旁边等，或者反复点重试。一年装十个套件，就是六七个晚上。

场景二，小团队共用。 六个人，每个人各自找源、各自踩坑、各自在群里问"你们那边能拉吗"。真出问题时，讨论成本比订阅费高得多。

场景三，生产环境。 上线窗口里基础镜像拉不下来，回滚也来不及。这时候的损失不是几百块能比的。

这三种情况里，付费解决的都不是"快一点"，而是**“不用再想这件事”**。这是它和免费方案最本质的区别——免费方案的隐性成本是把注意力长期挂在上面。

最短配置路径：NAS

NAS 用户占这类需求的一大半，先说这个。

群晖

群晖用户完全不用碰命令行，全程图形界面：进 Container Manager（DSM 7.2 之前的名字是 Docker），左侧切到「注册表」，右上角「设置」里新增一条，URL 填 你的前缀.xuanyuan.run，账号密码空着，点「测试连接」，通了就保存。

之后在「注册表」搜关键字、右键下载映像、填 tag，走的已经是加速通道，不需要再做别的。

如果卡在"测试连接失败"，八成是两个原因：系统里开了代理（国内节点反而被绕远了），或者 DNS 解析不到。前者去控制面板关掉代理，后者把 DNS 换成 223.5.5.5。

其他品牌

都是填同一个地址、账号密码留空、保存后重启容器服务。个别老固件的图形界面没这项，需要 SSH 改配置文件，字段名和 Linux 一致。

最短配置路径：Windows / Mac

Docker Desktop 里改一处：

Settings → Docker Engine，在 JSON 里加：

{
  "registry-mirrors": ["https://你的前缀.xuanyuan.run"]
}

点 Apply & Restart，等鲸鱼图标重新变绿。

注意：这是在原有 JSON 里加一行，不是整段替换。把 data-root、experimental 之类的字段清掉，Docker 可能直接起不来。

最短配置路径：Linux 服务器

不想手动改的，一条命令：

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

它会装 Docker、写 daemon.json、重启服务、验证一遍，国产系统（统信 UOS、麒麟、openEuler、TencentOS 等）也覆盖。

喜欢自己动手的，改 /etc/docker/daemon.json：

{
  "registry-mirrors": ["https://你的前缀.xuanyuan.run"]
}

然后 sudo systemctl daemon-reload && sudo systemctl restart docker。

验证只看一眼：docker info | grep -A 3 "Registry Mirrors"，能看到你的域名就成了。

配完还是慢

四个地方按顺序看：

1. 配置真的读到了吗：docker info 里没有你的域名，说明 JSON 写错了（多一个逗号、多一行注释都会让 Docker 拒绝加载）。
2. 拉的是不是 Docker Hub 的镜像：ghcr.io、quay.io 开头的不走 registry-mirrors，要么用前缀域名，要么别指望它变快。
3. 本地是不是已经有旧镜像：docker pull 会优先用本地缓存，看不出速度差异。加 --pull always 强制走网络再测。
4. 是不是流量用完了：返回 402 就是流量耗尽，和配置无关，单独测一次 docker pull 你的前缀.xuanyuan.run/library/busybox:latest 就能确认。

什么时候值得花钱

没有统一答案，按三条判断：

一看有没有人替你负责。 公共入口出问题时，你只能等，或者换一个再等。生产环境停了业务，这个成本远高于订阅费。

二看是不是团队在用。 一个人折腾，免费足够；十几个人共用一个不稳定的入口，每天有人来问"镜像拉不下来"，隐性成本很快超过付费。

三看要不要拉非 Docker Hub 的镜像。 只要你用过 ghcr.io 或 registry.k8s.io，这一条基本就直接指向专业版了——免费入口没有这些仓库，不是慢，是根本没有。

三条里中任意一条，就值得；一条都不中，说明你确实用不上，别花这个钱。

文中用到的专属域名来自 轩辕镜像，运营方是境内正规企业，镜像经过合规审核，属于"有主体可追责"的那一类，机构用户过审计会容易很多。

• 各平台配置入口汇总：https://xuanyuan.cloud/usage?source=linkedbus
• 常见报错与配置问题：https://xuanyuan.cloud/faq?source=linkedbus
• 专业版开通：https://xuanyuan.cloud/?source=linkedbus

三个常见误解

“配了加速器就等于有了梯子。” 不是。它只代理镜像仓库，浏览器、其他软件都不受影响。

“换的源越多越好。” registry-mirrors 里堆十几个地址不会更快，Docker 是按顺序试的，前面几个挂了反而拖慢。一个稳定的专属域名，比五个时好时坏的公益地址可靠。

“免费入口能拉，干嘛还买专业版。” 如果你一年只装两三个套件、只用 Docker Hub 的镜像，确实没必要。但只要你开始碰 GHCR 的镜像、开始被 429 卡住、或者有第二台机器要配，免费入口就会从"能用"变成"每天要检查一遍的东西"。

想深入配置的看这篇

上面只覆盖了最常见的几种设备。如果你要在 Kubernetes 里配 containerd、用 Podman、或者需要企业级的多仓库 fallback 和检查清单，这里有一篇按运行时逐个讲透的：

→ Docker 镜像源加速配置指南（2026）

那篇偏"怎么配、配错怎么查"，这篇偏"该不该配、选哪个"。两边内容不重复，按需取用。

本文会随可用方案变化持续更新。遇到具体报错，建议一并说明设备型号、系统版本和完整错误信息，比"拉不下来"更容易定位。