一键安装指南

📘概述

本文档介绍如何使用一键脚本快速部署 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

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

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

🧭 安装流程概述

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 秒
`--k3s-server <server_url>`	指定创建 AGENT 节点时指定的 Master 节点 URL	指定此参数将认定添加的是 Agent 节点
`--k3s-token <server_token>`	指定创建 AGENT 节点时指定的 Master 节点令牌	默认存放 /var/lib/rancher/k3s/server/token
`--k3s-version <version>`	指定创建 AGENT 节点的 Kubetrnetes 版本	默认 v1.34.3+k3s1

说明：

【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'"

添加 Agent 节点时，每次重复执行脚本时的命令要保持一致，即携带所有参数。

🌏 常见安装模式

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️⃣ K3s 集群部署​

3️⃣ NVIDIA GPU 支持（可选）​

4️⃣ 部署 CSGHUB 核心组件​

5️⃣ 网络与域名配置​

6️⃣ 私有仓库配置​

⚡ 参数配置​

必选参数​

可选参数​

🌏 常见安装模式​

1️⃣ 国内网络环境​

2️⃣ 启用 GPU 支持​

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

4️⃣ 使用 LoadBalancer 暴露服务​

5️⃣ 组合示例​

📋 安装验证与访问​

检查安装状态​

查看安装日志​

查看访问信息​

🧰 故障排查​

问题 1：脚本执行失败​

问题 2：域名无法解析​

问题 3：端口冲突​

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

查看 K3s 与 Pod 日志​

🧹 环境清理​

✅ 安装完成后建议​

📘概述

🧩 系统与前置条件

✅ 支持的操作系统

💻 硬件要求

🔧 软件依赖

⚙️ 一键安装命令

🧭 安装流程概述

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

2️⃣ K3s 集群部署

3️⃣ NVIDIA GPU 支持（可选）

4️⃣ 部署 CSGHUB 核心组件

5️⃣ 网络与域名配置

6️⃣ 私有仓库配置

⚡ 参数配置

必选参数

可选参数

🌏 常见安装模式

1️⃣ 国内网络环境

2️⃣ 启用 GPU 支持

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

4️⃣ 使用 LoadBalancer 暴露服务

5️⃣ 组合示例

📋 安装验证与访问

检查安装状态

查看安装日志

查看访问信息

🧰 故障排查

问题 1：脚本执行失败

问题 2：域名无法解析

问题 3：端口冲突

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

查看 K3s 与 Pod 日志

🧹 环境清理

✅ 安装完成后建议