从零到一：kubeadm 搭建 Kubernetes 集群完整实战指南（1.23.17 版本）
导读：Kubernetes 作为容器编排领域的事实标准，已成为运维工程师的必备技能。本文以生产环境推荐的1.23.17 版本（最后一个默认支持 Docker 运行时的版本）为例，从集群架构、环境准备、组件部署到业务上线的全流程，手把手带你完成一套完整的 K8S 集群搭建。所有步骤均经过生产验证，可直接复用。
一、为什么选择 1.23.17 版本？
在动手之前，先聊聊版本选择的问题。很多初学者一上来就装最新版，但实际工作中更看重的是稳定性。
| 版本 | Docker 支持 | 说明 |
|---|---|---|
| 1.23.17 | 默认支持 | 官方最后一个默认支持 Docker 的版本，生产环境首选 |
| 1.24+ | 弃用 Docker | 需手动部署 cri-dockerd，不推荐 |
| 1.24+ | 默认 Containerd | CNCF 官方推荐，性能更优 |
生产建议：如果公司已有 K8S 环境，直接用现有版本运维即可，没必要折腾升级。如果是新部署，1.23.17 和 Containerd 运行时都是稳定的选择。
二、理解 K8S 集群架构
动手之前，先理解架构才能知其所以然。K8S 集群分为两层：
2.1 Control Plane（控制平面 / Master）
| 组件 | 端口 | 作用 |
|---|---|---|
| etcd | 2379/2380 | Key-Value 数据库，存储集群所有数据 |
| api-server | 6443（HTTPS） | 集群统一入口，所有组件通信都经过它 |
| scheduler | 10259 | 调度器，决定 Pod 运行在哪个节点 |
| controller-manager | 10257 | 控制器管理者，维护集群期望状态 |
2.2 Worker Node（工作节点）
| 组件 | 端口 | 作用 |
|---|---|---|
| kubelet | 10250 | 管理 Pod 生命周期，上报节点状态 |
| kube-proxy | 10256 | 代理 Pod 请求，实现负载均衡和服务发现 |
2.3 CNI（容器网络接口）
负责跨节点 Pod 网络通信，常见插件：Flannel、Calico、Cilium。
2.4 三种网络类型
K8S 集群需要规划三个独立的网段，避免地址冲突：
物理机网络：10.0.0.0/24 ← 节点间通信 Pod 网络： 10.100.0.0/16 ← 跨节点 Pod 通信（最多 65536 个 IP） Service 网络：10.200.0.0/16 ← 服务发现与负载均衡排坑提醒：Pod 网段规划时一定要考虑未来容量。如果容器数量可能超过 65536，应该用
/8网段（如10.100.0.0/8）。
三、环境准备
3.1 主机规划
| 主机名 | IP 地址 | 系统 | 配置 |
|---|---|---|---|
| master231 | 10.0.0.231 | Ubuntu 22.04 LTS | 2C4G50G+ |
| worker232 | 10.0.0.232 | Ubuntu 22.04 LTS | 2C4G50G+ |
| worker233 | 10.0.0.233 | Ubuntu 22.04 LTS | 2C4G50G+ |
3.2 系统基础优化（所有节点执行）
1. 关闭 Swap 分区
# 临时关闭swapoff-a&&sysctl-wvm.swappiness=0# 永久关闭sed-ri'/^[^#]*swap/s@^@#@'/etc/fstabK8S 默认不允许使用 Swap，否则 Pod 调度会出现异常。
2. 加载内核模块（iptables 桥接流量）
cat<<EOF|tee/etc/modules-load.d/k8s.confbr_netfilter EOFcat<<EOF|tee/etc/sysctl.d/k8s.confnet.bridge.bridge-nf-call-ip6tables = 1 net.bridge.bridge-nf-call-iptables = 1 net.ipv4.ip_forward = 1 EOFsysctl--system3. Linux 内核参数优化
cat>/etc/sysctl.d/k8s.conf<<'EOF' net.ipv4.ip_forward = 1 net.bridge.bridge-nf-call-iptables = 1 net.bridge.bridge-nf-call-ip6tables = 1 net.ipv6.conf.all.disable_ipv6 = 1 fs.may_detach_mounts = 1 vm.overcommit_memory=1 vm.panic_on_oom=0 fs.inotify.max_user_watches=89100 fs.file-max=52706963 fs.nr_open=52706963 net.netfilter.nf_conntrack_max=2310720 net.ipv4.tcp_keepalive_time = 600 net.ipv4.tcp_keepalive_probes = 3 net.ipv4.tcp_keepalive_intvl = 15 net.ipv4.tcp_max_tw_buckets = 36000 net.ipv4.tcp_tw_reuse = 1 net.ipv4.tcp_max_orphans = 327680 net.ipv4.tcp_orphan_retries = 3 net.ipv4.tcp_syncookies = 1 net.ipv4.tcp_max_syn_backlog = 16384 net.ipv4.ip_conntrack_max = 65536 net.ipv4.tcp_max_syn_backlog = 16384 net.ipv4.tcp_timestamps = 0 net.core.somaxconn = 16384 EOFsysctl--system3.3 安装 ipvs 负载均衡模块（所有节点执行）
生产环境强烈推荐 kube-proxy 使用ipvs 模式替代默认的 iptables，性能更高。
# 安装工具apt-yinstallipvsadm ipset sysstat conntrack# 配置开机自动加载 ipvs 模块cat>/etc/modules-load.d/ipvs.conf<<'EOF' ip_vs ip_vs_lc ip_vs_wlc ip_vs_rr ip_vs_wrr ip_vs_lblc ip_vs_lblcr ip_vs_dh ip_vs_sh ip_vs_fo ip_vs_nq ip_vs_sed ip_vs_ftp ip_vs_sh nf_conntrack ip_tables ip_set xt_set ipt_set ipt_rpfilter ipt_REJECT ipip EOF重启后验证：
lsmod | grep --color=auto -e ip_vs -e nf_conntrack
3.4 安装 Docker 并确认 cgroup 驱动
# 安装 Docker（略，参考官方文档）# 关键：确认 cgroup 驱动为 systemddockerinfo|grep"Cgroup Driver"# 输出应为：Cgroup Driver: systemd排坑提醒：K8S 要求 Docker 的 cgroup 驱动必须和 kubelet 一致，默认都应该是
systemd。如果不一致，Pod 创建会失败。
四、安装 kubeadm / kubelet / kubectl（所有节点执行）
| 组件 | 作用 |
|---|---|
| kubeadm | 初始化集群的工具 |
| kubelet | 管理容器生命周期的守护进程 |
| kubectl | 命令行管理工具 |
4.1 配置软件源
apt-getupdate&&apt-getinstall-yapt-transport-httpscurlhttps://mirrors.aliyun.com/kubernetes/apt/doc/apt-key.gpg|apt-keyadd-cat<<EOF>/etc/apt/sources.list.d/kubernetes.listdeb https://mirrors.aliyun.com/kubernetes/apt/ kubernetes-xenial main EOFapt-getupdate4.2 安装指定版本
apt-get-yinstallkubelet=1.23.17-00kubeadm=1.23.17-00kubectl=1.23.17-004.3 验证版本
kubeadm version# kubeadm version: &version.Info{GitVersion:"v1.23.17",...}kubectl version# Client Version: version.Info{GitVersion:"v1.23.17",...}kubelet--version# Kubernetes v1.23.17排坑提醒：三个组件版本必须保持一致。kubelet 版本不可以超过 api-server 版本。
五、初始化 Master 节点
5.1 导入镜像（避免网络超时）
master-1.23.17.tar.gz包下载地址
链接: https://pan.baidu.com/s/1_muktv-75__PO7B_fMhVMg?pwd=vbc2 提取码: vbc2
# 提前下载好镜像包并导入dockerload-imaster-1.23.17.tar.gz# 确认镜像dockerimagels# kube-apiserver v1.23.17# kube-controller-manager v1.23.17# kube-scheduler v1.23.17# kube-proxy v1.23.17# etcd 3.5.6-0# coredns v1.8.6# pause 3.65.2 kubeadm init 初始化集群
kubeadm init\--kubernetes-version=v1.23.17\--image-repository registry.aliyuncs.com/google_containers\--pod-network-cidr=10.100.0.0/16\--service-cidr=10.200.0.0/16\--service-dns-domain=cn.com参数说明：
| 参数 | 作用 |
|---|---|
--kubernetes-version | 指定 K8S 版本 |
--image-repository | 镜像仓库地址（使用阿里云加速） |
--pod-network-cidr | Pod 网段 |
--service-cidr | Service 网段 |
--service-dns-domain | 集群 DNS 域名（默认 cluster.local） |
初始化成功后会输出关键信息：
Your Kubernetes control-plane has initialized successfully!# 保存 join 命令！24 小时内有效！kubeadmjoin10.0.0.231:6443--tokenhcfu6t.dw0qdsinnjs778mi\--discovery-token-ca-cert-hash sha256:c3f7dc36e438cd8e134797d472ddb0ab78766284a06a8b846f7eb37cf58bf951排坑提醒：Token 默认 24 小时过期，务必在有效期内完成 Worker 节点加入。如果过期，用
kubeadm token create --print-join-command重新生成。
5.3 配置 kubectl 管理集群
mkdir-p$HOME/.kubesudocp-i/etc/kubernetes/admin.conf$HOME/.kube/configsudochown$(id-u):$(id-g)$HOME/.kube/config5.4 验证 Master 组件状态
kubectl get componentstatuses# NAME STATUS MESSAGE# controller-manager Healthy ok# scheduler Healthy ok# etcd-0 Healthy {"health":"true","reason":""}kubectl get nodes# NAME STATUS ROLES AGE VERSION# master231 NotReady control-plane,master 3m v1.23.17此时节点状态为
NotReady，这是正常的，因为还没安装 CNI 网络插件。
六、Worker 节点加入集群
6.1 导入镜像（每个 Worker 节点）
slave-1.23.17.tar.gz包下载地址
链接: https://pan.baidu.com/s/13nACsXAfB9E0qH_MYBhxwQ?pwd=57pn 提取码: 57pn
dockerload-islave-1.23.17.tar.gz6.2 执行 join 命令
kubeadmjoin10.0.0.231:6443--tokenhcfu6t.dw0qdsinnjs778mi\--discovery-token-ca-cert-hash sha256:c3f7dc36e438cd8e134797d472ddb0ab78766284a06a8b846f7eb37cf58bf9516.3 验证节点加入
kubectl get nodes-owide# NAME STATUS ROLES AGE VERSION# master231 NotReady control-plane,master 8m v1.23.17# worker232 NotReady <none> 42s v1.23.17# worker233 NotReady <none> 38s v1.23.17七、部署 CNI 网络插件 Flannel
7.1 修改 Flannel 配置
wgethttps://github.com/flannel-io/flannel/releases/latest/download/kube-flannel.yml# 修改 Pod 网段与初始化时一致sed-i'/"Network":/s#10.244.0.0/16#10.100.0.0/16#'kube-flannel.yml7.2 应用 Flannel 资源
kubectl apply-fkube-flannel.yml7.3 验证网络插件
kubectl get pods-A#NAMESPACE NAME READY STATUS#kube-flannel kube-flannel-ds-5hbns 1/1 Running#kube-flannel kube-flannel-ds-dzffl 1/1 Running#kube-flannel kube-flannel-ds-h5kwh 1/1 Running#kube-system coredns-6d8c4cb4d-k52qr 1/1 Running#kube-system etcd-master231 1/1 Running#kube-system kube-apiserver-master231 1/1 Running#kube-system kube-controller-manager-master231 1/1 Running#kube-system kube-proxy-9bb67 1/1 Running#kube-system kube-scheduler-master231 1/1 Runningkubectl get nodes# NAME STATUS ROLES AGE VERSION# master231 Ready control-plane,master 27m v1.23.17# worker232 Ready <none> 23m v1.23.17# worker233 Ready <none> 23m v1.23.17所有节点状态变为Ready，集群部署完成。
八、验证跨节点 Pod 通信
创建两个分别在不同节点的 Pod，测试跨节点网络连通性：
apiVersion:v1kind:Podmetadata:name:test-v1spec:nodeName:worker232containers:-image:registry.cn-hangzhou.aliyuncs.com/eci_open/nginx:latestname:c1---apiVersion:v1kind:Podmetadata:name:test-v2spec:nodeName:worker233containers:-image:registry.cn-hangzhou.aliyuncs.com/acs/nginx:1.21name:c1kubectl apply-ftest-pod.yaml kubectl get pods-owide# NAME READY STATUS IP NODE# test-v1 1/1 Running 10.100.1.2 worker232# test-v2 1/1 Running 10.100.2.2 worker233# 跨节点访问测试curl10.100.1.2# worker232 上的 v1 服务curl10.100.2.2# worker233 上的 v2 服务两个 Pod 跨节点互通，说明 CNI 网络工作正常。
九、配置 kubectl 命令自动补全
kubectl completionbash>~/.kube/completion.bash.incecho'source $HOME/.kube/completion.bash.inc'>>~/.bashrcsource~/.bashrc# 测试：输入 kubectl 后连续按两次 Tab 键kubectl# 应出现所有子命令的补全列表十、K8S 部署方式对比
| 部署方式 | 难度 | 生产适用 | 说明 |
|---|---|---|---|
| kubeadm | 中 | 推荐 | 官方工具，快速部署，证书自动管理 |
| 二进制 | 高 | 大规模 | 完全手动控制每个组件，便于深度定制 |
| KubeSphere | 低 | 中小企业 | 图形化管理界面，底层基于 kubeadm |
| Rancher | 低 | 中小企业 | 图形化管理界面，支持 K3S |
| kubeasz | 中 | 推荐 | 基于 Ansible + 二进制方式 |
| 云产品（ACK/TKE/CCE） | 低 | 推荐 | 托管 K8S，免运维 Master |
建议：学习阶段用kubeadm搞懂原理，生产环境根据公司情况选择。
十一、部署第一个业务
集群搭建完成后，来部署一个 Nginx Web 应用，感受一下 K8S 的资源管理方式：
11.1 声明式管理 Pod
apiVersion:apps/v1kind:Deploymentmetadata:name:web-appspec:replicas:3selector:matchLabels:apps:webtemplate:metadata:labels:apps:webspec:containers:-name:nginximage:nginx:1.24ports:-containerPort:80kubectl apply-fweb-app.yaml kubectl get pods-owide# NAME READY STATUS IP# web-app-5d8f67c8d-abcde 1/1 Running 10.100.1.3# web-app-5d8f67c8d-fghij 1/1 Running 10.100.2.3# web-app-5d8f67c8d-klmno 1/1 Running 10.100.2.411.2 创建 Service 暴露服务
apiVersion:v1kind:Servicemetadata:name:web-svcspec:type:NodePortselector:apps:webports:-port:80targetPort:80nodePort:30080kubectl apply-fweb-svc.yaml# 浏览器访问http://10.0.0.231:30080 http://10.0.0.232:30080 http://10.0.0.233:30080十二、常见问题与排坑
Q1：初始化失败怎么处理？
# 重置节点kubeadm reset-f# 检查常见原因free-h# 确认 swap 已关闭lscpu# 确认 CPU >= 2 核dockerinfo# 确认 cgroup 驱动为 systemd# 重新初始化kubeadm init --kubernetes-version=v1.23.17...Q2：节点状态 NotReady？
# 检查 kubelet 状态systemctl status kubelet# 检查 CNI 插件kubectl get pods-nkube-flannel# 检查节点资源kubectl describenode<节点名>Q3：Token 过期了怎么办？
# 重新生成 join 命令kubeadm token create --print-join-commandQ4：Pod 一直处于 ContainerCreating？
kubectl describe pod<Pod名># 常见原因：镜像拉取失败、存储卷挂载失败、CNI 配置问题十三、总结
本文从零开始，完成了一套完整的 K8S 集群搭建，核心步骤如下：
1. 系统优化（关闭 Swap、内核参数、ipvs 模块） 2. 安装 Docker（确认 cgroup 驱动） 3. 安装 kubeadm / kubelet / kubectl 4. kubeadm init 初始化 Master 5. Worker 节点 join 加入集群 6. 部署 CNI 网络插件（Flannel） 7. 验证跨节点通信 8. 部署业务验证掌握了这套流程，你就具备了 K8S 集群部署的核心能力。后续可以在此基础上学习 Service、Ingress、HPA 自动扩缩容、PV/PVC 持久化存储、Helm 包管理等进阶内容。
推荐下一步学习路径：
- K8S 核心资源：Deployment、Service、Ingress、ConfigMap、Secret
- 存储体系：PV、PVC、StorageClass、对接 Ceph
- 监控体系：Prometheus + Grafana + Alertmanager
- 日志体系：ElasticStack（EFK）
- CI/CD：Jenkins + K8S 实现代码自动发布
参考资源：
- Kubernetes 官方文档：https://kubernetes.io/zh-cn/docs/
- kubeadm 安装指南：https://kubernetes.io/zh-cn/docs/setup/production-environment/tools/kubeadm/
- Flannel 网络插件：https://github.com/flannel-io/flannel
