KubeSphere v4.1.3 配置参数详解

详解 KubeSphere v4.1.3 四层参数体系：KubeKey config/inventory、ks-core Helm values、运行时 ConfigMap 的查看修改与生效验证，附单机与三节点高可用生产模板及无 JVM 进程的实测结论。

KubeSphereKubeSphereKubernetesk8s2026/10/24

KubeSphere v4.1.3 配置参数详解

目标：系统讲清 KubeSphere v4.1.3 平台的全部配置参数所在位置、查看方法、修改方式与生效路径，覆盖 KubeKey 集群配置（config.yaml + inventory.yaml）、ks-core Helm Chart values、平台运行时 ConfigMap（kubesphere-config / ks-console-config）三大参数层，并给出单机与高可用两套生产配置模板。本文所有参数值与命令回显均在真实环境实测取自一台已按部署篇完成安装的 Ubuntu 24.04 服务器（单机 all-in-one，KubeSphere v4.1.3 + Kubernetes v1.37.0），逐行照抄；版本信息查询日期为 2026-10-24。

一、环境信息

  • 操作系统：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，Helm release 名 ks-core）
  • KubeKey：v4.0.8（go1.26.9 构建，构建时间 2026-10-23）
  • Kubernetes：v1.37.0（kubeadm 静态 Pod 方式，etcd v3.7.0）
  • CRI：containerd 2.3.3（systemd 托管）；CNI：Calico v3.32.2（tigera-operator 部署）
  • Helm：v3.18.5（KubeKey 自动安装）
  • 版本口径：KubeSphere 官方最新稳定版 v4.1.3、KubeKey 最新稳定版 v4.0.8，均为官方渠道实查，查询日期 2026-10-24（溯源细节见《KubeSphere 4.1 介绍与选型指南》）
  • 配置文件位置实测清单：
    • KubeKey 集群配置：/root/config.yaml（集群级参数）+ /root/inventory.yaml（主机清单）
    • ks-core Helm release：ks-core，命名空间 kubesphere-system
    • 平台运行时 ConfigMap：kubesphere-config、ks-console-config（均在 kubesphere-system 命名空间）

二、前置条件

本章操作全部基于一台已按部署篇完成安装的服务器。KubeSphere v4.1.3 的参数体系分为四层，动手改参数前必须先弄清「参数在哪一层、改了之后由谁消费」：

层级载体消费者典型参数
第 1 层：集群部署config.yaml + inventory.yaml（KubeKey）KubeKey 安装引擎（kubeadm/containerd/Calico 等）K8s 版本、CRI、CNI、存储类、etcd、镜像仓库
第 2 层：平台发布ks-core Helm valuesHelm / K8s Deployment组件资源限额、控制台端口、镜像源、高可用
第 3 层：平台运行时ConfigMap kubesphere-config（ks-apiserver 读）ks-apiserver / ks-controller-manager认证限流、JWT、多集群角色、审计、终端镜像
第 4 层：控制台运行时ConfigMap ks-console-config（ks-console 读）ks-console端口、会话超时、Node 终端开关

前置检查（root 执行）：

kubectl version --output=yaml 2>/dev/null | head -12

实测回显：

clientVersion:
  buildDate: "2026-08-26T10:48:06Z"
  compiler: gc
  gitCommit: f54c212e3a2f75d674b717a9b29052b20b60aefc
  gitTreeState: clean
  gitVersion: v1.37.0
  goVersion: go1.26.6
  major: "1"
  minor: "37"
  platform: linux/amd64
kustomizeVersion: v5.8.1

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

kubectl get deploy -n kubesphere-system -o wide

实测回显（KubeSphere v4.1.3 核心即以下 4 个 Deployment，全部来自 hub.kubesphere.com.cn 镜像源）：

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

💡 说明：v4 微内核 + 扩展架构下，ks-core Chart 只装「平台内核」四个工作负载（apiserver / controller-manager / console / 扩展仓库 museum）；功能扩展（DevOps、可观测等）通过控制台扩展市场另行安装，其参数在各自扩展的 values 中，不在本文三层之内。

三、参数查看与修改方式

本章先给出四层参数各自「怎么查、怎么改、怎么确认生效」的完整闭环。原则：能走 Helm 的走 Helm（声明式、可回滚），运行时参数改 ConfigMap，集群部署参数改 KubeKey 配置文件。

3.1 第 1 层：KubeKey 集群配置（config.yaml / inventory.yaml）

查看当前集群配置（本环境安装时的实际文件，节选）：

cat /root/config.yaml

实测回显（节选，完整文件 139 行，逐项解读见第五章）：

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
    sandbox_image:
      tag: "3.10.2"
    control_plane_endpoint:
      type: local
  etcd:
    etcd_version: v3.7.0
  cni:
    type: calico
    multi_cni: none
    calico_version: v3.32.2
  storage_class:
    local:
      enabled: true
      default: true
    localpv_provisioner_version: 4.4.0
  dns:
    coredns:
      image:
        tag: v1.14.6
    nodelocaldns:
      enabled: true
      image:
        tag: 1.26.8
  image_manifests: []

修改方式一：编辑配置文件后重跑安装命令（幂等）。KubeKey 按 playbook 阶段推进，已就绪的任务会跳过或忽略，变更项会重新执行：

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

⚠️ 注意：重跑前用 kk precheck（用法见《KubeSphere 4.1 常用 CLI 命令与工具详解》第四章）预检；重跑时报「kubelet service must be running and active」的排障实录见部署篇第八章。

修改方式二：--set 命令行覆盖，不必改文件。kk create cluster --help 实测参数（节选）：

Flags:
  -a, --artifact string          Path of a KubeKey artifact
  -c, --config string            the config file path. support *.yaml
  -i, --inventory string         the host list file path. support *.yaml
  -n, --namespace string         the namespace which playbook will be executed, all reference resources(playbook, config, inventory, task) should in the same namespace (default "default")
      --set stringArray          set value in config. format --set key=val or --set k1=v1,k2=v2
      --skip-tags stringArray    the tags of playbook which skip execute (blacklist). e.g. --skip-tags cri
      --tags stringArray         the tags of playbook which to execute (whitelist). e.g. --tags cri,os. NOTE: for create cluster this filters the whole playbook, so use --skip-tags to disable one precheck category.
      --with-kubernetes string   Specify a supported version of kubernetes. default is v1.37.0 (default "v1.37.0")
      --workdir string           the base Dir for KubeKey. Default current dir.  (default "/kubekey")

例如临时把区域源改为海外默认：kk create cluster -c config.yaml --set spec.zone=default。

3.2 第 2 层：ks-core Helm values

查看「用户实际传入的 values」与「全量计算后的 values」：

helm get values ks-core -n kubesphere-system

实测回显（安装时通过 --set 传入的值，正是部署篇 4.5 节的两行镜像源参数）：

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

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

实测回显为全量 COMPUTED VALUES（约 310 行，含全部默认值，关键块见第六章逐项解读；此处节选 apiserver 块展示格式）：

COMPUTED VALUES:
affinity:
  nodeAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
    - preference:
        matchExpressions:
        - key: node-role.kubernetes.io/control-plane
          operator: In
          values:
          - ""
      weight: 100
agent:
  replicaCount: 1
apiserver:
  command:
  - ks-apiserver
  - --logtostderr=true
  image:
    pullPolicy: IfNotPresent
    repository: kubesphere/ks-apiserver
    tag: ""
  resources:
    limits:
      cpu: 1
      memory: 1024Mi
    requests:
      cpu: 20m
      memory: 100Mi

修改方式：与安装同形的 helm upgrade --install 命令，改动通过 --set 表达，已传过的值用 --reuse-values 保留。标准形式（与部署篇 4.5 节安装命令完全同形，改参数即重跑该命令）：

helm upgrade --install -n kubesphere-system ks-core \
  https://charts.kubesphere.io/main/ks-core-1.1.5.tgz \
  --reuse-values \
  --set console.nodePort=30880

生效验证分两步：第一步确认 Helm 层已记录（helm history 的 REVISION 递增），第二步确认运行时对象已更新（Deployment resources 等以 kubectl get -o jsonpath 实读）。本环境当前的 Helm 历史实测：

helm history ks-core -n kubesphere-system

实测回显：

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

⚠️ 注意（实测踩坑）：helm upgrade --install 引用 https://charts.kubesphere.io/main/ks-core-1.1.5.tgz 依赖该 URL 可下载。2026-10-24 实测发现该地址开始对 .tgz 请求返回官网 HTML 页而非 Chart 包，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'

定位过程：curl -sI https://charts.kubesphere.io/main/ks-core-1.1.5.tgz 实测返回 HTTP/2 200 但 content-type: text/html; charset=utf-8——HTTP 层「正常」、内容层已被替换，缓存里的 ks-core-1.1.5.tgz 用 head -c 200 看是 <!doctype html>... 的网页。解决办法：删掉被污染的缓存文件 rm -f ~/.cache/helm/repository/ks-core-1.1.5.tgz，改用事先留存的本机 Chart 包执行升级（helm upgrade --install ... /path/to/ks-core-1.1.5.tgz --reuse-values --set ...）。建议每次成功安装后把当次 Chart 包备份到本地固定目录，升级不依赖外网。

3.3 第 3 层：平台运行时 ConfigMap（kubesphere-config）

查看：

kubectl get cm -n kubesphere-system

实测回显：

NAME                DATA   AGE
ks-console-config   1      8h
kube-root-ca.crt    1      8h
kubesphere-config   1      8h

kubectl get cm -n kubesphere-system kubesphere-config -o yaml

实测回显（data.kubesphere.yaml 键，即 ks-apiserver 的运行时配置；jwtSecret 为系统级真实密钥，此处脱敏，实际值查看命令紧跟其后）：

authentication:
  authenticateRateLimiterMaxTries: 10
  authenticateRateLimiterDuration: 10m0s
  loginHistoryRetentionPeriod: 168h
  multipleLogin: true
  issuer:
    url: "http://ks-console.kubesphere-system.svc:30880"
    jwtSecret: "${JWT_SECRET}"
    maximumClockSkew: 10s
    accessTokenMaxAge: 2h
    accessTokenInactivityTimeout: 30m
s3:
  endpoint: ""
  region: us-east-1
  disableSSL: true
  forcePathStyle: true
  accessKeyID: admin
  secretAccessKey: admin
  bucket: uploads
multicluster:
  clusterRole: "host"
  hostClusterName: "host"
kubeconfig:
  authMode: client-certificate
terminal:
  kubectl:
    image: "hub.kubesphere.com.cn/kubesphere/kubectl:v1.27.16"
  node:
    image: "hub.kubesphere.com.cn/kubesphere/kubectl:v1.27.16"
  uploadFileLimit: 100Mi
helmExecutor:
  image: "hub.kubesphere.com.cn/kubesphere/kubectl:v1.27.16"
  timeout: 10m
  historyMax: 2
  jobTTLAfterFinished: 0s
  resources:
    limits:
      cpu: 500m
      memory: 500Mi
    requests:
      cpu: 100m
      memory: 100Mi
extension:
  imageRegistry: "hub.kubesphere.com.cn"
experimental:
  validationDirective: ""
composedApp:
  appSelector: ""
kubesphere:
  tls: false
auditing:
  auditLevel: Metadata
  enable: false
  logOptions:
    maxAge: 7
    maxBackups: 10
    maxSize: 100
    path: /etc/audit/audit.log

jwtSecret 实际值获取方式（敏感值不入正文，按需在服务器上执行）：

kubectl -n kubesphere-system get cm kubesphere-config -o jsonpath='{.data.kubesphere\.yaml}' | grep jwtSecret

修改方式与生效路径：kubectl -n kubesphere-system edit cm kubesphere-config 修改对应键后，重启消费方使其重读配置：

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 即为已生效。

⚠️ 注意：kubesphere-config 由 ks-core Chart 管理（annotations 中有 meta.helm.sh/release-name: ks-core），直接 edit cm 的改动会在下一次 helm upgrade 时被 Chart 渲染值覆盖。权威改法是改 Helm values（如 --set authentication.authenticateRateLimiterMaxTries=5）再升级，让 Chart 重新渲染 ConfigMap；edit cm 只适合临时试验。两种改法殊途同归：Chart values 中的键名与 kubesphere.yaml 中的键一一对应。

3.4 第 4 层：控制台 ConfigMap（ks-console-config）

kubectl get cm -n kubesphere-system ks-console-config -o yaml

实测回显（data.local_config.yaml 键，ks-console（Node.js 进程）读取）：

server:
  http:
    hostname: localhost
    port: 8000
    static:
      production:
        /public: server/public
        /assets: dist/assets
        /dist: dist
  redis:
    port: 6379
    host: redis.kubesphere-system.svc
  redisTimeout: 5000
  sessionTimeout: 7200000
  apiServer:
    url: http://ks-apiserver
    wsUrl: ws://ks-apiserver

client:
  version:
    kubesphere: v4.1.3
    kubernetes: v1.37.0
  enableKubeConfig: true
  enableNodeListTerminal: true

修改方式与 3.3 相同：kubectl -n kubesphere-system edit cm ks-console-config 后重启消费方 kubectl rollout restart deployment -n kubesphere-system ks-console；注意该 ConfigMap 同样由 ks-core Chart 管理，权威改法是 --set console.config.<key>=<value> 后升级（如关闭 Node 列表页的网页终端入口：--set console.config.enableNodeListTerminal=false）。

3.5 修改后如何确认「真的生效了」

无论改哪一层，最终都要落到「运行时对象实读」上，避免只看工具回显：

kubectl get deploy -n kubesphere-system ks-apiserver -o jsonpath='{.spec.template.spec.containers[0].resources}'

实测回显（与 3.2 中 COMPUTED VALUES 的 apiserver.resources 完全一致，说明 Helm 值已落到 Deployment）：

{"limits":{"cpu":"1","memory":"1Gi"},"requests":{"cpu":"20m","memory":"100Mi"}}

kubectl get endpoints -n kubesphere-system

实测回显（各组件后端就绪，控制台 8000、apiserver 9090、controller-manager 8443、扩展仓库 8080）：

Warning: v1 Endpoints is deprecated in v1.33+; use discovery.k8s.io/v1 EndpointSlice
NAME                    ENDPOINTS              AGE
extensions-museum       192.168.166.167:8080   8h
ks-apiserver            192.168.166.169:9090   8h
ks-console              192.168.166.170:8000   8h
ks-controller-manager   192.168.166.163:8443   8h

💡 技术拓展：Kubernetes 配置分发不止 Helm + ConfigMap 一种。常见方式对比——

方式原理适用场景
Helm values 渲染升级时整模板重渲染、可回滚有 Chart 管理的组件（本文 ks-core 采用）
直接改 ConfigMap + 重启改动即时、绕过包管理临时试验（会被下次升级覆盖）
Kustomize overlay多环境差异化 patchGitOps 多集群/多环境
Operator CRD控制器 watching CR 自动调和有专用 Operator 的组件

KubeSphere v4.1.3 的 ks-core 由官方 Chart 全权管理，本文采用 Helm values 为主、ConfigMap 直改为辅。

四、参数总览

三层参数域的关键参数与默认值总表（全部取自本环境实测：COMPUTED VALUES 为 helm get values -a、ConfigMap 为 kubectl get cm -o yaml、集群配置为 /root/config.yaml 原文）：

层参数域关键参数实测默认值作用
KubeKey下载源spec.zonecn国内源优先
KubeKeyK8skubernetes.kube_versionv1.37.0集群版本
KubeKey控制面端点control_plane_endpoint.typelocal单 master；多 master 用 kube-vip/haproxy
KubeKeyCRIcri.container_managercontainerd运行时类型
KubeKeyCNIcni.type / cni.calico_versioncalico / v3.32.2网络插件及版本
KubeKey存储storage_class.local.enabledtrue（且 default）本地 PV 存储类
KubeKeyDNSdns.coredns.image.tagv1.14.6CoreDNS 版本
ks-core镜像源global.imageRegistry（安装时设为 hub.kubesphere.com.cn）全组件镜像前缀
ks-core版本global.tagv4.1.3核心组件镜像 tag
ks-coreapiserver 资源apiserver.resourceslimits 1CPU/1024Mi，requests 20m/100Miks-apiserver 限额
ks-corecontroller 资源controller.resourceslimits 1CPU/1000Mi，requests 30m/50Miks-controller-manager 限额
ks-core控制台端口console.nodePort30880NodePort 端口
ks-coreRedisredis.persistentVolumeenabled，2Gi，镜像 7.2.4-alpine会话/队列存储
ks-core上传对象存储s3.*endpoint 空（内置 MinIO 模式），bucket uploads控制台上传文件
ks-core高可用ha.enabled / redisHA.enabledfalse / false组件多副本与 Redis HA
ks-coreIngressingress.enabledfalse七层入口（默认仅 NodePort）
ks-core扩展仓库ksExtensionRepository.enabledtrue扩展市场后端
ks-core遥测telemetry.enabledtrue匿名使用统计上报
运行时认证限流authentication.authenticateRateLimiterMaxTries10（时长 10m0s）连续错 10 次锁 10 分钟
运行时Tokenissuer.accessTokenMaxAge / InactivityTimeout2h / 30m登录态有效期
运行时多端登录authentication.multipleLogintrue同一账号多地登录
运行时多集群multicluster.clusterRolehost主/成员集群角色
运行时终端镜像terminal.kubectl.imagehub.kubesphere.com.cn/kubesphere/kubectl:v1.27.16网页终端镜像
运行时Helm 执行器helmExecutor.timeout / historyMax10m / 2扩展安装超时与历史数
运行时审计auditing.enable / auditLevelfalse / Metadata平台审计日志
控制台会话server.sessionTimeout7200000（毫秒，2h）Web 会话超时
控制台Node 终端client.enableNodeListTerminaltrue节点列表网页终端开关

关键差异与选型提示：KubeKey 层参数决定「装什么」，装完后改动成本高（需重跑安装）；ks-core 与 ConfigMap 层参数决定「跑成什么样」，随时可改可回滚。资源类参数（resources/nodePort）只在前两层；行为类参数（认证/审计/终端）几乎都在第三层。

五、KubeKey 集群配置参数详解

5.1 config.yaml 全分区解读

以下分区与键名全部来自本环境 /root/config.yaml（kk create config 生成后未删注释，注释内默认值即官方默认）。逐分区说明：

（1）spec.zone —— 默认 cn。cn 时 KubeKey 下载二进制/镜像优先走国内源（本环境实测生效：ks-core 组件镜像全部落在 hub.kubesphere.com.cn）。海外服务器建议 default。

（2）spec.kubernetes —— 集群内核参数：

键默认值说明
kube_versionv1.37.0K8s 版本，须在 kk 支持列表内
helm_versionv3.18.5随装 Helm 版本
sandbox_image.tag3.10.2Pod sandbox（pause）镜像
control_plane_endpoint.typelocallocal/kube-vip/haproxy 三选一
control_plane_endpoint.kube_vip.image.tagv0.7.2kube-vip 静态 Pod 镜像（type=kube-vip 时生效）
control_plane_endpoint.haproxy.image.tag2.9.6-alpineHAProxy 静态 Pod 镜像（type=haproxy 时生效）

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

类型原理适用场景
localAPI Server 绑定本机，无 VIP单 master / all-in-one（本环境采用）
kube-vip静态 Pod 提供 VIP 漂移，无需额外硬件无负载均衡器的自建多 master
haproxy每节点静态 Pod 反代各 master已有或偏好外部 LB 的场景

单机选 local；三节点及以上选 kube-vip（无 LB）或 haproxy（有 LB 习惯）。

（3）spec.etcd —— etcd_version: v3.7.0（K8s 1.37 默认对应版本；kubeadm 以静态 Pod 方式部署）。

（4）spec.image_registry —— 私有镜像仓库（离线环境核心参数）：

键默认值说明
type""（不装）harbor / docker-registry
auth.registry无私仓地址 host:port/project
auth.plain_httpfalse是否 HTTP 明文
auth.username / auth.password无私仓凭据（敏感，建议 Ansible-Vault 类方式管理）
ha_vip""设了即启用多仓库节点高可用 VIP
keepalived_version2.3.4HA VIP 用 keepalived 版本
harbor_versionv2.10.2type=harbor 时 Harbor 版本
docker_registry_version2.8.3type=docker-registry 时版本
http_port / https_port80 / 443一般由 registry 地址与 plain_http 自动推导

（5）spec.cri —— 容器运行时：

键默认值说明
container_managercontainerdcontainerd / docker
crictl_versionv1.37.0跟随 kube_version minor
docker_version29.7.2（注释）仅 container_manager=docker 时生效
cridockerd_versionv0.4.7（注释）K8s 1.24+ 用 docker 时的垫片
containerd_versionv2.3.3（注释）K8s 1.36+ 要求 containerd 2.x
runc_versionv1.4.3（注释）OCI 运行时

（6）spec.cni —— 网络插件：type 支持 calico/cilium/flannel/kubeovn/other，默认 calico；multi_cni 支持 multus/spiderpool/none，默认 none；各插件版本键 calico_version: v3.32.2、cilium_version: 1.20.1、flannel_version: v0.28.9、kubeovn_version: v1.16.2。注意 Calico v3.32 的 e2e 矩阵到 K8s 1.36，1.37 依赖前向兼容（config 注释原文实查）。

（7）spec.storage_class —— 存储类：

键默认值说明
local.enabled / local.defaulttrue / trueOpenEBS 本地 PV 存储类并设默认
localpv_provisioner_version4.4.0dynamic-localpv-provisioner Chart 版本
nfs.enabledfalseNFS 存储类
nfs_provisioner_version4.0.18（注释）NFS provisioner Chart 版本

（8）spec.dns —— 集群 DNS：coredns.image.tag: v1.14.6（K8s 1.37 kubeadm 常量默认）；nodelocaldns.enabled: true、镜像 1.26.8（NodeLocalDNS 缓存层）。

（9）spec.image_manifests —— 默认 []；离线 artifact 场景下追加需要打进离线包的额外镜像清单。

5.2 inventory.yaml 主机清单参数

kk v4 采用「配置 + 清单」双文件模型，节点、连接方式、分组全在 inventory.yaml。本环境实测文件（/root/inventory.yaml，all-in-one 默认全部指向 localhost）：

apiVersion: kubekey.kubesphere.io/v1
kind: Inventory
metadata:
  name: default
spec:
  hosts: # your can set all nodes here. or set nodes on special groups.
  groups:
    # all kubernetes nodes.
    k8s_cluster:
      groups:
        - kube_control_plane
        - kube_worker
    # control_plane nodes
    kube_control_plane:
      hosts:
        - localhost
    # worker nodes
    kube_worker:
      hosts:
        - localhost
    # etcd nodes when etcd_deployment_type is external
    etcd:
      hosts:
        - localhost

关键参数说明：spec.hosts 中每个主机可声明 connector（type: ssh、host、port、user、password，本机 all-in-one 免填）、internal_ipv4（节点内网 IP）、storage（块设备 → LVM VG/LV → 文件系统 → 挂载点，供存储类使用）；groups 定义四个标准组：k8s_cluster（聚合组）、kube_control_plane、kube_worker、etcd（外置 etcd 时用）。多节点部署时把各节点逐个加进 hosts 并按角色分入对应组即可，逐节点条目必须单独成块书写。

六、ks-core Helm values 参数详解

以下全部键名为 helm get values ks-core -n kubesphere-system -a 实测输出（COMPUTED VALUES，310 行）中的真实默认值。

6.1 镜像与版本

键默认值说明
global.imageRegistry""全组件镜像仓库前缀；国内环境设 hub.kubesphere.com.cn（本环境实测生效）
global.tagv4.1.3ks-apiserver / ks-controller-manager / ks-console 组件镜像 tag
extension.imageRegistry""扩展组件镜像前缀
global.imagePullSecrets[]私仓拉取凭据
*.image.pullPolicyIfNotPresent拉取策略

6.2 组件资源限额

组件limits（实测默认）requests（实测默认）启动命令（实测）
ks-apiservercpu 1 / memory 1024Micpu 20m / memory 100Miks-apiserver --logtostderr=true
ks-controller-managercpu 1 / memory 1000Micpu 30m / memory 50Micontroller-manager --logtostderr=true --leader-elect=true --controllers=*
ks-consolecpu 1 / memory 1024Micpu 20m / memory 100Mi（Chart 内置 Node.js 启动）
helmExecutor Jobcpu 500m / memory 500Micpu 100m / memory 100Mi（临时 Job 执行扩展安装）

修改示例（把 apiserver 上限提到 2C/2Gi）：

helm upgrade --install -n kubesphere-system ks-core /path/to/ks-core-1.1.5.tgz \
  --reuse-values --set apiserver.resources.limits.cpu=2 --set apiserver.resources.limits.memory=2Gi

生效后用 3.5 节的 jsonpath 实读复核。

6.3 控制台与入口

键默认值说明
console.nodePort30880ks-console Service 的 NodePort
console.config.enableNodeListTerminaltrue节点列表页网页终端开关
ingress.enabledfalse七层 Ingress 入口（开了就不再依赖裸 NodePort）
ingress.tls.enabled / secretName / sourcetrue / kubesphere-tls-certs / generationTLS 证书来源
letsEncrypt.environmentproductionLet's Encrypt 环境
internalTLSfalse组件间内部 TLS
portal.hostnameks-console.kubesphere-system.svc控制台主机名

本环境 Service 实测（ks-console 为 NodePort 30880）：

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

6.4 存储与依赖组件

键默认值说明
redis.image.repository/tagkubesphere/redis / 7.2.4-alpine内置 Redis
redis.persistentVolume.enabled/sizetrue / 2GiRedis 持久卷
redisHA.enabledfalseRedis 主从 + HAProxy（镜像 2.9.6-alpine）
ha.enabledfalse核心组件多副本高可用
s3.endpoint/region/bucket"" / us-east-1 / uploads上传文件对象存储（endpoint 空时走内置模式）
s3.accessKeyID/secretAccessKeyadmin / admin（Chart 默认值）⚠️ 生产必须改强口令
ksExtensionRepository.enabledtrue扩展市场仓库（ks-extensions-museum v1.1.5）
ksCRDs.tagv4.1.3KubeSphere CRD 镜像版本（imageRegistry 默认 docker.io）
upgrade.enabledfalsev3 → v4 升级作业（ks-upgrade 镜像，5Gi 卷）
telemetry.enabledtrue匿名遥测；内网环境可 --set telemetry.enabled=false 关闭
serviceAccount.namekubesphere组件服务账号
affinity / tolerationscontrol-plane 亲和 / master+control-plane 容忍默认调度策略（偏向控制面节点）

6.5 多集群参数

键默认值说明
multicluster.role""（默认单集群，等价 host）host / member
multicluster.hostClusterName""主集群名称

与运行时 ConfigMap 的 multicluster.clusterRole: "host" 联动：values 改角色后 Chart 会重渲染 ConfigMap，两者不要手工分别改。

七、平台运行时 ConfigMap 参数详解

7.1 kubesphere-config（ks-apiserver / controller-manager 消费）

逐项解读（默认值均为 3.3 节实测原文）：

  • authentication —— 认证行为：authenticateRateLimiterMaxTries: 10 + authenticateRateLimiterDuration: 10m0s（连续错 10 次锁 10 分钟，暴力破解防护第一道闸）；loginHistoryRetentionPeriod: 168h（登录历史保留 7 天）；multipleLogin: true（是否允许同账号多端同时在线，安全要求高的环境改 false）；issuer.accessTokenMaxAge: 2h 与 accessTokenInactivityTimeout: 30m（Token 绝对有效期与空闲超时，双闸设计）；maximumClockSkew: 10s（校验容忍时钟偏差）；jwtSecret 为签发密钥（系统级密钥，泄露即全域登录态失守，轮换会使所有在线用户下线重登）。
  • s3 —— 控制台文件上传后端：默认 endpoint: "" + bucket: uploads + accessKeyID/secretAccessKey: admin/admin（Chart 内置默认，仅适合单机体验）；对接外部对象存储（MinIO/S3 兼容）时填 endpoint 并改强口令；disableSSL: true、forcePathStyle: true 为路径风格访问。
  • multicluster —— clusterRole: "host"、hostClusterName: "host"：本集群默认是主集群；作为成员接入时改为 member 并由主集群纳管。
  • kubeconfig.authMode —— client-certificate（可选 service-account-token/oidc-token/webhook-token）：平台代用户访问成员集群凭据的签发方式。
  • terminal —— 网页终端：kubectl.image / node.image 均为 hub.kubesphere.com.cn/kubesphere/kubectl:v1.27.16（离线环境注意把该镜像同步进私仓）；uploadFileLimit: 100Mi（终端上传上限）。
  • helmExecutor —— 扩展安装执行器：临时 Job 跑 Helm，timeout: 10m、historyMax: 2（历史 Job 保留数）、jobTTLAfterFinished: 0s（0=完成后立即由平台清理）、资源 500m/500Mi；其 affinity 偏向与 ks-controller-manager 同节点。
  • extension.imageRegistry —— hub.kubesphere.com.cn：扩展组件拉镜像的前缀（与 values 的 extension.imageRegistry 联动）。
  • auditing —— 平台审计：默认 enable: false、auditLevel: Metadata（可选 Request/RequestResponse，粒度越细成本越高）；开启后日志写 /etc/audit/audit.log，轮转 maxAge: 7 天、maxBackups: 10、单文件 maxSize: 100 MB。

7.2 ks-console-config（ks-console 消费）

  • server.http.port —— 控制台进程监听 8000（Service 80 → 容器 8000 → NodePort 30880 三级映射）。
  • server.redis —— 会话存储指向 redis.kubesphere-system.svc:6379；redisTimeout: 5000（毫秒）；sessionTimeout: 7200000（毫秒 = 2 小时 Web 会话）。
  • server.apiServer —— 后端直连 http://ks-apiserver 与 ws://ks-apiserver（WebSocket 供终端/日志流使用）。
  • client.version —— 控制台页脚展示的平台与 K8s 版本（v4.1.3 / v1.37.0），由 Chart 渲染，勿手改。
  • client.enableKubeConfig / enableNodeListTerminal —— 是否允许用户上传 kubeconfig、是否开启节点列表网页终端；收紧运维面时把后者关掉。

八、进程资源与 JVM 说明

本章正面回答「KubeSphere 要不要调 JVM 堆」：KubeSphere v4.1.3 核心组件没有任何 Java 进程，不存在 JAVA_OPTS/堆配置项。核心四个工作负载全部是 Go 编译的静态二进制或 Node.js 前端进程，内存占用由 K8s resources limits 约束（见 6.2 表）。实测核实方法（在部署了 KubeSphere 的服务器上执行）：

ps -ef | grep -i java | grep -v grep; echo "exit=$?"

实测回显（无任何 java 进程行，grep 退出码 1）：

exit=1

运行中工作负载的进程清单亦可用 crictl 实读（ks-console / ks-apiserver 均为 Go/Node 镜像）：

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

核心进程的资源上限来自 Helm values（6.2 表），改法与复核见 6.2 与 3.5，无须、也没有 JVM 参数可调。

何时才出现 JVM：安装 DevOps 扩展（KubeSphere DevOps）后会引入 Jenkins（Java）。该场景下 Jenkins 堆内存不走本文三层参数，而在扩展自身的 values 中配置——在控制台「扩展管理 → DevOps → 编辑配置」或对应 Chart values 的 JVM 选项（如 javaOpts/JAVA_OPTS 类键）里设置，建议按经验值 -Xms256m -Xmx512m 起步（KubeSphere 官方扩展文档「DevOps 安装与配置」页有参数说明，查询日期 2026-10-24）。生效验证方法（安装该扩展后执行）：kubectl -n kubesphere-devops-system get pods 拿到 Jenkins Pod 后 crictl inspect <容器ID> | grep -i java 或进入 Pod 用 ps -ef | grep java 核对实际 -Xms/-Xmx 值。本文环境未安装 DevOps 扩展，故无对应回显；上述键名以所装扩展版本的实际 values 为准。

九、生产配置模板

9.1 单机/小规模模板（8–16GB 内存、单盘、试验或边缘场景）

基于本环境实测配置精简而成，可直接作为 config.yaml 使用：

apiVersion: kubekey.kubesphere.io/v1
kind: Config
spec:
  zone: cn
  kubernetes:
    kube_version: v1.37.0
    helm_version: v3.18.5
    control_plane_endpoint:
      type: local
  etcd:
    etcd_version: v3.7.0
  cri:
    container_manager: containerd
    crictl_version: v1.37.0
  cni:
    type: calico
    multi_cni: none
    calico_version: v3.32.2
  storage_class:
    local:
      enabled: true
      default: true
    localpv_provisioner_version: 4.4.0
  dns:
    coredns:
      image:
        tag: v1.14.6
    nodelocaldns:
      enabled: true
      image:
        tag: 1.26.8
  image_manifests: []

配套 ks-core 安装参数（16GB 内存以下建议同时压资源上限，防止与系统争内存——实测默认 limits 已是 1C/1Gi 级，一般无需再压）：

helm upgrade --install -n kubesphere-system --create-namespace ks-core \
  /path/to/ks-core-1.1.5.tgz \
  --set global.imageRegistry=hub.kubesphere.com.cn \
  --set extension.imageRegistry=hub.kubesphere.com.cn \
  --set telemetry.enabled=false \
  --wait

9.2 三节点高可用模板（32GB+ 内存/节点，生产入门）

改动集中在四处：控制面端点换 kube-vip、etcd 随控制面三副本、ha.enabled 打开、Redis 换主从。inventory.yaml 逐节点单独成块：

apiVersion: kubekey.kubesphere.io/v1
kind: Inventory
metadata:
  name: prod
spec:
  hosts:
    - node1:
        connector:
          type: ssh
          host: 192.168.10.11
          port: 22
          user: root
          password: "${NODE1_SSH_PASS}"
        internal_ipv4: 192.168.10.11
    - node2:
        connector:
          type: ssh
          host: 192.168.10.12
          port: 22
          user: root
          password: "${NODE2_SSH_PASS}"
        internal_ipv4: 192.168.10.12
    - node3:
        connector:
          type: ssh
          host: 192.168.10.13
          port: 22
          user: root
          password: "${NODE3_SSH_PASS}"
        internal_ipv4: 192.168.10.13
  groups:
    k8s_cluster:
      groups:
        - kube_control_plane
        - kube_worker
    kube_control_plane:
      hosts:
        - node1
        - node2
        - node3
    kube_worker:
      hosts:
        - node1
        - node2
        - node3
    etcd:
      hosts:
        - node1
        - node2
        - node3

config.yaml 在 9.1 基础上只改控制面端点段：

    control_plane_endpoint:
      type: kube-vip
      kube_vip:
        image:
          tag: v0.7.2
        # kube-vip 对外 VIP，三台机器共用
        vip: 192.168.10.10

ks-core 高可用增量参数：

helm upgrade --install -n kubesphere-system --create-namespace ks-core \
  /path/to/ks-core-1.1.5.tgz \
  --set global.imageRegistry=hub.kubesphere.com.cn \
  --set extension.imageRegistry=hub.kubesphere.com.cn \
  --set ha.enabled=true \
  --set redisHA.enabled=true \
  --set telemetry.enabled=false \
  --wait

⚠️ 注意：SSH 密码等系统级真实凭据一律用 ${VAR} 形式写在文件里，并另行用 export NODE1_SSH_PASS=... 注入或改用 SSH 密钥登录（connector.user + 免密）；上表 6.4 的 s3.accessKeyID/secretAccessKey 生产环境同理必须改掉 Chart 默认的 admin/admin。

十、常见问题（FAQ）

Q1：控制台用 http://localhost:30880 打不开，但用服务器 IP 能打开？ 实测复现：在同一台服务器上 curl -s -o /dev/null -w "HTTP %{http_code}\n" --max-time 5 http://localhost:30880/login 返回 HTTP 000（连接失败），而 http://10.89.59.2:30880/login 返回 HTTP 200（从服务器本机与外部访问均 200）。结论：NodePort 经本机回环地址的转发在本环境不可达（kube-proxy 转发链路对 loopback 目标的已知限制），访问控制台一律用服务器 IP 或域名：http://<服务器IP>:30880。

Q2：改了 ConfigMap，重装/升级后被改回去了？ kubesphere-config、ks-console-config 都带 meta.helm.sh/release-name: ks-core 注解，由 Chart 管理，helm upgrade 会按 values 重新渲染覆盖手工改动。权威改法见 3.3/3.4：改 --set 后走 helm upgrade --reuse-values。

Q3：helm upgrade 报 "does not appear to be a gzipped archive; got 'text/html; charset=utf-8'"？ Chart 下载地址返回了网页而非 Chart 包（本环境 2026-10-24 实测，见 3.2 ⚠️）。修复：rm -f ~/.cache/helm/repository/ks-core-<版本>.tgz，改用本地留存的 Chart 包执行升级；建议安装成功后立即备份 Chart 文件。

Q4：jwtSecret 能改吗？ 能，但轮换即失效所有已签发 Token（全员掉线重登），且主/成员集群的 secret 必须一致才能互信。改法：--set authentication.issuer.jwtSecret=<新值> 升级（Chart 会同步渲染进 kubesphere-config）。该值绝不入库、不入文档。

Q5：控制台页脚版本号在哪里控制？ ks-console-config 的 client.version.kubesphere/kubernetes（3.4 节实测原文 v4.1.3 / v1.37.0），由 Chart 按 global.tag 渲染，随版本升级自动更新，不要手工编辑。

Q6：遥测上报能否关闭？ 可以：--set telemetry.enabled=false 升级即可（默认 true，见 6.4）。离线/内网生产环境建议关闭。

十一、参考链接