Mac 使用 Colima k3d 和 KubeSphere 本地安装

本文用于在 macOS 上通过 Colima 和 Docker 运行一套本地 k3s 测试集群，再把 KubeSphere 安装到这套集群中。该方案适合验证 Kubernetes、KubeSphere 控制台、Pod 调度和 Helm 部署，不等同于生产环境的多服务器部署。

本文使用的拓扑如下：

text
复制
Mac
└── Colima
    └── Docker
        ├── 1 个 k3s server
        ├── 2 个 k3s agent（worker）
        └── KubeSphere Pod

一、准备环境

Apple Silicon Mac 可以使用下面的命令安装工具：

bash
复制
brew install colima k3d kubectl helm

启动 Colima。KubeSphere 组件比较占内存，建议至少分配 4 CPU 和 8 GB 内存：

bash
复制
colima start --cpu 4 --memory 8 --disk 60

确认 Docker 使用的是 Colima：

bash
复制
docker context show
colima status
docker info

如果 docker info 中出现 Registry Mirrors，说明配置了镜像加速器。需要直连 Docker Hub 时，可以编辑：

text
复制
~/.colima/default/colima.yaml

删除下面这类配置，然后重启 Colima：

yaml
复制
docker:
  bip: 172.254.0.1/24

配置文件中不要保留：

yaml
复制
registry-mirrors:
  - https://...

bash
复制
colima restart

代理软件只改变网络出口，不等于 Docker 镜像源。没有 Registry Mirrors 时，默认镜像源是 Docker Hub。

二、创建 k3d 测试集群

先检查是否已经存在同名集群：

bash
复制
k3d cluster list

如果没有 ks-test，创建 1 个 server 和 2 个 worker：

bash
复制
k3d cluster create ks-test \
  --servers 1 \
  --agents 2 \
  --api-port 6550 \
  --port "8081:80@loadbalancer"

参数说明：

text
复制
--servers 1       创建 1 个 k3s server，负责 Kubernetes 控制面
--agents 2        创建 2 个 k3s worker，负责运行 Pod
--api-port 6550   将 Kubernetes API 映射到 Mac 的 6550 端口
--port 8081:80    将 k3d 负载均衡器的 HTTP 端口映射到 Mac 的 8081 端口

验证节点：

bash
复制
kubectl config current-context
kubectl get nodes -o wide
kubectl get pods -A

预期能看到 3 个节点：

text
复制
k3d-ks-test-server-0   Ready   control-plane
k3d-ks-test-agent-0    Ready   <none>
k3d-ks-test-agent-1    Ready   <none>

如果之前停止过集群，可以恢复：

bash
复制
k3d cluster start ks-test

三、准备 KubeSphere chart

KubeSphere 的 Helm chart 需要和 Kubernetes 版本匹配。下面使用官方 KubeSphere v4.1.3 源码中的 ks-core chart：

bash
复制
git clone --depth 1 --branch v4.1.3 \
  https://github.com/kubesphere/kubesphere.git \
  ~/kubesphere-v4.1.3

检查 chart：

bash
复制
helm lint ~/kubesphere-v4.1.3/config/ks-core

查看 chart 需要的镜像：

bash
复制
helm template ks-core \
  ~/kubesphere-v4.1.3/config/ks-core \
  -n kubesphere-system \
  | rg 'image:' \
  | sort -u

四、拉取控制台镜像

本次测试使用的 chart 默认镜像：

text
复制
docker.io/kubesphere/ks-console:v4.1.3

该镜像在当前环境无法公开拉取。Docker Hub 上可拉取的是开发组织下的候选版：

bash
复制
docker pull docker.io/kubespheredev/ks-console:v4.1.3-rc.0

它与 KubeSphere v4.1.3 后端相近，适合本地功能测试。正式环境应使用同一正式版本的完整镜像集合。

五、安装 KubeSphere 核心组件

本地测试先禁用扩展市场，因为对应的 ks-extensions-museum:v1.1.3 镜像在当前公开仓库中无法拉取。控制台镜像使用上一步的 kubespheredev 仓库：

bash
复制
helm upgrade --install ks-core \
  ~/kubesphere-v4.1.3/config/ks-core \
  -n kubesphere-system \
  --create-namespace \
  --server-side=false \
  --set console.image.registry=docker.io \
  --set console.image.repository=kubespheredev/ks-console \
  --set console.image.tag=v4.1.3-rc.0 \
  --set ksExtensionRepository.enabled=false \
  --wait \
  --timeout 10m

--server-side=false 用于兼容较新的 Kubernetes API 校验。上次 server-side apply 失败的对象是扩展市场 Repository，不是 k3d 节点故障。

检查安装结果：

bash
复制
helm status ks-core -n kubesphere-system
kubectl get pods -n kubesphere-system -o wide

核心 Pod 都应该是 Running：

text
复制
ks-apiserver
ks-console
ks-controller-manager

如果 Pod 处于 ImagePullBackOff，先查看具体镜像和事件：

bash
复制
kubectl get pods -n kubesphere-system
kubectl describe pod -n kubesphere-system <pod-name>

六、访问 Web 控制台

本地测试使用端口转发。保持下面这个终端运行：

bash
复制
kubectl port-forward -n kubesphere-system svc/ks-console 30880:80

浏览器打开：

text
复制
http://127.0.0.1:30880

默认登录信息：

text
复制
账号：admin
密码：P@88w0rd

如果端口转发终止，Web 页面会无法访问，重新执行端口转发命令即可。

也可以检查控制台 Service：

bash
复制
kubectl get svc -n kubesphere-system ks-console

七、日常操作

查看所有资源：

bash
复制
kubectl get pods -A
kubectl get svc -A
kubectl get nodes

停止测试集群以降低 Mac 负载：

bash
复制
k3d cluster stop ks-test

恢复测试集群：

bash
复制
k3d cluster start ks-test

停止 Colima：

bash
复制
colima stop

删除整个 k3d 集群前确认不再需要其中的数据：

bash
复制
k3d cluster delete ks-test

删除集群会删除其中的 Kubernetes 资源和本地测试数据，但不会删除其他 Docker 容器。

八、与真实服务器部署的区别

本地 k3d 参数：

bash
复制
--servers 1 --agents 2

只是在 Docker 中模拟 1 个 server 和 2 个 worker。它们共享同一个 Colima 虚拟机的 CPU、内存、磁盘和 Linux 内核。

真实生产环境的 3 server + 10 worker 应在 13 台独立 Linux 服务器上安装原生 k3s：

text
复制
3 台 server：运行控制面和 embedded etcd
10 台 worker：运行业务 Pod

真实环境还需要准备 Kubernetes API 的负载均衡入口，例如：

text
复制
k3s-api.example.com:6443

本地 k3d 测试不需要这个生产域名。KubeSphere 安装在 k3d 集群里，使用的是 Kubernetes API，不是安装到某一个 Docker 节点容器中。

九、常见问题

1. kubectl get nodes 连接失败

确认 Colima 和 k3d 集群已经启动：

bash
复制
colima status
k3d cluster list
k3d cluster start ks-test

确认 kubectl context：

bash
复制
kubectl config use-context k3d-ks-test

2. KubeSphere 控制台镜像拉取失败

检查 Pod 使用的实际镜像：

bash
复制
kubectl get deploy -n kubesphere-system ks-console \
  -o jsonpath='{.spec.template.spec.containers[0].image}{"\n"}'

应该是：

text
复制
docker.io/kubespheredev/ks-console:v4.1.3-rc.0

3. Mac 发热或 CPU 占用高

暂停或停止不需要的测试服务：

bash
复制
docker stop libretranslate
k3d cluster stop ks-test
colima stop

优先使用 1 server + 2 agents 测试。不要在 Mac 上为了模拟生产规模直接创建 3 server + 10 agents，因为这些节点仍然共享 Mac 的资源。