Debian 上 Kubernetes 故障排查实战手册
一 快速定位路径
- 集群连通性：执行 kubectl cluster-info 与 kubectl get nodes，若 API 访问异常（如 6443 端口拒绝），优先检查控制面组件与网络连通性。
- 节点状态：查看 kubectl get nodes 的 Ready 条件与 Conditions 消息，定位是 kubelet、网络还是镜像问题。
- 系统侧日志：在节点上用 journalctl -u kubelet -xe、journalctl -xe 与 tail -f /var/log/syslog 观察启动与运行报错。
- 组件日志：对 kube-apiserver/kube-controller-manager/kube-scheduler/kube-proxy 等容器化组件，使用 kubectl logs -n kube-system 查看。
- 资源与事件：用 kubectl describe pod 获取事件（Events）；用 kubectl top nodes/pods 检查 CPU/内存 压力。
- 网络连通：节点间 ping/ss -lntp 检查端口与连通性；必要时排查 iptables/nftables 规则。
- 存储与 DNS：确认 PersistentVolume/PVC 状态与 CoreDNS 是否 Running 并能解析内部服务。
二 高频故障与修复要点
- API Server 连接被拒绝（如 The connection to the server :6443 was refused）
- 确认 kubelet 已启动：systemctl status kubelet；2) 查看 journalctl -u kubelet 与 apiserver 容器日志；3) 若使用 containerd，检查 cgroup driver 是否与 kubelet 一致：编辑 /etc/containerd/config.toml，设置 SystemdCgroup = true 并重启 containerd 与 kubelet；4) 核对 6443/2379/2380 等端口开放与防火墙策略。
- 节点 NotReady
- 查看 kubectl describe node 的 Conditions；2) 确认 kubelet 健康、容器运行时就绪、CNI 网络插件已安装（如 Flannel）；3) 检查 镜像拉取、磁盘空间、内核参数与 时间同步。
- Pod CrashLoopBackOff/ImagePullBackOff
- 用 kubectl logs -c 与 kubectl describe pod 定位启动失败原因；2) 若是私有镜像，核查 imagePullSecrets；3) 若是 Init Container 失败，先解决 Init 依赖。
- DNS 解析异常
- 确认 kube-dns/CoreDNS Pod 为 Running 且 Endpoints 就绪；2) 检查 ServiceAccount/ClusterRoleBinding 与 ConfigMap 配置；3) 在集群内执行 nslookup kubernetes.default.svc.cluster.local 验证。
- 权限与配置错误
- 核查 kubeconfig 路径与上下文：kubectl config view；2) 检查 RBAC 授权是否覆盖当前用户/ServiceAccount；3) 确认 TLS 证书有效且未过期。
三 日志与系统信息采集清单
- 集群概览：kubectl version、kubectl cluster-info、kubectl get nodes -o wide、kubectl get pods -A -o wide。
- 事件与状态：kubectl get events -A --sort-by=.metadata.creationTimestamp、kubectl describe node 、kubectl describe pod 。
- 组件日志：
- 节点服务：journalctl -u kubelet -xe、journalctl -xe、tail -f /var/log/syslog；
- 控制面容器：kubectl logs -n kube-system kube-apiserver-、kube-controller-manager-、kube-scheduler-；
- 网络与 DNS：kubectl logs -n kube-system kube-proxy-、coredns-。
- 资源与网络：kubectl top nodes/pods，ss -lntp | grep -E ‘6443|10250|2379|2380’，ip a/route/iptables -S/nft list ruleset。
- 运行时与内核：crictl ps -a、crictl logs （若使用 containerd），uname -r、lsmod | grep br_netfilter、sysctl -a | grep bridge。
- 建议将上述命令输出统一打包，便于后续分析或提交工单。
四 环境与配置核查要点
- 基础要求：至少 2GB RAM（推荐 4GB）、2 核 CPU、50GB 磁盘；内核版本建议 ≥ 3.10。
- 系统准备：执行 sudo apt update && sudo apt upgrade -y；确保 swap 已关闭（执行 sudo swapoff -a 并注释 /etc/fstab 中的 swap 行）；按需配置 sysctl 与 iptables/nftables。
- 容器运行时：如使用 containerd，确保与 kubelet 的 cgroup driver 一致（常见为 systemd）；修改 /etc/containerd/config.toml 后重启 containerd 与 kubelet。
- 组件安装与版本：安装 kubelet/kubeadm/kubectl，并保持组件版本匹配；必要时 apt-mark hold 避免误升级。
- 初始化与网络：执行 kubeadm init 后按提示配置 kubectl（拷贝 /etc/kubernetes/admin.conf 至 $HOME/.kube/config），随后安装 CNI 插件（如 Flannel）。
- 端口与防火墙：放行 6443（API）、2379/2380（etcd）、10250（kubelet）、10251/10252（scheduler/controller-manager）等关键端口。
五 高效工具与进阶建议
- 日志聚合与检索：在集群中部署 EFK（Elasticsearch/Fluentd/Kibana） 或 Loki+Grafana，集中存储与查询 Pod/容器/系统 日志。
- 命令行增强：使用 Stern 同时 tail 多 Pod 日志；使用 Kubernetes Dashboard 进行可视化巡检。
- 审计与 Ingress 日志：启用 审计日志（Audit） 追踪 API 操作；采集 Ingress Controller 访问日志用于链路与性能分析。
- 日志格式与级别：Kubernetes 1.23+ 统一写入 stderr，1.26 起移除部分 klog 标志；可用 -v 调高日志级别，1.19+ 支持 –logging-format=json 便于结构化检索。
