文档说明
本文档适用于国内环境下基于 Ubuntu 24.04 LTS 部署 Kubernetes 1.34 集群，采用 1 台 Master 节点 + 1 台 Node 节点架构，通过本地代理服务器直接从 k8s.io 官方源拉取镜像，规避国内镜像源同步延迟问题。
### 目录
环境准备
前置基础配置（所有节点）
代理配置（所有节点）
安装容器时（containerd）
安装 kubeadm、kubelet、kubectl
初始化 Master 节点
安装网络插件（Flannel）
Node 节点加入集群
集群验证
常见问题排查
1. 环境准备
1.1 服务器规划
| 节点角色 | 主机名 | IP 地址 | 操作系统 | 硬件配置
|—|—|—|—|
|Master | k8s-master | 192.168.1.100 | Ubuntu 24.04 LTS x86_64 | 2 核 4G 及以上
|Node | k8s-node | 192.168.1.101 | Ubuntu 24.04 LTS x86_64 | 2 核 2G 及以上
|代理服务器 | proxy-server | 192.168.1.200 | 任意 Linux 系统 | 能访问外网即可
1.2 网络要求
所有节点互通（Master/Node/ 代理服务器）
代理服务器能访问外网（k8s.io、gcr.io、github.com 等）
节点防火墙放行 K8s 核心端口：6443（apiserver）、2379-2380（etcd）、10250（kubelet）、10251/10252（kube-scheduler/kube-controller-manager）、8472（Flannel VXLAN）
1.3 软件版本
Kubernetes：1.34.0
容器时：containerd 1.7.11（Ubuntu 24.04 官方源兼容版本）
网络插件：Flannel v0.25.0
2. 前置基础配置（所有节点执行）
2.1 关闭防火墙、AppArmor（可选）、Swap
“`bash
# 关闭并禁用 UFW 防火墙（Ubuntu 默认防火墙）
sudo systemctl stop ufw && sudo systemctl disable ufw
# 关闭 Swap（K8s 要求）
sudo swapoff -a
# 永久禁用 Swap（注释 fstab 中的 swap 行）
sudo sed -i ‘/swap/s/^/#/’ /etc/fstab
# 验证 Swap 已关闭
sudo swapon –show # 无输出则生效
“`
2.2 配置主机名和 Hosts
“`bash
# Master 节点设置主机名
sudo hostnamectl set-hostname k8s-master
# Node 节点设置主机名
sudo hostnamectl set-hostname k8s-node
# 配置 Hosts（所有节点）
sudo tee -a /etc/hosts << EOF
192.168.1.100 k8s-master
192.168.1.101 k8s-node
192.168.1.200 proxy-server
EOF
```
2.3 时间同步（Ubuntu 24.04 默认用 systemd-timesyncd）
```bash
# 确保时间同步服务
sudo systemctl start systemd-timesyncd && sudo systemctl enable systemd-timesyncd
# 验证时间同步状态
timedatectl status
```
2.4 调整内核参数
```bash
# 添加内核模块
sudo tee /etc/modules-load.d/k8s.conf << EOF
overlay
br_netfilter
EOF
# 加载模块
sudo modprobe overlay && sudo modprobe br_netfilter
# 配置内核参数（开启 IP 转发、桥接网络）
sudo tee /etc/sysctl.d/k8s.conf << EOF
net.bridge.bridge-nf-call-iptables = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward = 1
EOF
# 生效内核参数
sudo sysctl --system
```
2.5 配置 IPVS（可选，提升 kube-proxy 性能）
```bash
# 安装 IPVS 工具
sudo apt update && sudo apt install -y ipset ipvsadm
# 添加 IPVS 内核模块
sudo tee /etc/modules-load.d/ipvs.conf << EOF
ip_vs
ip_vs_rr
ip_vs_wrr
ip_vs_sh
nf_conntrack
EOF
# 加载模块
sudo modprobe ip_vs ip_vs_rr ip_vs_wrr ip_vs_sh nf_conntrack
# 验证模块加载
lsmod | grep -e ip_vs -e nf_conntrack
```
3. 代理配置（所有节点执行）
```bash
# 创建 containerd.service.d 配置目录
sudo mkdir -p /etc/systemd/system/containerd.service.d/
sudo tee /etc/systemd/system/containerd.service.d/http-proxy.conf << EOF
[Service]
Environment="HTTP_PROXY=socks5://192.168.1.200:10808"
Environment="HTTPS_PROXY=socks5://192.168.1.200:10808"
Environment="NO_PROXY=localhost,127.0.0.1
EOF
systemctl daemon-reload
systemctl restart containerd
```
4. 安装容器时（containerd）（所有节点执行）
Ubuntu 24.04 推荐通过官方源安装 containerd，比二进制方式更简便：
```bash
# 安装 containerd 及依赖
sudo apt install -y containerd
# 创建 containerd 配置目录
sudo mkdir -p /etc/containerd
# 生成 containerd 默认配置
sudo containerd config default | sudo tee /etc/containerd/config.toml
# 修改配置：启用 SystemdCgroup、替换 sandbox 镜像、引入代理配置
# 1. 启用 Systemd 控制组（K8s 推荐）
sudo sed -i 's/SystemdCgroup \= false/SystemdCgroup \= true/g' /etc/containerd/config.toml
# 2. 替换 pause 镜像为1.34支持的版本，可使用kubeadm config images list 查看
sudo sed -i 's/registry.k8s.io\/pause:3.8/k8s.gcr.io\/pause:3.10.1/g' /etc/containerd/config.toml
# 重启 containerd 并设置开机自启
sudo systemctl restart containerd && sudo systemctl enable containerd
# 验证安装
containerd --version
```
5. 安装 kubeadm、kubelet、kubectl（所有节点执行）
5.1 配置 K8s 官方 APT 源
```bash
# 安装依赖包
sudo apt install -y apt-transport-https ca-certificates curl gpg
# 添加 K8s GPG 密钥
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.34/deb/Release.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/kubernetes-1.34.gpg
# 添加 K8s 源（通过代理访问官方源）
echo "deb [signed-by=/etc/apt/trusted.gpg.d/kubernetes-1.34.gpg] https://pkgs.k8s.io/core:/stable:/v1.34/deb/ /" | sudo tee /etc/apt/sources.list.d/kubernetes.list
# 更新 APT 缓存
sudo apt update
```
5.2 安装指定版本
```bash
# 安装 kubeadm、kubelet、kubectl 1.34.0（锁定版本防止自动更新）
sudo apt install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl
```
6. 初始化 Master 节点（仅 Master 执行）
6.1 预拉取镜像（验证代理是否生效）
```bash
sudo kubeadm config images pull \
--kubernetes-version=v1.34.0 \
--image-repository=k8s.gcr.io
```
6.2 初始化集群
```bash
sudo kubeadm init \
--kubernetes-version=v1.34.0 \
--image-repository=k8s.gcr.io \
--apiserver-advertise-address=192.168.1.100 \
--pod-network-cidr=10.244.0.0/16 \ # Flannel 适配的网段
--service-cidr=10.96.0.0/12 \
--ignore-preflight-errors=Swap # 如未重启关闭 Swap，添加此参数
# 初始化成功后，会输出 Node 节点加入集群的命令，务必保存！
# 示例：kubeadm join 192.168.1.100:6443 --token xxx --discovery-token-ca-cert-hash sha256:xxx
```
6.3 配置 kubectl 环境（Master 节点）
```bash
# 普通用户配置（推荐）
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
# 根用户配置（可选）
echo "export KUBECONFIG=/etc/kubernetes/admin.conf" | sudo tee -a /etc/profile
source /etc/profile
```
7. 安装网络插件（Flannel）（仅 Master 执行）
```bash
# 下载并应用 Flannel 配置（通过代理）
kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/v0.25.0/Documentation/kube-flannel.yml
# 验证网络插件状态（Running 则正常）
kubectl get pods -n kube-flannel
```
8. Node 节点加入集群（仅 Node 执行）
8.1 执行 Master 初始化后的 join 命令
```bash
# 替换为实际的 join 命令（从 Master 初始化输出中复制）
sudo kubeadm join 192.168.1.100:6443 \
--token abcdef.0123456789abcdef \
--discovery-token-ca-cert-hash sha256:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
# 如 token 过期，在 Master 节点重新生成：
# sudo kubeadm token create --print-join-command
```
9. 集群验证（仅 Master 执行）
9.1 检查节点状态
```bash
kubectl get nodes
# 正常输出：两个节点 STATUS 为 Ready，ROLES 分别为 control-plane,master 和 node
```
9.2 检查系统组件状态
```bash
kubectl get pods -n kube-system
# 所有 Pod 应处于 Running 状态（coredns、kube-proxy、flannel、etcd、apiserver 等）
```
9.3 验证集群功能
```bash
# 创建测试 Pod
kubectl run nginx --image=nginx:alpine --port=80
# 暴露 Service（NodePort 类型）
kubectl expose pod nginx --type=NodePort --port=80
# 查看 Service 端口（NODE_PORT 列）
kubectl get svc nginx
# 访问测试（替换为 Node IP 和实际 NodePort）
curl http://192.168.1.101:30xxx
```
10. 常见问题排查
10.1 镜像拉取失败
检查代理连通性：```curl -x http://192.168.1.200:18080 https://k8s.gcr.io```
验证 no_proxy 配置：确保包含内网网段（192.168.1.0/24、10.0.0.0/8 等）
查看 containerd 日志：```sudo journalctl -u containerd -f```
10.2 Node 节点状态 NotReady
检查 Flannel 插件：```kubectl get pods -n kube-flannel（需 Running）```
检查节点间网络：```ping 192.168.1.100（Node 能通 Master）```
查看 kubelet 日志：```sudo journalctl -u kubelet -f```
10.3 APT 安装 k8s 包失败
检查 GPG 密钥是否正确：sudo apt-key list | grep kubernetes
确认代理能访问 pkgs.k8s.io：```curl -x http://192.168.1.200:18080 https://pkgs.k8s.io/core:/stable:/v1.34/deb/```
10.4 Swap 未完全关闭
强制关闭：sudo swapoff -a && sudo sysctl vm.swappiness=0
重启节点后再次验证：swapon --show
附录：常用命令
```bash
# 查看集群信息
kubectl cluster-info
# 查看节点详细信息
kubectl describe node k8s-node
# 重启 kubelet
sudo systemctl restart kubelet
# 重置集群（如需重新部署）
sudo kubeadm reset -f
sudo rm -rf /etc/cni/net.d ~/.kube/config
```
