Ubuntu 24.04 安装 KubeSphere 4.1 指南

目标：在一台 Ubuntu 24.04 服务器上从零完成 KubeSphere 4.1.3 平台的安装、验证与首登加固，覆盖 KubeKey（kk）在线一键装 Kubernetes + Helm Chart 装 KubeSphere 核心、配置文件逐项解读、安装结果全套验证、以及五类真实踩坑的排障沉淀。本文所有命令与回显均在真实环境实测通过（Ubuntu 24.04.5 LTS，内核 6.8.0-138-generic，单节点 all-in-one），逐行照抄。

一、环境信息

操作系统：Ubuntu 24.04.5 LTS（x86_64，内核 6.8.0-138-generic）
服务器：1 台单机 all-in-one，主机名 node1，IP 10.89.59.2，内存 32GB（实测 free -h 报告 31Gi）
KubeSphere：v4.1.3（Helm Chart ks-core-1.1.5）
KubeKey：v4.0.8（2026-10-23 构建，go1.26.9）
Kubernetes：v1.37.0（KubeKey 默认版本）
etcd：v3.7.0（kubeadm 静态 Pod 方式）
CRI：containerd 2.3.3（systemd 托管）
CNI：Calico v3.32.2（tigera-operator v3.32.2 部署）
Helm：v3.18.5（KubeKey 自动安装）
存储类：openebs-hostpath（localpv-provisioner 4.4.0）
控制台端口：30880（NodePort）
KubeKey 工作目录：/root/kubekey

二、前置条件

KubeSphere v4 的组件以 Kubernetes 集群为运行底座，安装分为「装 Kubernetes 集群」与「装 KubeSphere 核心（ks-core）」两步。动手前逐项确认：

操作系统：Ubuntu 20.04/22.04/24.04、CentOS/Rocky 8/9 等 KubeKey 支持的发行版；本文以 Ubuntu 24.04 实测。
资源要求：KubeKey 安装前自检（precheck）会强制校验 master 节点内存不足则直接终止。全组件运行实测内存压力如下（组件齐全后）：

free -h

实测回显：

               total        used        free      shared  buff/cache   available
Mem:            31Gi        28Gi       383Mi       840Mi       3.5Gi       2.5Gi

⚠️ 注意：31GB 内存装完全套后仅剩 2.5GB 可用。KubeSphere 官方建议最小 8GB、推荐 16GB 以上；若开启可观测/DevOps 等扩展组件，内存需求还会增加。2C4G 的规格只能跑起最小核心，实测不建议低于 8GB。

网络：安装节点需能访问外网下载二进制与镜像；国内环境建议按第四章配置国内镜像源（hub.kubesphere.com.cn）。
端口：控制台默认 NodePort 30880，确保未被占用且防火墙放行；集群内部端口由 KubeKey 统一管理。
swap：内核开启 swap 时 kubeadm preflight 会给出 [WARNING Swap]（cgroup v2 下支持 swap 但 kubelet 需正确配置），实测 Ubuntu 24.04 默认不启用 swap，无需处理。
root 权限：KubeKey 以 root 运行，部署过程会安装 containerd、kubelet 等 systemd 服务。

三、版本选型说明

KubeSphere v4 的版本线与 v3 不同：平台本体以 Helm Chart ks-core 分发，Chart 版本与应用版本独立。实测组合与组件版本对照如下（均为本次环境真实安装并验证的版本）：

组件	版本	说明
KubeSphere	v4.1.3	平台应用版本（`helm list` APP VERSION 列实测）
ks-core Chart	1.1.5	KubeSphere 核心 Helm Chart
KubeKey	v4.0.8	部署工具，2026-10-23 构建
Kubernetes	v1.37.0	KubeKey v4.0.8 默认 K8s 版本
etcd	v3.7.0	kubeadm 静态 Pod
containerd	2.3.3	CRI，systemd 服务
Calico	v3.32.2	CNI，tigera-operator 部署
Helm	v3.18.5	KubeKey 自动安装
localpv-provisioner	4.4.0	本地路径存储类
操作系统	Ubuntu 24.04.5 LTS	宿主系统

💡 技术拓展：Kubernetes 的安装方式不止 KubeKey 一种，常见方案对比——

方案原理/特点适用场景
KubeKey（kk）一条命令装齐 CRI+K8s+CNI+Helm，自动生成配置快速建生产/测试集群，KubeSphere 官方推荐
kubeadm 原生引导工具，步骤手工可控已有 kubeadm 运维体系
RKE2/K3s 发行版封装，内置组件与安全默认值边缘/轻量场景
托管集群（EKS 等）云厂商托管控制面不想自维护控制面

本文采用 KubeKey all-in-one：它是 KubeSphere 官方部署通道，能自动处理 containerd/kubelet/Helm/Calico 的版本匹配与 systemd 托管，也是唯一能一条命令拿到「可用集群」的方式。

方案	原理/特点	适用场景
KubeKey（kk）	一条命令装齐 CRI+K8s+CNI+Helm，自动生成配置	快速建生产/测试集群，KubeSphere 官方推荐
kubeadm	原生引导工具，步骤手工可控	已有 kubeadm 运维体系
RKE2/K3s	发行版封装，内置组件与安全默认值	边缘/轻量场景
托管集群（EKS 等）	云厂商托管控制面	不想自维护控制面

版本确认命令与实测回显（安装完成后）：

kk version

{"major":"4","minor":"0","gitVersion":"v4.0.8","gitCommit":"f6b1019891844091ddb14580a8d3aeb3251c02fe","gitTreeState":"clean","buildDate":"2026-10-23T06:15:34Z","goVersion":"go1.26.9","compiler":"gc","platform":"linux/amd64"}

helm list -A

NAME                    NAMESPACE               REVISION        UPDATED                                 STATUS          CHART                           APP VERSION
ks-core                 kubesphere-system       1               2026-10-24 10:40:33.287473025 +0800 CST deployed        ks-core-1.1.5                   v4.1.3
localpv-provisioner     kube-system             1               2026-10-24 10:32:30.974052211 +0800 CST deployed        localpv-provisioner-4.4.0       4.4.0
tigera-operator         tigera-operator         1               2026-10-24 09:35:41.08207338 +0800 CST  deployed        tigera-operator-v3.32.2         v3.32.2

四、在线安装方案 A：KubeKey 一键 all-in-one（推荐）

4.1 方案说明

本方案是 KubeSphere 官方主线：先下载 KubeKey（kk），由 kk 生成配置文件，一条命令装齐单机 Kubernetes 集群（含 containerd、etcd、Calico、Helm、本地存储），再通过官方 Helm Chart 安装 KubeSphere 核心组件。全部步骤在目标服务器上以 root 执行。

4.2 下载 KubeKey（kk）

用官方脚本下载指定版本的 kk。执行：

curl -sfL https://get-kk.kubesphere.io | VERSION=v4.0.8 sh -

实测回显：

Downloading kubekey web_installer v1.0.6 from https://kubekey.pek3b.qingstor.com/github.com/kubesphere/web-installer/releases/download/v1.0.6/web-installer.tgz ...

Kubekey v4.0.8 Download Complete!

下载脚本会把 kk 放到当前目录并赋予执行权限。确认版本：

chmod +x kk
sudo mv kk /usr/local/bin/kk
kk version

实测回显（同第三章）：

{"major":"4","minor":"0","gitVersion":"v4.0.8","gitCommit":"f6b1019891844091ddb14580a8d3aeb3251c02fe","gitTreeState":"clean","buildDate":"2026-10-23T06:15:34Z","goVersion":"go1.26.9","compiler":"gc","platform":"linux/amd64"}

💡 说明：kk v4 下载时会附带 web_installer（Web 安装向导组件），这是 v4 新架构的一部分；命令行方式不受影响。若下载慢，可为 curl 指定代理：curl -x http://<proxy>:<port> -sfL https://get-kk.kubesphere.io | VERSION=v4.0.8 sh -。

4.3 生成集群配置文件

kk v4 采用「配置文件 + 主机清单」双文件模型。生成默认配置：

kk create config

会在当前目录生成 config.yaml（集群级配置）与 inventory.yaml（主机清单，all-in-one 模式默认只含本机）。查看生成的 config.yaml 关键内容：

cat config.yaml | head -30

实测回显（节选）：

apiVersion: kubekey.kubesphere.io/v1
kind: Config
spec:
  # If set to "cn", online downloads will prioritize domestic sources when available.
  zone: cn
  kubernetes:
    # Specify the Kubernetes version to be installed.
    kube_version: v1.37.0
    # Specify the Helm version to be installed.
    helm_version: v3.18.5
    # Tag for the sandbox (pause) image used by pods.
    sandbox_image:
      tag: "3.10.2"
    control_plane_endpoint:
      # Supported HA types: local, kube-vip, haproxy.
      # If set to local, configure local hostname resolution as follows:
      #   - Control-plane nodes: 127.0.0.1
      #   - Worker nodes: <the control-plane endpoint host>
      type: local
      # Kube-vip image tag used for static pod deployment (when type is kube-vip).
      kube_vip:
        image:
          tag: v0.7.2
      # HAProxy image tag used for multi control-plane deployment (when type is haproxy).
      haproxy:
        image:
          tag: 2.9.6-alpine
  etcd:
    # Specify the etcd version to be installed.
    etcd_version: v3.7.0

关键项逐条说明：

配置键	默认值	含义与改动影响
`spec.zone`	`cn`	国内源优先下载二进制/镜像；海外服务器改为 `default`
`spec.kubernetes.kube_version`	`v1.37.0`	要安装的 K8s 版本，须为 kk 支持列表内的版本
`spec.kubernetes.helm_version`	`v3.18.5`	随集群安装的 Helm 版本
`spec.kubernetes.sandbox_image.tag`	`3.10.2`	Pod sandbox（pause）镜像 tag
`spec.kubernetes.control_plane_endpoint.type`	`local`	控制面端点类型：`local`（单 master）/`kube-vip`/`haproxy`（多 master 高可用）
`spec.etcd.etcd_version`	`v3.7.0`	etcd 版本（K8s 1.37 默认对应 3.7.0）

💡 技术拓展：控制面高可用（control_plane_endpoint）三种实现对比——

类型原理适用场景
local API Server 绑定本机，无 VIP 单 master（本文 all-in-one 采用）
kube-vip 静态 Pod 提供 VIP 漂移，无需额外设备云上/无负载均衡器的自建多 master
haproxy 每节点静态 Pod 跑 HAProxy 反代各 master 已有 F5/云 LB 之外的自建方案

本文为单机 all-in-one，采用默认 local。

类型	原理	适用场景
local	API Server 绑定本机，无 VIP	单 master（本文 all-in-one 采用）
kube-vip	静态 Pod 提供 VIP 漂移，无需额外设备	云上/无负载均衡器的自建多 master
haproxy	每节点静态 Pod 跑 HAProxy 反代各 master	已有 F5/云 LB 之外的自建方案

4.4 安装 Kubernetes 集群

执行一键安装（all-in-one 即不带 -i 主机清单，默认安装到本机）：

kk create cluster --with-kubernetes v1.37.0 -c config.yaml

安装过程按 playbook 阶段推进，实测阶段日志节选（每行前缀为时间与任务名）：

09:28:31 CST [Playbook default/create-cluster-tvpj8] start
09:28:31 CST gather_facts
09:28:31 CST [roles/native/root] OS | Add sudo secure path
09:28:31 CST [roles/defaults] Defaults | Load version-specific settings for Kubernetes
09:28:31 CST [roles/defaults] Defaults | Get kubelet.service LoadState
09:28:32 CST [roles/defaults] Defaults | Get installed containerd version
09:28:32 CST [roles/precheck/inventory] Inventory | Kubernetes groups must not be empty
09:28:32 CST [roles/precheck/cri] CRI | Fail if container manager is not docker or containerd
09:28:32 CST [roles/precheck/cni] CNI | Validate calico version is allowed for the selected Kubernetes version
09:28:32 CST [roles/precheck/storageclass] StorageClass | Fail if localpv provisioner version is unsupported
09:28:32 CST [roles/precheck/os] OS | Validate inventory hostname is RFC-compliant
09:28:32 CST [roles/precheck/os] OS | Fail if operating system is not supported
09:28:32 CST [roles/precheck/os] OS | Fail if master node memory is insufficient

（以上为输出节选，完整输出含数百行任务进度，最终以 STATS 统计收尾：success: 255 / ignored: 9。）

安装成功的标志是日志尾部出现集群就绪信息。随后确认 kubelet/containerd 服务已由 systemd 接管：

systemctl is-active kubelet containerd

实测回显：

active
active

确认节点就绪：

kubectl get nodes -o wide

实测回显：

NAME    STATUS   ROLES                  AGE    VERSION   INTERNAL-IP   EXTERNAL-IP   OS-IMAGE             KERNEL-VERSION              CONTAINER-RUNTIME
node1   Ready    control-plane,worker   167m   v1.37.0   10.89.59.2    <none>        Ubuntu 24.04.5 LTS   6.8.0-138-generic (amd64)   containerd://2.3.3

⚠️ 注意：此时只是 Kubernetes 集群，KubeSphere 还未安装——kk v4.0.8 的 kk create cluster 不再提供 --with-kubesphere 参数（与 v3 的 kk 不同），KubeSphere 核心必须用 Helm Chart 单独安装，这正是下一步。

4.5 安装 KubeSphere 核心（ks-core Helm Chart）

用官方 Chart 一条命令安装 KubeSphere v4.1.3 核心，并指定国内镜像源：

helm upgrade --install -n kubesphere-system --create-namespace ks-core \
  https://charts.kubesphere.io/main/ks-core-1.1.5.tgz \
  --set global.imageRegistry=hub.kubesphere.com.cn \
  --set extension.imageRegistry=hub.kubesphere.com.cn \
  --wait

安装完成时输出 NOTES（实测照抄），包含访问地址与默认账号提示：

NOTES:
Thank you for choosing KubeSphere Helm Chart.

Please be patient and wait for several seconds for the KubeSphere deployment to complete.

1. Wait for Deployment Completion

    Confirm that all KubeSphere components are running by executing the following command:

    kubectl get pods -n kubesphere-system
2. Access the KubeSphere Console

    Once the deployment is complete, you can access the KubeSphere console using the following URL:

    http://10.89.59.2:30880

3. Login to KubeSphere Console

    Use the following credentials to log in:

    Account: admin
    Password: P@88w0rd

NOTE: It is highly recommended to change the default password immediately after the first login.
For additional information and details, please visit https://kubesphere.io.

💡 说明：--set 的两个镜像源键与最终生效值可随时复核（helm get values ks-core -n kubesphere-system），实测 USER-SUPPLIED VALUES 就是这两项：
extension:
  imageRegistry: hub.kubesphere.com.cn
global:
  imageRegistry: hub.kubesphere.com.cn
其余全部来自 Chart 默认值（如 ks-apiserver 资源限额 cpu 1 / memory 1024Mi、审计级别 Metadata 等），完整参数详解见本专栏 C1 配置篇（文末参考链接）。

4.6 安装结果验证

等待核心组件全部 Running 后逐层验证。

第一步，KubeSphere 核心组件状态：

kubectl get pods -n kubesphere-system

实测回显（组件齐备状态，仅保留当前在跑实例行）：

NAME                                    READY   STATUS    RESTARTS   AGE
extensions-museum-5f8b86d675-k7vpt      1/1     Running   0          20m
ks-apiserver-695ddf767d-xgptl           1/1     Running   0          14m
ks-console-75699cfc9b-c4b2x             1/1     Running   0          14m
ks-controller-manager-6c9f8bcf8-c29pt   1/1     Running   0          20m

第二步，服务与端口：

kubectl -n kubesphere-system get svc

实测回显：

NAME                    TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
extensions-museum       ClusterIP   10.233.48.84    <none>        443/TCP        89m
ks-apiserver            ClusterIP   10.233.10.47    <none>        80/TCP         89m
ks-console              NodePort    10.233.32.133   <none>        80:30880/TCP   89m
ks-controller-manager   ClusterIP   10.233.36.133   <none>        443/TCP        89m

ks-console 以 NodePort 30880 对外暴露。第三步，HTTP 探活：

curl -I http://10.89.59.2:30880/

实测回显：

HTTP/1.1 302 Found
Vary: Accept-Encoding
Location: /login
Content-Type: text/html; charset=utf-utf-8
Content-Length: 43
Connection: keep-alive
Keep-Alive: timeout=5

curl -s -o /dev/null -w '%{http_code}\n' http://10.89.59.2:30880/login

实测回显：

302 跳转到 /login 且登录页返回 200，说明控制台 Web 服务就绪。

第四步，存储类已就位（后续扩展组件持久化依赖它）：

kubectl get storageclass

实测回显：

NAME               PROVISIONER        RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
openebs-hostpath   openebs.io/local   Delete          WaitForFirstConsumer   false                  29m

4.7 首次登录与修改默认密码

浏览器访问 http://10.89.59.2:30880，用默认账号 admin / P@88w0rd 登录，控制台会强制要求修改初始密码。

KubeSphere 对新密码有复杂度校验（必须同时包含大写字母、小写字母和数字）。该策略在 API 层直接拒绝不合规密码，实测用 q1w2e3r4 会收到如下报错（输出节选）：

{
 "kind": "Status",
 "status": "Failure",
 "message": "User.iam.kubesphere.io \"admin\" is invalid: spec.password: Invalid value: \"q1w2e3r4\": spec.password in body should match '^(.*[a-z].*[A-Z].*[0-9].*)$|^(.*[a-z].*[0-9].*[A-Z].*)$|^(.*[A-Z].*[a-z].*[0...",
 "reason": "Invalid",
 "code": 422
}

本文改用满足策略的 Q1w2e3r4。改密后旧密码立即失效、新密码可正常登录，实测（通过平台 OAuth 令牌接口验证登录，该接口同样可用于 CI 自动化拿 Token）：

curl -s -X POST "http://10.89.59.2:30880/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "client_id=kubesphere" \
  --data-urlencode "client_secret=kubesphere" \
  --data-urlencode "username=admin" \
  --data-urlencode "password=Q1w2e3r4"

实测回显（Token 为 JWT，内容节选）：

{
 "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8va3MtY29uc29sZS5rdWJlc3BoZXJlLXN5c3RlbS5zdmM6MzA4ODAiLCJzdWIiOiJhZG1pbiIsImV4cCI6MTc5MjgyMjUwNywiaWF0IjoxNzkyODE1MzA3LCJ0b2t",
 "token_type": "Bearer",
 "refresh_token": "eyJhb"
}

拿到的 Bearer Token 可直接调平台 API 验证身份（如 curl -H "Authorization: Bearer <token>" http://10.89.59.2:30880/kapis/...）。旧密码 P@88w0rd 登录实测返回：

{
 "error": "invalid_grant",
 "error_description": "Invalid username or password."
}

⚠️ 注意：KubeSphere 的登录 OAuth 客户端固定为 client_id=kubesphere / client_secret=kubesphere（平台内置，随 ks-core Chart 部署）。grant_type=password 模式便于命令行与自动化场景获取令牌，但生产环境应避免在命令行明文传递密码，改用 OIDC 对接或控制台交互登录。

五、安装方案 B：已有 Kubernetes 集群直接安装 ks-core

5.1 方案说明

如果目标环境已有现成的 Kubernetes 集群（v1.22+ 均可，版本兼容矩阵见官方文档），可跳过第四章的 kk 装集群步骤，直接用 Helm 安装 ks-core。该方案不动集群本身，只新增 kubesphere-system 命名空间及核心组件。

5.2 安装步骤

确认 Helm 可用后执行（与 4.5 完全一致）：

helm upgrade --install -n kubesphere-system --create-namespace ks-core \
  https://charts.kubesphere.io/main/ks-core-1.1.5.tgz \
  --set global.imageRegistry=hub.kubesphere.com.cn \
  --set extension.imageRegistry=hub.kubesphere.com.cn \
  --wait

若集群缺少默认 StorageClass（KubeSphere 扩展组件的持久化依赖），先安装本地存储类（与 kk 方案内置的组件一致）：

helm upgrade --install -n kube-system --create-namespace localpv-provisioner \
  https://charts.kubesphere.io/main/localpv-provisioner-4.4.0.tgz

安装完成后确认存储类生效：

kubectl get storageclass

预期出现 openebs-hostpath（回显同 4.6 第四步）。

5.3 验证

验证方法与 4.6 完全一致：kubectl get pods -n kubesphere-system 四个核心组件 Running、curl -I http://<任意节点IP>:30880/ 返回 302 跳转 /login。

六、方案对比与选择建议

维度	方案 A：KubeKey all-in-one	方案 B：已有集群装 ks-core
前置条件	一台空白 Ubuntu 服务器	现成 Kubernetes 集群 + Helm
安装内容	CRI+K8s+CNI+Helm+存储+KubeSphere	仅 KubeSphere 核心（+可选存储）
是否动集群	新建	不动
版本匹配	kk 保证组件兼容矩阵	需自行核对 K8s 版本兼容
适用场景	从零起步、测试/PoC/单机生产	已有集群统一纳管

选择建议：全新环境直接用方案 A（一条链路把组件版本匹配全交给 kk）；已有生产集群务必用方案 B，避免在存量集群上重装 CRI/CNI。两方案的 KubeSphere 本体安装命令完全相同。

七、配置说明

7.1 KubeKey 配置文件（config.yaml）

第四章 4.3 已给出核心键。日常可能调整的还有：

多节点：编辑 inventory.yaml 增加 control-plane/worker 主机组，再执行同一句 kk create cluster -i inventory.yaml -c config.yaml；多 master 时把 control_plane_endpoint.type 改为 kube-vip 或 haproxy。
镜像仓库：spec.image_registry.type 支持 harbor/docker-registry，离线环境配私有仓库（详见 kk help）。
改完配置重跑命令即幂等生效（kk 会跳过已完成的任务阶段）。

7.2 ks-core Helm values

常用键速查（完整表见 C1 配置篇）：

values 键	默认值	说明
`global.imageRegistry`	空	全局镜像源前缀，国内环境设 `hub.kubesphere.com.cn`
`extension.imageRegistry`	空	扩展组件镜像源前缀
`authentication.adminPassword`	空	安装时直接注入 admin 初始密码（不设则用默认 P@88w0rd）
`auditing.enable`	false	开启审计日志
`apiserver.resources`	limits cpu 1 / mem 1024Mi	ks-apiserver 资源限额

修改已安装集群的 values 用同一句 helm upgrade --install（幂等），Chart 内渲染的 ConfigMap 会随之更新。

八、常见问题（排障实录）

以下五个问题全部来自本次安装的真实报错与定位过程，按发生顺序沉淀。

8.1 重跑安装报「kubelet service must be running and active」

现象：首次安装中途失败后直接重跑 kk create cluster，报错：

kubelet service must be running and active when it is loaded.
task [Kubernetes | Ensure kubelet service is active](default/create-cluster-tvqht-wjnrl) run failed:

定位：上一次失败在节点上留下了已加载但未启动成功的 kubelet systemd 服务，重跑时 precheck 校验「已加载的服务必须 active」直接终止。

解决：先清理残留再重装。轻则 systemctl restart kubelet 后重跑；重则用 kk delete cluster -f config.yaml 清空集群后全新安装（见第九章）。

8.2 kubeadm preflight 报内核配置模块缺失

现象：安装日志中出现 kubeadm preflight 报错（输出节选）：

[preflight] Some fatal errors occurred:
        [ERROR SystemVerification]: failed to parse kernel config: unable to load kernel module: "configs", output: "modprobe: FATAL: Module configs not found in directory /lib/modules/6.8.0-138-generic\n", err: exit status 1

伴随警告（可忽略级）：

    [WARNING Swap]: swap is supported for cgroup v2 only. ...
0.987037    3143 utils.go:69] The recommended value for "clusterDNS" in "KubeletConfiguration" is: [10.233.0.10]; the provided value is: [169.254.25.10]

定位：/lib/modules/ 下缺少当前内核的 configs 模块（部分虚拟化/最小化内核环境未安装 linux-modules 包），kubeadm 无法读取内核配置做 SystemVerification。

解决：安装对应内核模块包并重跑：apt-get install -y linux-modules-$(uname -r)（Ubuntu）。clusterDNS 警告是 kubeadm 默认值与 KubeKey 期望值的差异提示，KubeKey 会在后续任务里统一为 10.233.0.10，可忽略。

8.3 Calico CRD 应用阶段失败：dial tcp [::1]:8080 connection refused

现象：集群主体装完后，在「Apply Calico CRDs」任务处整批失败（输出节选，同一报错对每个 CRD 文件重复）：

task [Calico | Apply Calico CRDs from the CRD chart (v3.32+ no longer bundles CRDs)](default/create-cluster-tvpj8-k4lnq) run failed:
stderr: error validating "/etc/kubernetes/cni/calico-crds-v3.32.2/crd.projectcalico.org.v1/templates/operator.tigera.io_apiservers.yaml": error validating data: failed to download openapi: Get "http://localhost:8080/openapi/v2?timeout=32s": dial tcp [::1]:8080: connect: connection refused; if you choose to ignore these errors, turn validation off with --validate=false
error: exit status 1

定位：报错特征是 kubelet/kubectl 在尝试连 localhost:8080——这是 kubectl 在没有可用 kubeconfig 时的默认 API Server 地址。说明执行校验的会话缺少 KUBECONFIG 环境变量（如通过非登录 shell / 定时任务 / 断线重连的终端重跑安装时，~/.kube/config 尚未生成或未加载），kubectl 校验 CRD 时拿不到集群连接。

解决：确保以 root 登录 shell 重跑（kk 安装成功后会自动生成 /root/.kube/config）；若在已生成配置后仍报错，显式导出：export KUBECONFIG=/root/.kube/config 后重跑安装命令即可从失败任务处幂等续装。Calico v3.32+ 将 CRD 从主 Chart 拆到 CRD Chart，这一步需要能访问 API Server 下载 OpenAPI 校验，属新版本链路中的敏感环节。

8.4 密码复杂度校验拒绝弱口令

现象：首次登录修改默认密码时，形如 q1w2e3r4（纯小写+数字）的密码被平台拒绝，报错见 4.7 实测节选（spec.password ... should match '^(.*[a-z].*[A-Z].*[0-9].*)$|...'）。

定位：KubeSphere 用户密码策略要求同时含大写字母、小写字母与数字，长度不足亦会被拒。

解决：使用满足三类字符组合的口令（本文用 Q1w2e3r4）。若需放宽/收紧策略，可在平台「平台设置 → 安全设置」中调整密码策略后重试。

8.5 内存吃紧导致组件反复重启

现象：装完全套后 free -h 显示 31Gi 内存仅剩 2.5Gi available（回显见第二章），期间部分核心组件出现 ContainerStatusUnknown/Error 后自动恢复的历史 Pod 记录（kubectl get pods -A 可见多轮重启痕迹）。

定位：单机跑 K8s 控制面 + Calico + KubeSphere 全家桶，内存逼近上限，节点压力触发组件驱逐/重启。

解决：单机实测环境建议至少 16GB、组件全开建议 32GB 起步；生产环境将 control-plane 与业务负载分离，并为 ks-apiserver/ks-controller-manager 保留资源限额余量（默认 limits memory 1024Mi，可用 helm upgrade --set apiserver.resources... 调整）。

九、卸载与清理

kk 提供对称的卸载命令（帮助实测）：

kk delete --help

Delete node or cluster

Usage:
  kk delete [command]

Available Commands:
  cluster     Delete a cluster
  nodes       Delete a cluster nodes
  registry    Delete a image registry which create by kubekey.

Flags:
  -h, --help   help for delete

Global Flags:
      --add-dir-header                      If true, adds the file directory to the header of the log messages
      ...（全局日志参数同 kk create，此处略）

按需清理：

# 仅卸载 KubeSphere 平台（保留 K8s 集群）
helm uninstall ks-core -n kubesphere-system

# 整集群卸载（含 K8s、containerd、CNI，回滚到安装前系统状态）
kk delete cluster -f config.yaml

⚠️ 注意：kk delete cluster 会删除节点上全部 Kubernetes 数据，不可恢复；仅卸载 KubeSphere 时用 helm uninstall。若 kk delete 中途失败，检查 kubelet/containerd 服务状态后重跑（幂等清理）。

十、参考链接

KubeSphere 官方文档（安装）：https://kubesphere.io/docs/
KubeSphere 4.1 Release（ks-core Chart 对应关系）：https://github.com/kubesphere/kubekey/releases
KubeKey 官方仓库：https://github.com/kubesphere/kubekey
ks-core Helm Chart 仓库：https://charts.kubesphere.io/main/ks-core-1.1.5.tgz
本专栏前置认知篇：《KubeSphere 4.1 介绍与选型指南》
本专栏配置详解篇：《KubeSphere v4.1.3 配置参数详解》
本专栏命令详解篇：《KubeSphere 4.1 常用 CLI 命令与工具详解》