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

kubernetes Troubleshooting

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 有问题。

Ingress 404 多数是 host/path 没命中或打到了默认后端；502 多数是命中了规则但 Service/Pod 后端不可用。先用 Host 头精确复现。

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

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

Scenario

这篇文章解决什么问题

适用于“Kubernetes Ingress 404/502 排查流程”对应的线上或本地排障场景。不要只根据最终报错下结论，应先把问题拆成入口、链路、目标服务和资源限制几层，再用命令逐层证实。Ingress 404 多数是 host/path 没命中或打到了默认后端；502 多数是命中了规则但 Service/Pod 后端不可用。先用 Host 头精确复现。

Symptoms

典型现象

  • Kubernetes Ingress 返回 404 或 502 时，用 curl -H Host 精确复现路由，再 kubectl describe ingress 检查 rules/pathType/IngressClass，404 多为 host 或 path 没命中，502 多为 Service Endpoints 为空或 targetPort、Pod readiness 有问题。
  • 相关日志、命令或页面中反复出现 kubernetes、ingress、nginx 等关键词。
  • 同一服务在不同机器、不同入口或不同时间段表现不一致，需要通过证据链缩小范围。

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 Ingress 404/502 排查流程 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。

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

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

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

  • 从报错服务所在机器执行测试
  • 必要时加 Host、SNI、namespace 或代理参数
  • 把成功路径和失败路径的输出并排比较
2. 在故障发生的同一位置复现
kubectl get ingress -A
curl -v -H "Host: app.example.com" http://<ingress-ip>/path
kubectl get svc,endpoints -n <namespace>

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

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

  • 确认 DNS 或 Host 头打到正确 Ingress IP。
  • describe ingress 查看 rules、backend 和 events。
  • 404 时重点检查 host、pathType、路径前缀和 IngressClass。
3. 读取服务端证据，而不是只看客户端提示
curl -v -H "Host: app.example.com" http://<ingress-ip>/path
kubectl get svc,endpoints -n <namespace>
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --tail=200

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

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

  • 404 时重点检查 host、pathType、路径前缀和 IngressClass。
  • 502 时检查 Service Endpoints、targetPort 和 Pod readiness。
  • 查看 Ingress Controller 日志确认最终 upstream 和错误原因。
4. 做最小修复并立即回归验证
kubectl get svc,endpoints -n <namespace>
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --tail=200

Commands

排查命令与使用意图

命令 1

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

命令 1
kubectl describe ingress <name> -n <namespace>

命令 2

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

命令 2
kubectl get ingress -A

命令 3

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

命令 3
curl -v -H "Host: app.example.com" http://<ingress-ip>/path

命令 4

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

命令 4
kubectl get svc,endpoints -n <namespace>

命令 5

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

命令 5
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller --tail=200

Risk Notes

容易踩坑的地方

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

Verification

修复后怎么确认

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

Prevention

后续预防

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

常见问题

为什么直接访问 IP 是 404？

Ingress 通常按 Host 头路由，直接访问 IP 会落到默认后端。用 curl -H Host 精确测试。

IngressClass 错了会怎样？

Controller 可能完全不接管这个 Ingress，表现为规则不生效或一直访问旧配置。

Long-tail SEO

你可能正在搜索这些报错

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

  • Kubernetes Ingress 404
  • Ingress 502 Bad Gateway
  • nginx ingress no endpoints
  • ingress path rewrite 404
  • ingress service backend not found
  • ingress class 不生效
  • K8s ingress upstream timed out
  • ingress controller 日志排查

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命令

kubectl 排查 Service 和 Ingress 命令

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

kubernetes排障

Kubernetes ImagePullBackOff 排查流程

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

kubernetes排障

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 挂载缺失和内存限制。

kubernetes排障

Kubernetes Service 访问不通排查

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

kubernetes