阿里云 docker 镜像加速器配置与拉取超时排查

拉取镜像常被当成容器化流程里最不起眼的一步，却往往是最先拖慢节奏的地方。国内网络直连境外镜像仓库时，超时、中断和速度慢都很常见。阿里云docker镜像加速服务就是为这类问题准备的。

为什么需要镜像加速

Docker 默认从 Docker Hub 拉取公共镜像。国内直连时链路长、延迟高、丢包多，一个几百 MB 的基础镜像可能要等几分钟，中途失败还得重来。团队变大后问题会放大：CI/CD 每次构建都在重复拉同一批基础镜像。

加速的做法是在境内放一层缓存节点，由它代为拉取并缓存热门镜像，客户端改为访问离自己更近的地址。频繁拉取基础镜像的场景，效果通常最明显。如果服务器一天只拉一两次镜像，感受不会那么强。

阿里云会给每个账号分配独立的加速地址，格式一般是 <账号前缀>.mirror.aliyuncs.com。

以 Linux 服务器为例，建议把配置写进 /etc/docker/daemon.json。文件可以纳入版本管理，也不会因为各机器的环境变量不同而表现不一致。

第一步，创建目录并写入配置：

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

把 <your-id> 换成控制台里显示的专属前缀。注意 tee 会直接覆盖原文件。如果 daemon.json 里已经有日志驱动、存储路径之类的配置，要把 registry-mirrors 合并进同一个 JSON 对象，否则会影响已有服务。

第二步，重新加载配置并重启 Docker：

sudo systemctl daemon-reload
sudo systemctl restart docker

只改文件不会生效，必须重启。

第三步，验证加速器是否生效：

docker info | grep -A 2 "Registry Mirrors"

输出里出现刚才配置的地址，说明客户端已经识别。再执行一次 docker pull nginx:alpine，和改造前的耗时对比一下，差别一眼就能看出来。

某中型团队的后端由十多个微服务组成，每个服务的 Dockerfile 都基于同一个 Node.js 基础镜像。CI 流水线每次都在干净的构建节点上重新拉取。改造前，拉取步骤经常超时失败，工程师只能手动重跑，一次完整构建的耗时忽长忽短。

他们分三步处理：

在所有构建节点上统一写入加速器配置，通过配置管理工具分发，避免某台机器漏配。
把 Dockerfile 里的基础镜像固定到明确的版本标签，不再使用 latest。同一个标签在不同时间可能指向不同内容，固定版本后，构建结果更容易复现，出了问题也更好查。
把高频使用的基础镜像同步一份到自己在阿里云容器镜像服务中的命名空间，构建时直接从境内仓库拉取。

调整后，因拉取失败而重跑的次数明显减少，构建时长的波动也收窄了。这里加速器只解决了网络那一段。配置统一和版本固定做到位，拉取问题才真正少下来。

配置生效后仍然拉取缓慢或失败，可以按下面的顺序排查：

JSON 格式错误。daemon.json 对格式很敏感，多一个逗号，Docker 就起不来。改完先用 python3 -m json.tool /etc/docker/daemon.json 校验一遍。
地址填错。确认用的是控制台里的专属地址，检查协议头和域名后面有没有多余字符。
没有重启服务。只改文件不生效，执行 sudo systemctl restart docker 后再测。
镜像名指定了其他仓库。加速器对 Docker Hub 的镜像有效。如果镜像名里写了别的仓库域名，加速器不会介入，需要单独处理那个仓库的访问。
代理干扰。服务器如果配了全局 HTTP 代理，可能与加速地址冲突。检查 Docker 服务 systemd 单元里的环境变量，看是否有代理设置。

每一步的命令输出都保留下来。有原始输出，定位问题才快，团队复盘时也有依据。