KubeSphere 常用运维指令手册

适用版本：KubeSphere v3.4.x（存量） / v4.1 ~ v4.3.x（当前），配套 KubeKey 3.x 底座：Kubernetes 1.26 ~ 1.37（KubeSphere 版本与 K8s 版本有兼容矩阵，以官方发布说明为准） 宿主系统：Ubuntu 20.04/22.04/24.04、Debian 11/12、CentOS 7/8、RHEL 8/9、Rocky/Alma、openEuler、麒麟 V10、统信 UOS（信创适配） 约定：# root 或 sudo，$ 普通用户，<xxx> 为占位符；kk 指 KubeKey 二进制，kubectl 简写 k。 差异标注：> **版本差异** 主要用于 v3 → v4 的安装与配置方式变化，这是本手册最容易踩错的地方。 更新时间：2026-11（版本事实核对至 2026-11-05）

目录

1. 版本与架构演进
2. 部署前规划
3. KubeKey 部署 Kubernetes
4. v4：Helm 安装 KubeSphere Core
5. v3：ks-installer 安装方式
6. 离线部署与私有仓库
7. 命名空间、组件与运行机制
8. 扩展组件管理（LuBan）
9. 平台管理：四级 RBAC 与 License
10. 工作负载、网关与应用
11. 多集群管理
12. 可观测、日志与排障能力
13. 存储与网络
14. 日常运维操作
15. 升级与回滚
16. 备份与恢复
17. 卸载与残留清理
18. 故障速查
19. 安全基线与危险红线
20. 附录

1. 版本与架构演进

1.1 两个代际，两套安装方式

版本差异（最重要的一条）：v4 不再使用 ks-installer。搜到的教程里如果出现 kubectl apply -f kubesphere-installer.yaml 或 kubectl logs -n kubesphere-system installer，那是 v3 的。v4 照抄会装出一个空集群，然后一直等一个永远不存在的 installer Pod。

1.2 版本线（2026-11）

这些功能是"平台层"的，底层仍是标准 Kubernetes。kubectl 能做的事，KubeSphere 只是给了 UI 与多租户封装；排障最终要回到 K8s 分册与 containerd 分册。

1.3 先确认接手的是哪一代

# 有 ks-installer / ClusterConfiguration → v3
kubectl get deploy -n kubesphere-system | grep -i installer
kubectl get clusterconfiguration -A 2>/dev/null

# 有 ks-core Helm release / Extension CRD → v4
helm list -A | grep -i ks-core
kubectl get crd | grep -i extensions.kubesphere.io
kubectl get deploy -n kubesphere-system

1.4 组件分层

┌────────────────────────────────────────────────────────┐
│ 扩展组件（v4，按需）：Whizard 可观测 / DevOps / 网关 /     │
│ 应用商店 / 日志 / 网络 / Copilot / 服务网格 …             │
├────────────────────────────────────────────────────────┤
│ KubeSphere Core：ks-apiserver / ks-controller-manager /   │
│ ks-console / 多租户 RBAC / 扩展市场（KSE Repository）      │
├────────────────────────────────────────────────────────┤
│ Kubernetes（kubeadm / KubeKey 部署）+ CRI + CNI + CSI     │
├────────────────────────────────────────────────────────┤
│ OS / 存储 / 网络（国产系统与信创环境在此层适配）           │
└────────────────────────────────────────────────────────┘

2. 部署前规划

2.1 兼容性检查（决定能不能装成）

kubectl get nodes -o wide
kubectl get sc
kubectl get pods -A | grep -v Running | grep -v Completed
helm version --short
crictl info | jq '.config.containerd.runtimes.runc.options.SystemdCgroup'

2.2 网络与端口

2.3 国内环境三件套

1. 镜像源：在线装用 --set global.imageRegistry=hub.kubesphere.com.cn；完全内网用 --set global.imageRegistry=<私有仓库>/<前缀> 并提前同步镜像。
2. 离线包：用 KubeKey 的 artifact 机制导出 OS 依赖包 + 镜像，或用官方文档给的离线资源包。
3. Chart 源：v4 的 ks-core 走 OCI（oci://hub.kubesphere.com.cn/kse/ks-core）或 tgz（https://charts.kubesphere.io/main/ks-core-*.tgz），内网要提前 helm pull 后传到跳板机。

3. KubeKey 部署 Kubernetes

KubeKey（kk）是青云开源的集群部署工具，v3/v4 都用它装 K8s，只是装完 KubeSphere 的方式不同。

3.1 安装 kk

# 在线（国内下载节点）
export KKZONE=cn
curl -sfL https://get-kk.kubesphere.io | sh -
chmod +x kk
./kk version

# 或离线：从 GitHub Release 下 kk 二进制后传进内网

KKZONE=cn 会把下载源切到国内节点，内网环境必须走离线包。

3.2 生成配置

export KKZONE=cn
./kk create config --with-kubernetes v1.30.6     # 版本换成实际需要的
# 生成 config-sample.yaml（v4 文档里也用 inventory.yaml + config.yaml 两个文件）

典型配置结构（v3 风格 config-sample.yaml）：

apiVersion: kubekey.kubesphere.io/v1alpha2
kind: Cluster
metadata:
  name: sample
spec:
  hosts:
  - {name: master1, address: 10.0.0.11, internalAddress: 10.0.0.11,
     user: root, password: "<ssh密码>"}
  - {name: node1,   address: 10.0.0.21, internalAddress: 10.0.0.21,
     user: root, privateKeyPath: "~/.ssh/id_rsa"}
  roleGroups:
    etcd: [master1]
    control-plane: [master1]
    worker: [node1]
  controlPlaneEndpoint:
    domain: lb.kubesphere.local
    address: "10.0.0.10"       # VIP / LB 地址
    port: 6443
  kubernetes:
    version: v1.30.6
    clusterName: cluster.local
    containerManager: containerd
  network:
    plugin: calico
    kubePodsCIDR: 10.233.64.0/18
    kubeServiceCIDR: 10.233.0.0/18
  registry:
    privateRegistry: ""        # 离线时填自建 Harbor 地址
    registryMirrors: []
    insecureRegistries: []
  addons: []

坑：controlPlaneEndpoint.domain 用 lb.kubesphere.local 时，KubeKey 会在节点上起一个轻量 LB（HAProxy 类）来做 VIP。多 master 集群如果已经有外部四层 LB，就填真实 VIP/LB 地址，别两套 LB 叠着用。

3.3 创建集群

export KKZONE=cn
./kk create cluster -f config-sample.yaml

# v4 官方文档的双文件写法
./kk create cluster -i inventory.yaml -c config.yaml

# 离线（使用 artifact 包）
./kk create cluster -f config-sample.yaml --with-packages

创建过程会做：环境预检 → 分发二进制与镜像 → 初始化 etcd / 控制面 → 装 CNI → join worker → 打标签。失败时看 kk 输出和 /root/.kubekey/ 日志。

3.4 集群增删节点与升级

./kk add nodes -f config-sample.yaml            # 在 hosts/roleGroups 里加好新节点再执行
./kk delete node <node-name> -f config-sample.yaml
./kk upgrade --with-kubernetes v1.31.x -f config-sample.yaml
./kk create cluster --with-kubesphere v3.4.1 -f config-sample.yaml   # ★ v3 专用

版本差异：--with-kubesphere 是 v3 的用法，KubeKey 会顺手把 ks-installer 装上。v4 不要用这个参数，先只装 K8s，再用 Helm 装 ks-core。

3.5 集群验证

kubectl get nodes -o wide
kubectl get pods -A
kubectl get cs 2>/dev/null          # 新版本已废弃，用下面这条
kubectl get --raw='/readyz?verbose'
kubectl get sc

4. v4：Helm 安装 KubeSphere Core

4.1 在线安装（官方文档基线）

chart=oci://hub.kubesphere.com.cn/kse/ks-core
version=1.2.4
helm upgrade --install -n kubesphere-system --create-namespace ks-core $chart \
  --debug --wait --version $version --reset-values --take-ownership \
  --set global.imageRegistry=hub.kubesphere.com.cn,extension.imageRegistry=hub.kubesphere.com.cn \
  --set kseExtensionRepository.image.tag=v11.2.0

要点逐条：

安装成功输出：

1. Wait for Deployment Completion
   kubectl get pods -n kubesphere-system
2. Access the KubeSphere Console
   http://<IP>:30880
3. Login
   Account: admin   Password: P@88w0rd

首次登录立刻改密码。

4.2 用 tgz / 内网 Chart

helm fetch https://charts.kubesphere.io/main/ks-core-1.1.3.tgz
# 或
helm pull oci://hub.kubesphere.com.cn/kse/ks-core --version 1.2.4

helm upgrade --install -n kubesphere-system --create-namespace ks-core ./ks-core-1.2.4.tgz \
  --debug --wait --reset-values --take-ownership \
  --set global.imageRegistry=<私有仓库>/ks,extension.imageRegistry=<私有仓库>/ks

4.3 安装后检查清单

helm list -A | grep ks-core
helm -n kubesphere-system get values ks-core
kubectl get pods -n kubesphere-system -o wide
kubectl get svc -n kubesphere-system | grep console
kubectl get crd | grep -i kubesphere
curl -I http://<任一节点IP>:30880
kubectl -n kubesphere-system logs deploy/ks-apiserver --tail=100

坑：--wait 只等 Deployment 就绪，不等于扩展市场可用。装完 Core 后扩展市场列表为空，多半是 extension.imageRegistry 没设或内网不通 hub.kubesphere.com.cn，去看 kse-extension-repository Pod 的日志。

4.4 常见 values 覆盖

# values-override.yaml
global:
  imageRegistry: registry.internal/ks
extension:
  imageRegistry: registry.internal/ks
console:
  replicas: 2
apiserver:
  replicas: 2

helm -n kubesphere-system upgrade ks-core ./ks-core-1.2.4.tgz -f values-override.yaml

改 values 前先 helm get values -a 看当前生效值。--reset-values 会把之前用 --set 传的参数全部丢掉，重复用它做升级是常见事故来源。

5. v3：ks-installer 安装方式

存量集群维护时仍要会这一套。

kubectl apply -f https://github.com/kubesphere/ks-installer/releases/download/v3.4.1/kubesphere-installer.yaml
kubectl apply -f https://github.com/kubesphere/ks-installer/releases/download/v3.4.1/cluster-configuration.yaml

# 看安装进度（安装可能 10~30 分钟）
kubectl logs -n kubesphere-system $(kubectl get pod -n kubesphere-system \
  -l app=ks-install -o jsonpath='{.items[0].metadata.name}') -f

cluster-configuration.yaml 里按需开启组件：

---
apiVersion: installer.kubesphere.io/v1alpha1
kind: ClusterConfiguration
metadata:
  name: ks-installer
  namespace: kubesphere-system
spec:
  persistence:
    storageClass: ""
  authentication:
    jwtSecret: ""
  etcd:
    monitoring: true
    endpointIps: localhost
    port: 2379
    tlsEnable: true
  common:
    redis: {enabled: false}
    openldap: {enabled: false}
    minioVolumeSize: 20Gi
    es: {enabled: false, basicAuth: {enabled: false}}
  console:
    enableMultiLogin: true
    port: 30880
    type: NodePort
  alerting: {enabled: false}
  auditing: {enabled: false}
  devops: {enabled: false}
  events: {enabled: false}
  logging: {enabled: false}
  metrics_server: {enabled: true}
  monitoring:
    storageClass: ""
    node_exporter: {port: 9100}
  multicluster:
    clusterRole: none        # host / member / none
  network:
    networkpolicy: {enabled: false}
    ippool: {type: none}
    topology: {type: none}
  openpitrix:
    store: {enabled: false}
  servicemesh: {enabled: false}
  kubeedge: {enabled: false}

改了配置让它重装：

kubectl apply -f cluster-configuration.yaml
# 或重启 installer
kubectl rollout restart deploy/ks-installer -n kubesphere-system

坑：v3 的功能开关（devops / logging / servicemesh / events）改一次会触发一次全量 reconcile，可能重启多个组件。生产上不要频繁切。v4 已经把这些拆成独立 Extension，这是架构升级最实际的价值。

6. 离线部署与私有仓库

6.1 四个要准备的东西

6.2 生成离线包（有外网的一侧）

export KKZONE=cn
./kk create manifest --with-kubernetes v1.30.6
# 编辑 manifest-sample.yaml，补 image 列表与私有仓库地址
./kk artifact export -m manifest-sample.yaml -o kubesphere-v412-v1306-artifact.tar.gz

实测这类 artifact 包常在 8~9 GB 量级，提前准备磁盘与传输通道。

6.3 内网侧部署

# 1) 把 artifact、kk、chart 传到部署/仓库节点
ls -lh /srv/kubekey/

# 2) 导入镜像到内网 Harbor（artifact 里含 registry 目录）
# 3) 生成配置并填私有仓库
./kk create config --with-kubernetes v1.30.6
vi config-sample.yaml

spec:
  registry:
    privateRegistry: "harbor.internal"
    registryMirrors: []
    insecureRegistries: ["harbor.internal"]   # 若用 http 或自签证书
    auths:
      "harbor.internal":
        username: admin
        password: "<密码>"

# 4) 装 K8s（离线）
./kk create cluster -f config-sample.yaml --with-packages

# 5) 装 KubeSphere Core（镜像前缀指向内网仓库）
helm upgrade --install -n kubesphere-system --create-namespace ks-core ./ks-core-1.2.4.tgz \
  --debug --wait --reset-values --take-ownership \
  --set global.imageRegistry=harbor.internal/ks,extension.imageRegistry=harbor.internal/ks

坑：privateRegistry 解决的是 K8s 组件镜像；global.imageRegistry / extension.imageRegistry 解决的是 KubeSphere 组件镜像。两组都配才算离线完整，漏一组就会在某些 Pod 上报 ImagePullBackOff。

6.4 证书与 containerd

内网 Harbor 用自签 HTTPS 时，所有节点都要信任 CA，并配置 containerd certs.d（详见 containerd 分册）：

cp ca.crt /usr/local/share/ca-certificates/harbor.crt && update-ca-certificates
mkdir -p /etc/containerd/certs.d/harbor.internal
cat > /etc/containerd/certs.d/harbor.internal/hosts.toml <<'EOF'
server = "https://harbor.internal"
[host."https://harbor.internal"]
  capabilities = ["pull", "resolve", "push"]
  skip_verify = true
EOF
systemctl restart containerd
crictl pull harbor.internal/ks/ks-apiserver:<tag>

6.5 License 与离线

v4.3.0 起：支持 License 增量导入、分开管理软件许可期限与维保服务期限、导出许可证环境信息，离线环境可配置私有镜像仓库凭证。商业版离线交付时这几项要提前发给厂商生成 License。

7. 命名空间、组件与运行机制

7.1 命名空间

kubectl get ns | grep -i kubesphere
kubectl get deploy,sts,ds -n kubesphere-system
kubectl get pods -A -o wide | grep -v Running

7.2 Core 三件套

kubectl -n kubesphere-system get deploy
kubectl -n kubesphere-system logs deploy/ks-apiserver --tail=200
kubectl -n kubesphere-system describe pod <pod>

关键判断：控制台打不开但 kubectl 一切正常 → 只是 ks-console / ks-apiserver 的问题，业务 Pod 没受影响。不要因此去重启 kubelet 或整个集群。

7.3 平台自定义资源

kubectl api-resources | grep -i kubesphere
kubectl get workspacetemplates,workspaces -A 2>/dev/null
kubectl get extension,extensionversion -A 2>/dev/null
kubectl get cluster -A 2>/dev/null        # 多集群 CR
kubectl get crd | grep -iE 'kubesphere|tenant|extension'

8. 扩展组件管理（LuBan）

v4 把功能拆成 Extension，通过扩展市场（KSE Repository）安装。

8.1 概念

kubectl get extensions.core.kubesphere.io -A 2>/dev/null
kubectl get extensionversions -A 2>/dev/null
kubectl get repositories -A 2>/dev/null
kubectl get pods -n kubesphere-system | grep -i repository

8.2 常用扩展

8.3 安装与升级（控制台为主，命令行兜底）

# 在扩展市场点安装后，实际是 helm install 到对应命名空间
helm list -A | grep -iE 'whizard|gateway|devops'
kubectl get pods -A | grep -iE 'whizard|gateway'

# 查看扩展安装任务的失败原因
kubectl -n kubesphere-system logs deploy/ks-controller-manager --tail=200 | grep -i extension
kubectl get events -A --sort-by=.lastTimestamp | tail -30

坑：v4.2.1 之前的 Helm 升级存在"应用升级状态异常、仓库持续重试、字段变更引发异常"等问题，v4.3.0 已集中修复。老版本升扩展卡住时别一直点重试，先看 helm list 里 release 的真实状态（failed 需要 helm rollback 或 helm uninstall 再装）。

8.4 自建扩展仓库（离线）

1. 在内网搭一个 ChartMuseum / Harbor OCI 仓库，同步官方扩展 chart 与镜像。
2. 在平台里添加 Repository，指向内网地址。
3. 每个 chart 的 values 里把 imageRegistry 改成内网前缀。
4. 装一个最小扩展验证链路，再批量装。

9. 平台管理：四级 RBAC 与 License

9.1 层级模型

平台（Platform）
 └─ 集群（Cluster，多集群场景）
     └─ 企业空间（Workspace）
         └─ 项目 / 命名空间（Namespace）
             └─ 资源（工作负载、服务、配置…）

内置角色：

# 平台角色本质是 ClusterRole / RoleBinding
kubectl get clusterroles | grep -i kubesphere
kubectl get rolebindings -A | grep -i kubesphere | head
kubectl get clusterrolebindings | grep -i kubesphere | head

KubeSphere 的权限最终落到 K8s RBAC，但中间有一层平台自定义 CR。只改 K8s RBAC 可能让控制台显示与实际权限不一致；授权一律走控制台或平台 API。

9.2 常用运维

# 查看某用户能做什么（用平台账号登录后调 API，或用 admin token）
kubectl auth can-i --list --as=system:serviceaccount:<ns>:<sa>

9.3 License（v4.3.0+）

• 控制台「平台管理 → License」查看授权期限、维保期限、扩展权益。
• 支持增量导入（不必一次导入全部）、导出许可证环境信息（申请/排障用）。
• License 过期通常不会立刻停服，但扩展能力、技术支持与升级会受限；到期前 90 天开始走续期。

10. 工作负载、网关与应用

10.1 控制台与 kubectl 的对应关系

kubectl -n <project> get deploy,sts,pod,svc,ing
kubectl -n <project> describe pod <pod>
kubectl -n <project> logs -f deploy/<name>
kubectl -n <project> get events --sort-by=.lastTimestamp | tail -20

10.2 网关与流量

v4.2.1 起支持分级流量治理：集群维度统一规划企业空间级 / 项目级网关策略，网关资源分层部署、权限细粒度隔离；网关升级走滚动更新（静默式平滑升级）。

kubectl get ingress -A
kubectl get gatewayclasses,gateway,httproute -A 2>/dev/null   # Gateway API
kubectl -n kubesphere-controls-system get svc | grep -i gateway
kubectl -n <ns> get pods -l app=kubesphere-router

Ingress NGINX 已归档退役，新集群建议走 Gateway API 或厂商网关；KubeSphere 网关扩展的选型要跟这个趋势对齐。

10.3 应用商店与 Helm

helm repo add <name> <url>
helm repo update
helm install <release> <chart> -n <project> -f values.yaml
helm list -A
helm -n <project> history <release>
helm -n <project> rollback <release> <revision>

平台里"应用"和 helm list 里的 release 是同一份数据。控制台删不掉的应用，多半是 release 处于 pending-upgrade / failed，需要命令行 helm rollback 或 helm uninstall 清理。

11. 多集群管理

11.1 角色

kubectl get clusters.cluster.kubesphere.io -A 2>/dev/null
kubectl get cluster -A -o yaml | grep -E 'name:|role:|connection'

11.2 纳管检查

1. Member 集群的 kubeconfig / token 有足够权限（cluster-admin 或平台要求的最小权限集）。
2. Host 能访问 Member 的 apiserver 与 kubesphere 控制面端口（跨云/跨机房要放行）。
3. 两侧时间同步（证书校验对偏差敏感）。
4. Host / Member 的 KubeSphere 版本在兼容范围内。

# 检查连通性
curl -k https://<member-apiserver>:6443/version
chronyc sources 2>/dev/null || timedatectl
# 状态同步异常看 agent 日志
kubectl -n kubesphere-system logs deploy/cluster-agent --tail=100 2>/dev/null

v4.2.1 起支持成员集群在线版本升级（图形化、可实时追踪日志）与状态智能同步（主动探测离线/失联/异常）。v4.3.0 的 Copilot 支持手动选定集群绑定对话上下文，保障多租户数据隔离。

坑：多集群场景下 kubectl 默认上下文是当前连的集群，控制台里切了集群不代表终端里切了上下文。执行破坏性命令前 kubectl config current-context 确认一遍。

12. 可观测、日志与排障能力

12.1 v3 与 v4 的差异

kubectl get pods -n kubesphere-monitoring-system 2>/dev/null
kubectl get pods -A | grep -iE 'whizard|prometheus|loki|fluent'

12.2 命令行底线（平台监控挂了照样能查）

kubectl top nodes
kubectl top pods -A --sort-by=memory | head -20
kubectl get events -A --sort-by=.lastTimestamp | tail -50
kubectl describe node <node> | tail -30
journalctl -u kubelet -n 100 --no-pager
journalctl -u containerd -n 100 --no-pager
crictl ps -a | head

12.3 kubectl debug（v4.3.0 控制台也能点）

kubectl debug -it <pod> -n <ns> --image=busybox:1.36 --target=<container>
kubectl debug node/<node> -it --image=busybox:1.36

控制台可视化 debug 会在目标 Pod 里创建临时容器，会改变 Pod 状态并可能触发告警。生产环境用完记得删除临时容器/重建 Pod。

13. 存储与网络

kubectl get sc -o yaml
kubectl get pvc -A | grep -v Bound
kubectl describe pvc <pvc> -n <ns>
kubectl get networkpolicy -A
kubectl get ippool -A 2>/dev/null

离线环境如果选 OpenEBS / Longhorn 提供存储，它们的镜像也要提前同步到内网仓库，否则 kk 装完 K8s 看着正常，第一个 PVC 就 Pending。

14. 日常运维操作

14.1 巡检脚本

#!/usr/bin/env bash
echo "===== 节点 ====="; kubectl get nodes -o wide
echo "===== Core ====="; kubectl get pods -n kubesphere-system -o wide
echo "===== 异常 Pod ====="; kubectl get pods -A --field-selector=status.phase!=Running | grep -v Completed
echo "===== Helm ====="; helm list -A | grep -iE 'ks-core|whizard|gateway'
echo "===== 存储 ====="; kubectl get pvc -A | grep -v Bound
kubectl get sc
echo "===== 资源 ====="; kubectl top nodes
echo "===== 事件 ====="; kubectl get events -A --sort-by=.lastTimestamp | tail -20

14.2 重启与扩缩

kubectl -n kubesphere-system rollout restart deploy/ks-apiserver
kubectl -n kubesphere-system rollout restart deploy/ks-console
kubectl -n kubesphere-system scale deploy/ks-console --replicas=2
kubectl -n kubesphere-system rollout status deploy/ks-apiserver

只重启 Core，不动业务命名空间。多副本时先确认有 PodDisruptionBudget 或者流量已摘除。

14.3 日志定位

kubectl -n kubesphere-system logs deploy/ks-apiserver --tail=200 | grep -iE 'error|warn'
kubectl -n kubesphere-system logs deploy/ks-controller-manager --tail=200
kubectl -n kubesphere-system logs deploy/ks-console --tail=200
kubectl -n kubesphere-system get events --sort-by=.lastTimestamp | tail -30

15. 升级与回滚

15.1 升级顺序（不可颠倒）

1. 备份 etcd + Helm values + 平台 CR
2. 升级 Kubernetes（kk upgrade，一次只升一个 minor，不能跳级）
3. 校验节点与核心组件
4. 升级 KubeSphere Core（helm upgrade，用对应新版本的 chart）
5. 逐个升级扩展组件（注意依赖顺序）
6. 升级 Member 集群（多集群场景）
7. 功能回归：登录、企业空间/项目权限、网关、监控

15.2 Core 升级

helm -n kubesphere-system get values ks-core > /root/ks-core-values-$(date +%F).yaml
helm -n kubesphere-system get all ks-core > /root/ks-core-manifest-$(date +%F).txt

helm -n kubesphere-system upgrade ks-core oci://hub.kubesphere.com.cn/kse/ks-core \
  --version <新chart版本> --wait \
  -f /root/ks-core-values-<date>.yaml

坑：--reset-values 只适合首次安装或明确要丢弃自定义值时用。升级时带 --reset-values 会把 imageRegistry 等内网设置冲掉，Pod 立刻 ImagePullBackOff。升级用 -f values.yaml 复用。

15.3 v3 → v4 迁移现实

官方没有"一键原地升级"：v3 是单体 + ClusterConfiguration，v4 是微内核 + Helm + Extension，配置模型完全不同。可行路径是：

1. 新建一个 v4 集群（同版本 K8s 或新集群）。
2. 导出平台元数据（用户、企业空间、项目、角色）与应用清单。
3. 业务负载用 kubectl get -o yaml / Helm release / Velero 迁移。
4. 在新平台重建 RBAC 与扩展组件。
5. 灰度切流量，旧集群保留观察期。

把它当迁移项目做，不要当"升级操作"排进半小时维护窗口。

15.4 回滚

helm -n kubesphere-system history ks-core
helm -n kubesphere-system rollback ks-core <revision>
kubectl -n kubesphere-system rollout status deploy/ks-apiserver

K8s 本身不能降级。如果已经升过 K8s 大版本，Core 回滚也可能因 API 版本不兼容失败，此时要从 etcd 快照重建（见 K8s 分册）。

16. 备份与恢复

16.1 三层备份，缺一不可

# 平台配置导出
mkdir -p /root/ks-backup-$(date +%F)
helm -n kubesphere-system get values ks-core -a > /root/ks-backup-*/ks-core-values.yaml
helm list -A -o yaml > /root/ks-backup-*/helm-releases.yaml
kubectl get crd -o name | grep -iE 'kubesphere|tenant|extension' \
  | xargs -r -I{} sh -c 'kubectl get {} -A -o yaml >> /root/ks-backup-*/crs.yaml'
kubectl get ns -o yaml > /root/ks-backup-*/namespaces.yaml

16.2 etcd 快照（控制面节点）

ETCDCTL_API=3 etcdctl snapshot save /root/etcd-$(date +%F).db \
  --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/ssl/etcd/ssl/ca.crt \
  --cert=/etc/ssl/etcd/ssl/etcd.crt \
  --key=/etc/ssl/etcd/ssl/etcd.key
ETCDCTL_API=3 etcdctl snapshot status /root/etcd-*.db

路径随部署方式变（kubeadm 常在 /etc/kubernetes/pki/etcd/），以 ps -ef | grep etcd 里的实际参数为准。恢复流程见 K8s 分册，别在没演练过的情况下直接对生产做。

16.3 恢复验证清单

• 快照文件 CRC / etcdctl snapshot status 正常
• 在测试集群恢复过一次
• License 文件与扩展仓库凭证单独保存
• 镜像仓库本身有备份（否则恢复完拉不到镜像）

17. 卸载与残留清理

17.1 只卸载 KubeSphere，保留 K8s 与业务

# v4
helm -n kubesphere-system uninstall ks-core
# 逐个卸载扩展（先看下有哪些）
helm list -A | grep -iE 'whizard|gateway|devops'

# 删除平台 CRD（★会删掉所有平台元数据）
kubectl get crd | grep -i kubesphere | awk '{print $1}' | xargs -r kubectl delete crd

# 删除命名空间
kubectl delete ns kubesphere-system kubesphere-controls-system \
  kubesphere-monitoring-system kubesphere-logging-system --ignore-not-found

坑：删 CRD 是级联删除所有平台 CR（企业空间、项目、角色）——但不会删业务 Namespace 里的 Deployment/Service，因为那些是原生资源。所以卸载后业务还在跑，只是失去平台管理。这正是我们想要的，但也意味着"卸载"不等于"清理干净"。

17.2 v3 卸载

# 官方卸载脚本（老版本）
kubectl delete -f cluster-configuration.yaml
kubectl delete -f kubesphere-installer.yaml
# 或
wget https://raw.githubusercontent.com/kubesphere/ks-installer/master/scripts/kubesphere-delete.sh
sh kubesphere-delete.sh

17.3 连 K8s 一起销毁

./kk delete cluster -f config-sample.yaml
# 或 kubeadm reset（见 K8s 分册）+ 手工清 CNI/iptables

17.4 残留验证

helm list -A | grep -i ks-
kubectl get ns | grep -i kubesphere
kubectl get crd | grep -i kubesphere
kubectl get clusterrole,clusterrolebinding | grep -i kubesphere
kubectl get pods -A | grep -iE 'ks-|whizard|gateway'
# 节点上的残留
ls -la /etc/kubernetes/ /root/.kubekey/ 2>/dev/null
iptables -L -n | grep -i calico

18. 故障速查

18.1 三分钟定位脚本

kubectl get nodes -o wide
kubectl get pods -n kubesphere-system -o wide
kubectl get pods -A --field-selector=status.phase!=Running | grep -v Completed
helm list -A
kubectl get events -A --sort-by=.lastTimestamp | tail -20
kubectl -n kubesphere-system logs deploy/ks-apiserver --tail=50 | grep -iE 'error|warn'

19. 安全基线与危险红线

19.1 基线

• 首次登录改掉 admin / P@88w0rd
• 控制台 30880 不暴露公网，走 VPN / 堡垒机 / 反代 + SSO
• 平台角色最小权限，项目级不给 cluster-admin
• 开启审计（v3 配置 / v4 扩展），日志保留 ≥ 180 天
• 私有仓库启用 TLS 与最小权限账号
• License、Helm values、etcd 快照异地保存
• 扩展组件来源可信，不用第三方未签名 chart
• Copilot / AI 助手绑定的 LLM 与 API Key 走内网，审计对话内容
• 定期升级 K8s 与 KubeSphere，K8s 一次只升一个 minor

19.2 危险红线

20. 附录

20.1 命令速查

20.2 版本与端口速查

20.3 与其他手册的配合

维护建议：KubeSphere 的 chart 版本、扩展镜像 tag、K8s 兼容矩阵随发布变动快，本文给出的 version=1.2.4、tag=v11.2.0 是 v4.2.1 官方文档基线，落地前按当前发布说明核对。把私有仓库地址、K8s 版本、chart 版本、扩展清单写进集群交付单，升级与恢复都按单执行。