企业官网建设流程全解析

最近总有朋友问我："想正经学K8s，是不是上来就得照着文档搭一套三master的高可用集群？"我每次都会先反问一句：你搭这套集群，最终目的是什么？如果是为了生产环境承接业务，那确实不能省；但如果是为了把Kubernetes的核心概念吃透、为了在资源有限的测试环境里跑一套完整的编排流程、为了给团队做技术验证，那k8s单master集群是性价比最高的起点——一台机器就能跑，两三个小时就能从零到Ready，而核心链路（API Server、调度、控制器、etcd、Pod网络）一个都不缺。

这篇文章把我自己搭单master集群的完整过程整理出来，包括环境准备、容器运行时选型、kubeadm初始化、Pod网络插件部署、工作节点加入，以及我在实操中踩过的坑。适用对象是三类人：第一次搭k8s的新手、想用低成本环境验证业务配置的开发者、以及需要反复练习集群环境的人。如果你手头只有一台2核4G的机器，这篇文章能帮你把集群顺利跑起来。

1. 先想清楚：单master集群到底解决了什么问题

1.1 单master不是"残废版"，它有自己的位置

很多人一听"单master"，下意识觉得这是个阉割产品。实际上从Kubernetes的功能角度来看，单master集群和标准集群的唯一区别在于控制平面组件的副本数：API Server、controller-manager、scheduler、etcd都只有一份。这意味着它不具备高可用能力，控制平面任何组件宕掉，集群的管理功能就会受影响，但已经调度到工作节点上的Pod并不会立刻挂掉，业务流量仍然可以继续走。

所以单master集群的价值在于：用最低的资源成本，完整复刻k8s的管理链路和调度逻辑。对于学习场景来说，你不需要关注多实例选举、etcd集群一致性这些复杂概念，可以把全部精力放在Pod、Deployment、Service、Ingress这些核心对象上。我自己搭这套集群的时候，最大的感受就是"麻雀虽小五脏俱全"，该有的机制一个没少。

1.2 单master、minikube、k3s怎么选

我见过不少人在选择学习环境时反复纠结，其实这三者的边界很清晰：

如果你只是想知道kubectl某个命令怎么用，minikube就够了；但如果你要验证一个完整的CI/CD流程、要测试Ingress控制器、要看Pod在不同节点间的调度行为，我建议老老实实搭一个单master集群。这也是我最终选择用kubeadm搭建而不是偷懒用minikube的原因——生产环境怎么部署，学习环境就应该怎么部署，避免"换了个环境就不会了"。

1.3 单master加一台worker的经典组合

实际上我自己最喜欢的组合是"一台master加一台worker"，总共两台机器。master节点承载控制平面和etcd，worker节点专门跑业务Pod。这样有几个好处：第一，控制平面和业务负载物理隔离，master不容易被业务Pod拖垮；第二，Pod调度、节点亲和性这些功能有真实的跨节点场景可以观察；第三，NodePort、Ingress这些对外暴露能力需要真正跑在节点网络里才直观。

如果你的硬件非常紧张，只有一台机器，那也可以把master当作唯一的节点，通过污点策略决定要不要在master上跑业务Pod。下文第4节我会讲怎么操作。

2. 动手前的环境准备：硬件、系统与网络规划

2.1 硬件和操作系统怎么选

先说结论，我的建议配置是：master节点2核4G、磁盘40G以上；worker节点2核4G起步；操作系统选择Ubuntu 22.04 LTS或CentOS 7.9。系统需要64位Linux，内核版本3.10以上，建议4.4以上。注意，CentOS 7.9的iptables版本较老，配k8s时要把相关参数调对，否则会有网络问题；如果你没有历史包袱，直接上Ubuntu 22.04最省心。

磁盘方面，k8s的组件日志、镜像、etcd数据都会占空间，尤其是etcd，虽然不是高可用集群但也会持续写入。我见过有人用10G磁盘装k8s，装到一半镜像拉不下来，一查是磁盘满了。SSD不是必须的，但虚拟机的IOPS太差会影响kubelet和etcd性能，这个要注意。

2.2 端口规划：提前放行，别等报错了才排查

Kubernetes各个组件之间有固定的通信端口，搭建之前最好就把防火墙规则或者安全组策略配好，否则后续各种诡异问题都会找上你。我整理了一份常用端口清单：

如果你用的是云服务器，要在安全组里放行这些端口；如果是本机虚拟机，检查firewalld或ufw的状态，测试环境最简单粗暴的做法是直接关闭防火墙，或者按端口白名单放行。主机名规划也很重要，建议master叫master01，worker分别叫node01、node02，保持统一风格，后续看log和拓扑一目了然。

2.3 三件套：关swap、开模块、设内核参数

在安装任何k8s组件之前，有三件基础配置必须做：

1. 关闭swap：swapoff -a并注释掉/etc/fstab中的swap行，因为kubelet在启用swap的情况下会拒绝启动。
2. 加载内核模块：br_netfilter是必须的，同时把overlay模块加载上，容器网络依赖它们实现iptables规则和文件系统。
3. 设置内核参数：主要是net.bridge.bridge-nf-call-iptables和net.ipv4.ip_forward，前者让iptables能处理经过网桥的流量，后者是Pod网络转发的前提。

这里给出一套可以直接复制执行的命令，以Ubuntu为例：

# 关闭swap sudo swapoff -a sudo sed -i '/swap/s/^/#/' /etc/fstab # 加载内核模块 cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf overlay br_netfilter EOF sudo modprobe overlay sudo modprobe br_netfilter # 设置内核参数 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 --system执行完以后，可以用ls /proc/sys/net/bridge确认br_netfilter是否真的加载了。如果这个目录不存在，说明模块没加载成功，后面kube-proxy的iptables规则会不生效，表现在现象上就是"Pod能通，但Service访问时好时坏"。

2.4 时间同步别忽略

k8s的证书校验强依赖时间，节点之间时间差太大会导致"证书尚未生效"或者"x509: certificate has expired"这类报错。自己搭测试环境的时候，至少要做到所有节点使用同一个NTP服务器同步。Ubuntu默认有systemd-timesyncd，可以执行timedatectl set-ntp true开启，如果内网有统一的时间源，直接把chrony配置指向它。这个问题特别隐蔽，往往排查到怀疑人生才发现是时间漂移，提前处理好能省很多事。

3. 容器运行时：为什么我换掉了Docker

3.1 CRI与k8s 1.24之后的变化

在k8s 1.24版本之前，默认的容器运行时是Docker，kubelet通过dockershim这个内置组件调用Docker。但从1.24开始，dockershim被正式移除，k8s改用标准的CRI接口对接容器运行时，Docker本身并不直接实现CRI，需要依靠cri-dockerd这个桥接项目才能继续用。既然多绕了一层，我建议新搭建的集群直接使用containerd。

containerd和Docker是同一个家族的项目，Docker底层的容器管理能力就是containerd提供的。对k8s来说，containerd更轻量、更稳定，它天然支持CRI接口，配置正确的话性能损耗也小。这也是当前社区的主流方向，照着这个方向学，以后到真实生产环境也不会踩到过时的坑。

3.2 containerd安装与配置要点

安装containerd的方式取决于你的系统。Ubuntu可以用apt直接安装，也可以用编译好的二进制包解压部署。我比较推荐apt安装，版本和系统匹配度好，后续升级也方便：

sudo apt-get update && sudo apt-get install -y containerd

安装完成以后，第一件事是生成默认配置：

sudo mkdir -p /etc/containerd containerd config default | sudo tee /etc/containerd/config.toml

这里有一个关键参数必须手动改：SystemdCgroup。containerd默认的Cgroup驱动是cgroupfs，而kubelet默认期望的是systemd驱动（在使用了systemd作为init的Linux发行版上）。驱动不一致，轻则Pod状态异常，重则节点内存统计混乱。修改方式是在config.toml中找到SystemdCgroup这一项改为true。

另外就是镜像加速配置。k8s组件镜像很多托管在境外仓库，国内服务器直接拉取经常超时。比较靠谱的做法是在config.toml的mirrors配置段里添加一个可访问的镜像仓库地址，或者把kubeadm的--image-repository参数指向可用的镜像仓库，这个我在第4节会再讲。

改完配置以后执行：

sudo systemctl restart containerd sudo systemctl status containerd

顺便提一下，装完containerd后，我建议顺手安装crictl命令行工具，它是排查容器问题时的利器，用法和docker CLI很像：crictl ps、crictl logs，在排查Pod异常时比kubectl日志更底层、更直白。

4. kubeadm初始化master：从init到Ready的关键一步

4.1 安装kubeadm、kubelet、kubectl并锁定版本

三个核心组件要一起装，而且版本必须对齐。kubeadm是集群搭建工具，kubelet是节点上的核心代理程序，kubectl是命令行客户端。以k8s 1.28版本为例，整个过程如下：

sudo apt-get update sudo apt-get install -y apt-transport-https ca-certificates curl 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 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 sudo apt-get install -y kubelet=1.28.* kubeadm=1.28.* kubectl=1.28.* sudo apt-mark hold kubelet kubeadm kubectl

最后一行apt-mark hold很重要，防止后续执行apt-get upgrade时把组件版本带歪。k8s对版本敏感，kubelet和API Server的版本偏差过大会导致节点反复NotReady。隔离环境如果无法访问外网仓库，需要提前把deb包下载好，离线安装也是可以的，但依赖关系要理清楚。

装完之后kubelet默认是未启动状态，或者启动失败，这是正常的，因为还没有初始化集群，不用急着去拉起它。

4.2 kubeadm init参数逐项拆解

初始化master节点的标准命令如下，我加了最常用的参数：

sudo kubeadm init \ --kubernetes-version=v1.28.2 \ --apiserver-advertise-address=192.168.1.10 \ --pod-network-cidr=10.244.0.0/16 \ --cri-socket=unix:///run/containerd/containerd.sock \ --image-repository=registry.k8s.io

各参数的含义我逐个说清楚：

• --kubernetes-version：指定集群版本。如果不指定，kubeadm会去拉取最新版本，而这些信息它需要从网上获取。指定后可以跳过解析流程，也让你明确知道自己在装哪个版本。
• --apiserver-advertise-address：API Server对外广播的地址。如果你的机器有多个网卡，比如一块管理网卡一块业务网卡，一定要显式指定，否则kubeadm会自己挑一个，常常挑错。
• --pod-network-cidr：Pod网段。这个网段是给Pod分配IP用的，必须和后面的CNI插件配置匹配。我用Flannel，所以指定10.244.0.0/16；如果用Calico，通常是192.168.0.0/16。改掉的话，容器网络插件会工作异常。
• --cri-socket：CRI socket路径。多个容器运行时共存时尤其重要，告诉kubeadm用哪个运行时。如果你从头到尾只装了containerd，这个参数可加可不加，kubeadm能自动探测，但显式写出来更稳。
• --image-repository：镜像仓库地址。默认是registry.k8s.io，国内环境如果拉不动，可以换成可访问的镜像仓库，后面所有组件镜像都会从这个地址拉取，能省掉一大堆等待超时的时间。

init过程通常需要2-5分钟，期间kubeadm会拉取API Server、controller-manager、scheduler、etcd、CoreDNS、pause等组件的镜像，然后依次启动。看到类似"Your Kubernetes control-plane has been initialized successfully"的输出，就说明初始化成功了。

4.3 初始化失败怎么办：kubeadm reset的正确用法

初始化失败是最常见的情况，记住一个原则：不要慌，不要反复执行init，先看日志。排查步骤是：

1. 查看kubelet日志：journalctl -u kubelet -f，大多数失败原因都会在这里体现。
2. 检查容器运行时状态：crictl ps -a，确认pause容器有没有被拉起来。
3. 如果是镜像拉取失败，先手动执行crictl pull验证网络。

一旦明确是配置问题或者镜像地址不对，修完后要使用kubeadm reset -f清理现场，然后重新init。这里最容易踩的坑是：某些残留目录或iptables规则没清干净，导致第二次init后依旧报错。我建议在kubeadm reset -f之后，再手动执行：

sudo rm -rf /etc/cni/net.d sudo ipvsadm --clear 2>/dev/null || true sudo iptables -F && sudo iptables -t nat -F && sudo iptables -t mangle -F

把CNI配置、ipvs规则、iptables规则全部复位，这样第二次init才会有一个真正干净的环境。

4.4 kubectl配置与master节点的污点处理

init成功后，kubeadm会输出三件事：kubectl配置命令、join命令、join token相关的提示。第一件事就是把自己机器的kubectl配好：

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

配置完成后可以执行kubectl get nodes，这时候你会看到master节点状态是NotReady，不要紧张，这是正常的，因为Pod网络还没有部署。同时你会注意到master节点上有污点：

node-role.kubernetes.io/control-plane:NoSchedule

这个污点意味着默认情况下业务Pod不会调度到master上。如果你的环境只有一台机器，想直接在master上跑业务Pod，可以删掉这个污点：

kubectl taint nodes master01 node-role.kubernetes.io/control-plane:NoSchedule-

但有worker节点的话，我不建议这么做，让控制平面和业务负载分离是最佳实践，也方便你观察调度逻辑。

5. Pod网络插件：Flannel还是Calico？

5.1 为什么必须有CNI，以及两者怎么选

Pod网络是Kubernetes里最基础的能力之一。k8s对Pod网络的规划是：每个Pod都有一个集群内唯一的IP，Pod之间可以直接通信，不管它们落在哪个节点上。这个能力不是k8s内置实现的，而是通过CNI插件完成的。kubeadm初始化完集群之后，集群里只有CoreDNS调度不出来、节点状态也是一直NotReady，就是因为CNI还没装。

主流的CNI插件有两类代表，Flannel和Calico，它们的对比大致是这样的：

我自己的建议是：第一次搭集群、以学习为目的，直接用Flannel，部署简单，排查概念少；如果你的目标是生产环境或者要深度用网络策略，直接上Calico，它可以完全满足后续的功能扩展，不用二次迁移。

5.2 Flannel部署与CoreDNS Pending的排查

用Flannel的话，init时--pod-network-cidr必须指定为10.244.0.0/16，这是一个强绑定关系。之后直接应用它的manifest文件，通常是把kube-flannel.yml下载下来然后kubectl apply -f。用Calico的话则不同，它默认使用192.168.0.0/16这个网段，如果所在VPC网段冲突，需要通过环境变量修改。

部署完成后，如果发现CoreDNS一直Pending，第一反应不要去重启CoreDNS，而应该按这个顺序排查：

1. kubectl get pods -n kube-system -o wide，看Flannel的Pod落在哪个节点。
2. kubectl logs -n kube-system <flannel-pod>，看日志有没有报错。
3. 检查Flannel需要的网段配置是否和kubeadm init时的pod-network-cidr一致。
4. 检查节点上的iptables和后端网络接口，用iptables -L -n -t nat快速瞄一眼有没有flannel相关的规则。

最常见的原因是CNI配置文件没生成或者生成的时机不对。在Flannel Pod正常启动之前，/etc/cni/net.d目录一般是空的。如果反复删除重建Flannel Pod之后，CoreDNS还是Pending，我建议直接把Flannel的DaemonSet删掉重建：

kubectl delete -f kube-flannel.yml kubectl apply -f kube-flannel.yml

等所有Flannel Pod变成Running之后，CoreDNS会自己调度成功，不需要手动干预。这里强调一下，CoreDNS不Ready的原因大概率是它依赖的网络还没就绪，不要去修改CoreDNS的副本数或者强杀Pod。

5.3 一个典型的"Pod通了但Service不通"案例

我自己在搭建过程中遇到过这样一次问题：集群节点都Ready了，Pod之间ping得通，但通过ClusterIP访问Service就是不通。后来排查发现是一个细节——Flannel和kube-proxy的iptables规则有冲突。起因是我曾经手动把两个节点的网络接口管理改为no，导致NetworkManager没有把容器网络接口接管好，Flannel接口的状态一直不对。

最后解决办法是把接口管理权交还给NetworkManager，重启网络服务，再依次重启所有节点的kube-proxy Pod。这种情况其实并不少见，虚拟机上搭k8s网络问题尤其多。遇到这类问题不要盲目重装集群，从"接口状态"和"iptables规则是否存在"两个角度入手，往往能快速定位。

6. 工作节点加入集群：token过期与镜像优先级

6.1 重新生成join命令

init成功的时候，kubeadm会输出给worker节点的join命令，这个命令包含两个关键信息：API Server地址和加入token。问题在于token有效期默认只有24小时，很多人的worker节点不是当场加入的，等过几天想加了，token早就过期了。遇到这种情况，直接在master上重新生成即可：

kubeadm token create --print-join-command

这条命令会打印一条全新的带新token的join命令。如果连CA证书的hash都需要重新获取，可以用：

openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | openssl rsa -pubin -outform der 2>/dev/null | openssl dgst -sha256 -hex | sed 's/^.* //'

把join命令在worker上执行，看到"Node has joined the cluster"就说明成功了。返回master执行kubectl get nodes，worker状态会先显示NotReady，等它拉取pause镜像、启动kube-proxy等组件后就会变成Ready。

这里顺带提一下join命令背后的机制：worker节点执行kubeadm join时，kubelet会拿着token向API Server发起请求完成引导，然后从控制平面获取证书和配置，再启动一系列静态Pod组件。整个过程如果某个环节被防火墙挡住，报错会五花八门，但基本都是"连不上"或者"认证失败"两类。

6.2 worker节点常见的join失败原因

根据我自己的经历，join失败集中在三类问题上：

worker节点上同样要执行前面说的基础配置：关闭swap、加载br_netfilter、设置sysctl参数，否则join后会直接NotReady，而且日志里的报错会非常隐晦。我强烈建议worker节点和master节点使用相同的系统版本、相同的容器运行时版本，差异越小，坑越少。另一个容易被忽略的点是：worker节点不一定要装kubectl，但如果装了，注意不要自己创建~/.kube/config，否则容易和join生成的配置混淆。

7. 集群自检清单：确认每个核心链路都正常

7.1 从节点状态到业务Pod的完整验证

集群搭建完以后，不要急着说"弄好了"，按下面这套清单过一遍，基本可以确认集群从管理面到数据面都正常工作：

1. 节点状态：kubectl get nodes，所有节点都应该是Ready状态。
2. 核心组件：kubectl get pods -n kube-system，CoreDNS、kube-proxy、Flannel/Calico的Pod都应该是Running。
3. 管理链路：kubectl get cs查看etcd、scheduler、controller-manager的状态。如果组件版本较新，这个命令可能显示过期提示，可以用kubectl get --raw='/healthz'确认控制平面健康。
4. 部署业务：跑一个测试Deployment，比如kubectl create deployment nginx --image=nginx，确认Pod能正常调度并Running。
5. 服务发现：给测试Deployment创建一个Service，确认ClusterIP能访问，如果能用NodePort访问到，就说明kube-proxy的转发规则生效了。
6. 跨节点通信：如果你的集群有多台worker，特意把两个Pod调度到不同节点上验证通信，确认CNI插件工作正常。

这套流程我平时搭完任何k8s环境都会跑一遍，确实能避免很多"当前看起来正常，第二天业务一部署就各种问题"的尴尬。

7.2 频繁操作会用到的高频命令

日常使用中，有几条命令我几乎每天都会敲，放在这里供参考：

# 查看所有命名空间的Pod及所在节点 kubectl get pods -A -o wide # 查看节点资源使用情况 kubectl top nodes # 查看事件，排查异常时最有用 kubectl get events --sort-by='.lastTimestamp' # 进入Pod调试 kubectl exec -it <pod-name> -- /bin/sh # 查看Pod调度到了哪个节点 kubectl get pod -o wide

kubectl get events这条命令是排查的起点，很多问题在events里都有直接线索，比翻组件日志高效得多。

7.3 重启机器之后的注意事项

物理机或虚拟机重启后，最容易出现"节点NotReady"的情况。这通常不是集群坏了，而是服务启动顺序的问题。重启后要依次确认三件事：

systemctl status containerd systemctl status kubelet crictl ps

containerd先起来，kubelet才能正常工作；kubelet启动后会拉起静态Pod（etcd、API Server等）。如果etcd静态Pod一直CrashLoop，多半是上次非正常关机导致的数据目录异常，优先看journalctl -u kubelet里关于etcd的日志。另外重启后同样要注意时间同步是否恢复，虚拟机关机一段时间后时间漂移是常有的事。

8. 单master集群的日常运维：备份、升级与演进

8.1 一定要做的etcd备份

单master集群最脆弱的地方就是etcd，它保存了整个集群的状态数据，包括所有资源对象的定义、当前状态、配置信息。一旦数据损坏，集群就废了。所以不管多小的测试集群，我建议至少养成定时备份etcd的习惯。

etcd的备份命令依赖etcdctl这个客户端，版本要和etcd匹配。kubeadm部署的etcd在kube-system命名空间下的Pod里跑，官方推荐的备份方式是进入Pod内执行快照：

kubectl -n kube-system exec etcd-master01 -- sh -c \ "ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \ --cacert=/etc/kubernetes/pki/etcd/ca.crt \ --cert=/etc/kubernetes/pki/etcd/server.crt \ --key=/etc/kubernetes/pki/etcd/server.key \ snapshot save /var/lib/etcd-backup.db"

备份文件生成后，拷贝到安全位置，并配合定期的cron任务做自动备份。恢复流程是：停止API Server相关的组件，用etcdctl snapshot restore恢复到一个临时目录，再把etcd的data-dir替换回去，重新启动。整个操作不算复杂，但恢复过程中任何一步错了都可能二次损坏数据，所以"备份验证"比"备份动作"更重要——备份完以后，至少要在临时环境验证一次快照能恢复。

8.2 升级路线与高可用演进方向

单master集群搭建完成后，如果业务量上来了想升级，有两条常见路线：

第一条是"加机器做高可用"，通过kubeadm或托管机制把控制平面副本数提升到多个。这个过程不是简单地再init一台机器，而是要引入负载均衡器，把API Server的流量分发到所有master，etcd也要从单实例变成集群。复杂度会明显上升，建议在业务真正需要时再做。

第二条是"迁移到托管集群"，把业务从自建集群迁到云厂商的托管服务。这种方式省去了控制平面的运维压力，适合不想在基础设施上花太多精力的团队。无论选哪条路，平时养成用kubeadm upgrade plan查看升级路径的习惯，别让集群版本落后太多，否则后续升级要跨越多个版本，会非常痛苦。

对我来说，搭单master集群最大的价值是：把Kubernetes的内部运行机制亲手摸了一遍。当你真正理解了API Server怎么调度、kubelet怎么注册节点、CNI怎么打通网络，再看任何托管集群、任何自动化工具，都会有完全不一样的感觉。最后再分享一个小技巧：如果你在搭建过程中卡在一个报错超过半小时，别死磕，先去看看kube-system命名空间下的events，大部分答案都已经写在那里了。