Debian上Kubernetes故障排查实操手册
一 快速定位流程
- 集群概览与节点状态
- 查看集群与节点健康：kubectl cluster-info、kubectl get nodes -o wide。
- 查看系统组件与事件：kubectl get pods -n kube-system、kubectl get events -A --sort-by=.metadata.creationTimestamp。
- 工作负载与网络连通
- 定位异常Pod：kubectl get pods -A -o wide，进入详情：kubectl describe pod -n 。
- 查看容器日志：kubectl logs -n [-c ]；进入调试：kubectl debug -it --image=busybox:1.36 --target=。
- 资源与调度
- 资源压力与驱逐：kubectl top nodes、kubectl top pods -A；检查节点条件：kubectl describe node | grep -A5 Conditions。
- 外部访问与端口
- 服务可达性：在节点上测试 curl http://: 或 nc -vz ；必要时临时改为 NodePort/LoadBalancer 验证。
二 节点与系统层检查
- 基础环境
- 关闭Swap：swapoff -a 并注释 /etc/fstab 中的swap行；内核转发与桥接：
- sysctl：net.ipv4.ip_forward=1、net.bridge.bridge-nf-call-iptables=1、net.bridge.bridge-nf-call-ip6tables=1
- 模块：modprobe br_netfilter
- 容器运行时
- 自 v1.24 起内置 dockershim 移除，建议使用 containerd 作为运行时；如使用 Docker，需通过 cri-dockerd 适配。
- 防火墙与端口
- UFW/iptables：确保控制面与工作节点间必要端口开放，例如 6443（API）、2379/2380（etcd）、以及 kubelet 端口区间（默认 10250 等）；示例：
- sudo ufw allow 6443/tcp
- sudo ufw allow 2379/tcp
- sudo ufw allow 2380/tcp
- 系统日志与内核消息
- 节点侧排查：journalctl -u kubelet -xe、tail -f /var/log/syslog、dmesg | tail -n50。
三 常见故障与修复对照表
| 症状 |
快速检查 |
修复建议 |
| 节点 NotReady |
kubectl describe node；journalctl -u kubelet |
确认容器运行时就绪、网络插件已部署、内核参数与模块正确、节点资源充足 |
| Pod 状态 ErrImagePull/ImagePullBackOff |
kubectl describe pod；查看镜像名与仓库 |
修正镜像名/标签；私有仓库在节点放置 CA 证书至 /etc/docker/certs.d//ca.crt；必要时使用可拉取镜像 |
| Service 访问不通 |
kubectl get svc；curl/nc 测试；节点防火墙 |
核对 ports/targetPort；确认 Service type（ClusterIP/NodePort/LoadBalancer）；开放节点端口与云厂商安全组 |
| 节点加入失败（kubeadm join） |
检查 token/caCert/hash；admin.conf 权限 |
在控制面重新生成 kubeadm token create --print-join-command；确保 /etc/kubernetes/admin.conf 权限正确并分发到工作节点 |
| 网络插件异常（Pod 间不通/Service 解析失败） |
kubectl get pods -n kube-system；kubectl logs |
重新部署网络插件（如 Flannel/Calico）；检查 IP forwarding、iptables/nftables 规则与网段配置 |
| 证书错误（API/客户端） |
curl -vk；检查 kubeconfig 证书 |
更新/重新签发证书；客户端使用 –cacert 指定 CA；临时排障可用 -k（生产禁用） |
| 磁盘压力导致 Pod 被驱逐（Evicted） |
kubectl get pods -A |
清理节点磁盘（容器日志、镜像、临时文件）；扩容磁盘或调整驱逐阈值 |
| DNS 解析失败 |
kubectl get pods -n kube-system -l k8s-app=coredns；kubectl logs |
确认 CoreDNS 运行且配置正确；检查上游 DNS 与 NetworkPolicy 是否阻断 UDP/TCP 53 |
四 日志与可观测性
- 组件与容器日志
- 集群组件：kubectl logs -n kube-system
- 应用容器：kubectl logs -n [-c ]；调试：kubectl debug
- 集中式日志方案
- EFK（Elasticsearch + Fluentd + Kibana）：Fluentd 以 DaemonSet 收集节点与容器日志，写入 Elasticsearch，在 Kibana 检索与可视化。
- Loki + Grafana：轻量聚合日志，配合 Grafana 面板查询与告警。
五 高频命令清单
- 集群与节点
- kubectl cluster-info
- kubectl get nodes -o wide
- kubectl describe node
- 工作负载与事件
- kubectl get pods -A -o wide
- kubectl describe pod -n
- kubectl logs -n [-c ]
- kubectl get events -A --sort-by=.metadata.creationTimestamp
- 资源与网络
- kubectl top nodes、kubectl top pods -A
- kubectl get svc -A、kubectl get endpoints -n
- 节点侧：ping 、sudo ufw status、sudo iptables -L、journalctl -u kubelet -xe、tail -f /var/log/syslog、dmesg | tail
