KubeSphere 4.1 常用 CLI 命令与工具详解

目标：把运维一台 KubeSphere 4.1 平台服务器时真正会用的命令行工具一次讲透——KubeKey（kk）集群生命周期命令、kubectl 资源操作、helm 发布与回滚、crictl/ctr 运行时排障、etcdctl/etcdutl 数据备份、calicoctl 网络检查，每个子命令配参数与实测回显，并给出健康巡检、控制台探活、etcd 快照三套日常运维组合。本文所有命令与输出均在真实环境实测通过（Ubuntu 24.04.5 服务器，KubeSphere v4.1.3 + Kubernetes v1.37.0 单机 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，命名空间 kubesphere-system）
KubeKey：v4.0.8；Kubernetes：v1.37.0；Helm：v3.18.5；containerd：2.3.3；Calico：v3.32.2；etcd：v3.7.0
版本口径：KubeSphere/KubeKey 最新稳定版为官方渠道实查（查询日期 2026-10-24），溯源见《KubeSphere 4.1 介绍与选型指南》
部署过程与参数体系：分别见《Ubuntu 24.04 安装 KubeSphere 4.1 指南》与《KubeSphere v4.1.3 配置参数详解》
工具安装位置：kubectl / helm / crictl / ctr / etcdctl / etcdutl / calicoctl 均在 /usr/local/bin/（KubeKey 安装时布设），kk 按部署篇 4.2 节安装到 /usr/local/bin/kk

二、工具概览

运维 KubeSphere 服务器不是只用一个命令，而是一组各司其职的工具。先给全岗位分工表，再逐个详解：

工具	管辖层	典型任务	本文实测版本
kk（KubeKey）	集群生命周期	装集群、加删节点、升级、证书续期、离线包	v4.0.8
kubectl	Kubernetes 资源	查状态、看清单、改声明、滚动重启	v1.37.0
helm	平台发布层	ks-core 升级、改 values、回滚	v3.18.5
crictl	运行时（CRI）	看进程容器、取日志（kubectl logs 受限时的主力）	v1.37.0
ctr	运行时（containerd 原生）	镜像清理、命名空间管理	v2.3.3
etcdctl / etcdutl	数据层	健康检查、成员列表、快照备份	3.7.0
calicoctl	网络层	BGP/节点网络状态	v3.32.2

各工具版本一次性实测（可复制执行核对环境）：

kubectl version --output=yaml 2>/dev/null | head -6; helm version; crictl --version; ctr --version; etcdctl version; calicoctl version | head -4

实测回显：

clientVersion:
  buildDate: "2026-08-26T10:48:06Z"
  compiler: gc
  gitCommit: f54c212e3a2f75d674b717a9b29052b20b60aefc
  gitTreeState: clean
  gitVersion: v1.37.0

version.BuildInfo{Version:"v3.18.5", GitCommit:"b78692c18f0fb38fe5ba4571a674de067a4c53a5", GitTreeState:"clean", GoVersion:"go1.24.5"}
crictl version v1.37.0
ctr github.com/containerd/containerd/v2 v2.3.3
etcdctl version: 3.7.0
API version: 3.7
Client Version:    v3.32.2
Git commit:        051b21a48bc7b6ef71d69df887c239889b942edc

三、前置条件

root 或具备 sudo 的账号；KubeSphere 平台已按部署篇安装完成（本文所有命令在该前提下才有对象可操作）。
kubectl 已就绪：KubeKey 安装完成后 /etc/kubernetes/admin.conf 存在，kubeconfig 默认落在 /root/.kube/config（root 用户直接可用 kubectl get nodes 验证）。
外网下载慢时的代理用法见部署篇 4.2 节说明（curl -x http://<proxy>:<port>）。
权限预期：本文 5.3 节实测发现 kubectl logs/exec 走 nodes/proxy 通道时会被拒绝（KubeKey 1.37 部署的已知现象），排障与替代方案已给出；其余命令均实测可用。

四、KubeKey（kk）命令详解

kk 是 KubeSphere 官方的集群生命周期工具，v4 已重构为「配置 + 清单」双文件模型（config.yaml / inventory.yaml），命令面共 14 个子命令。

4.1 版本与命令总览

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 --help

实测回显（子命令清单部分，全局日志参数略）：

kubekey is a daemon that execute command in a node

Usage:
  kk [command]

Available Commands:
  add         Add nodes to kubernetes cluster
  artifact    Manage a KubeKey offline installation package
  certs       cluster certs
  completion  Generate the autocompletion script for the specified shell
  create      Create a cluster or a cluster configuration file
  delete      Delete node or cluster
  help        Help about any command
  init        Initializes the installation environment
  playbook    Executor a playbook in kubernetes
  precheck    Check if the nodes is eligible for cluster deployment.
  run         run a playbook by playbook file. the file source can be git or local
  upgrade     Upgrade a Kubernetes cluster
  version     Print the version of KubeSphere controller-manager
  web         start a http server with web UI.

💡 说明：与 v3 相比，kk v4 的 create cluster 不再提供 --with-kubesphere 参数——KubeSphere 平台改由 Helm Chart 单独安装（部署篇 4.5 节），kk 只管 Kubernetes 集群与底层设施。

4.2 集群创建与配置生成

生成配置骨架（在目标服务器任意工作目录执行）：

kk create config

实测行为：当前目录生成 config.yaml（集群级配置）与 inventory.yaml（主机清单）。其参数说明（kk create config --help 实测）：

Flags:
  -o, --output string            Output path for config file (file or directory). if not set will output to stdout
      --with-kubernetes string   Specify a supported version of kubernetes. default is v1.37.0 (default "v1.37.0")

一键创建集群（all-in-one 单机不传 -i，默认装到本机；部署篇 4.4 节完整实录）：

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

关键 flags（kk create cluster --help 实测）：

flag	默认值	说明
`-c, --config`	无	集群配置文件路径
`-i, --inventory`	无	主机清单路径；不传 = all-in-one 本机
`--with-kubernetes`	`v1.37.0`	目标 K8s 版本
`--set`	无	命令行覆盖配置项，如 `--set spec.zone=default`
`--skip-tags`	无	跳过指定阶段（黑名单），如 `--skip-tags cri`
`--tags`	无	只执行指定阶段（白名单）；对 create cluster 建议用 skip-tags
`-a, --artifact`	无	离线包路径（离线安装用）
`-n, --namespace`	`default`	playbook 执行命名空间
`--workdir`	`/kubekey`	kk 工作目录

4.3 部署预检：kk precheck

安装前/变更前先跑预检，按类别过滤。帮助文本实测（分类即白名单枚举）：

Precheck supports per-category filtering. Use --tags to run only the listed categories (whitelist), or --skip-tags to run all categories except the listed ones (blacklist). Available categories: artifact, cri, cni, storageclass, os, network, storage, kubernetes, etcd, nfs.

本环境实跑（对已装集群做体检）：

kk precheck -c /root/config.yaml -i /root/inventory.yaml --with-kubernetes v1.37.0

实测回显（输出节选，末行为统计）：

19:37:33 CST [roles/precheck/etcd] ETCD | Check if fio is installed
⠋ [localhost] ignore   [0s]
19:37:33 CST [roles/precheck/etcd] ETCD | Execute fio and collect results
⠋ [localhost] skip     [0s]
19:37:33 CST [roles/precheck/etcd] ETCD | Assert disk fsync latency meets requirements
⠋ [localhost] skip     [0s]
19:37:33 CST [roles/precheck/etcd] ETCD | Clean up fio test data directory
⠋ [localhost] skip     [0s]
19:37:33 CST [roles/precheck/nfs] NFS | Fail if more than one NFS server is defined
⠋ [localhost] skip     [0s]
19:37:33 CST [Playbook default/precheck-8q2mb] finish. total: 79,success: 78,ignored: 1,failed: 0

💡 解读：79 项检查 78 项成功、1 项忽略（fio 磁盘基准工具未安装，etcd 性能检查跳过）、0 失败。failed: 0 才继续安装/变更；安装 etcd 生产环境建议 apt install fio 后重跑让磁盘延迟检查生效。

4.4 扩容与删除：kk add / kk delete

kk add --help   # 子命令：nodes（按新清单把节点加进集群）
kk delete --help

实测回显（delete 子命令清单）：

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

用法要点：扩容 = 在 inventory.yaml 加节点条目（逐节点单独成块）→ kk add nodes -c config.yaml -i inventory.yaml；缩容 = kk delete nodes -c config.yaml -i inventory.yaml；销毁实验集群 = kk delete cluster -c config.yaml -i inventory.yaml。

⚠️ 注意：kk delete cluster 会清空 Kubernetes、containerd、CNI 与 etcd 数据，不可逆。生产环境禁用；确需重建时先做 8.4 节的 etcd 快照并备份 /root/config.yaml、inventory.yaml 与 ks-core Chart 包。

4.5 升级：kk upgrade

kk upgrade --help

实测回显：

Available Commands:
  cluster      Upgrade a Kubernetes cluster
  cni          Upgrade only the cni component
  cri          Upgrade only the cri component
  etcd         Upgrade only the etcd component
  storageclass Upgrade only the storageclass component

用途：小版本升级（如 v1.37.x → v1.38.x）改 config.yaml 的 kube_version 后执行 kk upgrade cluster -c config.yaml -i inventory.yaml；也可单独升 CNI/CRI/etcd/存储类。KubeSphere 平台本身的升级走 Helm（见第六章），两者独立。

4.6 证书续期：kk certs

kk certs --help

实测回显：

Available Commands:
  renew       renew a cluster certs

kubeadm 默认证书一年有效期，临近到期用 kk certs renew -c config.yaml -i inventory.yaml 续期；平时用 kubectl get leases -n kube-node-lease 与 openssl x509 -enddate -noout -in /etc/kubernetes/pki/apiserver.crt 抽查到期时间。

4.7 离线安装包：kk artifact

kk artifact --help

实测回显：

Available Commands:
  export      Export a KubeKey offline installation package
  images      push images to a registry from an artifact

离线环境流程：在能上网的机器上按官方 artifact 模板写 manifest.yaml → kk artifact export -m manifest.yaml -o artifact.tar.gz → 拷到内网 → kk artifact images -a artifact.tar.gz 把镜像推入私仓（对应 config.yaml 的 image_registry 配置）→ kk create cluster -a artifact.tar.gz -c config.yaml -i inventory.yaml 离线装集群。

4.8 环境初始化：kk init 与 Playbook 直跑

kk init --help

实测回显：

Available Commands:
  os          Init operating system
  registry    Init a local image registry

kk init os -c config.yaml -i inventory.yaml 只做系统层初始化（装依赖包、关 swap、内核模块），适合先把基础环境批量备好、择日装集群的节奏；kk init registry 部署本地镜像仓库。另有 kk playbook（执行内置 playbook）与 kk run（按文件跑，支持 git 来源），属高级用法，日常运维少用。

4.9 Web 安装向导：kk web

kk web --help

实测回显（节选）：

Flags:
      --host-check-playbook string   the host-check playbook path for web inventory checks. (default "web-installer/host_check.yaml")
      --port int                     the server port of kubekey web default is: 80 (default 80)
      --schema-path string           the json schema dir path to render web ui. (default "web-installer/schema")
      --ui-path string               the web ui package path. (default "web-installer/dist")
      --workdir string               the base Dir for kubekey. Default current dir.  (default "/kubekey")

kk web 起一个 HTTP 服务（默认 80 端口）提供浏览器表单式装机向导（kk v4 新能力，下载 kk 时附带 web_installer 组件）；服务器只能命令行操作时用 4.2 节的纯 CLI 流程即可，两者产出同一套 config/inventory。

五、kubectl 常用命令

5.1 节点与核心资源查询

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

kubectl get deploy -n kubesphere-system -o wide

实测回显（KubeSphere 四个核心工作负载）：

NAME                    READY   UP-TO-DATE   AVAILABLE   AGE   CONTAINERS              IMAGES                                                          SELECTOR
extensions-museum       1/1     1            1           9h    extensions-museum       hub.kubesphere.com.cn/kubesphere/ks-extensions-museum:v1.1.5    app=extensions-museum
ks-apiserver            1/1     1            1           9h    ks-apiserver            hub.kubesphere.com.cn/kubesphere/ks-apiserver:v4.1.3            app=ks-apiserver,tier=backend
ks-console              1/1     1            1           9h    ks-console              hub.kubesphere.com.cn/kubesphere/ks-console:v4.1.3              app=ks-console,tier=frontend
ks-controller-manager   1/1     1            1           9h    ks-controller-manager   hub.kubesphere.com.cn/kubesphere/ks-controller-manager:v4.1.3   app=ks-controller-manager,tier=backend

kubectl get svc -n kubesphere-system

实测回显：

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

5.2 终端执行与日志：实测受限与替代方案

kubectl 的日志与 exec 走 API Server 到 kubelet 的 nodes/proxy 通道。本环境实测该通道被拒：

kubectl logs -n kubesphere-system deploy/ks-apiserver --tail=3

实测回显：

Found 3 pods, using pod/ks-apiserver-695ddf767d-xgptl
Error from server (Forbidden): Forbidden (user=kube-apiserver-kubelet-client, verb=get, resource=nodes, subresource(s)=[proxy])
 ( pods/log ks-apiserver-695ddf767d-xgptl)

kubectl exec -n kubesphere-system deploy/ks-console -- ls /

实测回显：

error: unable to upgrade connection: Forbidden (user=kube-apiserver-kubelet-client, verb=create, resource=nodes, subresource(s)=[proxy])

原因定位：报错主体是 kube-apiserver-kubelet-client（API Server 访问 kubelet 用的客户端证书身份），其所需权限由 ClusterRole system:kubelet-api-admin 定义——该角色在本集群实查存在（kubectl get clusterrole system:kubelet-api-admin 返回 CREATED AT 2026-10-24T01:28:30Z），但缺少把它绑定到该用户的 ClusterRoleBinding。两条路修复：

补绑定（授权变更，按需执行）：kubectl create clusterrolebinding kubelet-api-admin --clusterrole=system:kubelet-api-admin --user=kube-apiserver-kubelet-client，执行后 kubectl logs/exec 即恢复；
不改集群，用 crictl 替代（本文采用）：KubeKey 部署的 containerd 与 kubectl 同机，运行时侧日志/执行不走 API Server，见 7.1 节，功能等价且无权限问题。

5.3 滚动重启与状态确认

配置变更后让 Deployment 重读配置的标准两连（命令形式；生效验证方法与实读回显见配置篇 3.5 节）：

kubectl rollout restart deployment -n kubesphere-system ks-apiserver
kubectl rollout status deployment -n kubesphere-system ks-apiserver --timeout=120s

第一条输出 deployment.apps/ks-apiserver restarted；第二条在滚动完成时输出 deployment "ks-apiserver" successfully rolled out，随后 kubectl get pods -n kubesphere-system -l app=ks-apiserver,tier=backend 应看到 AGE 归零的 Running Pod。

六、helm 命令详解

KubeSphere 平台层的安装/升级/回滚全部经由 helm（ks-core release），命令面集中在 list/get/upgrade/rollback/history 五个。

6.1 清单与版本

helm version
helm list -A

实测回显：

version.BuildInfo{Version:"v3.18.5", GitCommit:"b78692c18f0fb38fe5ba4571a674de067a4c53a5", GitTreeState:"clean", GoVersion:"go1.24.5"}

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

6.2 查看 values 与发布历史

helm get values ks-core -n kubesphere-system
helm history ks-core -n kubesphere-system

实测回显：

USER-SUPPLIED VALUES:
extension:
  imageRegistry: hub.kubesphere.com.cn
global:
  imageRegistry: hub.kubesphere.com.cn

REVISION        UPDATED                         STATUS          CHART           APP VERSION     DESCRIPTION
1               Sat Oct 24 10:40:33 2026        deployed        ks-core-1.1.5   v4.1.3          Install complete

全量计算值用 -a 追加（helm get values ks-core -n kubesphere-system -a，约 310 行，逐项解读见配置篇第六章）。

6.3 升级与改参数

改参数 = 重跑与安装同形的 helm upgrade --install，已传值用 --reuse-values 保留，新增改动用 --set 追加（示例：关遥测并保留既有镜像源配置）：

helm upgrade --install -n kubesphere-system ks-core /path/to/ks-core-1.1.5.tgz \
  --reuse-values --set telemetry.enabled=false --wait

⚠️ 实测踩坑（2026-10-24）：用在线地址 https://charts.kubesphere.io/main/ks-core-1.1.5.tgz 执行升级时，该 URL 开始对 .tgz 请求返回官网 HTML 页，helm 报错（实测照抄）：
Error: file '/root/.cache/helm/repository/ks-core-1.1.5.tgz' does not appear to be a gzipped archive; got 'text/html; charset=utf-8'
处理：删除被污染缓存 rm -f ~/.cache/helm/repository/ks-core-1.1.5.tgz，改用本地留存的 Chart 包路径执行升级。务必在每次成功安装后把 Chart 包备份到本地（部署篇 4.5 节安装成功当日该地址尚正常，次日即出现内容替换——升级永远不要赌外网）。

6.4 回滚

helm rollback ks-core <目标REVISION> -n kubesphere-system --wait
helm history ks-core -n kubesphere-system   # 回滚后 HISTORY 中会出现新的 rollback 记录

回滚按 REVISION 号操作（6.2 节的 history 列出可用版本）；注意 rollback 只回 Chart 渲染物，运行时手工改过的 ConfigMap 内容不会回（配置管理原则见配置篇 3.3 节）。

七、容器运行时 CLI：crictl 与 ctr

KubeKey 部署的运行时是 containerd，调试面用 crictl（CRI 视角，懂 Pod）与 ctr（containerd 原生视角，懂命名空间）。当 kubectl logs/exec 因 nodes/proxy 权限受限时（5.2 节实测），crictl 是同机运维的主力替代。

7.1 crictl：Pod 容器视角

crictl ps 2>/dev/null | head -5

实测回显：

CONTAINER           IMAGE               CREATED             STATE               NAME                      ATTEMPT             POD ID              POD                                       NAMESPACE
37ab7c3f51f5a       3027a10e53965       8 hours ago         Running             ks-console                0                   e7360b1b97013       ks-console-75699cfc9b-c4b2x               kubesphere-system
ad0aacc1a1b21       cb018b4b2bdde       8 hours ago         Running             ks-apiserver              0                   4ba63ecb0263a       ks-apiserver-695ddf767d-xgptl             kubesphere-system
110c08ea28689       d7eef55efdbf0       8 hours ago         Running             whisker-backend           0                   186ae3e3da055       whisker-6c4464cf8c-zq5lx                  calico-system
eeefd395903ff       db36509507e0d       8 hours ago         Running             whisker                   0                   186ae3e3da055       whisker-6c4464cf8c-zq5lx                  calico-system

取日志（替代 kubectl logs，参数同形：--tail、-f 跟随）：

crictl logs --tail 3 ad0aacc1a1b21

实测回显（ks-apiserver 访问日志节选）：

I1024 12:14:10.198763       1 filters.go:96] 10.89.59.2 - "PUT /apis/iam.kubesphere.io/v1beta1/users/admin HTTP/1.1" 422 550 5ms
I1024 12:14:22.405552       1 filters.go:96] 10.89.59.2 - "PUT /apis/iam.kubesphere.io/v1beta1/users/admin HTTP/1.1" 422 938 3ms
I1024 12:14:40.204704       1 filters.go:96] 10.89.59.2 - "PUT /apis/iam.kubesphere.io/v1beta1/users/admin HTTP/1.1" 409 395 3ms

镜像清单：

crictl images 2>/dev/null | head -5

实测回显：

IMAGE                                                                TAG                 IMAGE ID            SIZE
docker.io/kubespheredev/ks-console                                   release-4.1         3027a10e53965       59.8MB
hub.kubesphere.com.cn/kubesphere/ks-console                          v4.1.3              3027a10e53965       59.8MB
docker.io/openebs/linux-utils                                        4.3.0               b5f5ea6be336c       25.3MB
hub.kubesphere.com.cn/openebs/linux-utils                            4.3.0               b5f5ea6be336c       25.3MB

常用补充：crictl inspect <容器ID>（详细元数据，含启动命令/资源限额/挂载）、crictl stats（实时资源用量）、crictl pods（Pod 沙箱清单）、crictl exec -it <容器ID> sh（进入运行中进程，替代 kubectl exec）。

7.2 ctr：containerd 原生视角

ctr namespace list

实测回显：

NAME   LABELS
k8s.io
moby

ctr -n k8s.io images list -q 2>/dev/null | head -4

实测回显：

docker.io/kubespheredev/ks-console:release-4.1
docker.io/openebs/linux-utils:4.3.0
docker.io/openebs/provisioner-localpv:4.4.0
docker.m.daocloud.io/kubesphere/ks-apiserver:v4.1.3

💡 说明：Kubernetes 的全部镜像在 k8s.io 命名空间下（KubeKey 装的 containerd 默认配置）；moby 命名空间是 docker 工具链预留，KubeSphere 部署不使用。清理无用镜像优先 crictl rmi（CRI 语义，不误删运行中镜像层）；ctr -n k8s.io images rm 属强删，仅离线排障时使用。

八、etcdctl 与 etcdutl：数据层检查与备份

8.1 证书准备（先踩一个真实的坑）

kubeadm 部署的 etcd 客户端证书在 /etc/kubernetes/pki/etcd/。本环境实查：

ls /etc/kubernetes/pki/etcd/

实测回显：

ca.crt
client.crt
client.key

⚠️ 注意：网上常见的 healthcheck-client.crt、apiserver-etcd-client.crt 在本环境不存在（KubeKey 1.37 的 kubeadm 配置只签发了 ca.crt + client.crt + client.key 三件套）。用不存在的证书名会报 Error: open /etc/kubernetes/pki/etcd/healthcheck-client.crt: no such file or directory（实测）。健康检查、成员查询、快照统一用 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/client.crt --key=/etc/kubernetes/pki/etcd/client.key。

另一个实测细节：etcdctl 3.7 已不需要 ETCDCTL_API=3 前缀（API v3 为默认），设置该变量会得到警告 {"level":"warn",...,"msg":"unrecognized environment variable","environment-variable":"ETCDCTL_API=3"}，新脚本不要再写。

8.2 健康检查与成员列表

etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/client.crt \
  --key=/etc/kubernetes/pki/etcd/client.key \
  endpoint health

实测回显：

https://127.0.0.1:2379 is healthy: successfully committed proposal: took = 13.471655ms

etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/client.crt \
  --key=/etc/kubernetes/pki/etcd/client.key \
  member list -w table

实测回显：

│        ID        │ STATUS  │ NAME  │       PEER ADDRS        │      CLIENT ADDRS       │ IS LEARNER │
├──────────────────┼─────────┼───────┼─────────────────────────┼─────────────────────────┼────────────┤
│ 39fca35bf36d5e7c │ started │ node1 │ https://10.89.59.2:2380 │ https://10.89.59.2:2379 │      false │
└──────────────────┴─────────┴───────┴─────────────────────────┴─────────────────────────┴────────────┘

8.3 快照备份与校验

etcdctl --endpoints=https://127.0.0.1:2379 \
  --cacert=/etc/kubernetes/pki/etcd/ca.crt \
  --cert=/etc/kubernetes/pki/etcd/client.crt \
  --key=/etc/kubernetes/pki/etcd/client.key \
  snapshot save /var/backups/etcd-snap-20261024.db

实测回显：

Snapshot saved at /var/backups/etcd-snap-20261024.db
Server version 3.7.0

etcdutl snapshot status /var/backups/etcd-snap-20261024.db -w table

实测回显：

┌──────────┬──────────┬────────────┬────────────┬─────────┐
│   HASH   │ REVISION │ TOTAL KEYS │ TOTAL SIZE │ VERSION │
├──────────┼──────────┼────────────┼────────────┼─────────┤
│ 9d4b9e93 │   128302 │       1751 │      38 MB │   3.7.0 │
└──────────┴──────────┴────────────┴────────────┴─────────┘

💡 说明：本机 all-in-one 实测快照 1751 键、38MB。恢复操作用 etcdutl snapshot restore 生成新数据目录再由 kubelet 拉起 etcd 静态 Pod（恢复会清空其后的增量写入，务必先停写）；快照文件应异机存放。

九、calicoctl：网络层检查

calicoctl node status

实测回显：

Calico process is running.

IPv4 BGP status
No IPv4 peers found.

IPv6 BGP status
No IPv6 peers found.

💡 解读：单机 all-in-one 没有 BGP 对端，No IPv4 peers found 属正常；多节点集群此处应列出各节点 BGP 会话及 Up/Down 状态。补充命令：calicoctl get nodes -o wide（Calico 节点清单）、calicoctl get ippool -o wide（地址池）、calicoctl version（本环境实测 Client/Cluster 均为 v3.32.2，Cluster Type: k8s,operator,bgp,kdd,typha）。

十、日常运维组合实战

10.1 每日健康巡检五连

一条龙巡检（每条都有明确判据，配合 5.1/8.2/9 节实测回显使用）：

kubectl get nodes -o wide
kubectl get pods -n kubesphere-system
kubectl get endpoints -n kubesphere-system
curl -s -o /dev/null -w "console HTTP %{http_code}\n" --max-time 5 http://10.89.59.2:30880/login
etcdctl --endpoints=https://127.0.0.1:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/client.crt --key=/etc/kubernetes/pki/etcd/client.key endpoint health

判据：nodes 全 Ready；kubesphere-system 四个核心 Deployment 对应 Pod 全 Running；endpoints 四个服务均有地址（ks-console 应为 :8000）；控制台 HTTP 200；etcd is healthy 且耗时在百毫秒内（本环境实测 13.47ms）。

10.2 控制台探活与 NodePort 排障

控制台访问排障时的标准三步（实测数据）：

curl -s -o /dev/null -w "local HTTP %{http_code}\n" --max-time 5 http://localhost:30880/login
curl -s -o /dev/null -w "nodeip HTTP %{http_code}\n" --max-time 5 http://10.89.59.2:30880/login
crictl ps 2>/dev/null | grep ks-console

实测回显：

local HTTP 000
nodeip HTTP 200
37ab7c3f51f5a       3027a10e53965       8 hours ago         Running             ks-console                0                   e7360b1b97013       ks-console-75699cfc9b-c4b2x               kubesphere-system

定位结论：localhost:30880 连接失败而 节点IP:30880 正常（NodePort 对本机回环目标的转发限制），且 ks-console 进程容器 Running——服务本身健康，换用服务器 IP 访问即可，不要在回环地址上空耗排查。若节点 IP 也 000，再查 endpoints（ks-console 无后端 = Pod 未就绪）与 Pod 事件。

10.3 etcd 快照定期备份

把 8.3 节命令固化为每日任务（先手工执行一次确认路径与证书可用，再写入 /etc/cron.d/ 单独一行任务；快照文件名带日期防覆盖）：

mkdir -p /var/backups
etcdctl --endpoints=https://127.0.0.1:2379 --cacert=/etc/kubernetes/pki/etcd/ca.crt --cert=/etc/kubernetes/pki/etcd/client.crt --key=/etc/kubernetes/pki/etcd/client.key snapshot save /var/backups/etcd-snap-$(date +%Y%m%d).db
etcdutl snapshot status /var/backups/etcd-snap-$(date +%Y%m%d).db -w table

实测回显（当日执行）：

Snapshot saved at /var/backups/etcd-snap-20261024.db
Server version 3.7.0
┌──────────┬──────────┬────────────┬────────────┬─────────┐
│   HASH   │ REVISION │ TOTAL KEYS │ TOTAL SIZE │ VERSION │
├──────────┼──────────┼────────────┼────────────┼─────────┤
│ 9d4b9e93 │   128302 │       1751 │      38 MB │   3.7.0 │
└──────────┴──────────┴────────────┴────────────┴─────────┘

十一、注意事项

kk delete cluster 不可逆：会整集群销毁（含 etcd 数据）；任何 delete 类操作前先做 10.3 快照。
kk v4 无 --with-kubesphere：平台层只走 Helm（第六章），不要按 v3 老资料找参数。
precheck 的 fio：etcd 磁盘延迟检查依赖 fio，生产机先 apt install fio，否则该项被忽略（4.3 实测）。
etcdctl 证书名：本部署只有 ca.crt/client.crt/client.key 三件套，不要照搬旧教程的 healthcheck-client.crt（8.1 实测报错）。
ETCDCTL_API 变量：etcdctl 3.7 起废弃，写了会告警（8.1 实测）。
crictl 优先于 ctr 做清理：CRI 语义避免误删运行中镜像层（7.2 节）。
Chart 包本地留存：helm 升级不依赖外网在线地址（6.3 实测该地址出现过内容替换）。

十二、常见问题（FAQ）

Q1：kubectl logs / kubectl exec 报 Forbidden (nodes/proxy)？ 本环境实测复现与两种修复方案见 5.2 节：补 system:kubelet-api-admin 到 kube-apiserver-kubelet-client 用户的 ClusterRoleBinding（授权变更），或直接用 crictl logs/exec（同机运维等价替代，本文采用）。判断是否同因：报错里出现 user=kube-apiserver-kubelet-client 即是。

Q2：kubectl logs 指到旧 Pod（Found 3 pods, using pod/...）？ Deployment 历史滚动留下多个同名前缀 Pod 记录时 kubectl 自动选一个。指定具体 Pod：kubectl logs -n kubesphere-system <完整Pod名>，或先用 kubectl get pods -n kubesphere-system 挑 Running 的那个；彻底清理历史旧副本记录见部署篇第九章的集群重建流程（历史 Pod 记录不影响服务，属可容忍噪音）。

Q3：控制台 localhost 打不开？ NodePort 不保证经回环地址可达，本环境实测 localhost:30880 返回 000、节点 IP 返回 200（10.2 节）。统一用 http://<服务器IP>:30880 访问。

Q4：helm upgrade 报 gzipped archive 错误？ Chart 下载地址返回了 HTML 内容（6.3 节实测全文与修复步骤）。删缓存文件、改用本地 Chart 包。

Q5：etcdctl 连不上 2379？ 按 8.1 三件套核对证书路径；确认 etcd 静态 Pod 在跑：crictl pods 2>/dev/null | grep etcd；单机部署 CLIENT ADDRS 是节点 IP（8.2 实测 https://10.89.59.2:2379），127.0.0.1:2379 能通是本机访问的等价形态。

Q6：kk precheck 大量 skip？ 预检按类别执行，未安装的组件（如 NFS、离线 artifact）对应检查项为 skip 属正常；关注 failed 计数是否为 0（4.3 实测 total: 79,success: 78,ignored: 1,failed: 0）。

十三、参考链接

KubeKey 仓库与命令参考：https://github.com/kubesphere/kubekey
kubectl 命令参考：https://kubernetes.io/docs/reference/kubectl/
Helm 文档：https://helm.sh/docs/
crictl 工具说明：https://github.com/kubernetes-sigs/cri-tools
etcdctl 操作指南：https://etcd.io/docs/v3.7/op-guide/etcdctl/
Calico CLI 参考：https://docs.tigera.io/calico/latest/reference/clis/calicoctl/
本专栏前置阅读：《KubeSphere 4.1 介绍与选型指南》、《Ubuntu 24.04 安装 KubeSphere 4.1 指南》、《KubeSphere v4.1.3 配置参数详解》