Docker 配置镜像源后仍然 `pull` 失败：问题、原因与解决方案

文章目录

• • 引言：问题背景
  • 一、问题本质
  • • [daemon 配置](#daemon 配置)
    • [用户级 CLI 配置](#用户级 CLI 配置)
  • [二、为什么 `~/.docker/config.json` 会影响 `pull`](#二、为什么 ~/.docker/config.json 会影响 pull)
  • 三、判断方法
  • 四、解决方案
  • • [1. 仅拉公开镜像](#1. 仅拉公开镜像)
    • [2. 需要继续登录 Docker Hub](#2. 需要继续登录 Docker Hub)
    • [3. 保留备份](#3. 保留备份)
  • 五、需要避免的误解
  • • [1. 报错里出现 `registry-1.docker.io` 不代表镜像源没生效](#1. 报错里出现 registry-1.docker.io 不代表镜像源没生效)
    • [2. `~/.docker/config.json` 不是镜像源配置文件](#2. ~/.docker/config.json 不是镜像源配置文件)
  • 六、总结

引言：问题背景

在使用 Docker 时，可能会遇到这种情况：

已经在 /etc/docker/daemon.json 中配置了镜像源，docker info 里也能看到镜像源生效，但执行：

docker pull hello-world

仍然失败，报错类似：

Error response from daemon: Get "https://registry-1.docker.io/v2/": context deadline exceeded

但直接指定镜像源地址时，可以正常拉取：

docker pull m.daocloud.io/docker.io/library/hello-world:latest

终端输出类似：

latest: Pulling from hello-world
Digest: sha256:452a468a4bf985040037cb6d5392410206e47db9bf5b7278d281f94d1c2d0931
Status: Downloaded newer image for m.daocloud.io/docker.io/library/hello-world:latest
m.daocloud.io/docker.io/library/hello-world:latest

这种情况下，问题不一定出在镜像源本身，也可能出在当前用户的 Docker CLI 配置文件：

~/.docker/config.json

---

一、问题本质

Docker 常见的两类配置分别是：

daemon 配置

文件：

/etc/docker/daemon.json

作用：

• 配置镜像源
• 配置 DNS
• 配置 daemon 行为

用户级 CLI 配置

文件：

~/.docker/config.json

作用：

• 保存 Docker Hub 或私有仓库登录信息
• 保存凭证相关配置

因此，镜像源属于 daemon 层，但 docker pull 仍然会受到当前用户配置的影响。

---

二、为什么 ~/.docker/config.json 会影响 pull

如果这个文件里保存了 Docker Hub 的认证信息，例如：

{
  "auths": {
    "https://index.docker.io/v1/": {
      "auth": "..."
    }
  }
}

说明当前用户登录过 Docker Hub。

这不会修改镜像源地址，但会改变拉取时的认证上下文。

原本的匿名拉取，可能变成"带认证信息的拉取流程"。

在某些镜像源、网络环境或兼容实现下，这条带认证信息的链路可能失败，而匿名拉取反而成功。

---

三、判断方法

先确认镜像源本身是否已生效：

docker info

如果输出里有：

Registry Mirrors:
  https://docker.m.daocloud.io/

说明 daemon 镜像源配置已经生效。

接着，可以临时移走当前用户的 Docker 配置文件来验证：

mkdir -p ~/.docker
cp ~/.docker/config.json ~/.docker/config.json.bak
mv ~/.docker/config.json ~/.docker/config.json.tmp
docker pull hello-world

如果移走后 docker pull 恢复正常，就说明问题与：

~/.docker/config.json

高度相关。

---

四、解决方案

如果确认问题来自 ~/.docker/config.json，可以按下面方式处理。

1. 仅拉公开镜像

如果当前只是学习 Docker 或主要拉公开镜像，可以暂时不恢复这个文件，直接保持当前状态使用。

2. 需要继续登录 Docker Hub

如果后续还需要登录 Docker Hub，可以重新执行：

docker login

让 Docker 重新生成一份新的 ~/.docker/config.json。

3. 保留备份

原来的配置建议先保留备份：

~/.docker/config.json.bak

这样后续需要时还可以回看或恢复。

---

五、需要避免的误解

1. 报错里出现 registry-1.docker.io 不代表镜像源没生效

Docker 可能先尝试镜像源，失败后再回退到官方仓库，最后只显示官方仓库的错误。

2. ~/.docker/config.json 不是镜像源配置文件

它不会决定使用哪个 mirror，也不负责配置 registry-mirrors。

它影响的是当前用户访问 registry 时带不带认证信息。

---

六、总结

如果 Docker 已配置镜像源，但普通用户执行 docker pull 仍然失败，而移走：

~/.docker/config.json

后恢复正常，那么问题很可能不是镜像源本身，而是：

当前用户保存的 Docker Hub 认证信息干扰了 pull 流程。

最实用的处理方式是：

1. 先确认镜像源已生效
2. 临时移走 ~/.docker/config.json 做验证
3. 如果确认相关，再按需重新 docker login