核心内容摘要
提瓦特深渊的温度：当胡桃遇上“焯水”丘丘人
目录环境说明准备工作
准备离线安装包
传输文件到服务器
安装 Kuboard
解决 404 问题
绑定 K3s 集群常用管理命令
常见问题环境说明服务器环境服务器 IP:
10.
12.
1
110操作系统: CentOS/RHEL网络环境: 内网无法访问外网已安装服务: K3s v
1.
3
11k3s1本地环境操作系统: Windows网络: 可以联网已安装工具: Docker Desktop、SecureCRT准备工作所需工具Docker DesktopWindows 本地SecureCRTSSH 连接工具浏览器网络要求本地机器可以访问互联网本地机器可以 SSH 连接到服务器服务器处于内网环境
准备离线安装包
1 下载 Kuboard 镜像在 Windows 本地已安装 Docker Desktop的 PowerShell 中执行/* by
hk - online tools website :
hk/zh/xpath.html */ # 使用国内镜像源下载 Kuboard v3 docker pull swr.cn-east-
myhuaweicloud.com/kuboard/kuboard:v3 # 重新标记镜像 docker tag swr.cn-east-
myhuaweicloud.com/kuboard/kuboard:v3 eipwork/kuboard:v3 # 验证镜像 docker images | Select-String kuboard
2 导出镜像为 tar 文件/* by
hk - online tools website :
hk/zh/xpath.html */ # 创建目录 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-v
tar # 查看文件大小 Get-ChildItem D:\Documents\kuboard-offline\images\kuboard-v
tar
3 下载 Docker 离线安装包# 创建目录 New-Item -ItemType Directory -Force -Path D:\Documents\kuboard-offline\docker # 下载 Docker 离线包约
6
6 MB Invoke-WebRequest -Uri https://download.docker.com/linux/static/stable/x86_64/docker-
24.
0.
tgz -OutFile D:\Documents\kuboard-offline\docker\docker-
24.
0.
tgz
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.
tgz ]; then cd ${SCRIPT_DIR}/docker tar -xzf docker-
24.
0.
tgz cp docker/* /usr/bin/ chmod x /usr/bin/docker* # 创建 Docker systemd 服务 cat /etc/systemd/system/docker.service DOCKERSERVICE [Unit] DescriptionDocker Application Container Engine Documentationhttps://docs.docker.com Afternetwork-online.target firewalld.service Wantsnetwork-online.target [Service] Typenotify ExecStart/usr/bin/dockerd ExecReload/bin/kill -s HUP $MAINPID LimitNOFILEinfinity LimitNPROCinfinity TimeoutStartSec0 Delegateyes KillModeprocess Restarton-failure StartLimitBurst3 StartLimitInterval60s [Install] WantedBymulti-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-v
tar ]; then docker load -i ${SCRIPT_DIR}/images/kuboard-v
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.
1
110 # 检查是否已有运行的 kuboard 容器 if docker ps -a | grep -q kuboard; then echo 检测到已存在的 kuboard 容器正在删除... docker rm -f kuboard fi # 启动容器 docker run -d \ --restartunless-stopped \ --namekuboard \ -p 80:80/tcp \ -p 10081:10081/tcp \ -e KUBOARD_ENDPOINThttp://${SERVER_IP}:80 \ -e KUBOARD_AGENT_SERVER_TCP_PORT10081 \ -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
5 文件结构准备完成后目录结构如下D:\Documents\kuboard-offline\ ├── docker/ │ └── docker-
24.
0.
tgz (
6
6 MB) ├── images/ │ └── kuboard-v
tar (126 MB) └── install.sh (安装脚本)总大小: 约 193 MB
传输文件到服务器
1 使用 SecureCRT 的 SFTP 功能连接到服务器打开 SecureCRT新建会话或快速连接协议SSH2主机名
10.
12.
1
110端口22用户名sudoroot连接并输入密码上传文件按Alt P打开 SFTP 窗口在 SFTP 窗口中执行# 切换到服务器的 /tmp 目录 cd /tmp # 切换本地目录到 D:\Documents lcd D:\Documents # 上传整个文件夹 put -r kuboard-offline等待传输完成约
分钟
2 验证文件传输在 SecureCRT 命令行中执行# 检查文件是否完整 ls -lh /tmp/kuboard-offline/ ls -lh /tmp/kuboard-offline/docker/ ls -lh /tmp/kuboard-offline/images/
安装 Kuboard
1 执行安装脚本在 SecureCRT 中执行# 进入目录 cd /tmp/kuboard-offline # 给脚本执行权限 chmod x install.sh # 执行安装 sudo bash install.sh
2 等待安装完成安装脚本会自动完成以下操作✅ 检查并安装 Docker如果未安装✅ 加载 Kuboard 镜像✅ 创建数据目录/data/kuboard✅ 启动 Kuboard 容器安装过程约需
分钟。
3 验证安装# 查看容器状态 sudo docker ps | grep kuboard # 查看日志 sudo docker logs kuboard | tail -50 # 测试本地访问 curl -I http://localhost:80
解决 404 问题
1 问题现象初次安装后访问http://
10.
12.
1
110可能会遇到404 page not found错误。
2 问题原因Kuboard v3 镜像的 nginx 配置文件默认生成不完整缺少http {}块导致无法正确处理 HTTP 请求。
3 解决方案更换端口并修复配置步骤 1停止现有容器并使用新端口# 停止并删除现有容器 sudo docker stop kuboard sudo docker rm kuboard # 使用 41878 端口重新启动 sudo docker run -d \ --restartunless-stopped \ --namekuboard \ -p 41878:80/tcp \ -p 10081:10081/tcp \ -e KUBOARD_ENDPOINThttp://
10.
12.
1
110:41878 \ -e KUBOARD_AGENT_SERVER_TCP_PORT10081 \ -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.
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; 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 访问 Kuboard在浏览器中访问http://
10.
12.
1
110:41878登录信息用户名:admin密码:Kuboard123⚠️重要提醒首次登录后请立即修改默认密码
绑定 K3s 集群
1 检查 K3s 状态在 SecureCRT 中执行# 检查 K3s 服务状态 sudo systemctl status k3s # 查看节点信息 sudo kubectl get nodes # 查看 kubeconfig 文件 ls -la /etc/rancher/k3s/k3s.yaml
2 方法一使用 KubeConfig 导入推荐步骤 1生成修改后的 kubeconfig在 SecureCRT 中执行# 将
127.
0.
1 替换为服务器实际 IP sudo cat /etc/rancher/k3s/k3s.yaml | sed s/
127.
0.
1/
10.
12.
1
110/g步骤 2复制输出内容执行上面命令后会输出修改后的 kubeconfig全部复制从apiVersion: v1开始到最后。
步骤 3在 Kuboard 中导入浏览器访问http://
10.
12.
1
110:41878使用admin/Kuboard123登录点击页面上的「添加集群」按钮选择「通过 KubeConfig 导入」将刚才复制的 kubeconfig 内容粘贴到文本框点击「确定」或「导入」步骤 4验证集群连接导入成功后你应该能看到集群名称default节点数量1K3s 版本v
1.
3
11k3s1节点状态Ready
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.
1
110:41878点击「添加集群」选择「通过 Token 导入」或「手动添加」填写信息集群名称k3s-cluster自定义API Server 地址https://
10.
12.
1
110:6443Token粘贴步骤 2 获取的 TokenCA 证书粘贴步骤 2 获取的 CA 证书如果需要点击「确定」
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-
tar.gz -C /端口检查# 查看端口监听 sudo netstat -tlnp | grep -E 41878|10081 # 测试本地访问 curl -I http://localhost:41878 # 测试外部访问 telnet
10.
12.
1
110 41878K3s 集群管理# 查看节点状态 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排查步骤#
检查容器是否运行 sudo docker ps | grep kuboard #
检查端口监听 sudo netstat -tlnp | grep 41878 #
检查防火墙 sudo firewall-cmd --list-ports #
开放端口 sudo firewall-cmd --permanent --add-port41878/tcp sudo firewall-cmd --permanent --add-port10081/tcp sudo firewall-cmd --reloadQ3: K3s 集群无法连接可能原因API Server 地址错误应该是服务器 IP不是
127.
0.
1Token 或证书错误K3s 服务未运行解决方案# 检查 K3s 状态 sudo systemctl status k3s # 重启 K3s sudo systemctl restart k3s # 重新生成 kubeconfig sudo cat /etc/rancher/k3s/k3s.yaml | sed s/
127.
0.
1/
10.
12.
1
110/gQ4: 端口被占用检查端口占用sudo netstat -tlnp | grep :41878更换端口# 停止容器 sudo docker rm -f kuboard # 使用新端口如 8888 sudo docker run -d \ --restartunless-stopped \ --namekuboard \ -p 8888:80/tcp \ -p 10081:10081/tcp \ -e KUBOARD_ENDPOINThttp://
10.
12.
1
110:8888 \ -e KUBOARD_AGENT_SERVER_TCP_PORT10081 \ -v /data/kuboard:/data \ eipwork/kuboard:v3Q5: Docker 镜像拉取失败原因国内网络访问 Docker Hub 受限。
解决方案使用国内镜像源# 使用华为云镜像源 docker pull swr.cn-east-
myhuaweicloud.com/kuboard/kuboard:v3 # 重新标记 docker tag swr.cn-east-
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.
1