Debian上部署Kubernetes的常见错误与排查要点
一 环境准备与内核参数
- 未关闭或未彻底禁用 Swap：会导致 kubelet 无法启动或频繁报错。处理：执行 swapoff -a 并注释 /etc/fstab 中的 swap 行，重启验证。
- 未加载 overlay/br_netfilter 或未设置 sysctl：Pod 网络与跨主机通信异常。处理：加载模块 modprobe overlay、br_netfilter，并写入 /etc/sysctl.d/99-kubernetes-k8s.conf：net.bridge.bridge-nf-call-iptables=1、net.ipv4.ip_forward=1，执行 sysctl --system。
- 主机名、MAC 或 product_uuid 冲突（克隆/虚拟化环境常见）：节点注册异常或被拒。处理：确保各节点主机名唯一，检查并修正 /sys/class/dmi/id/product_uuid。
- 资源不足：节点 CPU/内存 紧张使控制面或 kubelet 异常。处理：扩容或降低组件与 Pod 的资源请求/限制。
二 网络连通与端口
- 节点间网络不通或防火墙阻断：控制面与节点通信失败。处理：在节点间 ping 互通，检查 ufw/iptables 规则，放行关键端口（如 6443、2379、2380 等）。
- 未安装或未正确部署 CNI 网络插件：节点 NotReady、Pod 间无法通信、DNS 解析失败。处理：部署 Flannel/Calico 等插件，确认 kube-proxy 正常运行。
- 服务暴露类型不当：使用 ClusterIP 导致外网不可达。处理：对外访问改为 NodePort/LoadBalancer，或配合 Ingress。
- kubeconfig 配置或环境变量错误：kubectl 报权限或找不到配置。处理：检查 KUBECONFIG 路径与内容，或执行 kubectl config view 核对当前上下文。
三 镜像与容器运行时
- ErrImagePull/ImagePullBackOff：镜像不存在、仓库不可达或私有仓库未配置凭据。处理：核对镜像名/标签，确保可访问；私有仓库在 /etc/docker/certs.d//ca.crt 放置 CA 证书。
- 容器运行时未就绪（Docker/containerd 未启动或配置不当）：kubelet 报 CRI 不可用。处理：确认 docker/containerd 服务运行，镜像仓库与驱动配置正确。
- 版本不兼容：如 containerd 与 Kubernetes 版本不匹配。处理：按官方兼容矩阵选择组件版本。
四 初始化加入与权限安全
- kubeadm join 失败：常见原因为 token 过期、CA 证书哈希不匹配、端口占用或配置残留。处理：在主节点重新生成 token 与哈希，清理残留文件后重试。
- RBAC 策略过严或缺失：组件/Pod 权限不足导致异常。处理：核查 ClusterRole/RoleBinding 配置。
- TLS 证书问题：证书过期或 CA 不一致导致 API 访问失败。处理：更新证书，必要时用 –cacert 指定信任链，生产环境避免 -k/–insecure。
- 组件版本不一致：控制面与节点组件版本差异大引发兼容性问题。处理：统一 kubelet/kubeadm/kubectl 版本。
五 存储 DNS 与日志排错
- PersistentVolume/StorageClass 未就绪：有状态应用无法挂载卷。处理：核查后端（如 NFS/Ceph）与 StorageClass 配置是否正确。
- CoreDNS 未运行或配置错误：服务发现与内部域名解析失败。处理：确认 CoreDNS Pod 就绪，检查 kube-dns 相关配置。
- 时区不一致：容器日志时间与业务不一致。处理：在 Deployment 中设置环境变量 TZ=Asia/Shanghai，或在镜像中配置时区。
- 日志与诊断命令：使用 journalctl -u kubelet、kubectl logs 、kubectl describe pod 定位问题；必要时 systemctl restart 恢复。
