K8s集群安装部署完整指南（Ubuntu24.04+K8s1.28）

PascalMing2026-06-02 12:38

Kubernetes 集群安装部署完整指南（Ubuntu 24.04 + K8s v1.28）

环境说明 ：本文基于实际生产部署经验整理，使用 Ubuntu 24.04 LTS + Kubernetes v1.28.15 + containerd 1.7.28 + Calico 3.26.1 的经过验证的稳定组合，详细记录了 3 节点集群的完整安装过程，包含踩坑记录与解决方案，适合作为生产或学习环境的参考手册。

目录

  • 一、软件版本选择
  • 二、环境规划
    • [2.1 节点规划](#2.1 节点规划)
    • [2.2 网络规划](#2.2 网络规划)
    • [2.3 端口规划](#2.3 端口规划)
  • 三、前置准备：操作系统配置
    • [3.1 安装 Ubuntu 24.04 LTS](#3.1 安装 Ubuntu 24.04 LTS)
    • [3.2 配置静态 IP](#3.2 配置静态 IP)
    • [3.3 配置 hosts 文件](#3.3 配置 hosts 文件)
    • [3.4 配置 SSH 免密登录](#3.4 配置 SSH 免密登录)
  • 四、所有节点：基础环境配置
    • [4.1 禁用 Swap](#4.1 禁用 Swap)
    • [4.2 配置内核参数](#4.2 配置内核参数)
    • [4.3 安装 containerd（关键版本）](#4.3 安装 containerd（关键版本）)
    • [4.4 配置 containerd](#4.4 配置 containerd)
    • [4.5 安装 Kubernetes 工具](#4.5 安装 Kubernetes 工具)
  • [五、Master 节点：初始化集群](#五、Master 节点：初始化集群)
    • [5.1 执行 kubeadm init](#5.1 执行 kubeadm init)
    • [5.2 配置 kubectl](#5.2 配置 kubectl)
    • [5.3 安装 Calico CNI 网络插件](#5.3 安装 Calico CNI 网络插件)
  • [六、Worker 节点：加入集群](#六、Worker 节点：加入集群)
  • 七、验证集群状态
  • 八、部署测试应用
    • [8.1 部署 Nginx 服务](#8.1 部署 Nginx 服务)
    • [8.2 部署 Kubernetes Dashboard](#8.2 部署 Kubernetes Dashboard)
  • 九、常见问题与解决方案
  • 十、附录：版本兼容性速查表

一、软件版本选择

重要说明：Kubernetes 各组件之间的版本兼容性问题是安装过程中最常见的踩坑点，务必使用经过验证的版本组合。

✅ 推荐稳定版本组合（已验证）

组件 版本 备注
操作系统 Ubuntu 24.04 LTS (Noble Numbat) 内核 6.8，LTS 长期支持
Kubernetes v1.28.15 稳定版，社区支持良好
containerd 1.7.28 关键！必须使用 1.7.x 系列
kubeadm 1.28.15-1.1 与 K8s 版本保持一致
kubelet 1.28.15-1.1 与 K8s 版本保持一致
kubectl 1.28.15-1.1 与 K8s 版本保持一致
Calico CNI 3.26.1 网络插件
CoreDNS 1.10.1（自动） K8s 自带，无需单独安装

❌ 不兼容版本说明（避免踩坑）

版本组合 问题描述 结论
containerd 2.2.x + K8s v1.28 containerd 2.x 默认生成 config v3 格式，而 K8s 1.28 的 kubelet 不支持，导致 API Server 启动崩溃 ❌ 不可用
K8s v1.32.x 镜像源 registry.k8s.io 部分镜像在国内拉取困难，且与 containerd 1.7 存在兼容问题 ❌ 不建议
containerd 1.6.x + Ubuntu 24.04 包管理器不提供 1.6.x，且 systemd 兼容性差 ❌ 不可用

核心原则：永远使用官方文档中记录的兼容版本矩阵，不要追新。

二、环境规划

2.1 节点规划

本文以 3 节点集群（1 Master + 2 Worker）为例，适用于开发测试及小型生产环境。

节点名称 角色 IP 地址 CPU 内存 存储 说明
k8s-master1 Control Plane 192.168.118.221 4 核 6 GB 100 GB SSD 集群控制节点
k8s-master2 Worker 192.168.118.222 4 核 6 GB 100 GB SSD 工作节点 1
k8s-worker1 Worker 192.168.118.223 4 核 6 GB 100 GB SSD 工作节点 2

集群总资源：

  • 总 CPU：12 核 / 总内存：18 GB / 总存储：300 GB
  • 工作负载可用：约 7.5 核 / 约 10.5 GB

节点最低配置要求：

  • CPU：≥ 2 核
  • 内存：≥ 2 GB（推荐 4 GB 以上）
  • 存储：≥ 20 GB
  • 网络：节点间可互通

2.2 网络规划

网络段 CIDR 说明
节点网络 192.168.118.0/24 物理/虚拟机网络
Pod 网络 10.244.0.0/16 Pod 间通信（Calico 管理）
Service 网络 10.96.0.0/12 ClusterIP 服务地址段
NodePort 范围 30000-32767 对外暴露服务端口范围

⚠️ 注意：三个网络段不能重叠，且不能与宿主机现有网络冲突。

2.3 端口规划

Master 节点需要开放的端口：

端口 协议 用途
6443 TCP Kubernetes API Server
2379-2380 TCP etcd 服务端与客户端通信
10250 TCP Kubelet API
10251 TCP kube-scheduler
10252 TCP kube-controller-manager

Worker 节点需要开放的端口：

端口 协议 用途
10250 TCP Kubelet API
30000-32767 TCP NodePort 服务

三、前置准备：操作系统配置

3.1 安装 Ubuntu 24.04 LTS

从 Ubuntu 官网 下载 Ubuntu 24.04 LTS Server ISO 镜像，安装时注意以下事项：

  • 选择 Ubuntu Server（minimized） 版本，节省系统资源
  • 安装时不要选择安装额外软件包（后续按需安装）
  • 建议使用 LVM 分区，便于后续扩容
  • 记住安装时设置的用户名和密码（本文示例：ubuntu/ubuntu）

安装完成后，更新系统：

bash 复制代码 
sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install -y curl wget vim git net-tools

3.2 配置静态 IP

以下操作在每个节点上分别执行，根据节点角色修改对应 IP 地址。

Ubuntu 24.04 使用 Netplan 管理网络配置，配置文件位于 /etc/netplan/ 目录。

步骤 1：查看当前网络接口名称

bash 复制代码 
ip addr show
# 记录网卡名称，通常为 ens33、enp0s3 或 eth0 等

步骤 2：备份并编辑 Netplan 配置

bash 复制代码 
# 备份现有配置
sudo cp /etc/netplan/*.yaml /etc/netplan/backup_$(date +%Y%m%d).yaml

# 创建新的静态IP配置文件
sudo vim /etc/netplan/01-static-ip.yaml

k8s-master1（192.168.118.221）配置：

yaml 复制代码 
network:
  version: 2
  renderer: networkd
  ethernets:
    ens33:          # 根据实际网卡名称修改
      dhcp4: no
      addresses:
        - 192.168.118.221/24
      routes:
        - to: 0.0.0.0/0
          via: 192.168.118.1
      nameservers:
        addresses:
          - 8.8.8.8
          - 114.114.114.114

k8s-master2（192.168.118.222）配置：

yaml 复制代码 
network:
  version: 2
  renderer: networkd
  ethernets:
    ens33:
      dhcp4: no
      addresses:
        - 192.168.118.222/24
      routes:
        - to: 0.0.0.0/0
          via: 192.168.118.1
      nameservers:
        addresses:
          - 8.8.8.8
          - 114.114.114.114

k8s-worker1（192.168.118.223）配置：

yaml 复制代码 
network:
  version: 2
  renderer: networkd
  ethernets:
    ens33:
      dhcp4: no
      addresses:
        - 192.168.118.223/24
      routes:
        - to: 0.0.0.0/0
          via: 192.168.118.1
      nameservers:
        addresses:
          - 8.8.8.8
          - 114.114.114.114

步骤 3：应用网络配置

bash 复制代码 
# 检查配置语法
sudo netplan generate

# 应用配置（断连风险，建议在控制台操作）
sudo netplan apply

# 验证 IP 地址
ip addr show | grep "inet "

步骤 4：验证网络连通性

bash 复制代码 
# 测试网关连通性
ping -c 3 192.168.118.1

# 测试外网连通性
ping -c 3 8.8.8.8

3.3 配置 hosts 文件

在所有节点上执行，确保节点间域名解析正常。

bash 复制代码 
sudo vim /etc/hosts

添加以下内容：

复制代码 
192.168.118.221 k8s-master1
192.168.118.222 k8s-master2
192.168.118.223 k8s-worker1

验证解析：

bash 复制代码 
ping -c 2 k8s-master1
ping -c 2 k8s-master2
ping -c 2 k8s-worker1

3.4 配置 SSH 免密登录

在 Master 节点配置到其他节点的免密登录，方便后续管理：

bash 复制代码 
# 在 k8s-master1 上生成密钥对
ssh-keygen -t rsa -b 4096 -C "k8s-master1" -f ~/.ssh/id_rsa -N ""

# 将公钥复制到各节点
ssh-copy-id ubuntu@k8s-master1
ssh-copy-id ubuntu@k8s-master2
ssh-copy-id ubuntu@k8s-worker1

四、所有节点：基础环境配置

⚠️ 以下所有步骤需要在 3 个节点上分别执行 ，可以通过 SSH 逐一操作，或使用 for 循环批量执行。

批量执行方式（在 master1 上操作）：

bash 复制代码 
for ip in 192.168.118.221 192.168.118.222 192.168.118.223; do
  echo "=== 配置节点 $ip ==="
  ssh ubuntu@$ip "sudo -i bash -s" << 'EOF'
  # 将后续命令粘贴到此处
EOF
done

4.1 禁用 Swap

Kubernetes 要求必须禁用 Swap，否则 kubelet 会启动失败。

bash 复制代码 
# 立即禁用
sudo swapoff -a

# 永久禁用（注释掉 fstab 中的 swap 行）
sudo sed -i '/swap/s/^/#/' /etc/fstab

# 验证（输出为空表示已禁用）
sudo swapon --show
free -h | grep Swap

4.2 配置内核参数

Kubernetes 需要加载特定的内核模块并调整网络参数：

bash 复制代码 
# 加载必要的内核模块
cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

sudo modprobe overlay
sudo modprobe br_netfilter

# 配置 sysctl 参数
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

# 验证配置
sysctl net.bridge.bridge-nf-call-iptables net.bridge.bridge-nf-call-ip6tables net.ipv4.ip_forward

预期输出：

复制代码 
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1

4.3 安装 containerd（关键版本）

🔴 关键步骤 ：Ubuntu 24.04 默认软件源提供的 containerd 版本为 2.2.x，必须降级到 1.7.28，否则会导致 API Server 崩溃。

步骤 1：检查当前 containerd 版本

bash 复制代码 
# 如果 containerd 已安装，查看版本
containerd --version 2>/dev/null || echo "未安装"

步骤 2：安装指定版本的 containerd

bash 复制代码 
# 更新包索引
sudo apt-get update

# 安装指定版本（--allow-downgrades 允许降级）
sudo apt-get install -y --allow-downgrades containerd=1.7.28-0ubuntu1~24.04.2

# 锁定版本，防止自动升级
sudo apt-mark hold containerd

# 验证版本
containerd --version
# 应输出: containerd github.com/containerd/containerd 1.7.28 ...

💡 版本查询 ：如果提示版本不存在，可以通过 apt-cache madison containerd 查看可用版本列表。

4.4 配置 containerd

🔴 关键步骤：如果从 2.x 降级到 1.7.x，必须重新生成配置文件。旧的 config v3 格式与 K8s 1.28 不兼容。

bash 复制代码 
# 创建配置目录
sudo mkdir -p /etc/containerd

# 生成默认配置（关键：必须用新安装的 1.7.x 生成，不能沿用旧配置）
sudo containerd config default | sudo tee /etc/containerd/config.toml > /dev/null

# 启用 SystemdCgroup（Kubernetes 推荐使用 systemd 作为 cgroup 驱动）
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml

# 验证修改生效
grep "SystemdCgroup" /etc/containerd/config.toml
# 应输出: SystemdCgroup = true

# 重启并设置开机自启
sudo systemctl restart containerd
sudo systemctl enable containerd

# 验证运行状态
sudo systemctl status containerd

可选：配置国内镜像加速（网络受限环境推荐）

bash 复制代码 
# 编辑 containerd 配置
sudo vim /etc/containerd/config.toml

# 找到 [plugins."io.containerd.grpc.v1.cri".registry.mirrors] 部分
# 添加以下内容（Docker Hub 镜像加速）：
# [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
#   endpoint = ["https://mirror.ccs.tencentyun.com"]

4.5 安装 Kubernetes 工具

需要在节点上安装 kubeadm、kubelet、kubectl 三个工具。

步骤 1：添加 Kubernetes 官方软件源（v1.28）

bash 复制代码 
# 安装依赖工具
sudo apt-get install -y apt-transport-https ca-certificates curl gpg

# 创建密钥存储目录
sudo mkdir -p /etc/apt/keyrings

# 下载并导入 GPG 公钥
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.28/deb/Release.key | \
  sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg --yes

# 添加 APT 软件源
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.28/deb/ /' | \
  sudo tee /etc/apt/sources.list.d/kubernetes.list

# 更新包索引
sudo apt-get update

步骤 2：安装指定版本

bash 复制代码 
# 查看可用版本（可选）
apt-cache madison kubeadm | head -5

# 安装 1.28.15 版本
sudo apt-get install -y \
  kubeadm=1.28.15-1.1 \
  kubelet=1.28.15-1.1 \
  kubectl=1.28.15-1.1

# 锁定版本，防止意外升级
sudo apt-mark hold kubeadm kubelet kubectl

# 验证版本
kubeadm version
kubectl version --client
kubelet --version

预期输出：

复制代码 
kubeadm version: &Version{Major:1, Minor:28, GitVersion:v1.28.15, ...}
Client Version: v1.28.15
Kubernetes v1.28.15

步骤 3：启动 kubelet

bash 复制代码 
sudo systemctl enable kubelet
sudo systemctl start kubelet
# 注意：此时 kubelet 会反复重启（因为集群还未初始化），这是正常现象

五、Master 节点：初始化集群

以下步骤仅在 k8s-master1 节点执行。

5.1 执行 kubeadm init

bash 复制代码 
sudo kubeadm init \
  --kubernetes-version=v1.28.15 \
  --pod-network-cidr=10.244.0.0/16 \
  --apiserver-advertise-address=192.168.118.221 \
  --service-cidr=10.96.0.0/12

参数说明：

参数 说明
--kubernetes-version 指定 K8s 版本，防止自动选择最新版
--pod-network-cidr Pod 网络地址段，需与 Calico 配置保持一致
--apiserver-advertise-address API Server 对外广播地址，使用 Master 节点 IP
--service-cidr Service 网络地址段

初始化成功输出示例：

复制代码 
Your Kubernetes control-plane has initialized successfully!

To start using your cluster, you need to run the following as a regular user:

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

You can now join any number of worker nodes by running the following on each as root:

kubeadm join 192.168.118.221:6443 --token abcdef.0123456789abcdef \
        --discovery-token-ca-cert-hash sha256:xxxxxxxxxxxxxxxxxxxx

🔴 重要 ：请立即保存 kubeadm join 命令，Worker 节点加入集群时需要用到！Token 默认有效期为 24 小时。

5.2 配置 kubectl

bash 复制代码 
# 为当前用户配置 kubectl 访问凭证
mkdir -p $HOME/.kube
sudo cp /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

# 验证 kubectl 可用
kubectl cluster-info
kubectl get nodes

可选：配置 kubectl 命令补全

bash 复制代码 
# 安装 bash-completion
sudo apt-get install -y bash-completion

# 添加到 .bashrc
echo 'source <(kubectl completion bash)' >> ~/.bashrc
echo 'alias k=kubectl' >> ~/.bashrc
echo 'complete -o default -F __start_kubectl k' >> ~/.bashrc

# 立即生效
source ~/.bashrc

5.3 安装 Calico CNI 网络插件

⚠️ 必须 在所有节点加入集群前安装 CNI 插件，否则节点会一直处于 NotReady 状态。

bash 复制代码 
# 应用 Calico 配置清单
kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/calico.yaml

# 等待 Calico 相关 Pod 启动（约 1-2 分钟）
watch kubectl get pods -n kube-system

# 验证 Calico Pod 均为 Running 状态
kubectl get pods -n kube-system | grep calico

预期输出：

复制代码 
calico-kube-controllers-xxxx   1/1   Running   0   2m
calico-node-xxxxx              1/1   Running   0   2m

网络受限时的替代方案（手动下载）：

bash 复制代码 
# 下载 YAML 文件
curl -O https://raw.githubusercontent.com/projectcalico/calico/v3.26.1/manifests/calico.yaml

# 应用本地文件
kubectl apply -f calico.yaml

六、Worker 节点：加入集群

以下步骤在 k8s-master2 和 k8s-worker1 上分别执行。

步骤 1：清理旧状态（如果是全新安装可跳过）

bash 复制代码 
# 如果节点之前加入过其他集群，先清理
sudo kubeadm reset -f
sudo rm -rf /etc/kubernetes/pki /etc/kubernetes/manifests
sudo rm -rf $HOME/.kube

步骤 2：执行加入命令（使用 master 初始化时输出的 join 命令）

bash 复制代码 
# 替换为实际的 token 和 hash 值
sudo kubeadm join 192.168.118.221:6443 \
  --token abcdef.0123456789abcdef \
  --discovery-token-ca-cert-hash sha256:xxxxxxxxxxxxxxxxxxxx

Token 已过期时重新获取（在 master1 执行）：

bash 复制代码 
# 生成新的加入命令（token 有效期 24 小时）
kubeadm token create --print-join-command

步骤 3：在 Master 节点验证节点加入成功

bash 复制代码 
# 在 k8s-master1 上执行
kubectl get nodes

# 等待所有节点变为 Ready 状态（约 2-3 分钟）
watch kubectl get nodes

预期输出：

复制代码 
NAME          STATUS   ROLES           AGE   VERSION
k8s-master1   Ready    control-plane   10m   v1.28.15
k8s-master2   Ready    <none>          2m    v1.28.15
k8s-worker1   Ready    <none>          1m    v1.28.15

七、验证集群状态

以下命令在 k8s-master1 上执行：

bash 复制代码 
# 查看节点状态
kubectl get nodes -o wide

# 查看所有系统 Pod（应全部为 Running）
kubectl get pods -A

# 查看集群信息
kubectl cluster-info

# 查看组件状态
kubectl get componentstatuses

# 查看节点资源使用情况（需要 Metrics Server）
kubectl top nodes

健康集群的预期状态：

复制代码 
NAME          STATUS   ROLES           VERSION    INTERNAL-IP
k8s-master1   Ready    control-plane   v1.28.15   192.168.118.221
k8s-master2   Ready    <none>          v1.28.15   192.168.118.222
k8s-worker1   Ready    <none>          v1.28.15   192.168.118.223

# 系统 Pod 数量：13 个，均为 Running 状态
NAMESPACE       NAME                                       READY   STATUS
kube-system     calico-kube-controllers-xxx                1/1     Running
kube-system     calico-node-xxx (x3)                      1/1     Running
kube-system     coredns-xxx (x2)                          1/1     Running
kube-system     etcd-k8s-master1                          1/1     Running
kube-system     kube-apiserver-k8s-master1                1/1     Running
kube-system     kube-controller-manager-k8s-master1       1/1     Running
kube-system     kube-proxy-xxx (x3)                       1/1     Running
kube-system     kube-scheduler-k8s-master1                1/1     Running

八、部署测试应用

8.1 部署 Nginx 服务

bash 复制代码 
# 创建 3 副本的 Nginx 部署
kubectl create deployment nginx \
  --image=nginx:1.25.5 \
  --replicas=3

# 暴露为 NodePort 服务
kubectl expose deployment nginx \
  --port=80 \
  --type=NodePort \
  --name=nginx-service

# 查看服务信息（获取 NodePort 端口号）
kubectl get svc nginx-service

# 查看 Pod 分布情况
kubectl get pods -o wide

访问验证：

bash 复制代码 
# 获取 NodePort
NGINX_PORT=$(kubectl get svc nginx-service -o jsonpath='{.spec.ports[0].nodePort}')
echo "访问地址: http://192.168.118.221:$NGINX_PORT"

# 使用 curl 测试
curl -s http://192.168.118.221:$NGINX_PORT | grep "<title>"
# 应输出: <title>Welcome to nginx!</title>

8.2 部署 Kubernetes Dashboard

bash 复制代码 
# 部署 Dashboard
kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v2.7.0/aio/deploy/recommended.yaml

# 创建管理员 ServiceAccount
kubectl create serviceaccount admin-user -n kubernetes-dashboard

# 绑定 cluster-admin 角色
kubectl create clusterrolebinding admin-user \
  --clusterrole=cluster-admin \
  --serviceaccount=kubernetes-dashboard:admin-user

# 将 Dashboard Service 改为 NodePort 暴露
kubectl patch svc kubernetes-dashboard -n kubernetes-dashboard \
  -p '{"spec":{"type":"NodePort","ports":[{"port":443,"targetPort":8443,"nodePort":30443}]}}'

# 验证 Dashboard Pod 状态
kubectl get pods -n kubernetes-dashboard

# 生成登录 Token（有效期 100 年）
kubectl -n kubernetes-dashboard create token admin-user --duration=87600h

访问 Dashboard：

  • URL：https://192.168.118.221:30443（浏览器会提示不安全，点击继续）
  • 选择 Token 登录方式，粘贴上一步生成的 Token

九、常见问题与解决方案

问题 1：containerd 启动失败 - "config version 3 not supported"

错误信息：

复制代码 
FATA[0000] Failed to load config file: config version "3" is not supported, only version "2" is supported

原因：从 containerd 2.x 降级到 1.7.x 后，原有配置文件格式不兼容。

解决方案：

bash 复制代码 
# 删除旧配置，重新生成（必须使用 1.7.x 版本的 containerd 生成）
sudo rm -f /etc/containerd/config.toml
sudo containerd config default | sudo tee /etc/containerd/config.toml > /dev/null
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/g' /etc/containerd/config.toml
sudo systemctl restart containerd
sudo systemctl status containerd  # 验证状态正常

问题 2：kubeadm join 报端口占用 - "port is already in use"

错误信息：

复制代码 
[ERROR Port-10250]: Port 10250 is in use

原因：节点之前加入过集群，kubelet 残留进程仍在运行。

解决方案：

bash 复制代码 
# 彻底重置节点状态
sudo kubeadm reset -f

# 清理残留目录
sudo rm -rf /etc/kubernetes/pki
sudo rm -rf /etc/kubernetes/manifests
sudo rm -rf /var/lib/etcd
sudo rm -rf $HOME/.kube

# 重启 kubelet
sudo systemctl restart kubelet

问题 3：节点长时间 NotReady

错误信息：

复制代码 
NAME          STATUS     ROLES
k8s-master1   NotReady   control-plane

排查步骤：

bash 复制代码 
# 步骤 1：查看节点详细信息
kubectl describe node k8s-master1 | grep -A 10 "Conditions:"

# 步骤 2：检查 kubelet 日志
sudo journalctl -u kubelet -f --no-pager | tail -50

# 步骤 3：检查 containerd 状态
sudo systemctl status containerd

# 步骤 4：检查 Calico Pod 状态
kubectl get pods -n kube-system | grep calico

常见原因及解决：

原因 解决方案
CNI 插件未安装 kubectl apply -f calico.yaml
Calico Pod 未就绪 kubectl delete pod -n kube-system -l k8s-app=calico-node
containerd 异常 参见问题 1 解决方案
网络不通（Pod CIDR 冲突） 检查网络规划，确保无地址段冲突

问题 4：镜像拉取失败 - "failed to pull image"

错误信息：

复制代码 
Failed to pull image "registry.k8s.io/kube-apiserver:v1.28.15": rpc error

原因 ：国内无法访问 registry.k8s.io。

解决方案一：配置代理

bash 复制代码 
# 为 containerd 配置 HTTP 代理
sudo mkdir -p /etc/systemd/system/containerd.service.d
cat <<EOF | sudo tee /etc/systemd/system/containerd.service.d/http-proxy.conf
[Service]
Environment="HTTP_PROXY=http://your-proxy:port"
Environment="HTTPS_PROXY=http://your-proxy:port"
Environment="NO_PROXY=localhost,127.0.0.1,192.168.0.0/16,10.0.0.0/8"
EOF
sudo systemctl daemon-reload
sudo systemctl restart containerd

解决方案二：使用国内镜像源（推荐）

bash 复制代码 
# 预先拉取镜像（使用阿里云镜像源）
kubeadm config images pull \
  --image-repository registry.cn-hangzhou.aliyuncs.com/google_containers \
  --kubernetes-version v1.28.15

# 初始化时指定镜像仓库
sudo kubeadm init \
  --image-repository registry.cn-hangzhou.aliyuncs.com/google_containers \
  --pod-network-cidr=10.244.0.0/16 \
  --apiserver-advertise-address=192.168.118.221

问题 5：kubeadm init 卡住 - 超时或 etcd 未启动

错误信息：

复制代码 
[wait-control-plane] Waiting for the kubelet to boot up the control plane
[kubelet-check] Initial timeout of 40s passed.

排查步骤：

bash 复制代码 
# 查看 kubelet 日志
sudo journalctl -u kubelet -n 100 --no-pager

# 常见原因：Swap 未关闭
sudo swapon --show  # 输出为空才正常

# 常见原因：containerd 配置错误
sudo systemctl status containerd

# 常见原因：节点时间不同步（etcd 对时间敏感）
timedatectl status
sudo apt-get install -y ntp
sudo systemctl enable ntp && sudo systemctl start ntp

问题 6：kubectl 无法连接 - "The connection to the server was refused"

错误信息：

复制代码 
The connection to the server 192.168.118.221:6443 was refused

解决方案：

bash 复制代码 
# 检查 kubeconfig 是否正确配置
ls -la ~/.kube/config

# 如果未配置，重新执行
mkdir -p $HOME/.kube
sudo cp /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

# 检查 API Server 是否运行
sudo systemctl status kube-apiserver 2>/dev/null || \
  kubectl get pod -n kube-system kube-apiserver-k8s-master1

问题 7：Dashboard 登录 Token 失效

解决方案：重新生成 Token

bash 复制代码 
# 生成新 Token（有效期 24 小时）
kubectl -n kubernetes-dashboard create token admin-user

# 或生成长期有效 Token（有效期 100 年）
kubectl -n kubernetes-dashboard create token admin-user --duration=87600h

常见问题速查表

问题现象 可能原因 快速解决
containerd 启动失败，提示 config version 3 2.x 降级后配置不兼容 containerd config default 重新生成配置
kubeadm join 端口被占用 旧 kubelet 残留 kubeadm reset -f 后重试
节点 NotReady CNI 未安装 确认 Calico 所有 Pod 为 Running
镜像拉取超时 registry.k8s.io 无法访问 使用阿里云镜像源或配置代理
kubeadm init 超时 Swap 未关闭 / containerd 异常 检查 swap 和 containerd 状态
kubectl 连接被拒绝 kubeconfig 未配置 复制 admin.conf 到 ~/.kube/config
Pod 一直 Pending 资源不足 / 节点污点 kubectl describe pod 查看 Events
DNS 解析失败 CoreDNS 未就绪 kubectl get pods -n kube-system

十、附录：版本兼容性速查表

Kubernetes 与 containerd 兼容矩阵

K8s 版本 containerd 推荐版本 说明
v1.28.x 1.7.x 本文使用，稳定
v1.29.x 1.7.x / 2.0.x 需测试
v1.30.x 1.7.x / 2.0.x 需测试
v1.32.x 2.0.x+ 部分镜像拉取问题

实际验证的最终集群状态

复制代码 
# 节点状态（2026-05-29 验证）
NAME          STATUS   ROLES           VERSION
k8s-master1   Ready    control-plane   v1.28.15
k8s-master2   Ready    <none>          v1.28.15
k8s-worker1   Ready    <none>          v1.28.15

# 版本组合（已验证）
K8s:          v1.28.15
containerd:   1.7.28
Calico:       3.26.1
OS:           Ubuntu 24.04 LTS

# 系统 Pod：13 个，全部 Running
# 部署服务：
#   nginx         NodePort 31441  3副本  nginx:1.25.5
#   Dashboard     NodePort 30443  1副本  v2.7.0

参考资料

文档版本 ：1.0

最后更新 ：2026-06-01

适用版本 ：Ubuntu 24.04 LTS + Kubernetes v1.28.15

验证环境 ：3 节点集群（4C6G/节点）

作者说明：本文基于真实生产部署过程整理，所有踩坑记录均来自实际操作，如有问题欢迎在评论区交流。

如果本文对你有帮助，欢迎点赞收藏 👍

相关推荐
IT策士1 小时前
第 34 篇 k8s之存储基础：emptyDir 与 hostPath
云原生·容器·kubernetes
取经蜗牛2 小时前
Docker 常用命令全面总结
运维·docker·容器
DO_Community2 小时前
AI推理成本砍半：DigitalOcean 批量推理服务正式上线
云原生·serverless·aigc·claude·deepseek
qq_382949222 小时前
推荐一门不错的微服务实战课：Spring Cloud Alibaba 从入门到落地
微服务·云原生·架构
IT策士2 小时前
第31篇 k8s之Ingress 进阶：TLS、重写与认证
云原生·容器·kubernetes
川石课堂软件测试2 小时前
作为一名测试工程师如何学习Kubernetes(k8s)技能
学习·测试工具·容器·职场和发展·kubernetes·测试用例·harmonyos
无聊的老谢3 小时前
DDD 驱动的电信网络优化微服务建模实战
微服务·云原生·架构
qq_452396234 小时前
第十一篇：《Docker Compose：多容器应用编排入门》
运维·docker·容器
Geoking.4 小时前
Docker安装Nacos指南
运维·docker·容器
热门推荐
01GitHub 镜像站点022026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf03【AI】2026 年具身智能模型和世界模型总结04【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法05Codex 下载安装指南：Windows 和 macOS 官方版下载06裂开！ChatGPT 居然开始要手机号验证，附详细解决方法07CC-Switch & Claude 基于 Linux 服务器安装使用指南08Codex 接入 DeepSeek API 完整配置文档09几个好用的ip纯净度检测网站10CC-Switch 下载、安装与使用配置指南【2026.5.29】