Kubernetes Ingress + TLS 故障排查全流程

注：本文虽然为大模型生成和整理，但是却具有极大的实践指导意义，请对大模型生成的文章质量多些信任，本作者通过多次根据指导实践，完成了问题查证，最终实现了预期效果

Kubernetes Ingress + TLS 故障排查全流程（命令+预期结果+流程图）

本文总结了 Ingress-Nginx 结合 TLS 证书访问不通的标准化排查流程，包含逐段验证命令、预期结果和故障定位逻辑，适用于 GitLab、Jenkins 等各类基于 Ingress 暴露的服务。

一、 故障排查核心流程图

开始
├── 1. 基础连通性验证（端口+进程）
│   ├── 1.1 检查 Ingress-Nginx Pod 状态 → 正常: Running；异常: CrashLoopBackOff/Error
│   ├── 1.2 检查 Ingress-Nginx 端口监听 → 正常: 80/443 端口被 nginx-ingress 占用
│   └── 1.3 检查 Ingress 资源配置 → 正常: HOSTS/SECRET 配置正确；异常: 配置缺失/错误
├── 2. TLS 证书有效性验证
│   ├── 2.1 检查 TLS Secret 是否存在 → 正常: Secret 存在且包含 tls.crt/tls.key
│   ├── 2.2 解码证书验证域名/有效性 → 正常: 域名匹配+私钥证书成对；异常: 域名不匹配/密钥不匹配
│   └── 2.3 检查 Ingress TLS 关联 → 正常: secretName 与 Secret 名称一致；异常: 名称不匹配
├── 3. 域名解析与端口转发验证
│   ├── 3.1 验证域名解析 IP → 正常: 解析到 Ingress 节点 IP；异常: 解析到非监听节点
│   ├── 3.2 直接访问节点 IP+Host 头 → 正常: 建立 SSL 连接；异常: Connection refused/超时
│   └── 3.3 检查防火墙/安全组 → 正常: 80/443 端口放行；异常: 端口被拦截
├── 4. 后端服务转发链路验证
│   ├── 4.1 测试 Ingress → Service 连通性 → 正常: 集群内访问 Service 通；异常: Service 不可达
│   ├── 4.2 测试 Service → Pod 连通性 → 正常: 访问 Pod IP 通；异常: Pod 未运行/端口错误
│   └── 4.3 检查 Pod 内部服务状态 → 正常: 服务进程运行；异常: 进程崩溃/资源不足
└── 5. 高级配置验证（重定向/HTTP2）
    ├── 5.1 检查 Ingress 注解配置 → 正常: ssl-redirect 等注解正确；异常: 注解缺失/冲突
    └── 5.2 查看 Ingress-Nginx 日志 → 正常: 无转发错误；异常: 日志中包含 upstream 错误
结束（定位问题并修复）

二、 分阶段排查步骤（命令+预期结果+故障处理）

阶段 1：基础连通性验证（Ingress 组件是否正常）

核心目标：确认 Ingress-Nginx 控制器本身运行正常，端口监听无误。

|-----------------------------|-----------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
| 排查步骤 | 执行命令 | 预期结果 | 异常处理方案 |
| 1.1 检查 Ingress-Nginx Pod 状态 | ​​kubectl get pod -n kube-system -l app=nginx-ingress​​ | Pod 状态为 ​​Running​​，RESTARTS 为 0 | 1. 异常状态（CrashLoopBackOff）：执行 ​​kubectl logs <pod-name> -n kube-system​​ 查看日志 2. 常见原因：资源不足/端口冲突 → 扩容资源/停止占用 80/443 的服务 |
| 1.2 检查节点 80/443 端口监听 | `netstat -tlnp | grep -E "80 | 443"` |
| 1.3 检查 Ingress 资源配置 | ​​kubectl get ingress -n <namespace> -o yaml​​ | 1. ​​spec.tls.hosts​​ 包含目标域名 2. ​​spec.tls.secretName​​ 正确 3. ​​spec.rules.host​​ 与 TLS 域名一致 4. ​​spec.rules.http.paths.backend​​ 指向正确 Service/Port | 1. 域名不匹配：修改 Ingress ​​hosts​​ 与证书域名一致 2. Secret 名称错误：调整 ​​secretName​​ 与实际 Secret 名称一致 |

阶段 2：TLS 证书有效性验证（证书是否合法可用）

核心目标：确认 Secret 中的证书/私钥有效，且与 Ingress 配置匹配。

|------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|---------------------------------------------------------------------------------------|
| 排查步骤 | 执行命令 | 预期结果 | 异常处理方案 |
| 2.1 检查 TLS Secret 是否存在 | ​​kubectl get secret <tls-secret-name> -n <namespace>​​ | Secret 存在，Type 为 ​​kubernetes.io/tls​​ | 不存在则重新创建： ​​kubectl create secret tls <name> --cert=xxx.crt --key=xxx.key -n <ns>​​ |
| 2.2 解码证书验证域名 | ​​kubectl get secret <tls-secret-name> -n <ns> -o jsonpath='{.data.tls\.crt}' | base64 -d > secret.crt<br>openssl x509 -in secret.crt -noout -subject​​ | Subject 中 ​​CN​​​ 字段等于目标域名（如 ​​CN=gitlab.devops.global-fairy.top​​） | 域名不匹配：重新生成包含正确域名的证书，再重建 Secret |
| 2.3 验证证书与私钥成对 | ​​kubectl get secret <tls-secret-name> -n <ns> -o jsonpath='{.data.tls\.key}' | base64 -d > secret.key<br># 验证私钥有效性<br>openssl rsa -in secret.key -check<br># 对比模数 MD5<br>openssl x509 -in secret.crt -noout -modulus | openssl md5<br>openssl rsa -in secret.key -noout -modulus | openssl md5​​ | 1. 私钥验证无报错 2. 两个 MD5 值完全一致 | 1. 私钥无效：重新生成证书私钥对 2. MD5 不一致：确认证书和私钥是成对生成的，重建 Secret |

阶段 3：域名解析与端口转发验证（请求能否到达 Ingress 节点）

核心目标：确认域名解析到正确的 Ingress 节点，且端口可访问。

|----------------------|---------------------------------------------------------------|-----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------|
| 排查步骤 | 执行命令 | 预期结果 | 异常处理方案 |
| 3.1 验证域名解析 IP | ​​nslookup <目标域名>​​​ 或 ​​getent hosts <目标域名>​​ | 解析到的 IP 是 Ingress-Nginx 运行的节点 IP | 1. 解析到错误 IP：修改 hosts 文件或 DNS 记录，指向正确节点 IP 2. 提示未知域名：检查 hosts/DNS 配置是否生效 |
| 3.2 直接访问节点 IP+Host 头 | ​​curl -v https://<节点IP> --insecure -H "Host: <目标域名>"​​ | 1. 输出 ​​SSL connection using TLSv1.3​​（SSL 握手成功） 2. 无 ​​Connection refused​​ 错误 | 1. 连接拒绝：检查 Ingress-Nginx 是否监听 443 端口 → 调整部署模式（NodePort/HostNetwork） 2. SSL 握手失败：回到阶段 2 重新验证证书 |
| 3.3 检查防火墙/安全组 | ```# CentOS 防火墙检查 firewall-cmd --list-ports | grep -E "80 | 443" # NodePort 模式需检查映射端口 kubectl get svc nginx-ingress-controller -n kube-system``` | 1. 80/443 端口已放行 2. NodePort 模式下 443 对应的 NodePort 已放行 |

阶段 4：后端服务转发链路验证（Ingress 能否转发到 Pod）

核心目标：确认 Ingress → Service → Pod 的转发链路畅通。

|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------|
| 排查步骤 | 执行命令 | 预期结果 | 异常处理方案 |
| 4.1 获取 Service 信息 | ​​kubectl get svc <service-name> -n <namespace> -o yaml​​ | 1. ​​spec.ports[0].port​​ 与 Ingress 配置的后端端口一致 2. ​​spec.selector​​ 标签与 Pod 标签匹配 | 1. 端口不匹配：修改 Ingress 后端端口或 Service 端口 2. 标签不匹配：调整 Service selector 或 Pod 标签 |
| 4.2 测试 Service 连通性 | ​​SVC_IP=$(kubectl get svc <svc-name> -n <ns> -o jsonpath='{.spec.clusterIP}')<br>curl -v http://$SVC_IP:<service-port>​​ | 返回后端服务响应（如 GitLab 的 302 重定向、Jenkins 的 200 响应） | 1. Service 不可达：检查 Service 是否关联到 Pod → ​​kubectl get endpoints <svc-name> -n <ns>​​2. 返回 404/500：检查后端 Pod 服务是否正常 |
| 4.3 测试 Pod 连通性 | ​​POD_IP=$(kubectl get pod <pod-name> -n <ns> -o jsonpath='{.status.podIP}')<br>curl -v http://$POD_IP:<pod-port>​​ | 返回后端服务响应（与 4.2 结果一致） | 1. Pod 不可达：检查 Pod 是否运行 → ​​kubectl get pod <pod-name> -n <ns>​​2. Pod 内服务未启动：进入 Pod 重启服务 → ​​kubectl exec -it <pod-name> -n <ns> -- bash​​ |
| 4.4 检查 Pod 资源与状态 | ​​# 无 Metrics Server 时查看 Pod 事件<br>kubectl describe pod <pod-name> -n <ns> | grep -A 10 Events<br># 有 Metrics Server 时查看资源<br>kubectl top pod <pod-name> -n <ns>​​ | 1. Events 无 ​​OOMKilled​​​/​​BackOff​​ 错误 2. 资源使用率未超过 limits | 1. OOM 错误：扩容 Pod 资源限制 2. 启动失败：查看 Pod 日志 → ​​kubectl logs <pod-name> -n <ns>​​ |

阶段 5：高级配置验证（解决 302/400/无响应问题）

核心目标：处理 Ingress 配置导致的重定向、超时等问题。

|---------------------------|----------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------|
| 排查步骤 | 执行命令 | 预期结果 | 异常处理方案 |
| 5.1 检查 Ingress 注解配置 | ​​kubectl get ingress <ingress-name> -n <ns> -o yaml​​ | 包含以下关键注解（按需配置）： ​​nginx.ingress.kubernetes.io/ssl-redirect: "true"​​ ​​nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"​​ ​​nginx.ingress.kubernetes.io/http2-disable: "true"​​ | 1. 缺失 ssl-redirect：添加注解强制 HTTP 转 HTTPS 2. 存在 HTTP2 兼容性问题：添加 ​​http2-disable: "true"​​ 注解 |
| 5.2 查看 Ingress-Nginx 日志 | ​​kubectl logs <nginx-ingress-pod> -n kube-system​​ | 无 ​​upstream timed out​​​/​​host not found​​ 等错误 | 1. upstream 超时：延长 proxy-read-timeout 注解 2. host not found：检查 Ingress host 配置是否正确 |
| 5.3 重启 Ingress-Nginx 生效配置 | ​​kubectl rollout restart deployment nginx-ingress-controller -n kube-system​​ | Ingress-Nginx Pod 重启后状态为 Running | 重启后仍报错：检查配置文件语法是否正确 → ​​kubectl apply -f ingress.yaml --dry-run=client​​ |

三、 常见故障速查表

|--------------------------------|--------|---------------------------------|
| 故障现象 | 对应排查阶段 | 高频原因 |
| ​​Connection refused (443)​​ | 阶段 1/3 | Ingress-Nginx 未监听 443 端口；防火墙未放行 |
| ​​SSL handshake failed​​ | 阶段 2 | 证书域名不匹配；证书私钥不匹配 |
| 域名解析到错误 IP | 阶段 3 | hosts/DNS 记录配置错误 |
| ​​upstream timed out​​ | 阶段 4/5 | 后端 Pod 资源不足；Ingress 超时时间过短 |
| ​​302 Found​​ 但浏览器无法访问 | 阶段 5 | 缺失 HTTPS 重定向注解；HTTP2 兼容性问题 |

四、 复用说明

1. 本文流程适用于 所有基于 Ingress-Nginx 暴露的服务 ，只需替换 ​<namespace>​/​<ingress-name>​ 等占位符；
2. 排查时按阶段顺序执行，优先解决前序阶段的问题，再推进到后序阶段；
3. 建议将本文保存为 Markdown 文件，结合实际场景补充自定义命令和故障案例。

需要我帮你把这份排查流程整理成一个可直接打印的排查 checklist吗？