在你的Linux服务器上到底怎么把Kubesphere集群版一次性装通这篇我直接给你梳理一份可落地的步骤从安装器选型、环境初始化、配置模板、存储准备到装到一半最容易翻车的几个坑都在里面。写这篇文章的起因很简单我之前接过一个内部学习环境的搭建需求团队已经有几台Linux虚拟机不想用托管服务也不想手动去部署一堆Prometheus、Grafana、Jenkins之类的组件就指望Kubesphere能把云原生PaaS的核心能力打包好一次性拉起一个能用的集群版。装完之后最大的感受是Kubesphere集群版本身并不难装难的是你在动手之前有没有把Linux环境、容器运行时、存储类这些“老三样”想清楚。这篇文章就适合正在准备在裸机或虚拟机上搭多节点K8s平台的人也适合那些刚从单机版All-in-One跳到集群版、想认清部署差别的入门者。1. 安装前决策为什么选择Linux直装集群版而不是单机版1.1 集群版和单机版到底差在哪里很多同学第一次接触Kubesphere都会从All-in-One的单节点安装开始。这个模式本质上是把Kubernetes控制面、工作负载、Kubesphere的各个组件全部压在一台机器上方便你快速看到登录页面、创建企业空间、跑一个示例应用。但说实话单机版适合“尝鲜”不适合真正学集群管理更不适合做后续的高可用和容量规划。集群版就不一样了。它最少要划分出control-plane角色和worker角色通常还会单独规划etcd节点。这样的好处是你可以真实地体会Pod是怎么被调度到不同节点的NodePort怎么在集群边界暴露PVC怎么跨节点绑定CNI插件在多节点之间怎么传播路由。哪怕你只有3台2核4G的虚拟机我也建议直接按集群版来练手而不是继续停留在单机体验里。直接在Linux上装集群版还有一个实际优势底层完全自管。你可以通过SSH随时进入任何节点查看日志可以调整内核参数、镜像加速配置、磁盘挂载路径也可以根据团队内部网络情况决定用什么CNI和存储方案。这些都是在托管环境里不容易做到的。1.2 安装器选型KubeKey、ks-installer还是纯手动Kubesphere集群版常见的部署路径有三条我先说结论如果Linux环境是从零开始最推荐你用KubeKey直接一条龙部署。安装方式适用场景优点缺点KubeKey一键部署空白的Linux节点需要同时装K8s和Kubesphere自动完成K8s初始化、CNI安装、Kubesphere组件部署配置集中在单文件安装器会占用一定控制权需要理解config模板ks-installer已有K8s集群已经跑起来只希望加Kubesphere层不碰已有K8s基础组件部署范围清晰对K8s版本有要求如果基础集群有问题仍需要你自己解决手动部署组件学习K8s原理想逐个搭建监控、DevOps等可控性最强理解最深刻组件数量太多排错成本极高不适合快速交付我自己在实际项目里最常用的是KubeKey因为KubeKey底层会调用kubeadm完成K8s初始化同时把etcd、控制面、网络插件、Kubesphere安装Job都编排好。你只需要在config文件里声明节点角色和版本剩下的交给安装器跑。它不是黑盒日志打印得也算清晰出现问题后可以顺着日志找到是哪一步卡住。1.3 资源规划与版本选择提前算清楚安装前最重要的事情是确认资源不要只盯着“官网最低要求”看。Kubesphere集群版装上之后可观测性相关的组件会常驻内存Prometheus那套监控栈通常要占到2核4G以上的资源如果还开启DevOpsJenkins的Pod又会再吃掉一部分内存。所以我的建议是节点角色CPU内存系统盘数据盘/容器目录control-plane4C8G50G100Gworker8C16G50G200G测试用最小集群2C4G起步40G80G版本方面不要盲目追最新。优先选择官方兼容矩阵里标明稳定的K8s版本和Kubesphere版本组合比如我用的组合就是经过验证的稳定版本。用太新的K8s版本有时候反而会因为CRD变更、API移除导致安装器里的组件起不来。网络规划也要提前做。节点之间需要互访的端口很多包括SSH的22、K8s API Server的6443、etcd的2379/2380、kubelet的10250以及NodePort范围的30000-32767Kubesphere控制台的30880。如果你有防火墙记得先放行。2. Linux环境准备每一步都是在给安装器减负2.1 系统基础设置先把节点身份统一我装集群版之前习惯先把所有节点的hostname和/etc/hosts配好。这个问题看起来小但实际影响很大etcd、kubelet、CoreDNS都会依赖主机名解析如果节点之间互相不认识后面会出现各种“奇怪”的报错比如证书里IP对不上、kubelet无法注册。hostnamectl set-hostname master1 hostnamectl set-hostname node1 hostnamectl set-hostname node2然后在每台节点上把其余节点的IP和主机名都写进/etc/hosts192.168.1.10 master1 192.168.1.11 node1 192.168.1.12 node2接下来处理swap。Kubernetes希望节点上的swap处于关闭状态虽然新版本对swap的容忍度有调整但为了避免kubelet参数问题我还是建议学习环境直接关掉并且从fstab中注释掉防止重启后swap又自动挂上。swapoff -a sed -i / swap / s/^/#/ /etc/fstab时间同步也不要漏。etcd对时钟偏差很敏感偏差太大集群会出现leader频繁切换。直接启用系统自带的chrony就行systemctl enable --now chronyd防火墙这块如果是学习环境我一般先直接关掉减少干扰systemctl stop firewalld systemctl disable firewalld如果是生产环境请务必按端口维度放行而不是简单关闭防火墙。2.2 内核模块与系统参数提前加载Kubernetes的流量转发依赖Linux网桥和iptables规则所以需要加载overlay和br_netfilter这两个模块同时开启桥接流量的iptables处理。不配这一步后面装好Calico后Pod之间的通信经常出问题。cat /etc/modules-load.d/k8s.conf EOF overlay br_netfilter EOF modprobe overlay modprobe br_netfilter cat /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 sysctl --system这里的几个参数的作用分别是net.bridge.bridge-nf-call-iptables让经过Linux网桥的流量也走iptables规则这是CNI插件实现Pod隔离的基础net.ipv4.ip_forward开启IP转发Pod之间的流量和Service转发都需要它。2.3 容器运行时containerd的SystemdCgroup才是关键从Kubernetes 1.24开始容器运行时默认就是containerdKubesphere本身也不要求你必须装Docker。所以我建议直接在Linux上装containerd然后重点检查两件事cgroup driver是否设置为systemd以及镜像加速是否配置到位。apt install -y containerd mkdir -p /etc/containerd containerd config default /etc/containerd/config.toml生成默认配置后需要找到SystemdCgroup这个字段把它改成true。可以用sed快速处理sed -i s/SystemdCgroup false/SystemdCgroup true/ /etc/containerd/config.toml这一步不做会怎样kubelet和containerd各自管理cgroup的方式不一致节点可能一直处于NotReady状态或者Pod能创建但起不来这类问题排查起来非常绕。然后是镜像加速。安装Kubesphere需要拉取大量镜像网络稍不稳定就会卡在Downloading阶段。containerd的镜像加速配置在config.toml里要给docker.io单独配一个镜像源[plugins.io.containerd.grpc.v1.cri.registry.mirrors] [plugins.io.containerd.grpc.v1.cri.registry.mirrors.docker.io] endpoint [https://mirror-host]改完以后重启containerdsystemctl restart containerd systemctl enable containerd所有节点都要做同样的操作不只是master节点。2.4 共享存储类提前准备好能省一大半时间这一点可能很多人会忽略但我可以明确告诉你Kubesphere集群版安装完之后监控、日志、DevOps组件全都需要持久化存储。如果集群里没有默认StorageClass你会发现大批Pod处于Pending状态因为PVC无法被自动创建。裸机环境最简单的方案是搭一个NFS Server再用Helm部署一个基于NFS的StorageClass。先选一台节点做NFS服务端apt install -y nfs-kernel-server mkdir -p /data/nfs chmod 1777 /data/nfs echo /data/nfs *(rw,sync,no_subtree_check,no_root_squash) /etc/exports exportfs -av每个worker节点安装NFS客户端apt install -y nfs-common然后部署NFS Provisioner把storageClass设置成默认helm repo add nfs-community nfs-subdir官方chart仓库地址 helm install nfs-client nfs-community/nfs-subdir-external-provisioner \ --set nfs.server192.168.1.10 \ --set nfs.path/data/nfs \ --set storageClass.namenfs-client kubectl patch storageclass nfs-client -p {metadata:{annotations:{storageclass.kubernetes.io/is-default-class:true}}}这里要解释一个原理多节点集群里如果每个节点都只用本地磁盘创建local volume那么PV只能调度到数据所在节点PVC会一直Pending。NFS这类共享存储能让所有节点都能访问同一份数据Kubesphere组件被调度到任意节点都不会因为找不到数据卷而崩溃。3. 实操过程用KubeKey一次拉起Kubesphere集群版3.1 下载KubeKey并用一条命令生成配置文件准备工作做完后在master节点上下载KubeKey。下载命令很简单直接执行官方脚本curl -sfL https://get-kk.kubesphere.io | VERSIONv3.0.7 sh - chmod x kk ./kk version然后生成带Kubesphere版本的配置文件./kk create config --with-kubesphere v3.4.0这条命令会生成一个config-sample.yaml里面包含了节点、角色组、K8s版本、网络插件等所有部署参数。3.2 修改集群配置模板理解每个字段再动手打开config-sample.yaml核心结构大概是下面这样apiVersion: kubekey.kubesphere.io/v1alpha2 kind: Cluster metadata: name: sample spec: hosts: - {name: master1, address: 192.168.1.10, internalAddress: 192.168.1.10, user: root, password: password} - {name: node1, address: 192.168.1.11, internalAddress: 192.168.1.11, user: root, password: password} - {name: node2, address: 192.168.1.12, internalAddress: 192.168.1.12, user: root, password: password} roleGroups: etcd: - master1 control-plane: - master1 worker: - node1 - node2 controlPlaneEndpoint: domain: lb.kubesphere.local address: 192.168.1.10 port: 6443 kubernetes: version: v1.26.5 clusterName: sample.local network: plugin: calico kubePodsCIDR: 10.233.64.0/18 kubeServiceCIDR: 10.233.0.0/18 registry: registryMirrors: [] insecureRegistries: []hosts里的address是KubeKey通过SSH连接节点时使用的地址internalAddress是集群内部通信地址。如果节点有多个网卡建议internalAddress填内网网段避免走公网流量。roleGroups里面的control-plane在旧版本模板里可能叫master以你生成的模板为准就好。controlPlaneEndpoint这里是关键点。学习环境可以把address直接写成master节点的IP不需要额外部署负载均衡。但生产环境一定要用LoadBalancer或者至少是VIP否则控制面一旦切换节点API Server地址就变了。kubernetes.version要选一个和Kubesphere版本兼容的稳定版本。network.plugin默认用Calico这也是官方推荐的选择性能和多节点路由能力比较平衡。3.3 执行部署命令耐心看完日志再动手配置文件修改无误后直接执行创建集群命令./kk create cluster -f config-sample.yaml安装过程会分几个阶段环境检查、安装依赖、初始化etcd、初始化master节点、安装CNI、等待节点Ready、部署Kubesphere组件。日志里如果看到INFO级别的进度输出比如[INFO] Pulling images说明安装器正在拉镜像。这个阶段通常最耗时取决于网络和镜像大小。我踩过的坑是有些人看到进度条久久不动就忍不住CtrlC结果半途中断再重跑就要处理一堆残留的etcd和证书。如果你也遇到这种情况先检查网络、磁盘和镜像拉取日志不要盲目中断。确实需要重来的时候可以用以下命令清理集群./kk delete cluster -f config-sample.yaml安装成功完成后终端会输出这样的信息包括控制台访问地址和初始账号Console: http://192.168.1.10:30880 Account: admin Password: Pssw0rd看到这行字说明集群版已经装起来了。接下来要做的不是急着登录而是先检查集群和核心组件状态。3.4 安装后的第一轮状态检查登录控制台之前先在master节点上执行几个检查命令kubectl get nodes kubectl get pods -A -o wide kubectl get svc -n kubesphere-system kubectl get sc这几条命令分别检查节点是否Ready、核心Pod是否Running、控制台Service是否已经暴露、默认StorageClass是否存在。重点看kubesphere-system命名空间下的ks-console它是前端控制台的入口。如果状态是Running就可以访问30880端口了。我第一次装完集群版后节点是Ready的但控制台一直打不开后来发现是ks-console的Pod还没跑起来。所以别急着在浏览器敲地址先用kubectl把Pod状态确认好。4. 集群版初始化存储确认、组件开关与权限沉淀4.1 存储与PVC的二次确认登录控制台之前我会再看一次PVC状态kubectl get pvc -A正常情况下Kubesphere的监控和日志组件会同时创建一批PVC。如果发现很多PVC卡在Pending说明默认StorageClass没有生效。回到2.4的NFS方案把StorageClass部署好并确保它被标记为默认存储类。已经Pending的PVC通常会在存储类可用后自动绑定但如果等待很久仍然无反应可以删掉对应Pod让控制器重建。4.2 控制台操作组件管理、企业空间与项目创建首次用admin账号登录后页面会引导你修改密码。然后我习惯按这个顺序做初始化先进入“平台管理”里的“组件管理”Kubesphere把可插拔组件都放在这里包括DevOps、可观测性、事件、审计、网络策略等。学习阶段我建议只开启可观测性暂不开DevOps因为Jenkins组件对内存和构建缓存的要求比较高开启后会让worker节点负载明显上升。然后创建企业空间名字随意比如demo-ws。企业空间是一个逻辑租户边界里面可以再划分多个项目每个项目对应Kubernetes里的Namespace。创建好企业空间后在里面建一个项目比如demo-proj然后添加一个测试用户给用户分配企业空间和项目的相应角色。通过这一套操作你基本就能理解Kubesphere里的多租户模型了企业空间管资源配额和成员项目管具体应用和负载。4.3 日常使用的安全基线集群版装完不是终点维护才是。我建议至少做这几件事立即修改admin密码尤其当你的控制台端口暴露在办公网时。定期备份etcd和Kubesphere配置哪怕是测试环境也可以写一个简单的cron任务。了解NodePort的暴露范围不要为了省事把Service直接用NodePort暴露到外网。如果团队多人登录先分配好企业空间和项目角色不要共享admin账号。5. 常见问题与排查技巧实录5.1 镜像拉取失败或卡在Downloading这是安装时出现频率最高的问题。最常见报错是Failed to pull image ... context deadline exceeded。原因只有一个安装器在拉取镜像时网络超时。解决办法分两步。第一步确保containerd或Docker的镜像加速配置正确并且重启了容器运行时。第二步耐心等待安装器重试因为KubeKey对部分镜像有重试机制。如果同一镜像反复失败可以手动拉取一次观察具体错误crictl pull image-name另外提醒一下不要因为一台节点镜像拉得慢就在其他节点手动拉一堆镜像那样反而容易造成版本不一致。5.2 节点长时间NotReady节点NotReady先别急着查CNI先确认kubelet和容器运行时的状态journalctl -u kubelet -f crictl info kubectl describe node node-name常见的两个原因一个是containerd的SystemdCgroup没有改成true另一个是节点磁盘空间不足。后者我遇到过几次因为镜像和容器日志把/var/lib/containerd目录占满了kubelet健康检查失败节点自动标记为NotReady。5.3 控制台打不开30880端口不通时装好集群版浏览器访问http://master节点IP:30880却打不开。先看Service是否正常kubectl get svc -n kubesphere-system重点看ks-console对应的Service类型和NodePort。如果是NodePort确认节点防火墙和安全组放行了30000-32767端口段。然后确认ks-console的Pod是否Runningkubectl logs -n kubesphere-system deploy/ks-console如果Pod一直CrashLoopBackOff通常要往上翻日志看具体报错常见原因包括依赖的Redis或MySQL没起来、配置中心读取不到数据等。5.4 PVC Pending导致组件CrashLoopBackOff集群跑了一段时间发现监控组件的Pod反复重启情况通常是kubectl get pods -A | grep CrashLoopBackOff kubectl get pvc -A | grep Pending你只要跟着PVC走就能定位到问题。执行kubectl describe pvc pvc名称 -n 命名空间如果看到类似waiting for a volume to be created, either by external provisioner的信息说明集群没有可用的StorageClass或者provisioner没有正常工作。解决思路就是先确保NFS服务端可用、NFS相关端口放行然后重新部署StorageClass并标记为默认。5.5 升级与重装的正确姿势Kubesphere和Kubernetes升级时不要手动改镜像tag最稳妥的方式是用KubeKey升级./kk upgrade --with-kubernetes v1.26.5 --with-kubesphere v3.4.0重装的话用delete命令清理整个集群./kk delete cluster -f config-sample.yaml这条命令会把K8s集群和Kubesphere组件都清掉所以操作前一定要想清楚数据备份的问题。6. 最后的一点经验在一次实际部署中我把三台Linux虚拟机规划成单控制面加双worker提前配好containerd的SystemdCgroup和镜像加速又准备好了NFS默认StorageClass最后跑KubeKey基本一把过。说实话最浪费时间的环节反而是装完之后梳理组件依赖关系。这里分享一个我个人觉得很有用的习惯在任何节点上执行集群操作前先统一hostname和/etc/hosts再确认所有节点能通过SSH免密访问最后看一遍默认StorageClass是否存在。这三个条件满足KubeKey的安装成功率会高很多。Kubesphere集群版后续的玩法也很多组件管理里的DevOps、告警、审计策略都可以按需打开但我不建议一次性全开先把核心模块跑稳定再一层层加。在生产环境正式部署之前先用相同配置文件在测试环境完整跑一遍这个习惯能帮你省下大量救火时间。