新加坡服务器拉取容器镜像失败,如何区分DNS故障与镜像仓库连接异常
镜像拉取失败时,首先要区分是“仓库域名无法解析”,还是“域名已解析,但服务器无法连到仓库或其后端”。两类故障的表象可能相同:Docker 或 containerd 报超时、连接失败,应用部署因此停滞。单看一条 pull 错误通常不足以定因,需要结合 DNS 查询、TCP 连接、TLS 响应和运行时日志逐层判断。
排查时还要考虑镜像拉取不一定只访问一个域名:客户端可能先连接镜像仓库,再访问认证服务或镜像层存储地址。新加坡服务器所在区域本身不能证明故障由地域网络造成;应先确认具体失败在哪个域名、端口和阶段,再判断是本机配置、出站网络还是仓库侧问题。
一、先确认症状和影响范围
先记录失败时间、完整错误信息、镜像地址和标签,以及执行拉取的工具。不要只保留命令最后一行;错误中的域名、端口、HTTP 状态码和超时阶段都可能影响判断。
docker pull registry.example.com/team/app:1.2.3
如果使用 containerd,可先确认实际使用的命令与命名空间:
sudo crictl pull registry.example.com/team/app:1.2.3
重点确认以下问题:
- 只有某个镜像失败,还是所有仓库、所有镜像都失败?
- 只有新加坡的一台服务器失败,还是同区域多台服务器都失败?
- 同一台服务器访问其他站点或仓库是否正常?
- 失败发生在解析域名、建立连接、TLS 握手、获取认证令牌,还是下载镜像层阶段?
- 命令行手动执行失败,还是只有自动化部署、定时任务或应用内拉取失败?
这些范围信息能缩小原因树。例如,单个标签失败可能是镜像名、权限或标签问题;多个仓库同时超时则更应检查服务器出站网络、DNS 或运行时代理配置。
容器镜像拉取涉及域名解析、仓库连接、认证与镜像层下载,部署环境的地域和网络资源也会影响业务链路的组织。A5idc数据提供新加坡及中国香港、日本、韩国、美国等地区的物理服务器,配置涵盖不同CPU、存储与网络线路,可为容器服务、业务后台和数据服务提供部署资源。多地区产品组合便于企业结合服务覆盖范围安排部署,让服务器所在区域与业务访问需求相匹配。
二、建立原因树:先看失败发生在哪一层
可以把镜像拉取链路分成几段:运行时读取镜像配置,解析仓库域名,建立到目标地址的 TCP 连接,完成 TLS 通信,再处理认证与镜像清单,最后下载镜像层。故障落在哪一段,排查方向也不同。

| 观察到的错误或现象 | 优先排查方向 | 不能据此直接断定 |
|---|---|---|
no such host、server misbehaving | DNS 解析、本机解析配置、DNS 服务可达性 | 不能只凭一次查询失败认定仓库不可用 |
i/o timeout、context deadline exceeded | 出站路由、端口、防火墙、丢包、代理链路 | 可能是 TCP 超时,也可能是下载阶段超时 |
connection refused | 目标地址的监听状态、端口策略、连接目标是否正确 | 不等于 DNS 故障 |
x509、证书验证失败 | 系统时间、证书链、TLS 检查设备、运行时信任配置 | 通常不是单纯的 DNS 解析问题 |
401 或 403 | 登录状态、仓库权限、令牌获取、访问策略 | 说明至少有部分网络请求已到达 HTTP 服务 |
| 清单已获取,但下载某层失败 | 镜像层存储域名、重定向目标、下载链路 | 仓库首页或 API 可达不代表所有文件地址都可达 |
表中错误文本可能因 Docker、containerd 版本和调用方式不同而变化。应以完整日志和失败域名为准,不要把相似的超时提示一律归为 DNS 故障。
三、按由外到内的顺序排除
1. 先核对镜像地址和运行时状态
检查镜像名、标签、仓库前缀是否正确;私有仓库还要确认该镜像对当前账号或机器人账号可见。对于只在某个镜像上失败的情况,先用同一仓库中已知存在、且有权限访问的镜像做对照,避免把标签不存在误判为网络故障。
再检查运行时本身是否正常:
docker info
systemctl is-active docker
如果使用 containerd:
systemctl is-active containerd
sudo crictl info
如果运行时服务未启动、磁盘空间不足或本地状态异常,可能导致拉取失败,但这并不说明 DNS 或远端连接有问题。查看对应服务日志时,时间范围应与失败时间一致:
sudo journalctl -u docker --since "30 minutes ago" --no-pager
使用 containerd 时,将服务名替换为实际运行的服务:
sudo journalctl -u containerd --since "30 minutes ago" --no-pager
不要因为看到运行时日志中的一个告警就立即重启或改配置;先确认报错是否与拉取任务同一时间发生。
2. 检查 DNS:解析失败与解析成功分别意味着什么
先查询实际报错中的主机名,而不是只查一个熟悉的仓库域名。常见查询工具如下:
getent ahosts registry.example.com
如果系统安装了 dig,还可检查 A 和 AAAA 记录:
dig +time=2 +tries=1 registry.example.com A
dig +time=2 +tries=1 registry.example.com AAAA
判断时注意:
- 返回
NXDOMAIN,表示当前查询路径认为该名称不存在;先核对域名拼写、仓库地址和 DNS 配置。 - 查询超时或无响应,说明 DNS 请求可能没有得到答复。继续检查本机配置的解析器、到解析器的网络,以及服务器是否使用了预期的 DNS 服务。
- 返回一个或多个地址,只能说明此次查询得到结果,不能证明这些地址可连接,也不能证明运行时使用了同一套解析配置。
- A 记录可用而 AAAA 记录也存在时,客户端可能尝试 IPv6。若 IPv6 路由不通,部分客户端会延迟回退,表现为拉取较慢或超时;应结合客户端日志和连接测试确认,不能仅凭存在 AAAA 记录就认定故障。
可查看常见 Linux 解析配置:
cat /etc/resolv.conf
如果系统使用 systemd-resolved,可进一步查看:
resolvectl status
resolvectl query registry.example.com
若查询失败,先确认服务器预期使用的 DNS 地址和配置来源,例如网络管理服务、云平台网络配置或本机解析服务。不要直接覆盖 /etc/resolv.conf:该文件可能由系统服务管理,手动修改可能被重写,也可能影响同机其他服务。变更 DNS 前,应记录原配置、确认适用范围,并准备按原配置恢复。
3. DNS 正常后,确认仓库端口是否能建立连接
容器镜像仓库通常通过 HTTPS 的 443 端口提供服务,但具体端口应以仓库配置为准。对实际错误中的域名进行测试:
nc -vz -w 5 registry.example.com 443
如果系统没有 nc,可使用 curl 观察连接和响应:
curl -sS -o /dev/null \
--connect-timeout 5 --max-time 15 \
-w 'remote_ip=%{remote_ip} http_code=%{http_code} connect=%{time_connect} tls=%{time_appconnect}\n' \
https://registry.example.com/v2/
对符合 OCI Distribution API 的仓库,未登录访问 /v2/ 返回 200 或 401 都可能是正常现象:前者表示接口可访问,后者通常表示需要认证。这里重点看是否能完成连接并收到 HTTP 响应,而不是要求必须返回 200。
结果可这样解读:
- 域名能解析,连接超时:继续检查服务器出站路由、云侧安全策略、本机防火墙、上游网络和企业出口策略。
- 连接被拒绝:核对目标端口、仓库监听状态和实际连接的地址;如果是自建仓库,也要检查服务端监听与入口配置。
- 能建立 TCP 连接,但 TLS 报错:转查证书链、系统时间、TLS 配置和中间设备,不要改 DNS 作为第一反应。
- 收到
401、403或其他 HTTP 响应:至少有请求到达了某个 HTTP 服务;继续确认响应是否来自预期仓库,以及认证和权限是否正确。
curl 与容器运行时的结果可能不同:前者使用当前 shell 的环境和系统网络,Docker 守护进程或 containerd 可能使用不同的 DNS、代理和证书配置。因此,curl 成功只能证明这条测试路径可用,不能单独证明运行时的拉取链路无故障。

4. 检查防火墙、路由和网络入口
若 DNS 查询正常、TCP 连接失败,应从服务器出站路径逐项核对:
- 本机防火墙是否允许运行时访问目标端口;
- 云平台安全策略、网络 ACL 或出口网关是否限制出站连接;
- 服务器是否存在默认路由,目标地址是否走预期网卡和出口;
- 企业网络是否要求通过指定出口设备访问外部仓库;
- 是否只有某一组目标 IP 失败,或 IPv4、IPv6 表现不同。
可先查看路由与本机防火墙状态:
ip route
ip -6 route
sudo nft list ruleset
如果系统实际使用的是其他防火墙管理工具,应检查当前生效规则,不要把某一条命令的输出当成完整策略。更不要为“试试看”而清空防火墙规则、关闭防护服务或开放所有出站端口。这类操作可能扩大影响范围,甚至造成管理连接中断。
如果确需变更规则,应先保存现有策略,确认只影响相关目标和端口,并安排有带外管理或其他恢复方式;验证无效后按记录回滚。服务器侧看到 TCP 超时也可能是远端服务或中间网络丢弃报文,需结合云侧流日志、出口设备日志或同网段对照测试定位,不能只凭一台主机推断责任边界。
5. 检查运行时代理和配置差异
有些环境要求守护进程通过企业出口代理访问外部仓库;也有环境明确禁止运行时使用代理。此时需要核对 Docker 服务或 containerd 服务实际采用的代理设置,而不是只检查当前终端:
systemctl show docker --property=Environment
systemctl show containerd --property=Environment
输出为空不一定表示没有代理:代理可能来自 systemd drop-in、服务配置文件或运行时专用配置。应按实际发行版和服务配置来源继续检查。还要核实代理是否可达、是否允许访问仓库及其认证服务、TLS 证书是否受信任,以及运行时是否需要为内网仓库配置不经代理的例外。
如果 shell 中的 curl 成功而 docker pull 失败,或反过来,优先比较两者的代理、DNS、证书信任和服务运行用户环境。修改 systemd 服务环境后通常需要重新加载服务配置并重启对应服务,这会影响正在运行的容器管理操作;实施前应确认业务维护窗口和回退配置,不要未经评估直接重启生产运行时。
6. 从主仓库扩展到认证和镜像层地址
镜像拉取往往会发生多次请求:先访问仓库接口,之后获取认证令牌,再下载清单和镜像层。镜像层可能从单独的存储域名或 CDN 地址返回。因此,“/v2/ 能收到响应”并不能证明整个镜像都能下载。

查看完整运行时日志,找到最后成功的阶段以及之后失败的主机名。若错误显示认证令牌请求失败,检查认证服务的解析和连接;若清单获取成功但下载层超时,重点检查日志中出现的存储或重定向目标。对失败域名逐个重复 DNS 和 TCP 检查,不要只测试仓库主域名。
登录或令牌失效通常会出现认证相关的 HTTP 状态或明确的授权错误;此时先检查账号、访问令牌、仓库项目权限和令牌有效期。若错误是连接超时,单纯重新登录通常不能修复网络链路问题。
四、根据结果定位根因
可用以下判断链收敛:
- DNS 查询没有得到预期地址:核对域名、解析器和 DNS 网络路径;在解析恢复前,不必先调整仓库端口或重置运行时。
- DNS 返回地址,但 TCP 连接失败:检查出站路由、端口策略、防火墙、代理和上游网络;进一步比较不同目标地址及 IPv4、IPv6 的结果。
- TCP 成功,但 TLS 失败:检查系统时间、证书链、运行时信任配置和 TLS 检查设备;确认 curl 与运行时是否使用相同的信任来源。
- TLS 成功并收到 HTTP 错误:根据状态码区分认证、权限、限流、镜像不存在或仓库应用故障,确认响应来自预期服务。
- 仓库接口可用,但镜像层失败:沿日志中的认证、重定向和存储域名继续检查,重点关注下载目标的 DNS、端口和出口策略。
- 只有运行时失败,系统工具测试正常:比较守护进程的代理、DNS、证书和服务配置;确认是否使用镜像加速器或自定义仓库配置。
例如,模拟日志如下:
lookup registry.example.com: no such host
这优先指向解析链路或域名配置。若日志变成:
dial tcp 203.0.113.10:443: i/o timeout
则说明客户端已得到目标 IP,排查重点应转到 TCP 路径;但仅凭这一行仍不能区分服务器防火墙、云出口策略和远端丢包。若 /v2/ 返回 401,而实际拉取报 denied,则应优先核对身份认证和仓库权限,而非继续反复修改 DNS。
以上日志中的域名和地址仅作格式示例,不代表任何特定服务器或仓库的实际检查结果。
五、验证恢复并观察是否复发
修复后,应使用原先失败的镜像和相同运行时复测,而不是只用浏览器或 curl 验证。确认镜像清单和镜像层都能拉取,再检查部署任务或应用是否恢复;如果失败涉及某个特定后端域名,还要确认完整下载链路已通过。
同时记录本次变更内容、受影响的服务器与服务、验证结果和回滚方式。若通过修改 DNS、网络规则、代理或证书配置恢复,应观察这些设置是否被系统管理服务覆盖,以及重启服务或网络后是否仍有效。
建议持续关注以下复发信号:
- DNS 查询超时、解析失败比例及异常的解析结果;
- 到仓库、认证服务和镜像层存储地址的 443 连接超时;
- 拉取任务的失败率、持续时间及失败阶段;
- 运行时代理或仓库配置是否发生漂移;
- 云出口、防火墙和网络策略变更记录;
- 仅 IPv6 或某个后端地址失败时的连接异常。
监控应尽量区分解析、连接、认证和下载阶段。只统计“镜像拉取失败”无法说明根因;能保留失败域名、阶段和时间,才便于下一次快速判断问题是在 DNS、网络入口还是仓库应用本身。
本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/8118.html
