Kubernetes Ingress 404 — 主机或路径无匹配规则

症状

本篇调试指南针对“Kubernetes Ingress 404 — 主机或路径无匹配规则”。内容涵盖可观察的症状、可复现的诊断路径、根本原因、具体修复方式，以及如何验证修复并防止回归。

可观察到的症状包括：

• 请求到达 ingress 控制器却返回 404
• 应用经端口转发可用，经 Ingress 不可用
• 路径前缀对 / 可用，对 /api 不可用

诊断

先在隔离环境中复现故障，再按顺序执行以下检查，逐步缩小范围。

步骤 1

kubectl describe ingress <ing> | grep -A 10 "Rules"

主机与路径规则显示必须请求何种地址才能匹配。

步骤 2

curl -i -H 'Host: app.example.com' http://<ingress-ip>/api/health

用正确 Host 与路径得到 200 即确认规则可用；404 则显示不匹配。

常见诱因（按出现频率排序）：

• 请求中的主机或路径不匹配任何 Ingress 规则
• Ingress 使用的 class 不被该控制器服务
• 后端 Service 名或端口名错误，导致路由失败

根因

Ingress 控制器按主机与路径把请求匹配到声明的规则，并转发到具名 Service 端口。不匹配任何规则的请求——或后端名错误的规则——会由控制器返回 404 或 503。

修复

让请求主机与路径匹配规则，设置正确的 ingressClassName，并让后端 Service 名与 Service 上声明的具名端口匹配。

注意：使用错误的 ingressClassName 可能让 Ingress 被静默忽略；应确认控制器接管了它。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
spec:
  ingressClassName: nginx            # class the controller serves
  rules:
    - host: app.example.com          # request must send this Host
      http:
        paths:
          - path: /api               # matches /api/...
            pathType: Prefix
            backend:
              service:
                name: web               # must match the Service name
                port:
                  name: http            # named port on the Service

验证

用匹配的主机与路径请求应用并确认 200；验证 kubectl describe ingress 显示预期的后端与地址。

修复后补充一条回归测试，复现原始症状，防止问题再次出现。

这类故障通常是环境问题而非纯逻辑错误，因此在缺陷记录中应写明完整命令、环境变量与工作目录。请用最小的脚本复现，待最小用例清楚后再扩大范围。为这类故障准备一份简短的排查清单，能显著减少下次排障时间。