Debian 上部署与运行 Kubernetes 的常见问题及解决
一 环境准备与系统要求
- 资源与系统：建议至少2 核 CPU、4GB RAM、50GB 磁盘，使用Debian 12等稳定版本，保证节点间网络互通与稳定互联网。
- 关闭 Swap：Kubelet 不支持启用 Swap 的环境，执行：
sudo swapoff -a
sudo sed -i ‘/ swap / s/^(.*)$/#\1/g’ /etc/fstab
- 内核与网络参数：加载必要模块并开启转发与桥接流量入 iptables：
sudo modprobe overlay && sudo modprobe br_netfilter
echo -e “overlay\nbr_netfilter” | sudo tee /etc/modules-load.d/k8s.conf
echo -e “net.bridge.bridge-nf-call-iptables = 1\nnet.bridge.bridge-nf-call-ip6tables = 1\nnet.ipv4.ip_forward = 1” | sudo tee /etc/sysctl.d/k8s.conf
sudo sysctl --system
- 防火墙放行：如使用 UFW，放行 API Server 等端口（示例）：
sudo ufw allow 6443/tcp && sudo ufw reload
- 容器运行时：推荐安装并启用 containerd；如使用 Docker，需额外安装 cri-dockerd 并在 kubeadm 加入时指定 –cri-socket unix:///var/run/cri-dockerd.sock。
二 安装与初始化阶段高频问题
- 组件安装与版本：添加 Kubernetes APT 源并安装 kubelet/kubeadm/kubectl，安装后用 apt-mark hold 固定版本，避免升级导致不兼容。
- 镜像拉取失败：初始化或加入时可能因 gcr.io 等镜像不可达而失败，可使用国内镜像仓库（如 registry.aliyuncs.com/google_containers）或先手动拉取并重标记。
- kubeadm init 预检失败：常见为Swap 未关闭、内核参数未生效、端口被占用等，按准备阶段逐项修复后重试。
- 加入节点失败：常见为 Token 过期或 CA 证书哈希不匹配，在主节点重新生成 Token 与哈希后再执行 kubeadm join。
- kubectl 配置：初始化完成后将 /etc/kubernetes/admin.conf 拷贝至用户目录并导出 KUBECONFIG，否则 kubectl 无法连接集群。
三 网络与访问类问题
- 服务访问失败：优先排查证书是否正确、端口映射是否准确、Service 类型是否匹配访问需求（外部访问应使用 NodePort/LoadBalancer 而非 ClusterIP）。
- 外部无法访问：确认 Service 为 NodePort/LoadBalancer，云上需配置对应的 负载均衡 或 节点安全组/防火墙 放行对应端口。
- Pod 间或 Pod 到 Service 不通：多因网络插件未就绪或CNI 配置错误，检查并重新部署网络插件（如 Calico/Flannel），确认 Pod CIDR 与网络插件配置一致。
- DNS 解析异常：检查 CoreDNS Pod 是否 Running、Endpoints 是否正确、是否存在网络策略阻断。
- 证书错误：curl 访问 API 或 Ingress 出现证书校验失败，更新服务端证书或在测试环境使用 -k/–insecure（生产环境不建议）。
四 运行时与镜像问题
- Pod 状态为 ErrImagePull/ImagePullBackOff：核对镜像名称与标签、仓库可达性；私有仓库需在节点配置 /etc/docker/certs.d//ca.crt 或使用 imagePullSecrets。
- 容器运行时不匹配：Kubernetes 1.24+ 默认使用 containerd/CRI，若坚持使用 Docker，需部署 cri-dockerd 并在 kubeadm 与 crictl 中正确设置 –cri-socket。
- crictl 无法连接运行时：配置 /etc/crictl.yaml 指定运行时端点，例如 containerd：
runtime-endpoint: unix:///var/run/containerd/containerd.sock
image-endpoint: unix:///var/run/containerd/containerd.sock
- 节点磁盘压力导致 Pod 被驱逐（Evicted）：清理节点无用镜像/日志、扩容磁盘或调整 kubelet 驱逐阈值。
五 日志与快速排查命令清单
- 查看系统日志与内核消息：tail -f /var/log/syslog；dmesg；journalctl -xe
- 查看容器运行时与 kubelet 日志：journalctl -u containerd；journalctl -u kubelet -f
- 集群状态与连通性：kubectl cluster-info；kubectl get nodes；kubectl get pods -A；kubectl describe pod ；kubectl logs
- 网络连通性：在节点上 ping/curl 测试 Service ClusterIP/DNS；检查节点间 6443/10250 等端口连通性
- 资源与进程：top；ps aux；df -h；检查是否存在端口占用（ss -tulpen | grep ）
- 重置与重加入：kubeadm reset（如用 Docker，加入 –cri-socket 参数）；随后按流程重新 init/join