Kuboard 离线安装与 K3s 集群绑定完整指南

📋 目录

环境说明
准备工作
一、准备离线安装包
二、传输文件到服务器
三、安装 Kuboard
四、解决 404 问题
五、绑定 K3s 集群
常用管理命令
常见问题

环境说明

服务器环境

服务器 IP: 10.12.12.110
操作系统: CentOS/RHEL
网络环境: 内网，无法访问外网
已安装服务: K3s v1.30.11+k3s1

本地环境

操作系统: Windows
网络: 可以联网
已安装工具: Docker Desktop、SecureCRT

准备工作

所需工具

Docker Desktop（Windows 本地）
SecureCRT（SSH 连接工具）
浏览器

网络要求

本地机器可以访问互联网
本地机器可以 SSH 连接到服务器
服务器处于内网环境

一、准备离线安装包

1.1 下载 Kuboard 镜像

在 Windows 本地（已安装 Docker Desktop）的 PowerShell 中执行：

# 使用国内镜像源下载 Kuboard v3
docker pull swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3

# 重新标记镜像
docker tag swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3 eipwork/kuboard:v3

# 验证镜像
docker images | Select-String kuboard

1.2 导出镜像为 tar 文件

# 创建目录
New-Item -ItemType Directory -Force -Path "D:\Documents\kuboard-offline\images"

# 导出镜像（约 126 MB）
docker save eipwork/kuboard:v3 -o "D:\Documents\kuboard-offline\images\kuboard-v3.tar"

# 查看文件大小
Get-ChildItem "D:\Documents\kuboard-offline\images\kuboard-v3.tar"

1.3 下载 Docker 离线安装包

# 创建目录
New-Item -ItemType Directory -Force -Path "D:\Documents\kuboard-offline\docker"

# 下载 Docker 离线包（约 66.6 MB）
Invoke-WebRequest -Uri "https://download.docker.com/linux/static/stable/x86_64/docker-24.0.7.tgz" -OutFile "D:\Documents\kuboard-offline\docker\docker-24.0.7.tgz"

1.4 创建安装脚本

在 D:\Documents\kuboard-offline\ 目录下创建 install.sh 文件：

#!/bin/bash
# Kuboard 离线安装脚本

set -e

echo "=========================================="
echo "Kuboard 离线安装"
echo "=========================================="

# 检查是否为 root 用户
if [ "$EUID" -ne 0 ]; then 
    echo "请使用 root 用户或 sudo 执行此脚本"
    exit 1
fi

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# 检查 Docker 是否已安装
if ! command -v docker &> /dev/null; then
    echo "[1/4] 安装 Docker..."
    
    if [ -f "${SCRIPT_DIR}/docker/docker-24.0.7.tgz" ]; then
        cd "${SCRIPT_DIR}/docker"
        tar -xzf docker-24.0.7.tgz
        cp docker/* /usr/bin/
        chmod +x /usr/bin/docker*
        
        # 创建 Docker systemd 服务
        cat > /etc/systemd/system/docker.service << 'DOCKERSERVICE'
[Unit]
Description=Docker Application Container Engine
Documentation=https://docs.docker.com
After=network-online.target firewalld.service
Wants=network-online.target

[Service]
Type=notify
ExecStart=/usr/bin/dockerd
ExecReload=/bin/kill -s HUP $MAINPID
LimitNOFILE=infinity
LimitNPROC=infinity
TimeoutStartSec=0
Delegate=yes
KillMode=process
Restart=on-failure
StartLimitBurst=3
StartLimitInterval=60s

[Install]
WantedBy=multi-user.target
DOCKERSERVICE

        systemctl daemon-reload
        systemctl start docker
        systemctl enable docker
        
        echo "✓ Docker 安装完成"
    else
        echo "⚠ 未找到 Docker 安装包"
    fi
else
    echo "[1/4] Docker 已安装: $(docker --version)"
fi

echo ""
echo "[2/4] 加载 Kuboard 镜像..."
if [ -f "${SCRIPT_DIR}/images/kuboard-v3.tar" ]; then
    docker load -i "${SCRIPT_DIR}/images/kuboard-v3.tar"
    echo "✓ Kuboard 镜像加载完成"
else
    echo "✗ 未找到 Kuboard 镜像文件"
    exit 1
fi

echo ""
echo "[3/4] 创建数据目录..."
mkdir -p /data/kuboard
echo "✓ 数据目录创建完成: /data/kuboard"

echo ""
echo "[4/4] 启动 Kuboard 容器..."

SERVER_IP="10.12.12.110"

# 检查是否已有运行的 kuboard 容器
if docker ps -a | grep -q kuboard; then
    echo "检测到已存在的 kuboard 容器，正在删除..."
    docker rm -f kuboard
fi

# 启动容器
docker run -d \
  --restart=unless-stopped \
  --name=kuboard \
  -p 80:80/tcp \
  -p 10081:10081/tcp \
  -e KUBOARD_ENDPOINT="http://${SERVER_IP}:80" \
  -e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
  -v /data/kuboard:/data \
  eipwork/kuboard:v3

echo ""
echo "等待容器启动..."
sleep 5

# 检查容器状态
if docker ps | grep -q kuboard; then
    echo "✓ Kuboard 启动成功！"
    echo ""
    echo "=========================================="
    echo "安装完成！"
    echo "=========================================="
    echo "访问地址: http://${SERVER_IP}"
    echo "默认用户名: admin"
    echo "默认密码: Kuboard123"
    echo ""
    echo "⚠️  请立即登录并修改默认密码！"
    echo "=========================================="
else
    echo "✗ Kuboard 启动失败，请查看日志:"
    docker logs kuboard
    exit 1
fi

1.5 文件结构

准备完成后，目录结构如下：

D:\Documents\kuboard-offline\
├── docker/
│   └── docker-24.0.7.tgz          (66.6 MB)
├── images/
│   └── kuboard-v3.tar             (126 MB)
└── install.sh                      (安装脚本)

总大小: 约 193 MB

二、传输文件到服务器

2.1 使用 SecureCRT 的 SFTP 功能

连接到服务器

打开 SecureCRT
新建会话或快速连接
- 协议：SSH2
- 主机名：10.12.12.110
- 端口：22
- 用户名：sudoroot
连接并输入密码

上传文件

按 Alt + P 打开 SFTP 窗口
在 SFTP 窗口中执行：

# 切换到服务器的 /tmp 目录
cd /tmp

# 切换本地目录到 D:\Documents
lcd D:\Documents

# 上传整个文件夹
put -r kuboard-offline

等待传输完成（约 2-5 分钟）

2.2 验证文件传输

在 SecureCRT 命令行中执行：

# 检查文件是否完整
ls -lh /tmp/kuboard-offline/
ls -lh /tmp/kuboard-offline/docker/
ls -lh /tmp/kuboard-offline/images/

三、安装 Kuboard

3.1 执行安装脚本

在 SecureCRT 中执行：

# 进入目录
cd /tmp/kuboard-offline

# 给脚本执行权限
chmod +x install.sh

# 执行安装
sudo bash install.sh

3.2 等待安装完成

安装脚本会自动完成以下操作：

✅ 检查并安装 Docker（如果未安装）
✅ 加载 Kuboard 镜像
✅ 创建数据目录 /data/kuboard
✅ 启动 Kuboard 容器

安装过程约需 1-3 分钟。

3.3 验证安装

# 查看容器状态
sudo docker ps | grep kuboard

# 查看日志
sudo docker logs kuboard | tail -50

# 测试本地访问
curl -I http://localhost:80

四、解决 404 问题

4.1 问题现象

初次安装后，访问 http://10.12.12.110 可能会遇到 404 page not found 错误。

4.2 问题原因

Kuboard v3 镜像的 nginx 配置文件默认生成不完整，缺少 http {} 块，导致无法正确处理 HTTP 请求。

4.3 解决方案：更换端口并修复配置

步骤 1：停止现有容器并使用新端口

# 停止并删除现有容器
sudo docker stop kuboard
sudo docker rm kuboard

# 使用 41878 端口重新启动
sudo docker run -d \
  --restart=unless-stopped \
  --name=kuboard \
  -p 41878:80/tcp \
  -p 10081:10081/tcp \
  -e KUBOARD_ENDPOINT="http://10.12.12.110:41878" \
  -e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
  -v /data/kuboard:/data \
  eipwork/kuboard:v3

# 等待容器启动
sleep 30

步骤 2：修复 nginx 配置

# 创建完整的 nginx 配置
sudo docker exec kuboard sh -c 'cat > /etc/nginx/nginx.conf << "EOF"
user www-data;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

events {
    worker_connections 65535;
}

http {
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;

    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;

    gzip on;

    server {
        listen 80;
        server_name _;
        
        client_max_body_size 1024m;

        location / {
            proxy_pass http://127.0.0.1:10080;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";
        }
    }
}

stream {}
EOF'

# 重载 nginx 配置
sudo docker exec kuboard nginx -s reload

步骤 3：验证访问

# 测试本地访问
curl -I http://localhost:41878

# 查看容器状态
sudo docker ps | grep kuboard

4.4 访问 Kuboard

在浏览器中访问：

http://10.12.12.110:41878

登录信息：

用户名: admin
密码: Kuboard123

⚠️ 重要提醒：首次登录后请立即修改默认密码！

五、绑定 K3s 集群

5.1 检查 K3s 状态

在 SecureCRT 中执行：

# 检查 K3s 服务状态
sudo systemctl status k3s

# 查看节点信息
sudo kubectl get nodes

# 查看 kubeconfig 文件
ls -la /etc/rancher/k3s/k3s.yaml

5.2 方法一：使用 KubeConfig 导入（推荐）

步骤 1：生成修改后的 kubeconfig

在 SecureCRT 中执行：

# 将 127.0.0.1 替换为服务器实际 IP
sudo cat /etc/rancher/k3s/k3s.yaml | sed 's/127.0.0.1/10.12.12.110/g'

步骤 2：复制输出内容

执行上面命令后，会输出修改后的 kubeconfig，全部复制（从 apiVersion: v1 开始到最后）。

步骤 3：在 Kuboard 中导入

浏览器访问 http://10.12.12.110:41878
使用 admin/Kuboard123 登录
点击页面上的「添加集群」按钮
选择「通过 KubeConfig 导入」
将刚才复制的 kubeconfig 内容粘贴到文本框
点击「确定」或「导入」

步骤 4：验证集群连接

导入成功后，你应该能看到：

集群名称：default
节点数量：1
K3s 版本：v1.30.11+k3s1
节点状态：Ready

5.3 方法二：使用 Token 方式

如果 KubeConfig 导入失败，可以使用 Token 方式。

步骤 1：创建 ServiceAccount

在 SecureCRT 中执行：

# 创建 Kuboard 专用账号和权限
cat <<EOF | sudo kubectl apply -f -
---
apiVersion: v1
kind: Namespace
metadata:
  name: kuboard

---
apiVersion: v1
kind: ServiceAccount
metadata:
  name: kuboard-admin
  namespace: kuboard

---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: kuboard-admin
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin
subjects:
- kind: ServiceAccount
  name: kuboard-admin
  namespace: kuboard

---
apiVersion: v1
kind: Secret
metadata:
  name: kuboard-admin-token
  namespace: kuboard
  annotations:
    kubernetes.io/service-account.name: kuboard-admin
type: kubernetes.io/service-account-token
EOF

步骤 2：获取 Token

# 等待 Secret 创建
sleep 5

# 获取 Token
echo "=========================================="
echo "Token:"
echo "=========================================="
sudo kubectl get secret kuboard-admin-token -n kuboard -o jsonpath='{.data.token}' | base64 -d
echo ""
echo ""

# 获取 CA 证书
echo "=========================================="
echo "CA Certificate:"
echo "=========================================="
sudo kubectl get secret kuboard-admin-token -n kuboard -o jsonpath='{.data.ca\.crt}'
echo ""

步骤 3：在 Kuboard 中添加集群

访问 http://10.12.12.110:41878
点击「添加集群」
选择「通过 Token 导入」或「手动添加」
填写信息：
- 集群名称：k3s-cluster（自定义）
- API Server 地址：https://10.12.12.110:6443
- Token：粘贴步骤 2 获取的 Token
- CA 证书：粘贴步骤 2 获取的 CA 证书（如果需要）
点击「确定」

5.4 验证集群绑定

绑定成功后，在 Kuboard 界面中可以：

查看集群节点状态
查看命名空间列表
查看工作负载（Deployments、Pods 等）
管理配置和存储
查看日志和监控数据

常用管理命令

Kuboard 容器管理

# 查看容器状态
sudo docker ps | grep kuboard

# 查看实时日志
sudo docker logs -f kuboard

# 重启服务
sudo docker restart kuboard

# 停止服务
sudo docker stop kuboard

# 启动服务
sudo docker start kuboard

# 查看容器详细信息
sudo docker inspect kuboard

数据备份

# 手动备份
sudo tar -czf kuboard-backup-$(date +%Y%m%d).tar.gz /data/kuboard

# 查看备份文件
ls -lh kuboard-backup-*.tar.gz

# 恢复备份
sudo tar -xzf kuboard-backup-20260129.tar.gz -C /

端口检查

# 查看端口监听
sudo netstat -tlnp | grep -E '41878|10081'

# 测试本地访问
curl -I http://localhost:41878

# 测试外部访问
telnet 10.12.12.110 41878

K3s 集群管理

# 查看节点状态
sudo kubectl get nodes

# 查看所有 Pod
sudo kubectl get pods --all-namespaces

# 查看 K3s 服务状态
sudo systemctl status k3s

# 重启 K3s
sudo systemctl restart k3s

# 查看 K3s 日志
sudo journalctl -u k3s -f

常见问题

Q1: 访问 Kuboard 显示 404 错误

原因：nginx 配置不完整，缺少 http {} 块。

解决方案：

更换端口（避开 80 端口）
手动修复 nginx 配置（参考四、解决 404 问题）

Q2: 无法从浏览器访问 Kuboard

排查步骤：

# 1. 检查容器是否运行
sudo docker ps | grep kuboard

# 2. 检查端口监听
sudo netstat -tlnp | grep 41878

# 3. 检查防火墙
sudo firewall-cmd --list-ports

# 4. 开放端口
sudo firewall-cmd --permanent --add-port=41878/tcp
sudo firewall-cmd --permanent --add-port=10081/tcp
sudo firewall-cmd --reload

Q3: K3s 集群无法连接

可能原因：

API Server 地址错误（应该是服务器 IP，不是 127.0.0.1）
Token 或证书错误
K3s 服务未运行

解决方案：

# 检查 K3s 状态
sudo systemctl status k3s

# 重启 K3s
sudo systemctl restart k3s

# 重新生成 kubeconfig
sudo cat /etc/rancher/k3s/k3s.yaml | sed 's/127.0.0.1/10.12.12.110/g'

Q4: 端口被占用

检查端口占用：

sudo netstat -tlnp | grep :41878

更换端口：

# 停止容器
sudo docker rm -f kuboard

# 使用新端口（如 8888）
sudo docker run -d \
  --restart=unless-stopped \
  --name=kuboard \
  -p 8888:80/tcp \
  -p 10081:10081/tcp \
  -e KUBOARD_ENDPOINT="http://10.12.12.110:8888" \
  -e KUBOARD_AGENT_SERVER_TCP_PORT="10081" \
  -v /data/kuboard:/data \
  eipwork/kuboard:v3

Q5: Docker 镜像拉取失败

原因：国内网络访问 Docker Hub 受限。

解决方案：使用国内镜像源

# 使用华为云镜像源
docker pull swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3

# 重新标记
docker tag swr.cn-east-2.myhuaweicloud.com/kuboard/kuboard:v3 eipwork/kuboard:v3

总结

本文详细介绍了在内网环境下离线安装 Kuboard 并绑定 K3s 集群的完整流程：

准备阶段：在联网的 Windows 机器上下载 Kuboard 镜像和 Docker 离线包
传输阶段：使用 SecureCRT 的 SFTP 功能将文件传输到内网服务器
安装阶段：执行安装脚本，自动完成 Docker 和 Kuboard 的安装
修复阶段：解决 nginx 配置问题，更换端口确保正常访问
绑定阶段：通过 KubeConfig 或 Token 方式将 K3s 集群绑定到 Kuboard

关键要点

✅ 使用国内镜像源加速下载
✅ 离线安装适用于内网环境
✅ 手动修复 nginx 配置解决 404 问题
✅ 使用非标准端口避免冲突
✅ KubeConfig 方式是最简单的集群绑定方法

最终效果

Kuboard 访问地址：http://10.12.12.110:41878
默认账号：admin / Kuboard123
K3s 集群：已成功绑定，可通过 Kuboard 管理

参考资源

Kuboard 官网：https://kuboard.cn
K3s 官网：https://k3s.io
Docker 官网：https://www.docker.com
SecureCRT 官网：https://www.vandyke.com/products/securecrt/

作者：技术博客
日期：2026-01-29
版本：v1.0

附录

A. 完整的安装脚本

参考三、安装 Kuboard 中的 install.sh

B. nginx 完整配置

参考四、解决 404 问题中的 nginx 配置

C. 端口说明

端口	用途	协议
41878	Kuboard Web 界面	HTTP
10081	Kuboard Agent 通信	TCP/UDP
6443	K3s API Server	HTTPS

D. 目录结构

/data/kuboard/              # Kuboard 数据目录
├── etcd-data/              # etcd 数据
├── questdb/                # QuestDB 数据
└── ...

/etc/rancher/k3s/           # K3s 配置目录
└── k3s.yaml                # K3s kubeconfig

/tmp/kuboard-offline/       # 离线安装包
├── docker/
├── images/
└── install.sh

感谢阅读！如有问题，欢迎留言讨论。 🎉

posted @ 2026-01-29 14:29 ghostmen 阅读(11) 评论(0) 收藏举报

刷新页面返回顶部

ghostmen

Kuboard 离线安装与 K3s 集群绑定完整指南

📋 目录

环境说明

服务器环境

本地环境

准备工作

所需工具

网络要求

一、准备离线安装包

1.1 下载 Kuboard 镜像

1.2 导出镜像为 tar 文件

1.3 下载 Docker 离线安装包

1.4 创建安装脚本

1.5 文件结构

二、传输文件到服务器

2.1 使用 SecureCRT 的 SFTP 功能

连接到服务器

上传文件

2.2 验证文件传输

三、安装 Kuboard

3.1 执行安装脚本

3.2 等待安装完成

3.3 验证安装

四、解决 404 问题

4.1 问题现象

4.2 问题原因

4.3 解决方案：更换端口并修复配置

步骤 1：停止现有容器并使用新端口

步骤 2：修复 nginx 配置

步骤 3：验证访问

4.4 访问 Kuboard

五、绑定 K3s 集群

5.1 检查 K3s 状态

5.2 方法一：使用 KubeConfig 导入（推荐）

步骤 1：生成修改后的 kubeconfig

步骤 2：复制输出内容

步骤 3：在 Kuboard 中导入

步骤 4：验证集群连接

5.3 方法二：使用 Token 方式

步骤 1：创建 ServiceAccount

步骤 2：获取 Token

步骤 3：在 Kuboard 中添加集群

5.4 验证集群绑定

常用管理命令

Kuboard 容器管理

数据备份

端口检查

K3s 集群管理

常见问题

Q1: 访问 Kuboard 显示 404 错误

Q2: 无法从浏览器访问 Kuboard

Q3: K3s 集群无法连接

Q4: 端口被占用

Q5: Docker 镜像拉取失败

总结

关键要点

最终效果

参考资源

附录

A. 完整的安装脚本

B. nginx 完整配置

C. 端口说明

D. 目录结构

公告