Kuboard v3 是一个 Kubernetes 多集群管理控制面板，可以用来查看和管理工作负载、节点、命名空间、配置、日志等资源。

本文主线采用 集群外部署：在一台独立的 Ubuntu / Linux 虚拟机上用 Docker 运行 Kuboard Server，再把 Kubernetes 集群导入 Kuboard。

部署方式选择

官方文档建议优先使用 docker run 方式运行 Kuboard v3。原因是 Kuboard 作为多集群管理界面，独立于任何一个 Kubernetes 集群之外，结构更清晰，排查也更简单。参考：Kuboard v3 安装方式说明。

两种部署方式的区别：

部署方式位置适合场景注意事项
集群外部署Kuboard Server 运行在独立 Linux 主机或虚拟机推荐方式，适合管理一个或多个 Kubernetes 集群Kuboard 主机需要能被集群里的 Kuboard Agent 访问
集群内部署Kuboard Server 作为工作负载运行在 Kubernetes 集群内临时实验、单集群内网使用Kuboard 自己依赖被管理集群，集群故障时面板也可能不可用

本文推荐把 Kuboard Server 放在集群外。这样即使某个 Kubernetes 集群异常，Kuboard 主机本身仍然独立存在，后续排查和重新导入集群会更方便。

和集群高可用的关系

Kuboard 是管理面板，不是 Kubernetes 控制平面组件。它不参与 kube-apiserver、etcd、controller-manager、scheduler 的高可用。

也就是说：

  • Kuboard 挂了，不会导致 Kubernetes 集群停止运行。
  • Kubernetes 集群高可用，不等于 Kuboard 自动高可用。
  • 普通 Kuboard v3 部署通常是单容器实例，Kuboard 自身存在单点故障。
  • 如果 Kubernetes API Server 前面有 HAProxy / Keepalived / kube-vip 等高可用入口，导入集群时优先使用这个稳定入口。

Kuboard 官方从 v3.5.0.0 开始提供 Kuboard 自身的高可用部署模式。它需要多台 Kuboard 服务器、负载均衡、独立 etcd 集群，并且审计日志组件 QuestDB 仍有单点取舍。普通内网管理场景一般不需要做到这一步。参考：Kuboard v3 高可用部署。

前置条件

本文使用一台独立 Linux 虚拟机作为 Kuboard Server，它不加入 Kubernetes 集群：

Kuboard Server: 192.168.3.212
Kubernetes API: 192.168.3.217:8443
Kuboard Web:    http://192.168.3.212:8080
Agent Server:   192.168.3.212:10081

Kubernetes 集群为三主三从，高可用入口为 192.168.3.217：

192.168.3.214  k8s-master1
192.168.3.215  k8s-master2
192.168.3.216  k8s-master3
192.168.3.217  vip
192.168.3.218  k8s-worker1
192.168.3.219  k8s-worker2
192.168.3.220  k8s-worker3

要求：

  • Kuboard Server 已安装 Docker，Docker 版本不低于 19.03。
  • Kubernetes 集群版本不低于 v1.13。
  • Kubernetes 集群里的 Pod 能访问 Kuboard Server 的 8080/tcp 和 10081/tcp。
  • 运维电脑能访问 Kuboard Server 的 8080/tcp。

如果 Docker 还没有安装，可以先参考本站的 Docker 入门：Ubuntu 安装与基础配置。

固定 Kuboard 镜像版本

官方安装命令常使用 eipwork/kuboard:v3 或 swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3。为了避免以后重新部署时拉到不同镜像，本文固定为：

swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3.5.2.9

这个地址是 Kuboard 官方文档中给出的华为云 SWR 镜像地址，更适合国内服务器拉取。当前可在 Docker Hub eipwork/kuboard Tags 查看 Kuboard 镜像标签，SWR 镜像通常同步同名标签。

如果后续要升级 Kuboard，不要直接改成 v3 或 v4。先看官方升级说明，备份 /opt/kuboard/data 后再调整镜像版本。

创建数据目录

在 Kuboard Server 虚拟机上执行：

sudo mkdir -p /opt/kuboard/data
sudo chown -R "$USER:$USER" /opt/kuboard
cd /opt/kuboard

启动 Kuboard Server

这里把 Kuboard Web 端口映射到宿主机 8080，把 Agent Server 端口映射到宿主机 10081。

docker run -d \
  --restart=unless-stopped \
  --privileged \
  --name=kuboard \
  -p 8080:80/tcp \
  -p 10081:10081/tcp \
  -e KUBOARD_ENDPOINT="http://192.168.3.212:8080" \
  -e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
  -v /opt/kuboard/data:/data \
  swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3.5.2.9

KUBOARD_ENDPOINT 是给 Kubernetes 集群里的 Kuboard Agent 使用的地址，不能写 127.0.0.1 或 localhost。如果有内网域名，建议写域名，例如：

KUBOARD_ENDPOINT="http://kuboard.jihw.lan:8080"

如果使用域名，需要确保 Kubernetes 集群里的 Pod 能正确解析这个域名。

镜像拉取失败处理

如果执行 docker run 时出现下面的报错：

error from registry: 这镜像不在白名单. this image is not in the allowlist

通常是 Docker 配置了 DaoCloud 等镜像加速器，而该加速器只允许拉取白名单中的镜像。此时不要继续使用 eipwork/kuboard:v3.5.2.9，改用上面的 SWR 镜像地址：

docker pull swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3.5.2.9

如果仍然失败，检查 Docker 镜像加速器配置：

cat /etc/docker/daemon.json

如果里面配置了不可用或有限制的 registry-mirrors，可以先备份配置，再移除该镜像加速器并重启 Docker：

sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak
sudo vim /etc/docker/daemon.json
sudo systemctl restart docker

重启 Docker 后重新执行 docker pull 或 docker run。

查看运行状态

docker ps --filter name=kuboard
docker logs -f kuboard

浏览器访问：

http://192.168.3.212:8080

默认账号：

用户名：admin
密码：Kuboard123

首次登录后建议立刻修改默认密码。

防火墙放行

如果 Kuboard Server 开启了 ufw，可以只允许内网访问：

sudo ufw allow from 192.168.3.0/24 to any port 8080 proto tcp
sudo ufw allow from 192.168.3.0/24 to any port 10081 proto tcp
sudo ufw status

不要把 Kuboard 直接暴露到公网。Kuboard 面板具备集群管理能力，公网访问应放在 VPN、堡垒机或可信反向代理之后。

导入 Kubernetes 集群

登录 Kuboard 后，点击添加集群，常见有两种导入方式：

  • 使用 kuboard-agent 导入：适合 Kuboard Server 和 Kubernetes 集群网络互通的场景。
  • 使用 kubeconfig 导入：适合已经有稳定 kubeconfig 的场景。

本文推荐使用 kuboard-agent 导入。这个页面里不会让你手动填写 Kubernetes API Server 地址，因为 Agent 会部署到 Kubernetes 集群内部，由 Agent 在集群内访问 Kubernetes API，再和 Kuboard Server 建立连接。

在 Kuboard Agent 页签中按下面方式填写：

  • 名称：自定义，例如 homeSpace。
  • 描述：自定义，例如 家空间。
  • Agent 部署名称：保持默认或自定义，多个 Kuboard 实例导入同一个集群时需要不同名称。
  • Agent 镜像：优先选择 swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard-agent。
  • 代理设置：本文内网环境留空。

截图里的 代理设置 不是 Kubernetes API Server 地址，而是 Kuboard Agent 访问 Kuboard Agent Server 时使用的 HTTP / SOCKS5 代理。本文的 Kuboard Server 192.168.3.212 和 Kubernetes 集群在同一个 192.168.3.0/24 内网，一般不需要代理，留空即可。

如果你的网络环境要求 Agent 通过代理才能访问 Kuboard Server，再填写代理设置。官网给的代理格式是：

http://user:passwd@192.168.1.128:8080
socks5://user:passwd@192.168.1.128:8080

没有代理账号密码时，可以写成：

http://192.168.1.128:8080
socks5://192.168.1.128:8080

不要把代理地址写成 https://192.168.3.217:8443。这个地址是 Kubernetes API Server，不是 HTTP / SOCKS5 代理服务器。

点击确定后，Kuboard 页面会生成一段 kubectl apply 命令。复制到能操作 Kubernetes 集群的机器上执行即可。

如果改用 KubeConfig 或 Token 页签导入，才需要关心 Kubernetes API Server 地址。对于本文的三主三从高可用集群，kubeconfig 中的 server 建议使用高可用入口：

https://192.168.3.217:8443

不要优先使用单个 master 节点的 6443，否则该 master 节点故障时，Kuboard 访问集群也会跟着失败。

执行后查看 Agent 状态：

kubectl -n kuboard get pod,svc -o wide

如果 Agent 一直无法连接，优先检查：

  • 集群 Pod 是否能访问 http://192.168.3.212:8080。
  • 集群 Pod 是否能访问 192.168.3.212:10081/tcp。
  • KUBOARD_ENDPOINT 是否写成了 127.0.0.1、localhost 或无法解析的域名。

公网集群和内网 Kuboard

如果 Kubernetes 集群部署在公网，而 Kuboard Server 部署在内网，需要先判断连接方向。

方式一：使用 KubeConfig 导入

如果公网 Kubernetes API Server 可以从内网 Kuboard Server 访问，推荐使用 KubeConfig 或 Token 页签导入。这样连接方向是：

内网 Kuboard Server -> 公网 Kubernetes API Server

这种方式不需要把内网 Kuboard 暴露到公网，也不需要公网集群里的 Pod 访问 192.168.3.212。

在 Kuboard 的 KubeConfig 页签中粘贴 kubeconfig。kubeconfig 里的 server 应该填写公网集群的 API Server 地址，例如：

clusters:
- cluster:
    certificate-authority-data: <CA证书>
    server: https://公网API入口:6443
  name: public-k8s

如果公网集群也是高可用集群，server 应该使用公网负载均衡、云厂商控制面板提供的 API 地址，或者公网可访问的高可用入口。不要写某一台 master 的临时 IP。

安全建议：

  • 只允许 Kuboard Server 的出口公网 IP 访问 Kubernetes API Server。
  • 不要把 Kubernetes API Server 对全网开放。
  • 不要长期使用个人管理员 kubeconfig；生产环境建议给 Kuboard 单独创建账号和权限。

方式二：继续使用 Kuboard Agent

如果继续使用 Kuboard Agent 页签导入，连接方向是：

公网 Kubernetes 集群里的 Agent Pod -> 内网 Kuboard Server

这种情况下，公网集群里的 Pod 必须能访问 Kuboard Server：

http://Kuboard可达地址:8080
Kuboard可达地址:10081/tcp

如果 Kuboard 仍然只监听内网地址 192.168.3.212，公网集群通常无法访问它，Agent 就会连接失败。解决办法有几种：

  • 建立 VPN，例如 WireGuard、Tailscale、ZeroTier，让公网集群节点和内网 Kuboard 进入同一个专用网络。
  • 使用公网反向代理或内网穿透，例如 frp、云厂商负载均衡，但必须同时转发 8080/tcp 和 10081/tcp。
  • 把 Kuboard Server 部署到公网集群所在 VPC 或一台公网可控服务器上，再通过防火墙限制访问来源。

如果使用 VPN，假设 Kuboard Server 在 VPN 中的地址是 10.8.0.212，启动 Kuboard 时 KUBOARD_ENDPOINT 要写这个公网集群可达的地址：

docker run -d \
  --restart=unless-stopped \
  --privileged \
  --name=kuboard \
  -p 8080:80/tcp \
  -p 10081:10081/tcp \
  -e KUBOARD_ENDPOINT="http://10.8.0.212:8080" \
  -e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
  -v /opt/kuboard/data:/data \
  swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3.5.2.9

如果 Kuboard 容器已经启动过，可以保留数据目录，删除旧容器后用新的 KUBOARD_ENDPOINT 重新启动：

docker stop kuboard
docker rm kuboard

docker run -d \
  --restart=unless-stopped \
  --privileged \
  --name=kuboard \
  -p 8080:80/tcp \
  -p 10081:10081/tcp \
  -e KUBOARD_ENDPOINT="http://10.8.0.212:8080" \
  -e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
  -v /opt/kuboard/data:/data \
  swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3.5.2.9

如果使用公网域名，例如 kuboard.example.com，需要确认：

  • http://kuboard.example.com:8080 能访问 Kuboard Web。
  • kuboard.example.com:10081/tcp 能从公网 Kubernetes 集群访问。
  • 防火墙只放行可信来源，不要把 Kuboard 面板和 Agent 端口无保护地暴露到全网。

代理设置怎么用

Kuboard Agent 页签里的代理设置只在下面这种场景使用：

Agent Pod -> HTTP/SOCKS5 代理 -> Kuboard Server

也就是说，代理服务器本身必须能访问 Kuboard Server。如果只是 Kuboard 在内网、代理也访问不到内网 Kuboard，填写代理不会解决问题。

代理不一定是 SOCKS5，Kuboard 这里支持两类常见格式：

  • http://...：HTTP 代理。
  • socks5://...：SOCKS5 代理。

选哪一种取决于你实际搭建或购买的代理服务。如果你自己能控制代理，公网集群访问内网 Kuboard 这种场景更推荐 VPN；如果必须使用代理，SOCKS5 通常更适合转发这类 TCP 连接。

代理格式示例：

http://user:passwd@代理服务器IP:8080
socks5://user:passwd@代理服务器IP:1080

没有账号密码时：

http://代理服务器IP:8080
socks5://代理服务器IP:1080

填写前先确认三段网络都通：

Agent Pod 能访问代理服务器
代理服务器能访问 Kuboard Web:    http://Kuboard可达地址:8080
代理服务器能访问 Agent Server:   Kuboard可达地址:10081/tcp

可以在公网 Kubernetes 集群里起一个临时 Pod 测试 HTTP 代理：

kubectl run curl-test --rm -it --image=curlimages/curl:8.10.1 -- sh

curl -x http://user:passwd@代理服务器IP:8080 http://Kuboard可达地址:8080

测试 SOCKS5 代理：

kubectl run curl-test --rm -it --image=curlimages/curl:8.10.1 -- sh

curl --socks5-hostname user:passwd@代理服务器IP:1080 http://Kuboard可达地址:8080

没有账号密码时去掉 user:passwd@：

curl --socks5-hostname 代理服务器IP:1080 http://Kuboard可达地址:8080

8080 测通后，还要确认 10081/tcp 可达。可以用带 nc 的临时镜像测试：

kubectl run net-test --rm -it --image=busybox:1.36 -- sh

nc -vz Kuboard可达地址 10081

本文内网集群场景不需要代理；公网集群管理内网 Kuboard 时，更推荐优先使用 KubeConfig 导入，或者先打通 VPN 后再使用 Agent。

集群内部署方式

如果只是实验环境，也可以把 Kuboard v3 直接部署到 Kubernetes 集群内部：

kubectl apply -f https://addons.kuboard.cn/kuboard/kuboard-v3.yaml

部署后通过 NodePort 访问：

http://192.168.3.218:30080

这里也可以换成任意 master 或 worker 节点 IP，例如 192.168.3.214:30080、192.168.3.219:30080。

默认账号：

用户名：admin
密码：Kuboard123

查看资源：

kubectl -n kuboard get pod,svc -o wide

这种方式属于 集群内部署。它的优点是快速，缺点是 Kuboard 依赖当前 Kubernetes 集群本身。如果当前集群控制平面、网络、调度或存储异常，Kuboard 也可能不可用。

另外，官方文档说明集群内部署会包含 Kuboard 依赖的 etcd，并且 Kuboard v3 的 Deployment 暂时保持单副本。参考：Kuboard v3 Kubernetes 内部安装。

卸载

集群外 Docker 部署的卸载方式：

docker stop kuboard
docker rm kuboard

如果确认不再需要 Kuboard 数据，再删除数据目录：

sudo rm -rf /opt/kuboard

集群内部署的卸载方式：

kubectl delete -f https://addons.kuboard.cn/kuboard/kuboard-v3.yaml

如果使用了官方默认 hostPath 持久化方式，还需要在 master 节点以及带有 k8s.kuboard.cn/role=etcd 标签的节点上清理：

sudo rm -rf /usr/share/kuboard

删除数据目录前一定要确认不再需要 Kuboard 中保存的集群配置、用户配置和审计数据。

小结

日常内网环境建议使用集群外 Docker 部署 Kuboard v3，把它当作独立的多集群控制面板。

Kuboard 的可用性和 Kubernetes 集群高可用是两件事。Kubernetes 高可用负责保证集群控制平面稳定；Kuboard 高可用只负责保证管理面板自身稳定。普通部署下 Kuboard 单点故障不会影响集群运行，但会影响 Web 管理入口。