K8s 网关（Ingress-Nginx/Envoy/云原生网关）20 个高频故障速查手册

一、网关控制器本身故障（4 个）

1. 网关 Pod 启动失败 / CrashLoopBackOff

现象：ingress-nginx / envoy Pod 状态为 CrashLoopBackOff、Error、Pending
排查命令

bash 复制代码

kubectl get pods -n ingress-nginx -l app.kubernetes.io/name=ingress-nginx
kubectl describe pod <网关Pod名> -n ingress-nginx
kubectl logs <网关Pod名> -n ingress-nginx --tail=200 -f

常见原因

节点资源不足（CPU/内存 Limit 不够）
ConfigMap 配置语法错误（如 nginx-configuration）
网络插件异常，Pod 无法获取 IP / 通信
镜像拉取失败（仓库权限、网络）
端口冲突（80/443 被主机占用）
修复：调整资源配额、修正 ConfigMap、重装网络插件、检查镜像

2. 网关 Service 无 ExternalIP / 无法外网访问

现象：ingress-nginx Service 为 LoadBalancer，但 EXTERNAL-IP 为
排查命令

bash 复制代码

kubectl get svc -n ingress-nginx ingress-nginx-controller
kubectl describe svc ingress-nginx-controller -n ingress-nginx

常见原因

云厂商 EIP 未自动分配（公有云需手动配）
节点安全组/防火墙未放行 80/443
集群网络模式不支持 LoadBalancer（如自建集群）
云厂商负载均衡器异常
修复：手动绑定 EIP、放行安全组、改用 NodePort+反向代理

3. 网关配置不生效 / 规则不更新

现象：更新 Ingress 后，访问无变化，网关日志无 reload
排查命令

bash 复制代码

kubectl get ingress <名称> -o yaml
kubectl exec -it <网关Pod> -n ingress-nginx -- cat /etc/nginx/nginx.conf | grep <域名/路径>
kubectl logs <网关Pod> -n ingress-nginx | grep "reload"

常见原因

Ingress 资源 YAML 语法错误（kubectl describe ingress 看 Events）
注解（annotation）拼写错误（如 nginx.ingress.kubernetes.io/*）
网关控制器监听命名空间错误（--watch-namespace）
控制器版本与 K8s 不兼容
修复：修正 Ingress YAML、核对注解、调整控制器启动参数

4. 网关性能差 / 高并发报错 / 连接超时

现象：QPS 高时 502/504、连接被重置、响应慢
排查命令

bash 复制代码

kubectl top pods -n ingress-nginx
kubectl exec <网关Pod> -n ingress-nginx -- nginx -T  # 看连接数/worker配置

常见原因

worker_processes / worker_connections 配置过低
网关 CPU/内存资源不足
keepalive_timeout、proxy_send_timeout 过短
HTTP2 最大流数限制（默认 128）
修复：调大 ConfigMap 性能参数、扩容网关 Pod、增加资源配额

二、访问 404 类故障（4 个）

5. 访问返回 default backend - 404

现象：请求未匹配任何 Ingress 规则，走默认 404
排查命令

bash 复制代码

kubectl get ingress
kubectl describe ingress <名称>  # 看 host/path
kubectl exec <网关Pod> -- cat /etc/nginx/conf.d/* | grep <host>

常见原因

访问域名与 Ingress.host 不匹配（含大小写、泛域名）
路径 Path 配置错误（含 PathType：Exact/Prefix）
Ingress 未加正确注解（如重写路径 rewrite-target）
路径含非法字符（?、&、中文）
修复：核对 host、修正 Path/PathType、配置重写规则

6. Ingress 存在但 404，网关日志无记录

现象：curl 返回 404，但网关日志看不到该请求
常见原因

DNS 解析错误，域名指向非网关 IP
本地 hosts 配置错误
公网 DNS 未生效 / 缓存旧解析
流量被防火墙/安全组拦截
修复：nslookup 验证域名、清空 DNS 缓存、检查防火墙

7. 路径重写后 404（rewrite-target）

现象：配置 rewrite-target 后，后端服务 404
常见原因

rewrite 正则错误（如 $1、$ 2 引用错误）
PathType 与 rewrite 不兼容（建议用 Prefix）
后端服务实际路径与重写后路径不匹配
修复：测试正则、修正 PathType、核对后端真实路径

8. 跨命名空间 Ingress 404

现象：Ingress 与 Service 跨 Namespace 时 404
常见原因

Ingress 中 backend.serviceName 未带命名空间（K8s 1.21+ 支持）
网关未开启跨命名空间权限（--watch-namespace=*）
修复：serviceName 写 .、允许网关监听全命名空间

三、502 / 503 类故障（4 个）

9. 访问 503 Service Unavailable（最常见）

现象：503，网关日志：no endpoints available for service
排查命令

bash 复制代码

kubectl get endpoints <service-name>
kubectl get pods -l <app-label> -o wide  # 看 READY
kubectl describe pod <pod名>  # 看 Events/健康检查

常见原因

Service 无 Endpoints（Pod 未就绪、标签不匹配）
Pod 状态：Pending、Crash、Not Ready
健康检查失败（liveness/readiness 误判）
Service 端口与容器端口不匹配
修复：核对标签、修复 Pod、调整健康检查、修正端口

10. 访问 502 Bad Gateway

现象：网关收到响应但无效，日志：upstream prematurely closed
排查命令

bash 复制代码

kubectl port-forward svc/<服务> 8080:80
curl http://localhost:8080  # 直连Service测试
kubectl logs <业务Pod> --tail=100  # 看业务报错

常见原因

业务 Pod 内部异常（进程挂、OOM、报错退出）
业务端口未监听 / 监听错误
网关到 Pod 网络不通（CNI、网络策略）
后端超时时间过短（业务启动慢）
修复：修复业务代码、核对端口、检查网络策略、调大超时

11. 503 偶发 / 间歇性故障

现象：时而正常时而 503，流量不均
常见原因

部分 Pod 异常（部分 Ready 部分 Not Ready）
Pod 所在节点网络不稳定
网关负载不均、连接池耗尽
后端服务空闲超时小于网关（idle timeout）
修复：驱逐异常 Pod、检查节点、调大连接池、匹配超时

12. 网关到后端 HTTPS 服务 502/400

现象：报错 The plain HTTP request was sent to HTTPS port
常见原因 ：Ingress 未配置 backend-protocol: HTTPS，网关用 HTTP 访问 HTTPS 后端
修复：添加注解

yaml 复制代码

annotations:
  nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

四、HTTPS/证书故障（4 个）

13. TLS 握手失败 / SSL_ERROR

现象：浏览器提示证书无效、不安全；curl SSL handshake failed
排查命令

bash 复制代码

kubectl get secret <tls-secret> -n <ns>  # 确认存在
openssl s_client -connect <域名>:443  # 测试证书

常见原因

Secret 不存在 / 类型非 kubernetes.io/tls
证书域名与 Ingress.host 不匹配（含泛域名）
证书过期 / 私钥不匹配
证书链不完整（缺少中间 CA）
修复：重新创建证书 Secret、核对域名、更新有效期

14. HTTPS 访问 404 / 跳 HTTP 异常

现象：HTTPS 404，HTTP 正常；或强制 HTTPS 失效
常见原因

TLS 配置错误（secretName 错误、跨命名空间）
未配置 http-redirect 注解
80/443 端口未同时放行
修复：核对 TLS.secretName、配置强制 HTTPS

yaml 复制代码

annotations:
  nginx.ingress.kubernetes.io/ssl-redirect: "true"
  nginx.ingress.kubernetes.io/force-ssl-redirect: "true"

15. 多域名证书冲突 / SNI 不生效

现象：多 Ingress 共用证书，部分域名证书错误
常见原因

一个证书包含多个域名，但 Ingress 未正确匹配
网关未开启 SNI（默认开启）
证书配置重复
修复：使用通配符证书、确保 Secret 正确引用、清理重复配置

16. 证书自动更新（cert-manager）不生效

现象：证书过期，cert-manager 未自动续期
排查命令

bash 复制代码

kubectl get certificates
kubectl describe certificate <名称>

常见原因

cert-manager Pod 异常
DNS 验证失败（公网 DNS 不生效）
账号权限/额度不足（Let's Encrypt）
修复：重启 cert-manager、检查 DNS、核对账号

五、高级功能故障（4 个）

17. 会话保持不生效

现象：配置 sticky 后，请求仍分发到不同 Pod
常见原因

注解拼写错误（如 cookie-affinity）
Service 端口配置错误
网关未开启会话保持
修复

yaml 复制代码

annotations:
  nginx.ingress.kubernetes.io/affinity: "cookie"
  nginx.ingress.kubernetes.io/session-cookie-name: "route"

18. 限流/熔断异常（429 或不生效）

现象：限流不生效或误拦截正常请求
常见原因

限流注解参数错误（rate-limit）
共享内存 zone 大小不足
网关重启后配置丢失
修复：核对限流参数、调大 shared memory、稳定网关

19. WebSocket / gRPC 访问异常

现象：WebSocket 断开、gRPC 报错
常见原因

未开启 WebSocket 支持（注解）
超时时间过短（默认 60s）
不支持 HTTP2（gRPC 依赖）
修复

yaml 复制代码

annotations:
  nginx.ingress.kubernetes.io/websocket-services: "svc-name"
  nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
  nginx.ingress.kubernetes.io/backend-protocol: "GRPC"  # gRPC

20. 网络策略导致网关无法访问后端

现象：一切配置正常，但 502/503，网络不通
排查命令

bash 复制代码

kubectl get networkpolicies -n <业务NS>
kubectl describe networkpolicy <名称>

常见原因 ：NetworkPolicy 限制入口，未放通网关命名空间
修复：添加 ingress 规则，允许 ingress-nginx 命名空间访问

网关故障排查万能 6 步

查网关状态：Pod 运行、日志无报错、Service IP 正常
查 Ingress 规则：host、path、serviceName、port 正确
查后端服务：Service 存在、Endpoints 非空、Pod Ready
查网络连通：网关 → Service → Pod 网络通、端口可访问
查配置注解：TLS、重写、协议、超时等注解正确
查日志：网关日志 + 业务 Pod 日志，定位报错点