Docker 拉取镜像时出现 i/o timeout、context deadline exceeded 或长时间停留在某个 Layer，往往不只是“网速慢”这么简单。DNS、代理、防火墙、Docker 服务配置和镜像仓库状态都可能成为阻塞点。本文给出一套从定位故障到配置 Registry Mirror 的实用流程，帮助你快速恢复镜像拉取。🐳
一、先判断超时发生在哪一层 🔍
不要一遇到超时就立即更换镜像源，先执行以下命令观察完整报错：
docker pull nginx:alpine
docker info
docker version
如果错误包含 lookup registry-1.docker.io，通常应优先检查 DNS；如果包含 Client.Timeout exceeded 或 net/http: request canceled，可能是网络连接、代理或防火墙问题；如果返回 429 Too Many Requests，则属于访问频率限制，并非连接超时，可先执行 docker login 后重试。
还要确认镜像名称和标签是否存在。manifest unknown、pull access denied 分别更接近标签不存在和权限不足，配置 Mirror 通常无法解决。
二、按顺序完成基础网络排查 🧭
- 检查域名解析：执行 getent hosts registry-1.docker.io 或 nslookup registry-1.docker.io。若无法返回地址，应检查系统 DNS、网络管理器或企业内部解析策略。
- 测试 Registry 端点：执行 curl -I 来源链接。收到 401 Unauthorized 不一定是故障，它通常说明端点可达，只是访问需要鉴权。
- 检查系统时间：时间偏差可能导致 TLS 证书校验失败，可使用 timedatectl status 查看同步状态。
- 检查代理和防火墙：Docker Daemon 不一定自动继承当前终端中的代理变量。企业网络还可能限制 443 端口、SNI 或外部仓库域名，需要同时核对网关策略。
- 读取服务日志：在使用 systemd 的 Linux 上执行 journalctl -u docker --since "10 minutes ago"，通常能看到比命令行更完整的连接错误。
三、配置 Registry Mirror 加速 🚀
Registry Mirror 相当于 Docker Hub 的拉取缓存入口。首次请求时，Mirror 从上游获取内容并缓存，后续请求可直接从缓存返回，从而减少重复的外部网络访问。其工作原理和限制可参考 Docker 官方文档。
在 Linux 上编辑或创建 /etc/docker/daemon.json。请将示例地址替换为云服务商分配给你的专属加速地址，或由组织维护且已经验证可信的 Mirror：
{
"registry-mirrors": [
"https://mirror.example.com"
]
}
如果文件中已经存在日志驱动、数据目录等配置，应将 registry-mirrors 合并到原有 JSON 对象中，不能直接覆盖。JSON 不支持注释，也不能在最后一个字段后保留多余逗号。
保存后先校验格式，再重新加载服务：
python3 -m json.tool /etc/docker/daemon.json
sudo systemctl daemon-reload
sudo systemctl restart docker
如果 Docker 无法启动，应立即执行 systemctl status docker 和 journalctl -u docker -n 100，重点排查 JSON 语法错误、重复字段以及不受支持的配置项。
四、验证 Mirror 是否真正生效 ✅
执行以下命令确认 Docker 已读取配置：
docker info | grep -A 10 "Registry Mirrors"
看到配置的地址，只能证明配置已载入，还不能证明服务可用。建议继续拉取一个体积较小、标签明确的公共镜像进行实际验证：
docker pull busybox:latest
若仍然超时，可直接测试 Mirror 的 v2 接口并观察连接过程：
curl -I 来源链接
curl -v 来源链接
需要注意，Docker 的 registry-mirrors 主要面向 Docker Hub，不会自动加速 GHCR、Quay、MCR 或企业私有仓库。若问题出现在 Kubernetes 节点，还应确认容器运行时究竟是 Docker、containerd 还是 CRI-O，因为 containerd 通常需要单独配置，不能只修改 Docker 的 daemon.json。
五、代理环境下的补充配置 🌐
如果必须通过 HTTP 或 HTTPS 代理访问外网，应为 Docker Daemon 配置代理，而不是只在 Shell 中执行 export。使用 systemd 时，可创建 Docker 服务的代理覆盖配置，并设置 HTTP_PROXY、HTTPS_PROXY 与 NO_PROXY，随后执行 daemon-reload 和 restart。
NO_PROXY 中通常需要加入本机地址、内网域名、私有 Registry 和 Mirror 域名，避免内部流量绕行外部代理。修改完成后，可以通过 systemctl show --property=Environment docker 检查服务实际读取到的环境变量。
六、生产环境的安全与稳定建议 🛡️
- 优先使用企业自建缓存、云服务商专属加速地址或来源明确的服务，不要盲目复制长期无人维护的公共 Mirror 列表。
- 不要为了绕过证书错误随意配置 insecure-registries，否则传输链路可能失去 TLS 保护。内部仓库使用自签名证书时，更合理的办法是部署并信任内部 CA。
- 团队和 CI/CD 环境可部署 Registry Pull Through Cache，减少重复下载并提高可控性，但需要同步规划磁盘容量、缓存清理、访问控制和上游限流。
- 对关键镜像固定版本或摘要，避免长期依赖 latest 标签；同时结合镜像签名、漏洞扫描和来源审计，降低供应链风险。
总结 📌
排查 Docker 镜像拉取超时，应遵循“识别错误类型、检查 DNS 与连通性、核对代理和日志、配置可信 Mirror、重启并实际拉取验证”的顺序。Registry Mirror 能改善 Docker Hub 的访问效率，但它不能修复错误标签、权限不足、代理配置缺失或其他 Registry 的连接问题。只有把网络、运行时、镜像来源和安全策略逐层拆开检查，才能得到稳定、可维护的解决方案。
