Kuboard与K3s离线安装部署全攻略

1. 为什么需要Kuboard离线安装方案

在企业级Kubernetes管理实践中，离线环境部署是许多传统行业和特殊场景下的硬性需求。以金融行业为例，某省级银行的数据中心由于合规要求，其生产环境完全隔离于互联网，但运维团队又急需可视化的Kubernetes管理工具。这正是Kuboard离线安装方案的价值所在。

K3s作为轻量级Kubernetes发行版，在边缘计算和资源受限环境中广受欢迎。但当它与Kuboard结合时，在离线环境中会遇到几个典型问题：

• 容器镜像依赖复杂（Kuboard前端+后端组件约15个镜像）
• 离线包版本匹配困难（Kuboard版本与K3s版本存在兼容性矩阵）
• 证书签发依赖网络（默认自动签发需要访问Let's Encrypt）

我曾为一家制造业客户实施过类似方案，他们的工厂车间部署了20个K3s节点用于设备监控，但整个厂区只有办公区有网络出口。通过本文介绍的离线安装方法，最终实现了：

1. 单台跳板机完成所有组件的离线打包
2. 内网镜像仓库的自动同步策略
3. 证书的预生成与离线分发

2. 离线安装包准备与完整性校验

2.1 官方资源获取与版本匹配

首先在可联网的环境中访问Kuboard官方GitHub仓库（https://github.com/eip-work/kuboard-press），下载对应版本的离线安装包。这里需要特别注意版本对应关系：

建议通过以下命令验证下载包的完整性：

bash复制# 校验sha256
echo "a1b2c3d4...  kuboard-offline-v3.2.1.tar.gz" | sha256sum -c

# 解压验证文件结构
tar -ztvf kuboard-offline-v3.2.1.tar.gz | grep -E 'install.sh|images/'

2.2 私有镜像仓库的预处理

离线环境需要预先搭建私有镜像仓库，推荐使用Harbor。在联网机器上执行镜像同步：

bash复制# 加载Kuboard提供的镜像列表
IMAGES=$(cat kuboard-offline-v3.2.1/images/list.txt)

# 批量拉取并重新打标签
for image in $IMAGES; do
  docker pull $image
  docker tag $image my-harbor.com/kuboard/$image
  docker push my-harbor.com/kuboard/$image
done

注意：如果遇到证书问题，需要在每台节点上执行：

bash复制mkdir -p /etc/docker/certs.d/my-harbor.com
scp harbor-ca.crt root@node:/etc/docker/certs.d/my-harbor.com

3. K3s集群的特殊配置要点

3.1 禁用默认组件与网络调整

K3s默认会启用Traefik等组件，可能与Kuboard产生端口冲突。建议安装时添加以下参数：

bash复制curl -sfL https://get.k3s.io | INSTALL_K3S_VERSION=v1.24.6+k3s1 \
  sh -s - --disable traefik --disable servicelb --cluster-init

关键参数说明：

• --disable traefik：避免80/443端口占用
• --cluster-init：为后续高可用部署留出扩展空间
• --tls-san：如果有多网卡需指定访问域名

3.2 离线环境的证书管理技巧

在没有Let's Encrypt的离线环境中，推荐使用cfssl工具预生成证书：

bash复制# 生成CA证书
cfssl gencert -initca ca-csr.json | cfssljson -bare ca

# 生成服务器证书
cfssl gencert -ca=ca.pem -ca-key=ca-key.pem \
  -config=ca-config.json -profile=server \
  server-csr.json | cfssljson -bare server

将生成的证书放入指定位置：

bash复制mkdir -p /etc/kuboard/ssl
cp server.pem /etc/kuboard/ssl/kuboard.crt
cp server-key.pem /etc/kuboard/ssl/kuboard.key

4. Kuboard离线安装全流程

4.1 安装脚本的定制化修改

解压离线包后，需要修改install.sh脚本中的几个关键变量：

bash复制# 原配置
REGISTRY="docker.io"
IMAGE_PREFIX="eipwork"

# 修改为私有仓库地址
REGISTRY="my-harbor.com"
IMAGE_PREFIX="kuboard"

同时注释掉证书自动生成的部分（约第45行附近）：

bash复制# 注释掉以下内容
# if [ ! -f "${KUBOARD_SSL_KEY}" ] || [ ! -f "${KUBOARD_SSL_CERT}" ]; then
#   generate_self_signed_cert
# fi

4.2 分步执行安装过程

建议分步执行而非直接运行脚本，便于排查问题：

bash复制# 加载镜像
docker load -i kuboard-offline-v3.2.1/images/kuboard-all-in-one.tar

# 手动启动安装
docker run -d \
  --name kuboard-installer \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /etc/kuboard/ssl:/ssl \
  -e KUBOARD_SSL_CERT=/ssl/kuboard.crt \
  -e KUBOARD_SSL_KEY=/ssl/kuboard.key \
  my-harbor.com/kuboard/installer:v3.2.1

验证安装日志：

bash复制docker logs -f kuboard-installer | grep -A 10 'Starting Kuboard'

5. 集群绑定与权限配置实战

5.1 ServiceAccount的创建与绑定

在K3s控制节点上创建专属ServiceAccount：

bash复制cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ServiceAccount
metadata:
  name: kuboard-admin
  namespace: kube-system
---
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: kube-system
EOF

获取访问令牌：

bash复制kubectl -n kube-system get secret \
  $(kubectl -n kube-system get sa kuboard-admin -o jsonpath='{.secrets[0].name}') \
  -o jsonpath='{.data.token}' | base64 -d

5.2 界面绑定过程中的常见问题

在Kuboard界面添加集群时，可能会遇到：

1. 证书错误：需要在浏览器中导入之前生成的CA证书
2. 节点显示不全：检查K3s节点的labels是否包含：

   bash复制kubectl get nodes --show-labels | grep 'k3s.io/hostname'
   

3. 监控数据缺失：手动部署metrics-server：

   bash复制kubectl apply -f kuboard-offline-v3.2.1/addons/metrics-server.yaml
   

6. 离线环境下的运维技巧

6.1 版本升级的稳妥方案

离线环境升级需要特别注意：

1. 下载新版本离线包后，先在测试环境验证
2. 使用kubectl drain安全驱逐节点
3. 分批次升级，确保业务连续性

升级命令示例：

bash复制# 备份当前配置
cp -r /etc/kuboard /backup/kuboard-$(date +%Y%m%d)

# 执行升级
docker stop kuboard-installer
docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /etc/kuboard:/etc/kuboard \
  my-harbor.com/kuboard/upgrader:v3.3.0

6.2 日志收集的替代方案

由于无法使用ELK等云原生方案，推荐：

1. 使用Kuboard内置的日志查看器
2. 配置集群节点日志轮转：

   bash复制cat > /etc/logrotate.d/k3s <<EOF
   /var/log/k3s/*.log {
     daily
     rotate 7
     missingok
     notifempty
     compress
   }
   EOF
   

3. 对于关键业务Pod，添加sidecar容器实现本地日志收集

我在实际运维中发现，通过合理配置logrotate可以节省40%的存储空间。同时建议在Kuboard的"集群概览"中设置日志自动清理策略：

yaml复制apiVersion: kuboard.cn/v1
kind: KuboardClusterConfig
metadata:
  name: cluster-main
spec:
  logRetention:
    enabled: true
    days: 7
    maxSize: "5Gi"