企业官网建设流程全解析

在你的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，因为KubeKey底层会调用kubeadm完成K8s初始化，同时把etcd、控制面、网络插件、Kubesphere安装Job都编排好。你只需要在config文件里声明节点角色和版本，剩下的交给安装器跑。它不是黑盒，日志打印得也算清晰，出现问题后可以顺着日志找到是哪一步卡住。

1.3 资源规划与版本选择，提前算清楚

安装前最重要的事情是确认资源，不要只盯着“官网最低要求”看。Kubesphere集群版装上之后，可观测性相关的组件会常驻内存，Prometheus那套监控栈通常要占到2核4G以上的资源，如果还开启DevOps，Jenkins的Pod又会再吃掉一部分内存。所以我的建议是：

版本方面，不要盲目追最新。优先选择官方兼容矩阵里标明稳定的K8s版本和Kubesphere版本组合，比如我用的组合就是经过验证的稳定版本。用太新的K8s版本有时候反而会因为CRD变更、API移除导致安装器里的组件起不来。

网络规划也要提前做。节点之间需要互访的端口很多，包括SSH的22、K8s API Server的6443、etcd的2379/2380、kubelet的10250，以及NodePort范围的30000-32767，Kubesphere控制台的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/hosts：

192.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开始，容器运行时默认就是containerd，Kubesphere本身也不要求你必须装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>"]

改完以后重启containerd：

systemctl 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.server=192.168.1.10 \ --set nfs.path=/data/nfs \ --set storageClass.name=nfs-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 | VERSION=v3.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，说明安装器正在拉镜像。这个阶段通常最耗时，取决于网络和镜像大小。

我踩过的坑是：有些人看到进度条久久不动就忍不住Ctrl+C，结果半途中断，再重跑就要处理一堆残留的etcd和证书。如果你也遇到这种情况，先检查网络、磁盘和镜像拉取日志，不要盲目中断。确实需要重来的时候，可以用以下命令清理集群：

./kk delete cluster -f config-sample.yaml

安装成功完成后，终端会输出这样的信息，包括控制台访问地址和初始账号：

Console: http://192.168.1.10:30880 Account: admin Password: P@ssw0rd

看到这行字，说明集群版已经装起来了。接下来要做的不是急着登录，而是先检查集群和核心组件状态。

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是否Running：

kubectl 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、告警、审计策略都可以按需打开，但我不建议一次性全开，先把核心模块跑稳定，再一层层加。在生产环境正式部署之前，先用相同配置文件在测试环境完整跑一遍，这个习惯能帮你省下大量救火时间。