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

一、网关控制器本身故障4 个1. 网关 Pod 启动失败 / CrashLoopBackOff现象ingress-nginx / envoy Pod 状态为 CrashLoopBackOff、Error、Pending排查命令kubectl get pods-ningress-nginx-lapp.kubernetes.io/nameingress-nginx kubectl describe pod网关Pod名-ningress-nginx kubectl logs网关Pod名-ningress-nginx--tail200-f常见原因节点资源不足CPU/内存 Limit 不够ConfigMap 配置语法错误如 nginx-configuration网络插件异常Pod 无法获取 IP / 通信镜像拉取失败仓库权限、网络端口冲突80/443 被主机占用修复调整资源配额、修正 ConfigMap、重装网络插件、检查镜像2. 网关 Service 无 ExternalIP / 无法外网访问现象ingress-nginx Service 为 LoadBalancer但 EXTERNAL-IP 为排查命令kubectl get svc-ningress-nginx ingress-nginx-controller kubectl describe svc ingress-nginx-controller-ningress-nginx常见原因云厂商 EIP 未自动分配公有云需手动配节点安全组/防火墙未放行 80/443集群网络模式不支持 LoadBalancer如自建集群云厂商负载均衡器异常修复手动绑定 EIP、放行安全组、改用 NodePort反向代理3. 网关配置不生效 / 规则不更新现象更新 Ingress 后访问无变化网关日志无 reload排查命令kubectl get ingress名称-oyaml kubectlexec-it网关Pod-ningress-nginx --cat/etc/nginx/nginx.conf|grep域名/路径kubectl logs网关Pod-ningress-nginx|grepreload常见原因Ingress 资源 YAML 语法错误kubectl describe ingress 看 Events注解annotation拼写错误如 nginx.ingress.kubernetes.io/*网关控制器监听命名空间错误–watch-namespace控制器版本与 K8s 不兼容修复修正 Ingress YAML、核对注解、调整控制器启动参数4. 网关性能差 / 高并发报错 / 连接超时现象QPS 高时 502/504、连接被重置、响应慢排查命令kubectltoppods-ningress-nginx kubectlexec网关Pod-ningress-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排查命令kubectl get ingress kubectl describe ingress名称# 看 host/pathkubectlexec网关Pod--cat/etc/nginx/conf.d/*|grephost常见原因访问域名与 Ingress.host 不匹配含大小写、泛域名路径 Path 配置错误含 PathTypeExact/PrefixIngress 未加正确注解如重写路径 rewrite-target路径含非法字符?、、中文修复核对 host、修正 Path/PathType、配置重写规则6. Ingress 存在但 404网关日志无记录现象curl 返回 404但网关日志看不到该请求常见原因DNS 解析错误域名指向非网关 IP本地 hosts 配置错误公网 DNS 未生效 / 缓存旧解析流量被防火墙/安全组拦截修复nslookup 验证域名、清空 DNS 缓存、检查防火墙7. 路径重写后 404rewrite-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排查命令kubectl get endpointsservice-namekubectl get pods-lapp-label-owide# 看 READYkubectl describe podpod名# 看 Events/健康检查常见原因Service 无 EndpointsPod 未就绪、标签不匹配Pod 状态Pending、Crash、Not Ready健康检查失败liveness/readiness 误判Service 端口与容器端口不匹配修复核对标签、修复 Pod、调整健康检查、修正端口10. 访问 502 Bad Gateway现象网关收到响应但无效日志upstream prematurely closed排查命令kubectl port-forward svc/服务8080:80curlhttp://localhost:8080# 直连Service测试kubectl logs业务Pod--tail100# 看业务报错常见原因业务 Pod 内部异常进程挂、OOM、报错退出业务端口未监听 / 监听错误网关到 Pod 网络不通CNI、网络策略后端超时时间过短业务启动慢修复修复业务代码、核对端口、检查网络策略、调大超时11. 503 偶发 / 间歇性故障现象时而正常时而 503流量不均常见原因部分 Pod 异常部分 Ready 部分 Not ReadyPod 所在节点网络不稳定网关负载不均、连接池耗尽后端服务空闲超时小于网关idle timeout修复驱逐异常 Pod、检查节点、调大连接池、匹配超时12. 网关到后端 HTTPS 服务 502/400现象报错 The plain HTTP request was sent to HTTPS port常见原因Ingress 未配置 backend-protocol: HTTPS网关用 HTTP 访问 HTTPS 后端修复添加注解annotations:nginx.ingress.kubernetes.io/backend-protocol:HTTPS四、HTTPS/证书故障4 个13. TLS 握手失败 / SSL_ERROR现象浏览器提示证书无效、不安全curl SSL handshake failed排查命令kubectl get secrettls-secret-nns# 确认存在openssl s_client-connect域名:443# 测试证书常见原因Secret 不存在 / 类型非 kubernetes.io/tls证书域名与 Ingress.host 不匹配含泛域名证书过期 / 私钥不匹配证书链不完整缺少中间 CA修复重新创建证书 Secret、核对域名、更新有效期14. HTTPS 访问 404 / 跳 HTTP 异常现象HTTPS 404HTTP 正常或强制 HTTPS 失效常见原因TLS 配置错误secretName 错误、跨命名空间未配置 http-redirect 注解80/443 端口未同时放行修复核对 TLS.secretName、配置强制 HTTPSannotations:nginx.ingress.kubernetes.io/ssl-redirect:truenginx.ingress.kubernetes.io/force-ssl-redirect:true15. 多域名证书冲突 / SNI 不生效现象多 Ingress 共用证书部分域名证书错误常见原因一个证书包含多个域名但 Ingress 未正确匹配网关未开启 SNI默认开启证书配置重复修复使用通配符证书、确保 Secret 正确引用、清理重复配置16. 证书自动更新cert-manager不生效现象证书过期cert-manager 未自动续期排查命令kubectl get certificates kubectl describe certificate名称常见原因cert-manager Pod 异常DNS 验证失败公网 DNS 不生效账号权限/额度不足Let’s Encrypt修复重启 cert-manager、检查 DNS、核对账号五、高级功能故障4 个17. 会话保持不生效现象配置 sticky 后请求仍分发到不同 Pod常见原因注解拼写错误如 cookie-affinityService 端口配置错误网关未开启会话保持修复annotations:nginx.ingress.kubernetes.io/affinity:cookienginx.ingress.kubernetes.io/session-cookie-name:route18. 限流/熔断异常429 或不生效现象限流不生效或误拦截正常请求常见原因限流注解参数错误rate-limit共享内存 zone 大小不足网关重启后配置丢失修复核对限流参数、调大 shared memory、稳定网关19. WebSocket / gRPC 访问异常现象WebSocket 断开、gRPC 报错常见原因未开启 WebSocket 支持注解超时时间过短默认 60s不支持 HTTP2gRPC 依赖修复annotations:nginx.ingress.kubernetes.io/websocket-services:svc-namenginx.ingress.kubernetes.io/proxy-read-timeout:3600nginx.ingress.kubernetes.io/backend-protocol:GRPC# gRPC20. 网络策略导致网关无法访问后端现象一切配置正常但 502/503网络不通排查命令kubectl get networkpolicies-n业务NSkubectl describe networkpolicy名称常见原因NetworkPolicy 限制入口未放通网关命名空间修复添加 ingress 规则允许 ingress-nginx 命名空间访问网关故障排查万能 6 步查网关状态Pod 运行、日志无报错、Service IP 正常查 Ingress 规则host、path、serviceName、port 正确查后端服务Service 存在、Endpoints 非空、Pod Ready查网络连通网关 → Service → Pod 网络通、端口可访问查配置注解TLS、重写、协议、超时等注解正确查日志网关日志 业务 Pod 日志定位报错点