Containerd 镜像拉取失败问题分析与解决方案

问题背景

在使用 Containerd 容器运行时拉取镜像时，用户可能会遇到拉取失败的问题，特别是在设置了网络环境变量的情况下。典型的错误表现为连接超时，例如 dial tcp 199.59.148.20:443: i/o timeout，即使通过 curl 命令测试网络连接是正常的。

问题分析

网络设置机制

Containerd 的镜像拉取过程实际上由两个组件共同完成：

1. containerd 守护进程：负责管理容器生命周期
2. ctr 客户端工具：执行具体的镜像拉取操作

关键点在于，实际的 HTTP/HTTPS 请求是由 ctr 工具发起的，而不是 containerd 守护进程。因此，仅仅为 containerd 设置网络环境变量是不够的。

常见误区

许多用户会通过 systemd 服务文件为 containerd 设置网络：

[Service]
Environment="HTTP_NETWORK=http://network.example.com:8080"
Environment="HTTPS_NETWORK=http://network.example.com:8080"

但这种设置只影响 containerd 守护进程本身，不会影响 ctr 命令的执行环境。

解决方案

正确设置网络的方法

1. 为当前会话设置环境变量：

export HTTP_NETWORK=http://network.example.com:8080
export HTTPS_NETWORK=http://network.example.com:8080
ctr images pull docker.io/library/nginx:alpine

2. 通过 sudo 保留环境变量：

sudo -E ctr images pull docker.io/library/nginx:alpine

-E 参数会保留当前用户的环境变量。

3. 配置系统级环境变量： 在 /etc/environment 文件中添加：

HTTP_NETWORK=http://network.example.com:8080
HTTPS_NETWORK=http://network.example.com:8080
NO_NETWORK=localhost,127.0.0.1

网络验证技巧

1. 检查实际生效的环境变量：

cat /proc/$(pgrep -f ctr)/environ | tr '\0' '\n' | grep -i network

2. 测试网络连接：

curl -v -x http://network.example.com:8080 https://registry-1.docker.io/v2/

高级配置

对于需要长期稳定使用网络的环境，可以考虑以下方案：

1. 配置 Containerd 的 registry 镜像： 在 /etc/containerd/config.toml 中添加：

[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
    endpoint = ["https://registry-1.docker.io"]

2. 使用网络自动发现协议： 某些网络环境支持 WPAD 协议，可以配置：

export HTTP_NETWORK=wpad://
export HTTPS_NETWORK=wpad://

常见问题排查

1. 网络不支持 HTTPS：

   • 现象：HTTP 网站可以访问，HTTPS 失败
   • 解决方案：确保网络服务器支持 HTTPS 隧道

2. 证书问题：

   • 现象：SSL 证书验证失败
   • 解决方案：将网络的 CA 证书添加到系统信任链

3. 网络认证问题：

   • 现象：返回 407 网络认证要求
   • 解决方案：在网络地址中包含认证信息：

   export HTTPS_NETWORK=http://username:[e-mail]:8080
   

总结

Containerd 镜像拉取的网络配置需要注意客户端工具与守护进程的区别。正确的做法是确保执行 ctr 命令的环境中有正确的网络设置。对于生产环境，建议采用系统级的网络配置方案，并结合 registry 镜像设置，以获得稳定可靠的镜像拉取体验。