一键安装指南

📘概述

本文档介绍如何使用一键脚本快速部署 CSGHUB 测试环境。该方式主要用于功能验证、开发测试和概念验证（PoC）场景。

⚠️ 重要提示：

此安装方式仅适用于测试与开发环境。生产环境请使用标准化部署流程。

---

🧩 系统与前置条件

✅ 支持的操作系统

系统类型	备注
Alpine Linux	轻量环境支持，部分功能受限（如 GPU）
Ubuntu / Debian	推荐使用
CentOS / RHEL / Rocky / Alma / Fedora	兼容支持

💻 硬件要求

资源类型	最低配置	推荐配置
CPU	4 核	8 核
内存	8 GB	16 GB
存储	200 GB	500 GB
网络	能访问互联网	固定公网 IP 优先

🔧 软件依赖

• bash：执行脚本
• curl：下载安装包
• root 权限（必要）

---

⚙️ 一键安装命令

# 请将 example.com 替换为您的实际域名
curl -sfL http://quick-install.opencsg.com | bash -s -- --domain example.com

执行后脚本将自动完成以下步骤：

1. 自动检测系统环境
2. 安装轻量级 K3s Kubernetes 集群
3. 自动安装 Helm 工具
4. 部署 CSGHUB Helm Chart
5. 自动配置域名解析和访问入口
6. 输出访问信息与登录凭证

---

🧭 安装流程概述

1️⃣ 环境检测与依赖安装

脚本自动执行以下检测与安装：

• 检查操作系统类型
• 更新系统软件仓库缓存
• 安装基础依赖包（bash, curl, jq, iproute2, gettext, gnupg2 等）
• 自动安装 Helm（若未安装）

2️⃣ K3s 集群部署

• 使用官方脚本自动安装 K3s（版本 v1.30.4+k3s1）
• 配置本地 registry 与镜像加速
• 自动检测网卡并设置集群通信接口
• 等待 K3s 节点 Ready

3️⃣ NVIDIA GPU 支持（可选）

若启用 --enable-gpu：

• 安装 NVIDIA Container Toolkit
• 配置 containerd GPU runtime
• 自动部署 nvidia-device-plugin 插件
• 标记节点 GPU 标签与产品型号

⚠️ Alpine 系统不支持 GPU 功能。

要求：

• NVIDIA 驱动 ≥ 384.81
• CUDA ≥ 12.1

4️⃣ 部署 CSGHUB 核心组件

• 自动添加并更新 Helm 仓库
• 创建命名空间 csghub
• 安装或升级 csghub Helm Chart
• 配置 Ingress、Kourier 服务类型
• 自动生成登录信息至 login.txt

5️⃣ 网络与域名配置

• 若启用 --hosts-alias（默认开启）：

  • 自动在 /etc/hosts 中注册域名
    • 自动更新 CoreDNS ConfigMap 实现域名本地解析
    • 域名包含：
      • csghub.{domain}
      • casdoor.{domain}
      • minio.{domain}
      • *.public.{domain}
      • csgship.{domain}
        • 如果开启 csgship
      • csgship-api.{domain}
        • 如果开启 csgship

6️⃣ 私有仓库配置

安装结束后自动：

• 获取 csghub-docker-credential Secret
• 更新 /etc/rancher/k3s/registries.yaml
• 重启 K3s 应用新的私有镜像仓库配置

---

⚡ 参数配置

必选参数

参数	说明	默认值
--domain <domain>	部署目标域名（必填）

可选参数

参数	说明	默认值
--data <data_dir>	定义部署 k3s 的数据目录	/var/lib/rancher
--enable-gpu	启用 NVIDIA GPU 支持	false
--enable-nfs-pv	启用 NFS PV Proversioner	true
--edition	【Deprecated】指定版本类型	ee
--install-cn	使用国内镜像加速源	false
--hosts-alias	启用本地 hosts 域名解析	true
--enable-csgship	【Deprecated】启用 CSGShip 服务模块	false
--extra-args "<args1> <args2>"	追加 Helm Chart 参数
--dry-run	仅打印执行命令，不实际执行	false
--verbose	打印详细信息	false
--ghproxy <url>	设置 GitHub 代理地址	https://ghfast.top
--knative-domain <domain>	【Deprecated】设置 Knative 内部域名	默认同 --domain
--ingress-service-type <type>	【Deprecated】设置 Ingress 服务类型	NodePort
--kourier-service-type <type>	【Deprecated】设置 Kourier 服务类型	NodePort
--interface <iface>	指定网卡接口	默认系统第一个网卡
--timeout <seconds>	自定义资源创建时的超时时间	默认 300 秒

说明：

• 【Deprecated】参数通过 --extra-args 传入，以上参数默认值已经通过以下内置：

  HELM_EXTRA_ARGS+=(--set global.edition='ee')
  HELM_EXTRA_ARGS+=(--set global.ingress.service.type=NodePort)
  HELM_EXTRA_ARGS+=(--set ingress-nginx.controller.service.type=NodePort)
  HELM_EXTRA_ARGS+=(--set csgship.enabled='false')

  你可以通过如下定义覆盖以上默认配置或者追加更多配置：

  curl -sfL http://quick-install.opencsg.com | bash -s -- --domain example.com --extra-args "--set global.edition='ce' --set csgship.enabled='false'"

---

🌏 常见安装模式

1️⃣ 国内网络环境

curl -sfL http://quick-install.opencsg.com | bash -s -- --domain example.com --install-cn

说明：

• 使用阿里云镜像源加速下载

2️⃣ 启用 GPU 支持

curl -sfL http://quick-install.opencsg.com | bash -s -- --domain example.com --enable-gpu

说明：

• 自动安装 NVIDIA 驱动依赖和运行时配置
• 启动 nvidia-device-plugin
• 标记节点 GPU 能力标签

3️⃣ 启用企业版功能（CSGShip）

curl -sfL http://quick-install.opencsg.com | bash -s -- --domain example.com --extra-args "--set csgship.enabled='true'"

4️⃣ 使用 LoadBalancer 暴露服务

curl -sfL http://quick-install.opencsg.com | bash -s -- --domain example.com --extra-args "--set global.ingress.service.type=='LoadBalancer' --set ingress-nginx.controller.service.type='LoadBalancer'"

⚠️ 注意：

• LoadBalancer 模式会自动占用端口 22，请提前修改本机 SSH 端口以避免冲突。

5️⃣ 组合示例

curl -sfL http://quick-install.opencsg.com | bash -s -- \
  --domain example.com \
  --enable-gpu \
  --install-cn \
  --extra-args "--set csgship.enabled='true' --set global.ingress.service.type=='LoadBalancer' --set ingress-nginx.controller.service.type='LoadBalancer'"

---

📋 安装验证与访问

检查安装状态

kubectl get nodes
kubectl get pods -A
kubectl get svc -n csghub
kubectl get ingress -n csghub

查看安装日志

cat ./quick-install.log

查看访问信息

cat ./login.txt

内容包括：

• CSGHUB 登录地址
• 管理员账户与密码
• 关键服务端点

---

🧰 故障排查

问题 1：脚本执行失败

curl -sfL http://quick-install.opencsg.com -o quick-install.sh
bash quick-install.sh --domain example.com

问题 2：域名无法解析

echo "$(hostname -I | awk '{print $1}') csghub.example.com" >> /etc/hosts

问题 3：端口冲突

netstat -tulpn | grep :22

问题 4：Error on line 138: Command [bash -c "$cmd"]

如果脚本执行过程中提示以上报错并伴有[WARN] Retry的日志，继续等待即可，程序会自动重试。

查看 K3s 与 Pod 日志

sudo journalctl -u k3s -f
kubectl logs -n csghub -l app=csghub

---

🧹 环境清理

# 卸载 CSGHUB
helm uninstall csghub -n csghub

# 卸载 K3s（谨慎操作）
/usr/local/bin/k3s-uninstall.sh

# 删除残留数据
rm -rf /var/lib/rancher /opt/csghub ~/.kube ~/.helm

---

✅ 安装完成后建议

1. 验证各服务运行正常
2. 备份管理员登录凭证