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

kubernetes Troubleshooting

Kubernetes Pod CrashLoopBackOff 排查流程

Kubernetes Pod 陷入 CrashLoopBackOff、Back-off restarting failed container 时，用 kubectl logs --previous 读取上一轮崩溃日志，kubectl describe pod 看 Last State/Exit Code/OOMKilled，逐个排查应用启动错误、liveness 探针误杀、ConfigMap/Secret 挂载缺失和内存限制。

先看上一轮容器日志和 describe events。CrashLoopBackOff 是结果，不是根因，根因通常在应用启动错误、探针误杀、配置缺失或 OOMKilled。

适用环境Kubernetes / kubectl / 容器运行时
风险等级低
最后验证2026-06-30
建议权限普通用户

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

Scenario

这篇文章解决什么问题

适用于 Pod 反复重启、重启次数持续增加、当前日志看不到关键错误的场景。重点看上一轮容器日志、退出码和探针/配置事件。

Symptoms

典型现象

  • Pod 状态为 CrashLoopBackOff。
  • kubectl logs 当前轮日志很短或为空。
  • describe 中 Last State 显示 Error、OOMKilled 或非 0 Exit Code。

Before Debugging

排查前先确认

  • 先确认 namespace、资源名、节点、镜像和最近一次变更。
  • 按 Pod → Service/Endpoint → Ingress/外部入口的顺序定位，不要跳层。
  • 优先看 describe events 和上一轮容器日志，它们通常比状态字段更接近根因。

Root Causes

常见根因分层

控制面状态只是结果，不是根因

CrashLoopBackOff、ImagePullBackOff、Pending 都是 Kubernetes 的状态归纳。真正原因在 Events、容器退出码、镜像拉取错误或调度失败信息里。

  • describe pod 看 Events
  • logs --previous 看上一轮崩溃
  • get events 按时间线排序

标签、端口和就绪状态断链

Service selector 不匹配、targetPort 写错、readiness 未通过，会让流量入口看起来存在但没有可用后端。

  • get svc,endpoints 同看
  • 核对 Pod labels
  • 确认容器监听端口

集群网络和策略限制

DNS、NetworkPolicy、IngressClass、节点到 Registry 网络、TLS Secret 都可能让同一应用在不同 namespace 或节点表现不同。

  • 从集群内临时 Pod 测试
  • 确认 IngressClass 和 Controller 日志
  • 检查 Secret 所在 namespace

Diagnosis Path

分步诊断流程

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

先记录故障时间、影响入口、完整错误和最近一次变更。Kubernetes Pod CrashLoopBackOff 排查流程 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。

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

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

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

  • 从报错服务所在机器执行测试
  • 必要时加 Host、SNI、namespace 或代理参数
  • 把成功路径和失败路径的输出并排比较
2. 在故障发生的同一位置复现
kubectl logs <pod> -n <namespace> --previous
kubectl get events -n <namespace> --sort-by=.lastTimestamp
kubectl get pod <pod> -n <namespace> -o yaml

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

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

  • 用 describe 查看 Last State、Exit Code、Reason 和 Events。
  • 用 --previous 读取上一轮崩溃容器日志。
  • 确认 ConfigMap、Secret、Volume 和环境变量是否完整挂载。
3. 读取服务端证据，而不是只看客户端提示
kubectl get events -n <namespace> --sort-by=.lastTimestamp
kubectl get pod <pod> -n <namespace> -o yaml
kubectl top pod <pod> -n <namespace>

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

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

  • 确认 ConfigMap、Secret、Volume 和环境变量是否完整挂载。
  • 检查 liveness/readiness/startup probe 是否过于激进。
  • 如果 Reason 是 OOMKilled，调整内存限制或定位应用内存峰值。
4. 做最小修复并立即回归验证
kubectl get pod <pod> -n <namespace> -o yaml
kubectl top pod <pod> -n <namespace>

Commands

排查命令与使用意图

命令 1

用于读取 Kubernetes Events、状态变化和资源引用关系。排查 Pod、Service、Ingress 时，它通常能直接暴露调度、拉镜像、探针或后端错误。

命令 1
kubectl describe pod <pod> -n <namespace>

命令 2

用于读取容器应用日志。CrashLoop 场景优先加 --previous，因为当前轮日志可能还没来得及输出。

命令 2
kubectl logs <pod> -n <namespace> --previous

命令 3

用于读取 Kubernetes 当前资源状态和 Events。重点看 STATUS、RESTARTS 和 Events 中的调度、探针、镜像错误。

命令 3
kubectl get events -n <namespace> --sort-by=.lastTimestamp

命令 4

用于读取 Kubernetes 当前资源状态和 Events。重点看 STATUS、RESTARTS 和 Events 中的调度、探针、镜像错误。

命令 4
kubectl get pod <pod> -n <namespace> -o yaml

命令 5

用于补充“Kubernetes Pod CrashLoopBackOff 排查流程”的排查证据链。kubectl 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。

命令 5
kubectl top pod <pod> -n <namespace>

Risk Notes

容易踩坑的地方

  • 不要直接删除有状态 Pod 或 PVC 来“试试”，先确认控制器和数据卷策略，避免数据丢失。
  • 不要只看当前容器日志，CrashLoop 场景必须看 --previous 获取上一轮崩溃的完整输出。
  • 不要在 production 集群上随意修改资源配额或节点标签，这类变更可能触发级联 Pod 调度。

Verification

修复后怎么确认

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

Prevention

后续预防

  • 发布模板中强制包含 probes、资源限制和回滚策略，确保所有工作负载都有存活和就绪检查。
  • 把 Service selector、端口名和 labels 做成约定，减少手写漂移导致的网络断链问题。
  • 为镜像拉取、Pod 重启和 Ingress 5xx 建立基础告警，第一时间发现异常。
  • 定期用 kubectl cluster-info dump 和容器运行时检查集群健康状态，提前发现调度和资源问题。

常见问题

为什么 kubectl logs 为空？

容器可能启动前就失败，或当前轮还没输出。加 --previous 查看上一轮崩溃日志。

readiness probe 会导致重启吗？

readiness 只影响流量接入，liveness 才会触发重启；startup probe 可保护慢启动应用。

Long-tail SEO

你可能正在搜索这些报错

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

  • Kubernetes CrashLoopBackOff
  • kubectl logs previous
  • pod 重启循环
  • CrashLoopBackOff exit code 1
  • K8s liveness probe failed
  • Kubernetes 容器启动后退出
  • Back-off restarting failed container
  • kubectl describe pod CrashLoopBackOff

Related

相关排障 / 命令 / 工具

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

速查

kubectl 常用命令速查表

kubectl 常用命令一页速查：get/describe/logs/exec 现场调试、scale 与 rollout 更新回滚、context 与 namespace 切换、events 事件筛查，覆盖 Pod CrashLoop 和 ImagePullBackOff 排障主路径。

kubernetes命令

kubectl 排查 Pod 状态常用命令

kubectl 排查 Pod 异常的核心命令组合，kubectl get pod 看状态与重启次数、describe pod 看调度/拉镜像/探针/OOM 事件、logs --tail=200 读近期日志，CrashLoopBackOff 场景加 --previous 读上一轮崩溃日志，exec -it 进容器复现问题。

kubernetes排障

Kubernetes ImagePullBackOff 排查流程

Kubernetes Pod 卡在 ImagePullBackOff/ErrImagePull 时，kubectl describe pod 读取 Events 里 Failed to pull image 的完整错误，逐个排查镜像 tag 是否存在、私有仓库 imagePullSecrets 是否引用、节点到 Registry 网络、以及多架构镜像 manifest 是否匹配当前节点。

kubernetes命令

kubectl 排查 Service 和 Ingress 命令

kubectl 排查 Kubernetes Service 与 Ingress 路由不通的常用命令，kubectl get svc,endpoints 看 endpoints 是否为空判断 selector 是否匹配，describe ingress 看 rules 和 IngressClass，用 curl -H Host 复现入口路由并核对 targetPort 与容器端口。

kubernetes排障

Kubernetes Ingress 404/502 排查流程

Kubernetes Ingress 返回 404 或 502 时，用 curl -H Host 精确复现路由，再 kubectl describe ingress 检查 rules/pathType/IngressClass，404 多为 host 或 path 没命中，502 多为 Service Endpoints 为空或 targetPort、Pod readiness 有问题。

kubernetes排障

Kubernetes Service 访问不通排查

Kubernetes Service 通过 ClusterIP/NodePort 访问不通时，先 kubectl get endpoints 看是否为空——空则是 selector 与 Pod labels 不匹配，有值再核对 targetPort、Pod readiness 和 NetworkPolicy，最后用 busybox nslookup 验证集群 DNS 是否解析 svc.cluster.local。

kubernetes