Debian k8s安装哪步易错

在 Debian 上安装 Kubernetes（k8s）时，很多错误都集中在“环境准备”和“组件初始化”阶段。下面按易错顺序给你梳理最常见、最容易踩坑的步骤，以及正确做法。

一、系统环境准备（最易错）

1️⃣ 关闭 swap（非常常见）

错误表现：
kubeadm init 直接失败，或节点 NotReady

✅ 正确做法：

sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

⚠️ 重启后 swap 不能自动开启

2️⃣ 禁用防火墙或放行端口

错误表现：
节点之间无法通信，Pod 网络不通

✅ 推荐（测试环境）：

sudo ufw disable

生产环境需精确放行：

6443
2379-2380
10250
10251
10252

3️⃣ 主机名 & /etc/hosts

错误表现：

kubeadm 报警 hostname 不合法
节点无法识别

✅ 要求：

主机名不能含 _
建议：

hostnamectl set-hostname master

cat >> /etc/hosts <<EOF
192.168.1.10 master
192.168.1.11 node1
EOF

二、内核 & 网络参数（非常容易漏）

4️⃣ 开启桥接流量（必做）

错误表现：
Pod 无法访问外网，网络插件起不来

cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
br_netfilter
EOF

cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
EOF

sudo sysctl --system

三、容器运行时（极易错）

5️⃣ Docker ≠ 直接可用（重点）

Debian 12+ 默认 不再支持 docker-shim

✅ 推荐方案（2024+）：

containerd

安装 containerd：

sudo apt install -y containerd

⚠️ 必须改配置：

containerd config default > /etc/containerd/config.toml

修改：

SystemdCgroup = true

重启：

systemctl restart containerd

四、kubeadm 初始化（最容易失败）

6️⃣ kubeadm init 参数错误

错误表现：

网络插件不匹配
CIDR 冲突

✅ 推荐命令：

kubeadm init \
  --pod-network-cidr=10.244.0.0/16 \
  --cri-socket=unix:///run/containerd/containerd.sock

7️⃣ kubeconfig 没配置（新手必错）

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

否则：

The connection to the server localhost:8080 was refused

五、网络插件（Calico / Flannel）

8️⃣ 网络插件版本不匹配

Flannel → 10.244.0.0/16
Calico → 192.168.0.0/16

错误示例：

kubeadm init --pod-network-cidr=10.244.0.0/16
# 却装了 Calico 默认网段

✅ 装 Flannel：

kubectl apply -f https://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml

六、节点加入（常被忽略）

9️⃣ token 过期

默认 24 小时失效

重新生成：

kubeadm token create --print-join-command

七、Debian 特有坑

项目	易错点
Debian 12	默认 nftables，需确认 iptables 模式
apt 源	必须加 `apt-transport-https`
内核	建议 ≥ 5.10

✅ 总结：最容易出错的 5 步

swap 没关
containerd Cgroup 没改
bridge-nf-call 没开
kubeadm CIDR 和网络插件不一致
kubeconfig 没拷贝

如果你愿意，可以告诉我：

Debian 版本（11 / 12）
k8s 版本
单节点还是多节点

我可以给你一份可直接复制执行的安装脚本。