KubeSphere 安装到插件管理实战：本地 K8s 搭建可视化容器平台

📝 本文首发于栏轩·阁

欢迎访问阅读原文，获取更好的阅读体验。

一、KubeSphere 是什么？

KubeSphere 是一个面向云原生应用的开源容器混合云平台，支持 Kubernetes 多集群管理。它在原生 K8s 的基础上提供了可视化的 Web 控制台，让开发者可以通过图形界面管理集群资源。

核心功能

Web 控制台：可视化查看和管理 Deployment、Pod、Service、ConfigMap 等 K8s 资源
多集群管理：一个控制台同时管理多个 K8s 集群
可观测性：内置监控、日志、告警功能
DevOps：内置 CI/CD 流水线引擎
应用商店：一键部署中间件（MySQL、Redis、Nginx 等）
多租户管理：项目、角色、权限管控

二、为什么要使用 KubeSphere 而不直接操作 K8s？

场景	直接操作 K8s	使用 KubeSphere
查看 Pod 状态	`kubectl get pods`，想看日志再加 `kubectl logs`	Web 页面点几下就行
部署应用	编写 Deployment YAML → `kubectl apply`	应用商店一键部署
监控资源	需额外部署 Prometheus + Grafana	内置监控面板
多团队协作	需手动配置 RBAC	内置多租户管理
发布流水线	需单独搭建 Jenkins 等	内置 DevOps 引擎

总结：K8s 本身是命令行工具，KubeSphere 在其之上提供了一个图形化管理界面。如果你习惯命令行，只用 K8s 完全够用；如果你想要可视化操作和开箱即用的附加功能（监控、日志、DevOps），KubeSphere 可以大大降低管理成本。

三、安装环境确认

本文的安装环境如下：

复制代码

宿主机：Windows 11 + WSL 2 Ubuntu 22.04
Docker Desktop：已启用 K8s 集群
K8s 节点：1 control-plane（单节点）

安装文档参考：KubeSphere 官方安装指南

四、安装 KubeSphere

4.1 确认基础环境

打开 FinalShell（或 WSL 终端），先检查环境是否满足要求。

检查 K8s 集群状态：

bash 复制代码

kubectl get nodes
kubectl get pods -n kube-system

节点应为 Ready 状态，系统组件全部 Running。

检查 Helm 是否已安装：

bash 复制代码

helm version

Helm 是什么？

Helm 是 K8s 的包管理器，类似 Ubuntu 的 apt 或 CentOS 的 yum。KubeSphere 通过 Helm Chart 进行安装和管理。

如果未安装 Helm，根据你的环境选择安装方式：

WSL / Linux 环境：

bash 复制代码

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
helm version

Windows 环境：

访问 Helm 官方 GitHub Releases 下载适合 Windows 的安装包（如 helm-v3.x.x-windows-amd64.zip）
解压安装包，将解压目录中的 helm.exe 所在路径添加到系统环境变量 PATH 中
重新打开 PowerShell 验证安装：

powershell 复制代码

helm version

4.2 执行安装命令

确认环境正常后，运行以下命令安装 KubeSphere。

在 WSL / Linux 终端中执行：

bash 复制代码

chart=oci://hub.kubesphere.com.cn/kse/ks-core
version=1.2.3-20251118
helm upgrade --install -n kubesphere-system --create-namespace ks-core $chart \
  --debug --wait --version $version --reset-values \
  --set extension.imageRegistry=swr.cn-north-9.myhuaweicloud.com/ks

在 Windows PowerShell 中执行：

powershell 复制代码

helm upgrade --install -n kubesphere-system --create-namespace ks-core `
  oci://hub.kubesphere.com.cn/kse/ks-core --debug --wait `
  --version 1.2.3-20251118 --reset-values `
  --set extension.imageRegistry=swr.cn-north-9.myhuaweicloud.com/ks

⚠️ 注意：后续的 kubectl patch 等命令涉及单引号和特殊字符，Windows PowerShell 兼容性较差，推荐在 WSL 终端中执行。因此建议安装步骤也在 WSL 中完成，保持环境统一。

命令参数说明：

参数	作用
`chart=oci://hub.kubesphere.com.cn/kse/ks-core`	指定 KubeSphere Helm Chart 的 OCI 仓库地址
`version=1.2.3-20251118`	指定安装版本
`--namespace kubesphere-system --create-namespace`	在 `kubesphere-system` 命名空间中安装
`--debug --wait`	输出调试信息，等待安装完成
`--set extension.imageRegistry=swr.cn-north-9.myhuaweicloud.com/ks`	指定镜像仓库为华为云（国内加速）

4.3 安装过程排错：镜像拉取超时

安装过程中如果卡住或超时，最常见的原因是镜像拉取失败（国内网络问题导致）。

排查方法：

bash 复制代码

# 查看 Pod 状态，找到异常的 Pod
kubectl get pods -n kubesphere-system

# 查看具体原因
kubectl describe pod -n kubesphere-system <异常的Pod名称>

我安装时就遇到了 extensions-museum:v11.1.2 这个镜像拉取超时。解决方法是手动用 Docker 拉取（Docker 配置了镜像加速器，拉取速度更快）：

bash 复制代码

# 手动拉取（注意版本和仓库路径与原始一致）
docker pull registry.cn-beijing.aliyuncs.com/kse/extensions-museum:v11.1.2

# 拉取完成后重新检查 Pod，KubeSphere 会自动重试
kubectl get pods -n kubesphere-system

原理：Docker Desktop 启用了 containerd 镜像存储后（Settings → General → Use containerd），Docker 拉取的镜像会缓存到 containerd 中，K8s 可以直接复用，不需要重新拉取。

4.4 确认安装完成

当终端输出以下信息时，表示 ks-core 安装成功：

复制代码

NOTES:
Thank you for choosing KubeSphere Helm Chart.

1. Wait for Deployment Completion
   kubectl get pods -n kubesphere-system

2. Access the KubeSphere Console
   http://192.168.6.10:30880

3. Login to KubeSphere Console
   Account: admin    Password: P@88w0rd

查看所有组件的运行状态：

bash 复制代码

kubectl -n kubesphere-system get pods

所有 Pod 应为 Running 或 Completed 状态：

复制代码

NAME                                         READY   STATUS      RESTARTS   AGE
extensions-museum-56c6b698dc-hmwrj           1/1     Running     0          99s
helm-install-ks-console-embed-kpr7s4-65swb   0/1     Completed   0          5m36s
ks-apiserver-84fc8cd9f-7ktgl                 1/1     Running     0          99s
ks-console-64bb4fd85c-4cbch                  1/1     Running     0          5m36s
ks-console-embed-6b44dbf4db-tj9k7            1/1     Running     0          112s
ks-controller-manager-565bbfcbcd-6t8tf       1/1     Running     0          99s
ks-posthog-8bb9b99-c4sd7                     1/1     Running     0          13m

五、访问 KubeSphere 控制台

5.1 查看端口信息

bash 复制代码

kubectl get svc -n kubesphere-system ks-console

输出示例：

复制代码

NAME         TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
ks-console   NodePort   10.96.127.214   <none>        80:30880/TCP   20m

可以看到 Service 类型为 NodePort，将 K8s 内部端口 80 映射到了宿主机的 30880。

5.2 为什么无法直接访问 30880？

在 Docker Desktop 中，K8s 集群运行在容器环境中，与 Windows 宿主机存在网络隔离 。NodePort 类型的 Service 将端口绑定在 K8s 节点的网络内部，而 Docker Desktop 的"节点"本身就是 Docker 容器，Windows 宿主机的 localhost:30880 无法直接到达容器内部。

5.3 方案一：端口转发（快速调试）

不修改 Service 类型，直接用 port-forward 将本地端口流量转发到集群内部：

bash 复制代码

kubectl port-forward -n kubesphere-system svc/ks-console 30880:80 --address 0.0.0.0

svc/ks-console：直接转发 Service，K8s 会自动解析到后端 Pod
--address 0.0.0.0：绑定所有网络接口，局域网内其他设备也可访问

终端保持打开状态，浏览器访问 http://localhost:30880 即可。

port-forward 适合快速验证，终端关闭后转发即停止，不适合长期使用。

5.4 方案二（推荐）：改为 LoadBalancer 类型

Docker Desktop 内置了 LoadBalancer 支持 ------将 Service 改为 LoadBalancer 类型后，它会自动在宿主机上创建 Envoy 代理容器 （kubeadm 模式下为 docker-desktop-lb，kind 模式下为 kindccm-xxx），直接在 Windows 上监听端口，将流量转发到集群内部。这种方式终端关闭后依然可用，适合长期使用。

bash 复制代码

# 将 NodePort 改为 LoadBalancer
kubectl patch svc -n kubesphere-system ks-console -p '{"spec":{"type":"LoadBalancer"}}'

⚠️ Windows 命令兼容性 ：Windows 的 PowerShell 对单引号和特殊字符兼容较差，推荐在 WSL 终端中执行上述命令。

查看是否分配了 External-IP：

bash 复制代码

kubectl get svc -n kubesphere-system ks-console

正常情况下 EXTERNAL-IP 会显示 localhost，此时浏览器打开 http://localhost:30880 即可访问。

端口冲突处理 ：如果该端口已被占用，代理容器会创建失败，EXTERNAL-IP 会一直处于 <pending> 状态。

正确的操作顺序如下（顺序很重要）：

bash 复制代码

# 1. 查找旧的代理容器
docker ps -a --filter "name=kindccm"

# 2. 删除旧容器（Docker Desktop 会自动重建）
docker rm -f kindccm-LXUFEC6ZYEIUPGUBRWB556226BYGOZKZSQBDOQZS

# 3. 修改 Service 端口（避开被占用的端口）
kubectl patch svc -n kubesphere-system ks-console --type='json' \
  -p='[{"op":"replace","path":"/spec/ports/0/port","value":30880}]'

等待几分钟后再次查看运行状态：

bash 复制代码

kubectl get svc -n kubesphere-system ks-console

⚠️ 关键顺序 ：先删除旧容器 → 再修改端口，这样 Docker Desktop 会自动创建新的代理容器。如果先改端口再删旧容器，新容器不会自动创建，需要重启 Docker Desktop。

5.5 登录系统

浏览器打开 http://localhost:30880/login，看到登录页面：

默认账号密码：

账号	密码
`admin`	`P@88w0rd`

⚠️ 首次登录后强烈建议修改默认密码。

六、激活 KubeSphere

6.1 为什么要激活？

KubeSphere 社区版免费使用，但需要通过激活来启用扩展中心，否则无法安装插件（如 DevOps、应用商店等）。激活后可以享受完整的插件生态。

6.2 激活步骤

第一步 ：登录 KubeSphere 控制台后，顶部会提示激活信息，点击进入激活页面。获取集群 ID。

第二步 ：访问 KubeSphere 社区版 License 申请页面，输入以下信息：

集群 ID（从 KubeSphere 页面复制）
邮箱地址
其他必要信息

提交后，激活码会发送到你的邮箱。

第三步：将收到的激活码填入 KubeSphere 激活页面，即可完成激活。

七、插件管理：以 DevOps 为例

激活后，可以通过扩展中心安装各种官方插件来扩展功能。

7.1 DevOps 是什么？

DevOps（开发运维一体化） 是将开发（Development）和运维（Operations）整合的一套实践。在 KubeSphere 中，DevOps 插件提供了内置的 CI/CD 流水线功能，可以自动完成代码构建、镜像打包、部署发布等流程。

7.2 安装 DevOps 插件

第一步 ：在 KubeSphere 控制台顶部菜单找到 扩展中心。

第二步 ：在扩展中心搜索 "DevOps"，点击安装。

第三步：选择要安装到的集群，配置参数后确认安装。

第四步：等待安装完成。可以在扩展中心查看安装进度。安装完成后，左侧导航栏会出现 DevOps 入口，即可创建和管理流水线。

7.3 其他插件

DevOps 插件的安装流程适用于其他所有插件，如：

应用商店：一键部署 MySQL、Redis、Nginx 等中间件
告警与通知：配置告警规则和通知渠道
日志系统：集中管理集群和应用日志
服务网格：Istio 集成，管理微服务流量

八、总结

本文从安装到使用，完整覆盖了 KubeSphere 的入门流程：

阶段	操作	关键点
安装	Helm 部署 ks-core	指定国内镜像仓库加速
排错	镜像拉取超时	Docker 手动拉取后 K8s 自动重试
访问	NodePort → LoadBalancer	端口冲突时手动指定端口
激活	申请免费 License	获取集群 ID，填入激活码
插件	扩展中心安装 DevOps	可视化操作，一键部署

KubeSphere 将 K8s 的复杂操作封装成了直观的图形界面，让开发者可以更专注于业务本身。基于这个环境，你可以进一步探索应用商店、多集群管理、监控告警等更多功能。