Debian 上部署 Kubernetes 的常见问题与排查清单
一 环境预检与系统配置
- 关闭 Swap：Kubelet 不支持启用 Swap 的环境，执行：sudo swapoff -a 并注释 /etc/fstab 中的 swap 行，防止重启后恢复。
- 内核与模块：加载必要模块并开启桥接与转发。
- sudo modprobe overlay && sudo modprobe br_netfilter
- tee /etc/modules-load.d/containerd.conf <<EOF
overlay
br_netfilter
EOF
- tee /etc/sysctl.d/99-kubernetes-k8s.conf <<EOF
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
EOF
- sudo sysctl --system
- 防火墙放行：如使用 UFW，放行控制面与节点通信端口（示例）：sudo ufw allow 6443/tcp；生产环境建议改为更严格的基于 nftables/firewalld 的白名单策略。
- 容器运行时：Kubernetes 自 v1.24 起移除内置 dockershim，推荐使用 containerd 作为运行时。
- 资源与网络：确保节点满足最低资源（如 2 核 CPU / 2GB 内存 / 20GB 磁盘），节点间网络互通且可访问外网镜像仓库。
二 初始化与加入集群
- 安装组件：sudo apt update && sudo apt install -y kubelet kubeadm kubectl；sudo apt-mark hold kubelet kubeadm kubectl 锁定版本，避免滚动升级导致不兼容。
- 初始化控制面：示例 sudo kubeadm init --apiserver-advertise-address=<MASTER_IP>；国内环境可指定镜像仓库加速（如 registry.aliyuncs.com/google_containers），并合理设置 --pod-network-cidr 与 --service-cidr。
- 配置 kubectl：mkdir -p $HOME/.kube && sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config && sudo chown $(id -u):$(id -g) $HOME/.kube/config。
- 加入工作节点：在 Master 上生成并打印加入命令（如 kubeadm token create --print-join-command），在 Node 上执行；若 Token 过期，重新生成后再 join。
三 网络与端口
- 端口放行清单（示例）：控制面 6443/tcp；etcd 2379-2380/tcp；kubelet 10250/tcp；控制面组件 10251/tcp（kube-scheduler）、10252/tcp（kube-controller-manager）；节点状态 10255/tcp（只读，建议按需限制）。
- 网络插件：初始化完成后必须安装 CNI 插件（如 Calico/Flannel）以使 Pod 间通信与 Service 正常。示例：kubectl apply -f https://docs.projectcalico.org/manifests/tigera-operator.yaml 与 custom-resources.yaml；或 kubectl apply -f https://raw.githubusercontent.com/coreos/flannel/master/Documentation/kube-flannel.yml。
- 外部访问：Service 默认 ClusterIP 仅集群内可达；需要从外部访问时改为 NodePort 或 LoadBalancer，并配合云厂商 LB 或 MetalLB 等方案。
四 镜像与拉取
- 常见现象：Pod 状态 ErrImagePull/ImagePullBackOff，多因镜像名称/标签错误、仓库不可达或私有仓库无凭据。
- 处理步骤：
- 核对镜像名与标签（含架构后缀，如 amd64/arm64）。
- 使用国内镜像源或在 kubelet 配置镜像仓库镜像（registry mirrors）。
- 私有仓库：在各节点创建 /etc/containerd/certs.d/<域名>/ca.crt 或使用 imagePullSecrets。
- 初始化加速：kubeadm init 时通过 --image-repository 指定镜像仓库，减少拉取失败。
五 存储与日志排障
- 持久化存储方案：
- NFS：在 Debian 上快速搭建 NFS Server，创建 PV/PVC 并在 Pod 中挂载，适合中小规模与共享目录场景。
- Rook + Ceph / Longhorn：为有状态应用提供高可用块存储；Rook 负责在 K8s 中编排 Ceph/Longhorn，简化部署与运维。
- 日志与诊断命令：
- 组件日志：journalctl -u kubelet；必要时 journalctl -xe 查看系统级错误。
- 集群状态：kubectl get nodes、kubectl get pods -A、kubectl describe pod 定位事件与原因。
- 节点资源：检查磁盘空间与 Inodes，避免因 磁盘不足 导致 Pod 被驱逐（Evicted）。
