Kubernetes Ingress + TLS 故障排查全流程

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

水上冰石

605人浏览 · 2026-01-25 18:49:20

水上冰石 · 2026-01-25 18:49:20 发布

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

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 兼容性问题