跳到主要内容

阿里云 ECS 上 Docker Hub 拉取失败的处理记录

问题背景​

在阿里云服务器上直接拉取 Docker Hub 镜像时，常见现象包括：

  • docker pull 很慢
  • 拉取过程中超时
  • 反复重试后仍然失败
  • 某些镜像在本地网络正常，但在云服务器上无法稳定下载

这类问题很多时候不是 Docker 本身损坏，而是访问 Docker Hub 的链路较慢或不稳定。

阿里云官方给出的一个常见处理办法，是先为当前账号获取 ACR 镜像加速器地址，再把它配置到 Docker 或 Containerd 中。

官方文档：

先说结论​

如果只是想先把机器拉起来、让 docker pull 别再卡死，最实用的做法是：

  1. 在阿里云容器镜像服务 ACR 控制台里获取你自己的镜像加速器地址
  2. 把这个地址写进 Docker 的 daemon.json
  3. 重启 Docker
  4. 用 docker info 和一次实际拉取确认是否生效

重要限制​

阿里云官方文档里有一个必须注意的点：

  • ACR 镜像加速目前已经停止同步最新镜像
  • 如果你依赖 latest 标签，拉到的镜像不一定是最新版本
  • 如果某个镜像始终拉不到，或者你明确需要最新版本，这个方案未必可靠

官方给出的替代方向主要有两个：

  • 在 ACR 中订阅海外源镜像
  • 使用全球加速 GA 直接加速海外源访问

所以这篇记录更适合下面这种场景：

  • 个人开发
  • 临时排障
  • 快速恢复 Docker Hub 拉取能力

如果是生产环境，最好不要把对 Docker Hub 的访问稳定性完全寄托在这个方案上。

步骤一：获取 ACR 镜像加速器地址​

按官方文档的路径进入控制台：

  1. 登录阿里云容器镜像服务控制台
  2. 进入：镜像工具 > 镜像加速器
  3. 复制当前账号对应的加速器地址

这个地址通常形如：

https://<your-id>.mirror.aliyuncs.com

步骤二：配置 Docker 镜像加速器​

如果你使用的是较新的 Docker 版本，直接改 /etc/docker/daemon.json 就够了。

推荐配置​

{
  "registry-mirrors": ["https://<your-id>.mirror.aliyuncs.com"]
}

实际操作​

sudo mkdir -p /etc/docker
sudo tee /etc/docker/daemon.json <<'EOF'
{
  "registry-mirrors": ["https://<your-id>.mirror.aliyuncs.com"]
}
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

验证是否生效​

docker info
docker pull ubuntu:22.04

检查 docker info 的输出里是否出现 Registry Mirrors，再看实际拉取是否恢复正常。

如果你用的是 Containerd​

官方文档也给了 Containerd 的处理方式，核心思路是：

  1. 确认 /etc/containerd/config.toml 里已经配置了 config_path
  2. 清理旧的 mirror 配置，避免冲突
  3. 创建 docker.io/hosts.toml
  4. 重启 Containerd

一个常见配置形态如下。

1. 确认 config_path​

[plugins."io.containerd.grpc.v1.cri".registry]
  config_path = "/etc/containerd/certs.d"

2. 创建 hosts.toml​

文件路径：

/etc/containerd/certs.d/docker.io/hosts.toml

文件内容：

server = "https://registry-1.docker.io"

[host."https://<your-id>.mirror.aliyuncs.com"]
  capabilities = ["pull", "resolve", "push"]

3. 重启并排错​

sudo systemctl restart containerd
sudo journalctl -u containerd

如果启动失败，优先检查是不是旧的 mirror 配置还残留在 config.toml 里。

我更建议的使用方式​

实际使用里，建议把这个方案理解成“先恢复可用”，而不是“永久解决 Docker Hub 问题”。

比较稳妥的做法是：

  • 基础镜像尽量固定明确版本，不要依赖 latest
  • 对常用镜像提前缓存或同步到自己的仓库
  • 生产环境尽量减少对 Docker Hub 直连的依赖

最小可用排障流程​

如果以后再遇到“阿里云上 Docker Hub 拉不动”，可以直接按这个顺序排查：

  1. 先确认机器本身能正常联网
  2. 进入 ACR 控制台复制镜像加速器地址
  3. 配置 /etc/docker/daemon.json
  4. 重启 Docker
  5. 执行 docker info
  6. 实际拉一个小镜像验证，例如 ubuntu:22.04
  7. 如果还是不行，再考虑是否切换到 ACR 订阅海外源或 GA

参考​