Docker 26镜像加速器没生效？配置、排查与自建方案全解析

先问一个问题：你是不是也遇到过这种情况——网上搜到的教程让你编辑 /etc/docker/daemon.json，添加 registry-mirrors，你也照做了，docker info 里面甚至能看到 Registry Mirrors 这一项，但 docker pull 该超时还是超时，该失败还是失败？

如果你用的恰好是 Docker Engine 26.x，同时又是 Ubuntu/Debian 系系统，那这个问题确实很典型。Docker 26 本身在镜像拉取链路上做了一些调整，再加上这两年公共镜像加速器的存活率大幅下降，导致很多老教程里的“换源三板斧”完全失灵。这篇文章我就把从现象到根因、从标准解法到自建方案、从排查命令到常见报错，一次性讲清楚，尽量让你照着操作就能把问题解决，而不是继续在各种过时教程里打转。

1. 先搞清楚：镜像源没生效到底卡在哪一步

先说个很反直觉的事：很多人所谓的“换源没生效”，并不是配置写错了，而是“配置对了，但加速器本身已经死了”。两者表现一模一样，都是 pull 卡半天，最后报超时。如果不先把这个问题分层，后面很容易白忙活。

1.1 三种“配置了但等于没配置”的典型状况

我帮人排查时，遇到的状况基本可以归成三类。

第一类是 daemon.json 根本没被 Docker 读取。常见原因是文件路径不对，比如写到了 ~/.docker/daemon.json，Docker daemon 根本不会看这个位置；或者权限不对，文件属主、权限过于开放，dockerd 启动时直接拒绝加载；再或者是 JSON 格式不合法，比如加了注释、多打了逗号，导致解析失败。这类问题有一个共性特征：docker info 里看不到 Registry Mirrors 项。

第二类是配置确实被加载了，docker info 也能看到镜像源列表，但源本身已经失效。这种情况尤其迷惑人，因为你从配置层面看一切正常。2024 年以来，大量第三方公共镜像加速器陆续关闭、限制访问或者只能拉取白名单仓库，老教程里那些“magic 域名”现在很多已经变成摆设，甚至有的会给你返回一个 404 或者直接 TLS 握手失败。你改了配置但不换源，效果等于零。

第三类是配置加载了、源也健康，但 Docker 26 在 pull 时没有真正走镜像源。比如你开着系统的 HTTP 代理，但代理对 docker 相关的域名做了奇怪的处理；再比如你同时配置了多个镜像源，而 Docker 会按顺序挨个尝试，排在第一个的源已经失联，它会在那里等很久，看起来就像是“加速没生效”。这种情况在镜像源列表特别长的机器上尤其明显。

1.2 为什么 Docker 26 上这个问题尤其普遍

不是 Docker 26 故意刁难人，而是几件事赶在一起了。

一是 Docker 26 这个版本在 daemon 配置校验上更严格。旧版本里，daemon.json 如果格式有问题，可能只是静默跳过，服务还能起来；到了 26 版本，配置解析失败时，服务可能直接起不来，或者在 systemd 里反复重启。你看到一个 Docker 服务状态异常，第一反应往往是“我是不是装坏了”，而不是“我写的 JSON 是不是有问题”。

二是 Docker 26 引入了更多的 containerd 集成逻辑。如果开启了 containerd image store 特性，镜像存储和拉取链路会发生变化，某些时候 daemon.json 里的 registry-mirrors 依然生效，但由于 containerd 那边也有自己的端点配置，两者叠加反而容易让人摸不着头脑。如果你同时改过 /etc/containerd/config.toml，那问题会更隐蔽。

三是现在很多用户是“换源教程”和“系统源教程”混着看。你在搜索引擎里搜 docker 换源，出来的结果可能一半是教你换 apt 源，一半是教你换 pip 源，真正针对 Docker daemon 镜像加速的反而是少数。有些人甚至把阿里云的 apt 源地址填进了 registry-mirrors，那自然是完全无效的。

所以，别急着怪 Docker 26，先把上面这几层问题逐个排除，才是正经路子。

2. 标准姿势：把镜像加速器正确写进 daemon.json

不管你是 Docker 26 还是更老的版本，这一步都是地基。我见过太多人在这里翻车，所以尽量把细节写透。

2.1 先写对文件：一个能通过校验的 daemon.json

先说路径：Linux 上 Docker Engine 的配置文件是 /etc/docker/daemon.json，不是用户目录，也不是 /etc/default/docker。Debian/Ubuntu 如果装了 docker.io 包，某些版本可能用默认配置跑，没有这个文件，需要自己创建。

一个最简配置长这样：

json复制{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://docker.1ms.run",
    "https://dockerproxy.net"
  ]
}

注意，上面这些地址只是示例，我不保证它们现在还能用。正确做法是先用后面的“健康体检”方法测一下，把状态正常的地址填进去。另外一个很容易犯的错是：去网上复制配置时，把注释也带进来了。JSON 里不允许有注释，哪怕是一行 // 都会导致解析失败。所以写完务必校验一下，用 jq 最方便：

bash复制jq empty /etc/docker/daemon.json

没有 jq 就用 Python：

bash复制python3 -m json.tool /etc/docker/daemon.json

如果命令无输出、没有报错，说明格式没问题。只要这一步通过，就排除了一个很大的坑。

还有个小细节：registry-mirrors 是一个数组，顺序是有意义的。Docker 会从左到右依次尝试，如果第一个源失联，会等一段时间才去请求第二个。所以不要把一堆已经失效的源堆在前面，那相当于给自己加延迟。建议只保留 1 到 2 个验证过可用的地址，宁缺毋滥。

2.2 改完必须做这三步，否则等于没改

很多人改完配置就 systemctl restart docker，然后发现没用。其实关键是重启的顺序和验证方法。

第一步，重新加载 systemd 配置。如果 docker.service 的启动参数里引用了环境变量或 drop-in 文件，这一步能确保改动被识别：

bash复制sudo systemctl daemon-reload

第二步，重启 Docker 服务，顺手看下状态，别让重启失败被无视：

bash复制sudo systemctl restart docker
sudo systemctl status docker --no-pager -l

如果 restart 之后 Docker 没起来，用 journalctl 看具体报错：

bash复制journalctl -u docker -n 50 --no-pager

很多 daemon.json 语法错误、权限问题，在这里都会露出马脚。

第三步，看配置是否真的被加载：

bash复制docker info | grep -A 5 "Registry Mirrors"

正常情况会显示你的镜像源列表。如果没有这一项，说明 daemon.json 没被读取，回到 2.1 检查路径和文件权限。

最后，拉个小镜像实测。不要拉那种几百兆的，先拉一个几十兆的，比如：

bash复制time docker pull nginx:alpine

用 time 看真实耗时。如果秒级完成，那就是走的加速器；如果卡半天，继续往下看。

2.3 注意这个隐藏覆盖：docker.service 里的启动参数

这是一个非常冷门但真实存在的坑。某些第三方安装脚本、云平台镜像或者教程，会在 docker.service 的 ExecStart 里直接写上 --registry-mirror=https://xxx。而 dockerd 的规则是：命令行传入的 flag 优先级高于 daemon.json 里的同名配置。也就是说，你辛辛苦苦改了 daemon.json，结果启动时被命令行参数覆盖了。

检查方法：

bash复制systemctl cat docker.service

重点看 ExecStart 行，如果发现带 --registry-mirror，那就要么把启动参数改掉，要么把 drop-in 配置放在 /etc/systemd/system/docker.service.d/ 下覆盖原设置。实际上，我个人更推荐后者，因为第三方脚本一旦更新，改动的原始 service 文件会被重置，drop-in 文件不会被覆盖。

另外，Debian/Ubuntu 上还有一个 /etc/default/docker 的老配置路径，里面可能设置 DOCKER_OPTS="--registry-mirror=..."。Docker 26 时代这个文件默认已经不在启动链路里，但有些早期教程会教人改这里，如果你改了，建议删掉或注释，避免干扰。

3. 加速器本身失效了怎么办：从选源到自建

现在再处理最让人头疼的情况：配置没问题、daemon.json 也加载了，但就是没有加速效果。大概率就是源本身出了问题。这时候不要急着去搜“最新可用镜像源”，先学会自己判断一个源是否健康，比收藏任何列表都管用。

3.1 先给加速器做个“健康体检”

判断一个 registry mirror 是否能用，最直接的方法是请求它的 /v2/ 端点。一个健康的镜像加速器，对这个路径的响应通常不是 200 就是 401，最差也是 403；如果返回 404、连接超时、TLS 握手失败，那基本可以断定它已经废了。

用 curl 测一下：

bash复制curl -I -s -m 10 https://你选的加速地址/v2/ | head -n 1

比如：

bash复制curl -I -s -m 10 https://docker.m.daocloud.io/v2/ | head -n 1

如果返回 HTTP/2 200 或者 HTTP/1.1 200 OK，说明这个源还活着。如果卡到超时，或者报 Could not resolve host、Failed to connect，那就换下一个。这个方法远比看博客里的“可用列表”靠谱，因为公共源的存活状态真的是一天一变。

顺便提醒一下，有些加速器为了防滥用，会限制匿名拉取的仓库范围，或者对某些大镜像限流。你测 /v2/ 是通的，不代表所有镜像都能拉得动。最稳的验证方式仍然是实际 docker pull 一个你常用的小镜像。

3.2 自建一个 pull-through cache 镜像加速

如果你有台长期开机的服务器（哪怕是 2C4G 的小机器），我强烈建议自己搭一个 pull-through cache 镜像加速。这玩意儿其实就是 Docker Registry 的代理缓存功能，它本身不存镜像，而是你在启动 registry 时指定一个上游地址，比如官方 Docker Hub。请求过来时，它从上游拉取，然后在本地磁盘上缓存一份。同一个镜像第二次拉取，直接命中本地，速度飞快。

好处是显而易见的：不受第三方公共源关停的影响，拉取热门镜像时内网速度极快，而且配置一次之后一劳永逸。我甚至拿一台不用的旧机器跑过，磁盘占用其实还好，运行几年下来缓存也就几十 GB。

自建命令极简，跑一个容器就行：

bash复制docker run -d \
  --name registry-mirror \
  --restart=always \
  -p 5000:5000 \
  -e REGISTRY_PROXY_REMOTEURL=https://registry-1.docker.io \
  -v /data/registry:/var/lib/registry \
  registry:2

注意，这里 -p 5000:5000 暴露的是本机端口。如果你只是自己这台机器用，daemon.json 里可以这样配置：

json复制{
  "registry-mirrors": [
    "http://127.0.0.1:5000"
  ]
}

默认情况下，Docker 对 127.0.0.1 这个本地回环地址是允许走 HTTP 的，不需要额外搞证书。如果你想让局域网内其他机器也用，那就把地址改成 http://你的服务器IP:5000，但这时候就要在每台客户机的 daemon.json 里把该地址加进 insecure-registries，否则 Docker 会拒绝用 HTTP 访问。

这个方案还有个额外好处：如果是公司或团队内用，几台机器共用同一个 cache，拉镜像占用的公网带宽会明显下降。我自己在团队里推广之后，CI 拉镜像的速度肉眼可见地变快了。

3.3 团队内网场景：给 dockerd 配置 HTTP_PROXY

自建 registry mirror 适合“多机共享缓存”的场景，但还有一种场景是：你机器访问公网本身就要走团队统一出口，或者内网对公网访问本来就受限。这种情况下，与其折腾镜像源，不如直接在 daemon 层让 dockerd 走内网代理。注意，我这里说的是正常的企业内网出口或办公网络代理，属于常规运维操作，不是让你去折腾奇奇怪怪的通道。

Docker daemon 的代理配置和普通 shell 环境变量是两回事。你在 ~/.bashrc 里 export 一个 HTTP_PROXY，对 dockerd 完全不起作用，因为 dockerd 是 systemd 管理的服务，得通过 systemd 的 drop-in 注入环境变量。

创建目录和配置文件：

bash复制sudo mkdir -p /etc/systemd/system/docker.service.d

然后编辑 /etc/systemd/system/docker.service.d/http-proxy.conf：

ini复制[Service]
Environment="HTTP_PROXY=http://你的内网代理IP:端口"
Environment="HTTPS_PROXY=http://你的内网代理IP:端口"
Environment="NO_PROXY=localhost,127.0.0.1,.local,你的内部镜像仓库域名"

接着同样执行：

bash复制sudo systemctl daemon-reload
sudo systemctl restart docker

这时候 docker pull nginx 时，镜像请求会通过内网代理出去。NO_PROXY 必须把内网需要直连的地址排除掉，否则你连内部私有仓库都会走代理，反而可能失败。这个方法在云服务器、内网办公环境里都非常实用，很多人只给 shell 配了代理，忘了底层 daemon 才是真正需要出口的那个进程。

4. 排查实录：六步定位 + 常见报错对照

有句话叫“会排查的人不会乱改”。把下面这套流程走完，大多数换源不生效的问题都能定位到具体环节。我建议把这六步当成肌肉记忆，以后不管 Docker 升到哪个版本，都拿这套逻辑去套。

4.1 六步排查清单，照着敲一遍

第一步，确认 Docker 版本和运行状态：

bash复制docker version
systemctl status docker --no-pager -l

确认你确实跑的是 Docker Engine 26.x，别拿 docker compose 的版本号来替代。如果服务根本没起来，后面就不用看了，先解决服务问题。

第二步，查看当前 daemon.json：

bash复制cat /etc/docker/daemon.json

重点看它是否存在、属主是否为 root、格式是否合法。顺手执行：

bash复制jq empty /etc/docker/daemon.json

第三步，看 Docker 启动日志有没有报错：

bash复制journalctl -u docker -n 100 --no-pager

关键词是 parse、error、invalid、permission。如果日志里提示 daemon.json 解析失败，那问题就在文件本身。

第四步，看镜像源是否真的加载：

bash复制docker info | grep -A 5 "Registry Mirrors"

不是看文件里写了什么，而是看运行时实际加载了什么。这一步最容易看出“配置没生效”和“配置生效但源挂了”的区别。

第五步，测源的健康状态：

bash复制curl -I -s -m 10 你的加速地址/v2/ | head -n 1

如果前面几步都对，但这里不通，那就是源的问题，不是你的问题。

第六步，实际 pull 一个镜像并计时：

bash复制time docker pull busybox:latest

如果 busybox 这种几 MB 的镜像都要卡几十秒，那肯定没走加速；如果秒下，说明链路通了，问题解决。

这六步里的每一步都能单独定位一层问题，哪怕最后没解决，至少你能准确告诉别人“我卡在哪一步”，而不是笼统说“换源没生效”。

4.2 高频报错速查表

下面这个表格是我根据实际经验整理的，不一定能覆盖全部报错，但覆盖了我见过最多的几种情况。

这里重点说下第四行的 http: server gave HTTP response to HTTPS client，这个报错在自建缓存时非常常见。如果你在 daemon.json 里写的是 http://你的服务器IP:5000，那就必须在同一个文件里加上：

json复制{
  "insecure-registries": [
    "你的服务器IP:5000"
  ],
  "registry-mirrors": [
    "http://你的服务器IP:5000"
  ]
}

否则 Docker 会固执地用 HTTPS 去访问这个 HTTP 端口，然后报上面的错。我第一次搭 pull-through cache 时就被这个绕了一下，当时还以为是 registry 容器没跑起来。

4.3 Docker Desktop 上的同款问题

Windows/macOS 用户遇到这个问题更迷惑，因为 Docker Desktop 有图形界面，你会在设置界面里看到一个镜像加速配置框，填了半天却发现 pull 依然很慢。

Docker Desktop 的配置逻辑是这样的：你填的地址会写入一个内部生成的 daemon.json，然后重启 Docker Engine。但如果你之前手动改过 WSL2 里的 /etc/docker/daemon.json，或者 Desktop 版本升级时把配置重置了，就可能出现“设置页面显示已保存，实际不生效”的情况。

Docker Desktop 用户我建议这样处理：打开 Dashboard，进入 Settings，找到 Docker Engine 标签页，直接在 JSON 编辑框里改，不要在外面用编辑器改 WSL 内部文件。改完点击 Apply & Restart。注意看右下角有没有提示重启失败，如果失败，十有八九是 JSON 写错了。Windows 下这个编辑框对注释和尾逗号的容忍度极低，你从网上复制配置时千万看清楚。

另外，Docker Desktop 4.x 里有一个实验特性叫 “Use containerd for pulling and storing images”。我第一次用的时候也踩了坑：开了这个开关后，某些版本的 Desktop 对 registry-mirrors 的支持会有问题，表现为镜像源列表里能看到配置，但拉取时仍然直连官方源。如果你开了这个特性且换源无效，可以先把它关掉，再把配置重写一遍、重启。这不是让你永远不用这个功能，而是先排除干扰项。

5. 我用下来最省心的几个习惯

如果你已经照着上面的步骤把问题解决了，那剩下的内容可以当经验笔记看。这几个习惯是我踩了不少坑才养成的，写在这里希望对你有用。

5.1 镜像加速器放几个才有性价比

我之前在一台机器上放过 5 个公共加速器，觉得“多放几个总有一个能用”。结果恰恰相反，因为 Docker 会按顺序逐个尝试，排第一的源如果连接超时，它会卡很长一段时间才跳到第二个。我第一次遇到这个情况，还以为是配置写错了，最后才发现是被失联的源拖慢了节奏。

所以我的习惯是：公共源只保留 1 个验证过可用的；如果加自建 cache，就再加一个 http://127.0.0.1:5000，把自建 cache 放在第一位。这样每次拉镜像都会先命中本机缓存，没有缓存才去公共源，速度最稳。与其堆一堆源，不如把一两个源头彻底搞通。

5.2 几个容易忽略的细节

配置文件改完一定要做语法校验。我见过太多人把网上的配置直接粘贴过来，结果里面混了注释、全角冒号，甚至还有括号不匹配的情况。Docker 26 对这种错误很严格，服务起不来算好的，最怕的是起起来了但配置没生效，你排查半天才发现是多了个逗号。

还有一个容易被忽略的点：daemon.json 的权限。通常来说它应该属于 root，权限 0644 就够了。如果出现 permission denied 或者 unable to configure the Docker daemon with file /etc/docker/daemon.json 这类报错，先检查文件属主和权限，别急着怀疑 Docker 版本。

最后再说一个和镜像源无关但经常让人误会的点：docker pull 慢不一定是源的问题，也可能是你拉取的镜像特别大，或者本地磁盘 IO 慢。判断方法很简单，先拉一个 busybox 试试，秒下说明网络没问题；再拉你的目标镜像，如果特别慢，就要区分是网络问题还是镜像本身太大。

5.3 我最后悔没早点知道的一招

如果你有一台长期在线的服务器，别把它只当成“自建镜像源的机器”，完全可以再把另一个服务搭起来：把公共加速器列表用脚本定时测一遍，把不可用的自动从 daemon.json 里摘掉，可用性结果推送到通知里。这听起来有点小题大做，但说实话，自从我做了这个定时检查，就再也没被“今天还能用、明天突然挂了”的公共源坑过。

脚本逻辑不复杂，核心就是定时 curl 几个候选地址的 /v2/，把能通的结果拼成 JSON，写入 /etc/docker/daemon.json，然后 systemctl reload docker。注意是 reload 不是 restart，reload 对 Docker daemon 来说会重新加载配置，不停现有容器，影响要小得多。当然，如果改了 registry-mirrors，reload 是否完全生效要看版本，保险起见建议 restart。这个脚本你不用抄我的，按你实际环境习惯调整就行，重点是思路：别把加速器列表当成一次配置、终身有效的东西。