真实命令 · 少走弯路·已沉淀 95 篇排障/命令手册，25 份速查表，15 个配置工具进入排障台
LaoHand开发者排障手册
配置生成

docker Troubleshooting

Docker 镜像拉取失败排查：超时、证书和架构不匹配

docker pull 出现 TLS handshake timeout、manifest unknown、no matching manifest 或 x509 unknown authority 时，先按错误文本区分网络、Registry 认证、镜像 tag 不存在或 CPU 架构不匹配，再针对性配置代理、镜像源、docker login 或私有仓库 CA。

先区分是网络连接、Registry 认证、镜像标签不存在还是 CPU 架构不匹配。docker pull 的报错文本通常已经暴露了第一判断方向。

适用环境Linux / Docker / Docker Compose
风险等级低
最后验证2026-06-30
建议权限普通用户 + sudo

2026-06-30 更新·约 3 分钟阅读

Scenario

这篇文章解决什么问题

适用于“Docker 镜像拉取失败排查：超时、证书和架构不匹配”对应的线上或本地排障场景。不要只根据最终报错下结论，应先把问题拆成入口、链路、目标服务和资源限制几层，再用命令逐层证实。先区分是网络连接、Registry 认证、镜像标签不存在还是 CPU 架构不匹配。docker pull 的报错文本通常已经暴露了第一判断方向。

Symptoms

典型现象

  • docker pull 出现 TLS handshake timeout、manifest unknown、no matching manifest 或 x509 unknown authority 时，先按错误文本区分网络、Registry 认证、镜像 tag 不存在或 CPU 架构不匹配，再针对性配置代理、镜像源、docker login 或私有仓库 CA。
  • 相关日志、命令或页面中反复出现 docker、image、registry 等关键词。
  • 同一服务在不同机器、不同入口或不同时间段表现不一致，需要通过证据链缩小范围。

Before Debugging

排查前先确认

  • 先确认问题发生在镜像拉取、容器启动、容器内服务监听，还是宿主机/外部访问。
  • 记录 docker ps、docker logs 和 docker inspect 的同一时间窗口，避免状态已变化后误判。
  • 区分 Docker 网络、宿主机防火墙、云安全组和应用自身监听地址。

Root Causes

常见根因分层

容器状态和应用状态不是一回事

容器 Running 只代表主进程存在，不代表应用已经 ready；容器 Restarting 通常是应用启动失败或健康检查不断失败。

  • 看退出码和最近 200 行日志
  • 检查 healthcheck 是否过于激进
  • 确认依赖服务是否 ready

端口、网络和监听地址不匹配

服务只监听 127.0.0.1、端口映射写错、bridge 网络不可达、宿主机防火墙拦截，都会造成“容器里通、外部不通”。

  • 容器内 ss -lntp
  • 宿主机 curl 127.0.0.1:端口
  • 外部机器再测宿主机 IP

Registry、代理和平台架构问题

镜像拉取失败不仅是网络慢，也可能是认证、标签不存在、私有 CA、代理环境变量或 amd64/arm64 架构不匹配。

  • 保留完整 pull 错误
  • 检查 docker info 中代理配置
  • 用 manifest inspect 看架构

Diagnosis Path

分步诊断流程

1. 固定现场，避免追着变化状态跑

先记录故障时间、影响入口、完整错误和最近一次变更。Docker 镜像拉取失败排查：超时、证书和架构不匹配 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。

  • 截图或保存完整错误文本
  • 记录请求域名/IP/端口/namespace/服务名
  • 标出最近发布、配置、证书、镜像或依赖变更
1. 固定现场，避免追着变化状态跑
docker pull nginx:latest
docker login <registry>

2. 在故障发生的同一位置复现

很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。

  • 从报错服务所在机器执行测试
  • 必要时加 Host、SNI、namespace 或代理参数
  • 把成功路径和失败路径的输出并排比较
2. 在故障发生的同一位置复现
docker login <registry>
docker manifest inspect nginx:latest
docker info | grep -i "Registry|Proxy"

3. 读取服务端证据，而不是只看客户端提示

客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。

  • 记录完整 docker pull 报错，不要只截最后一行。
  • 如果是 timeout 或 TLS handshake timeout，先检查代理、DNS、镜像源和公司网关。
  • 如果是 manifest unknown，确认镜像名、命名空间和 tag 是否真实存在。
3. 读取服务端证据，而不是只看客户端提示
docker manifest inspect nginx:latest
docker info | grep -i "Registry|Proxy"
curl -I https://registry-1.docker.io/v2/

4. 做最小修复并立即回归验证

每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。

  • 如果是 manifest unknown，确认镜像名、命名空间和 tag 是否真实存在。
  • 如果是 no matching manifest，检查当前机器架构与镜像支持架构。
  • 私有仓库失败时检查 docker login、证书链和 insecure registry 配置。
4. 做最小修复并立即回归验证
docker info | grep -i "Registry|Proxy"
curl -I https://registry-1.docker.io/v2/

Commands

排查命令与使用意图

命令 1

用于补充“Docker 镜像拉取失败排查：超时、证书和架构不匹配”的排查证据链。docker 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 1
docker pull nginx:latest

命令 2

用于补充“Docker 镜像拉取失败排查：超时、证书和架构不匹配”的排查证据链。docker 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 2
docker login <registry>

命令 3

用于补充“Docker 镜像拉取失败排查：超时、证书和架构不匹配”的排查证据链。docker 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 3
docker manifest inspect nginx:latest

命令 4

用于补充“Docker 镜像拉取失败排查：超时、证书和架构不匹配”的排查证据链。docker 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 4
docker info | grep -i "Registry|Proxy"

命令 5

用于从指定位置模拟真实请求。加 -v 可以看到 DNS、TCP、TLS、HTTP 头和代理连接过程，是定位链路阶段的关键证据。

命令 5
curl -I https://registry-1.docker.io/v2/

Risk Notes

容易踩坑的地方

  • 不要一上来 docker system prune，先确认是否有需要保留的停止容器、卷或构建缓存。
  • 不要把 restart: always 当成稳定性方案，它可能掩盖启动失败的根本原因。
  • 不要在容器内使用 systemd 作为入口进程，除非使用特权模式或专门的基础镜像。

Verification

修复后怎么确认

  • 原始故障现象已经消失，且使用同一入口重新测试 Docker 镜像拉取失败 能稳定成功。
  • 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
  • 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。

Prevention

后续预防

  • Compose 文件里显式写健康检查、资源限制和必要环境变量，确保容器启动后能自动恢复。
  • 上线前用 docker compose config 展开最终配置做审查，避免遗漏或覆盖了错误的配置值。
  • 为镜像使用固定 tag 或 digest，避免 latest 漂移导致部署了非预期的版本。
  • 建立容器日志轮转策略，防止日志无限增长撑满磁盘分区。

常见问题

换镜像源能解决所有拉取失败吗？

不能。镜像源只解决连接和加速问题，标签不存在、权限不足、架构不匹配仍需要分别处理。

x509 certificate signed by unknown authority 怎么办？

应把私有仓库 CA 放到 Docker 信任目录并重启 Docker，不建议直接把仓库加入 insecure registry。

Long-tail SEO

你可能正在搜索这些报错

下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。

  • docker image pull failed
  • docker pull timeout
  • docker manifest unknown
  • docker TLS handshake timeout
  • docker registry mirror 配置
  • imagepullbackoff docker pull
  • docker pull proxy 代理
  • docker no matching manifest

Related

相关排障 / 命令 / 工具

按分类和标签关联的排障流程、命令模板和配置工具，方便顺着同一个问题继续往下查。

排障

Docker 镜像清理与瘦身

Docker 镜像和构建缓存占满磁盘时，用 docker system df 查看整体占用，按 dangling 中间层、未使用镜像、构建缓存的顺序渐进清理，避免直接 docker system prune -a 误删仍被停止容器引用的镜像。

docker速查

Docker Compose 命令速查表

Docker Compose 命令一页速查：up/down/restart 启停编排、ps/logs/top 日志与状态、config/build/exec/run 配置构建与调试、--scale 水平扩容与命名卷管理，多服务项目起停排障直接对照。

docker工具

Docker Compose 配置生成器

根据镜像、端口、卷、环境变量生成 docker-compose.yml 模板。

docker速查

Docker 常用命令速查表

Docker 常用命令一页速查：镜像构建拉取、容器 run/exec/logs、网络与数据卷、Compose 编排以及 system prune 清理孤儿资源等 30+ 高频操作，含关键参数说明与典型排障场景示例。

docker命令

Docker 查看容器日志与状态命令

使用 docker logs、inspect、stats、events 排查容器启动失败或运行异常的常用命令，docker ps -a 看退出状态，docker logs --tail 200 -f --since 读取近期日志，docker inspect 展开端口、挂载和环境变量，stats 看资源占用。

docker排障

Docker Compose 容器反复重启排查

Docker Compose 容器一直 Restarting 时，用 docker compose ps 看退出码和重启次数，读取失败服务的历史日志、docker compose config 展开环境变量与端口卷，常见根因是启动命令失败、环境变量缺失、端口冲突或 depends_on 未等依赖 ready。

docker