Kuboard v3 完整部署配置清单 & 排障清单（基于 Ubuntu 24.04 K8s 环境）

经过多次折腾，kuboard V3才成功安装部署完成，特将过程和经验分享给跟我有同样困惑的人。

一、 前置条件

1. K8s 集群（v1.30）正常运行，kubectl 可正常访问集群
2. 节点已配置国内镜像源（阿里云 / 华为云），确保镜像拉取顺畅
3. 关闭节点防火墙（或放行 30080 端口）：sudo ufw disable
4. 启用内核 IP 转发（关键，解决 NodePort 不通问题）

   sudo sysctl -w net.ipv4.ip_forward=1
   sudo sysctl -w net.bridge.bridge-nf-call-iptables=1
   echo "net.ipv4.ip_forward=1" | sudo tee -a /etc/sysctl.conf
   echo "net.bridge.bridge-nf-call-iptables=1" | sudo tee -a /etc/sysctl.conf
   sudo sysctl -p
   

二、 分步安装配置

步骤 1：创建 Kuboard 专属命名空间

kubectl create namespace kuboard

步骤 2：部署 Kuboard ETCD 组件（DaemonSet 模式）

这里etcd的默认端口为2381

cat <<EOF | kubectl apply -f -
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: kuboard-etcd
  namespace: kuboard
  labels:
    k8s.kuboard.cn/name: kuboard-etcd
spec:
  selector:
    matchLabels:
      k8s.kuboard.cn/name: kuboard-etcd
  template:
    metadata:
      labels:
        k8s.kuboard.cn/name: kuboard-etcd
    spec:
      tolerations:
        - effect: NoExecute
          operator: Exists
        - effect: NoSchedule
          operator: Exists
      containers:
        - name: etcd
          image: swr.cn-east-2.myhuaweicloud.com/kuboard/etcd-host:3.4.16-2
          ports:
            - containerPort: 2381
              hostPort: 2381
            - containerPort: 2382
              hostPort: 2382
          livenessProbe:
            httpGet:
              path: /health
              port: 2381
            initialDelaySeconds: 30
            periodSeconds: 10
          volumeMounts:
            - name: data
              mountPath: /data
      volumes:
        - name: data
          hostPath:
            path: /usr/share/kuboard/etcd
            type: DirectoryOrCreate
EOF

步骤 3：创建核心 ConfigMap（关键：变量名无 KUBOARD_ 前缀）

正确配置etcd的访问地址：ETCD_ENDPOINTS: http://172.20.10.120:2381

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: kuboard-v3-config
  namespace: kuboard
data:
  # Kuboard v3 识别的 ETCD 地址变量名：ETCD_ENDPOINTS（无前缀）
  ETCD_ENDPOINTS: http://172.20.10.120:2381
  LOG_LEVEL: info
EOF

注意：将 172.20.10.120 替换为你的实际节点 IP

步骤 4：部署 Kuboard v3 核心服务

cat <<EOF | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    k8s.kuboard.cn/name: kuboard-v3
  name: kuboard-v3
  namespace: kuboard
spec:
  replicas: 1
  selector:
    matchLabels:
      k8s.kuboard.cn/name: kuboard-v3
  template:
    metadata:
      labels:
        k8s.kuboard.cn/name: kuboard-v3
    spec:
      tolerations:
        - operator: Exists
      serviceAccountName: kuboard-boostrap
      containers:
        - name: kuboard
          image: swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3.5.0.2
          # 从 ConfigMap 注入环境变量
          envFrom:
            - configMapRef:
                name: kuboard-v3-config
          ports:
            - containerPort: 80
          livenessProbe:
            httpGet:
              path: /kuboard-resources/version.json
              port: 80
            initialDelaySeconds: 30
            periodSeconds: 10
EOF

步骤 5：创建 NodePort Service（暴露 30080 端口供外部访问）

bash

运行

cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Service
metadata:
  name: kuboard-v3
  namespace: kuboard
spec:
  selector:
    k8s.kuboard.cn/name: kuboard-v3
  type: NodePort
  ports:
    - port: 80
      targetPort: 80
      nodePort: 30080
      protocol: TCP
EOF

三、 验证部署结果

步骤 1：检查所有组件状态

# 检查 Pod 状态（全部 Running 为正常）
kubectl get pods -n kuboard

# 检查 Service 状态（NodePort 为 30080）
kubectl get svc -n kuboard

正常输出示例：

NAME                          READY   STATUS    RESTARTS   AGE
kuboard-etcd-phqjb            1/1     Running   0          10m
kuboard-v3-778d6f48d9-h95sl   1/1     Running   0          8m

NAME         TYPE       CLUSTER-IP      EXTERNAL-IP   PORT(S)        AGE
kuboard-v3   NodePort   10.103.56.136   <none>        80:30080/TCP   7m

步骤 2：检查 Kuboard 启动日志（确认 ETCD 连接正常）

kubectl logs -n kuboard -f $(kubectl get pods -n kuboard -l k8s.kuboard.cn/name=kuboard-v3 -o name)

正常日志标识：无 ETCD_ENDPOINTS=[] 报错，无 connection error 提示

步骤 3：访问 Kuboard 控制台

浏览器打开地址：

http://<你的节点IP>:30080

初始账号：admin初始密码：Kuboard123

四、 常见问题排查清单