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

ghostmen2026-01-29 14:48

📋 目录

环境说明

服务器环境

  • 服务器 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 中执行：

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 文件

powershell 复制代码 
# 创建目录
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 离线安装包

powershell 复制代码 
# 创建目录
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 文件：

bash 复制代码 
#!/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 功能

连接到服务器

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

上传文件

  1. 按 Alt + P 打开 SFTP 窗口
  2. 在 SFTP 窗口中执行：
bash 复制代码 
# 切换到服务器的 /tmp 目录
cd /tmp

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

# 上传整个文件夹
put -r kuboard-offline
  1. 等待传输完成（约 2-5 分钟）

2.2 验证文件传输

在 SecureCRT 命令行中执行：

bash 复制代码 
# 检查文件是否完整
ls -lh /tmp/kuboard-offline/
ls -lh /tmp/kuboard-offline/docker/
ls -lh /tmp/kuboard-offline/images/

三、安装 Kuboard

3.1 执行安装脚本

在 SecureCRT 中执行：

bash 复制代码 
# 进入目录
cd /tmp/kuboard-offline

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

# 执行安装
sudo bash install.sh

3.2 等待安装完成

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

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

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

3.3 验证安装

bash 复制代码 
# 查看容器状态
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：停止现有容器并使用新端口

bash 复制代码 
# 停止并删除现有容器
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 配置

bash 复制代码 
# 创建完整的 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：验证访问

bash 复制代码 
# 测试本地访问
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 中执行：

bash 复制代码 
# 检查 K3s 服务状态
sudo systemctl status k3s

# 查看节点信息
sudo kubectl get nodes

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

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

步骤 1：生成修改后的 kubeconfig

在 SecureCRT 中执行：

bash 复制代码 
# 将 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 中导入

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

步骤 4：验证集群连接

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

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

5.3 方法二：使用 Token 方式

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

步骤 1：创建 ServiceAccount

在 SecureCRT 中执行：

bash 复制代码 
# 创建 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

bash 复制代码 
# 等待 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 中添加集群

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

5.4 验证集群绑定

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

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

常用管理命令

Kuboard 容器管理

bash 复制代码 
# 查看容器状态
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

数据备份

bash 复制代码 
# 手动备份
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 /

端口检查

bash 复制代码 
# 查看端口监听
sudo netstat -tlnp | grep -E '41878|10081'

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

# 测试外部访问
telnet 10.12.12.110 41878

K3s 集群管理

bash 复制代码 
# 查看节点状态
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 {} 块。

解决方案：

  1. 更换端口（避开 80 端口）
  2. 手动修复 nginx 配置（参考 [四、解决 404 问题](#四、解决 404 问题)）

Q2: 无法从浏览器访问 Kuboard

排查步骤：

bash 复制代码 
# 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 集群无法连接

可能原因：

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

解决方案：

bash 复制代码 
# 检查 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: 端口被占用

检查端口占用：

bash 复制代码 
sudo netstat -tlnp | grep :41878

更换端口：

bash 复制代码 
# 停止容器
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 受限。

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

powershell 复制代码 
# 使用华为云镜像源
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 集群的完整流程：

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

关键要点

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

最终效果

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

参考资源

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

附录

A. 完整的安装脚本

参考 [三、安装 Kuboard](#三、安装 Kuboard) 中的 install.sh

B. nginx 完整配置

参考 [四、解决 404 问题](#四、解决 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

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

相关推荐
j_xxx404_1 小时前
Linux：进程状态
linux·运维·服务器
济6171 小时前
linux 系统移植（第二十三期）---- 进一步完善BusyBox构建的根文件系统---- Ubuntu20.04
linux·运维·服务器
程序员 _孜然1 小时前
openkylin、ubuntu等系统实现串口自动登录
linux·运维·ubuntu
hweiyu002 小时前
Linux 命令：csplit
linux·运维·服务器
守正出琦2 小时前
Linux信号核心函数速查表
linux·运维·服务器
花花鱼2 小时前
Linux中的755及644等等速记
linux·运维·服务器
草草_2 小时前
【内核驱动基础】主设备号与次设备号
linux·内核驱动
cws2004012 小时前
Linux如何通过命令实现立即关机？shutdown命令的now参数使用详解
linux·运维·服务器
何以不说话2 小时前
记录一下学习日常⑩（docker）
linux·运维·docker·容器
热门推荐
01GitHub 镜像站点02OpenCode 入门教程：介绍 · 安装 · 配置第三方 API (如 Claude)03【网络安全测试】Burp Suite工具使用说明、配置及常见问题（有关必回）04Claude Code Skills 实用使用手册05Clawdbot 中文汉化版 接入微信、飞书06在Trae中使用Pencil MCP07struts2 XML外部实体注入漏洞复现（CVE-2025-68493）08UV安装并设置国内源09AI 规范驱动开发“三剑客”深度对比：Spec-Kit、Kiro 与 OpenSpec 实战指南10零门槛部署本地 AI 助手：Clawdbot/Meltbot 部署深度保姆级教程