Kubernetes 在 Debian 上的故障排查技巧

一 快速自检与环境准备

• 资源与系统：至少准备2 核 CPU、2 GB 内存、20–50 GB 磁盘，系统为Debian 稳定版，内核建议≥ 4.19，并确保NTP 时间同步与稳定网络。
• 禁用 Swap：Kubernetes 不支持启用 Swap，执行：
  sudo swapoff -a
  sudo sed -i ‘/ swap / s/^(.*)$/#\1/g’ /etc/fstab
• 容器运行时：安装并启动 containerd（或 Docker，二选一）。示例：
  sudo apt update && sudo apt install -y containerd
  sudo systemctl enable --now containerd
• 组件安装：添加 Kubernetes APT 源并安装 kubelet、kubeadm、kubectl，然后执行：
  sudo apt-mark hold kubelet kubeadm kubectl（防止被升级破坏版本一致性）
• 初始化要点：控制平面执行 kubeadm init，常用参数：
  –apiserver-advertise-address=<本机IP>
  –pod-network-cidr=10.244.0.0/16（与所选网络插件匹配）
  必要时指定 --image-repository 使用国内镜像源（如 registry.aliyuncs.com/google_containers）
• 配置 kubectl：
  mkdir -p $HOME/.kube && sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config
• 安装网络插件：如 Flannel：
  kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml
• 节点就绪：工作节点加入后，使用 kubectl get nodes 检查状态是否为 Ready。

二 高频故障与修复

• 镜像拉取失败：国内环境可指定镜像仓库（如 registry.aliyuncs.com/google_containers），或提前用 crictl/docker 拉取并重新打标签；若使用 containerd，确保 /etc/containerd/config.toml 的 sandbox_image 与拉取镜像一致。
• 预检失败（常见为 Swap 未关闭、端口被占用、内核参数不当）：关闭 Swap、释放端口、按需设置内核参数（如启用桥接转发 net.bridge.bridge-nf-call-iptables=1 等）。
• 端口未放行：若启用 UFW，放行关键端口（示例）：
  sudo ufw allow 6443,2379,2380,10250,10251,10252,10255/tcp && sudo ufw reload
  如使用 firewalld/iptables，做等价放行规则。
• 节点 NotReady：多因网络插件未就绪或 kube-proxy 异常，检查 kubectl get pods -n kube-system，确认 flannel/cilium/kube-proxy 运行正常；必要时重新应用网络插件清单。
• 组件版本不兼容：核对 kubelet/kubeadm/kubectl 与要部署的 Kubernetes 版本一致，参考官方兼容矩阵，避免混装。
• kubeconfig 配置错误：确认 $HOME/.kube/config 存在且有效，执行 kubectl config view 校验当前上下文与集群信息。
• 节点无法加入集群：可能因 Token 过期、网络不通、防火墙阻止通信。在主节点重新生成加入命令：
  sudo kubeadm token create --print-join-command
  在工作节点执行新的加入命令；同时开放 6443、2379、2380 等端口。
• Pod 无法启动（ImagePullBackOff/CrashLoopBackOff）：查看 Pod 详情与事件（kubectl describe pod、kubectl get events），手动拉取镜像验证，检查资源请求/限制与容器配置。
• CoreDNS 无法解析：检查 CoreDNS Pod 是否 Running，查看日志与 ConfigMap（forward 规则），确认网络插件转发正常。

三 关键日志与定位命令

• 查看 kubelet 日志：sudo journalctl -u kubelet -xe（关注镜像、cgroup、swap、端口冲突等）
• 查看系统日志：sudo journalctl -xe 或 /var/log/syslog（定位网络、服务、权限相关错误）
• 查看集群组件日志：kubectl logs -n kube-system （优先排查 coredns、kube-proxy、flannel 等系统 Pod）
• 查看节点与组件状态：kubectl get nodes、kubectl get pods -A -o wide（快速判断网络插件与控制平面是否就绪）
• 查看 kubelet 服务状态：sudo systemctl status kubelet
• 查看事件与详情：kubectl describe pod 、kubectl get events（定位调度、镜像、网络策略等问题）
• 端口占用排查：sudo lsof -i :<端口号>（定位端口冲突）

四 一键纠偏脚本示例

• 用途：快速完成 Debian 上的基础纠偏（关闭 Swap、安装 containerd、安装并锁定 kubelet/kubeadm/kubectl、放行 UFW 端口、初始化控制平面、部署 Flannel、输出 join 命令）。

• 注意：按需修改 API_IP 与 pod-network-cidr，在受限网络下可替换镜像仓库；执行前确保具备 sudo 权限与网络连通。

• 脚本：
  #!/usr/bin/env bash
  set -e

  0) 基本环境

  sudo apt update && sudo apt install -y ca-certificates curl gnupg lsb-release

  1) 关闭 Swap

  sudo swapoff -a
  sudo sed -i ‘/ swap / s/^(.*)$/#\1/g’ /etc/fstab

  2) 安装 containerd

  sudo apt install -y containerd
  sudo systemctl enable --now containerd

  3) 安装 kubelet/kubeadm/kubectl

  curl -fsSLo /usr/share/keyrings/kubernetes-archive-keyring.gpg https://packages.cloud.google.com/apt/doc/apt-keyring.gpg
  echo “deb [signed-by=/usr/share/keyrings/kubernetes-archive-keyring.gpg] https://apt.kubernetes.io/ kubernetes-xenial main” | sudo tee /etc/apt/sources.list.d/kubernetes.list > /dev/null
  sudo apt update
  sudo apt install -y kubelet kubeadm kubectl
  sudo apt-mark hold kubelet kubeadm kubectl

  4) UFW 放行（如启用）

  sudo ufw allow 6443,2379,2380,10250,10251,10252,10255/tcp || true
  sudo ufw reload || true

  5) 初始化控制平面（按需修改参数）

  API_IP=$(ip -4 addr show scope global | grep -oP ‘(?<=inet\s)\d+(.\d+){3}’ | head -n1)
  sudo kubeadm init \ –apiserver-advertise-address=$API_IP \ –pod-network-cidr=10.244.0.0/16 \ –image-repository=registry.aliyuncs.com/google_containers

  6) 配置 kubectl

  mkdir -p $HOME/.kube
  sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
  sudo chown $(id -u):$(id -g) $HOME/.kube/config

  7) 安装 Flannel 网络插件

  kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml

  echo “Init done. Run on worker nodes:”
  echo " sudo kubeadm join $API_IP:6443 --token --discovery-token-ca-cert-hash sha256:"
  说明：请将 与 替换为 kubeadm init 输出中的实际值；如使用云厂商或受限网络，请提前准备镜像或使用内网镜像仓库。

五 仍未解决时请准备的信息

• 执行 kubeadm init 的完整输出与关键报错片段。
• sudo journalctl -u kubelet -xe 的最后 100 行。
• kubectl get nodes -o wide 与 kubectl get pods -A -o wide 的结果。
• 当前系统信息：uname -a、lsb_release -a、free -m、df -h、ip a、sudo ufw status 或防火墙规则。
• 使用的 Kubernetes 版本与容器运行时版本（kubelet --version、crictl version 或 docker version）。