本文首发于 栏轩·阁欢迎访问阅读原文获取更好的阅读体验。一、KubeSphere 是什么KubeSphere是一个面向云原生应用的开源容器混合云平台支持 Kubernetes 多集群管理。它在原生 K8s 的基础上提供了可视化的 Web 控制台让开发者可以通过图形界面管理集群资源。核心功能Web 控制台可视化查看和管理 Deployment、Pod、Service、ConfigMap 等 K8s 资源多集群管理一个控制台同时管理多个 K8s 集群可观测性内置监控、日志、告警功能DevOps内置 CI/CD 流水线引擎应用商店一键部署中间件MySQL、Redis、Nginx 等多租户管理项目、角色、权限管控官网KubeSphere 官网二、为什么要使用 KubeSphere 而不直接操作 K8s场景直接操作 K8s使用 KubeSphere查看 Pod 状态kubectl get pods想看日志再加kubectl logsWeb 页面点几下就行部署应用编写 Deployment YAML →kubectl apply应用商店一键部署监控资源需额外部署 Prometheus Grafana内置监控面板多团队协作需手动配置 RBAC内置多租户管理发布流水线需单独搭建 Jenkins 等内置 DevOps 引擎总结K8s 本身是命令行工具KubeSphere 在其之上提供了一个图形化管理界面。如果你习惯命令行只用 K8s 完全够用如果你想要可视化操作和开箱即用的附加功能监控、日志、DevOpsKubeSphere 可以大大降低管理成本。三、安装环境确认本文的安装环境如下宿主机Windows 11 WSL 2 Ubuntu 22.04 Docker Desktop已启用 K8s 集群 K8s 节点1 control-plane单节点安装文档参考KubeSphere 官方安装指南四、安装 KubeSphere4.1 确认基础环境打开 FinalShell或 WSL 终端先检查环境是否满足要求。检查 K8s 集群状态kubectl get nodes kubectl get pods-nkube-system节点应为Ready状态系统组件全部Running。检查 Helm 是否已安装helm versionHelm 是什么Helm 是 K8s 的包管理器类似 Ubuntu 的apt或 CentOS 的yum。KubeSphere 通过 Helm Chart 进行安装和管理。如果未安装 Helm根据你的环境选择安装方式WSL / Linux 环境curlhttps://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3|bashhelm versionWindows 环境访问 Helm 官方 GitHub Releases 下载适合 Windows 的安装包如helm-v3.x.x-windows-amd64.zip解压安装包将解压目录中的helm.exe所在路径添加到系统环境变量PATH中重新打开 PowerShell 验证安装helm version4.2 执行安装命令确认环境正常后运行以下命令安装 KubeSphere。在 WSL / Linux 终端中执行chartoci://hub.kubesphere.com.cn/kse/ks-coreversion1.2.3-20251118 helm upgrade--install-nkubesphere-system --create-namespace ks-core$chart\--debug--wait--version$version--reset-values\--setextension.imageRegistryswr.cn-north-9.myhuaweicloud.com/ks在 Windows 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--setextension.imageRegistryswr.cn-north-9.myhuaweicloud.com/ks⚠️注意后续的kubectl patch等命令涉及单引号和特殊字符Windows PowerShell 兼容性较差推荐在WSL 终端中执行。因此建议安装步骤也在 WSL 中完成保持环境统一。命令参数说明参数作用chartoci://hub.kubesphere.com.cn/kse/ks-core指定 KubeSphere Helm Chart 的 OCI 仓库地址version1.2.3-20251118指定安装版本--namespace kubesphere-system --create-namespace在kubesphere-system命名空间中安装--debug --wait输出调试信息等待安装完成--set extension.imageRegistryswr.cn-north-9.myhuaweicloud.com/ks指定镜像仓库为华为云国内加速4.3 安装过程排错镜像拉取超时安装过程中如果卡住或超时最常见的原因是镜像拉取失败国内网络问题导致。排查方法# 查看 Pod 状态找到异常的 Podkubectl get pods-nkubesphere-system# 查看具体原因kubectl describe pod-nkubesphere-system异常的Pod名称我安装时就遇到了extensions-museum:v11.1.2这个镜像拉取超时。解决方法是手动用 Docker 拉取Docker 配置了镜像加速器拉取速度更快# 手动拉取注意版本和仓库路径与原始一致dockerpull registry.cn-beijing.aliyuncs.com/kse/extensions-museum:v11.1.2# 拉取完成后重新检查 PodKubeSphere 会自动重试kubectl get pods-nkubesphere-system原理Docker Desktop 启用了 containerd 镜像存储后Settings → General → Use containerdDocker 拉取的镜像会缓存到 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: P88w0rd查看所有组件的运行状态kubectl-nkubesphere-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 查看端口信息kubectl get svc-nkubesphere-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将本地端口流量转发到集群内部kubectl port-forward-nkubesphere-system svc/ks-console30880:80--address0.0.0.0svc/ks-console直接转发 ServiceK8s 会自动解析到后端 Pod--address 0.0.0.0绑定所有网络接口局域网内其他设备也可访问终端保持打开状态浏览器访问http://localhost:30880即可。port-forward适合快速验证终端关闭后转发即停止不适合长期使用。5.4 方案二推荐改为 LoadBalancer 类型Docker Desktop内置了 LoadBalancer 支持——将 Service 改为 LoadBalancer 类型后它会自动在宿主机上创建Envoy 代理容器kubeadm 模式下为docker-desktop-lbkind 模式下为kindccm-xxx直接在 Windows 上监听端口将流量转发到集群内部。这种方式终端关闭后依然可用适合长期使用。# 将 NodePort 改为 LoadBalancerkubectl patch svc-nkubesphere-system ks-console-p{spec:{type:LoadBalancer}}⚠️Windows 命令兼容性Windows 的 PowerShell 对单引号和特殊字符兼容较差推荐在WSL 终端中执行上述命令。查看是否分配了 External-IPkubectl get svc-nkubesphere-system ks-console正常情况下EXTERNAL-IP会显示localhost此时浏览器打开http://localhost:30880即可访问。端口冲突处理如果该端口已被占用代理容器会创建失败EXTERNAL-IP会一直处于pending状态。正确的操作顺序如下顺序很重要# 1. 查找旧的代理容器dockerps-a--filternamekindccm# 2. 删除旧容器Docker Desktop 会自动重建dockerrm-fkindccm-LXUFEC6ZYEIUPGUBRWB556226BYGOZKZSQBDOQZS# 3. 修改 Service 端口避开被占用的端口kubectl patch svc-nkubesphere-system ks-console--typejson\-p[{op:replace,path:/spec/ports/0/port,value:30880}]等待几分钟后再次查看运行状态kubectl get svc-nkubesphere-system ks-console⚠️关键顺序先删除旧容器 → 再修改端口这样 Docker Desktop 会自动创建新的代理容器。如果先改端口再删旧容器新容器不会自动创建需要重启 Docker Desktop。5.5 登录系统浏览器打开 http://localhost:30880/login看到登录页面默认账号密码账号密码adminP88w0rd⚠️ 首次登录后强烈建议修改默认密码。六、激活 KubeSphere6.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 的复杂操作封装成了直观的图形界面让开发者可以更专注于业务本身。基于这个环境你可以进一步探索应用商店、多集群管理、监控告警等更多功能。