Helm Chart

目前 csghub helm chart ce/ee 已经合并。

优势

作为 Kubernetes 的原生包管理工具，Helm Chart 是 CSGHUB 在生产环境中的首选部署方式。其设计严格遵循以下原则：

向后兼容性：通过规范的版本控制确保升级路径平滑，用户可通过 helm upgrade 命令实现无缝版本迭代，显著降低生产环境变更风险。
持续架构优化：定期进行 Chart 重构，优化参数化配置架构，在提升部署性能的同时，增强配置灵活性和可维护性。
企业级管理：支持多环境差异化配置、版本回滚及与企业级特性，符合云原生最佳实践。

系统要求

CSGHUB 采用 Kubernetes Helm Chart 作为生产环境的标准部署方案，以下是运行所需的软硬件规格要求：

硬件要求

资源类型	最低配置	推荐配置	备注
CPU/内存	4核8GB	8核16GB
处理器架构	-	AMD64/ARM64	支持x86和ARM架构

Kubernetes 基础要求

集群版本：1.28+

持久化卷：需支持 Dynamic Volume Provisioning，如不支持请参考测试集群不支持 Dynamic Volume Provisioning。
Helm版本：3.12.0+

可选组件要求

组件名称	推荐版本	功能说明
Knative Serving	1.16.1+	启用自动配置时需要K8S 1.28+，可通过 autoConfigure 自动部署。
Argo Workflow	v3.5.12+	模型评测和镜像构建工作流，可通过 autoConfigure 自动部署。
LeaderWorkSet	v0.6.1	多机多卡分布式训练支持，可通过 autoConfigure 自动部署。
Nvidia Device Plugin	CUDA≥12.1	GPU加速支持（需配合NVIDIA驱动≥384.81）

建议生产环境采用推荐配置以获得最佳性能和稳定性。对于资源受限的环境，可使用最低配置，但可能影响系统响应能力。

提示：以上组件（除 Nvidia Device Plugin外）在 csghub helm chart 安装时会自动配置。

快速部署（仅测试用途）

如何准备域名

注意：当前仅支持 ubuntu/debian 系统。

一键安装会自动配置如下资源：

单节点 k3s 集群
csghub helm chart
nvidia-device-plugin（如果启用）

通过以下命令进行安装配置：

脚本可重复执行。

默认安装

默认使用 NodePort 方式暴露 csghub 服务。

# example.com 仅为示例域名
curl -sfL http://quick-install.opencsg.com | bash -s -- example.com

使用 Loadbalancer 方式暴露服务：

提示：使用LoadBalancer服务类型安装时，请提前将服务器sshd服务端口改为非22端口，该类型会自动占用22端口作为 git ssh 服务端口。
```
curl -sfL http://quick-install.opencsg.com | INGRESS_SERVICE_TYPE=LoadBalancer bash -s -- example.com
```

启用 NVIDIA GPU 支持

curl -sfL http://quick-install.opencsg.com | ENABLE_NVIDIA_GPU=true bash -s -- example.com

启用 Starship 支持

curl -sfL http://quick-install.opencsg.com | EDITION=ee ENABLE_STARSHIP=true bash -s -- example.com

国内安装

curl -sfL http://quick-install.opencsg.com | INSTALL_CN=true bash -s -- example.com

说明：部署完成后，通过查看login.txt访问 CSGHub。

可配置变量说明：

ENABLE_K3S

默认 true，安装 K3S 单节点集群。
ENABLE_NVIDIA_GPU

默认 false，启用后会自动配置 nvidia RuntimeClass 并且安装 Nvidia Device Plugin。
ENABLE_STARSHIP

默认 false，安装 Starship，仅 EE 版本可用（默认安装 ee 版本）。
HOSTS_ALIAS

默认 true，安装后自动配置域名解析到本宿主机。
INSTALL_HELM

默认 true，安装 helm 工具。
INGRESS_SERVICE_TYPE

默认 NodePort，使用 NodePort 服务类型暴露 csghub 服务。

如果 ENABLE_K3S=true 此项可以设置为 Loadbalancer（仅此一项，因为内置 Loadbalancer 服务仅能绑定 localhost），但是请注意，如果使用 LoadBalancer，22 端口将被 ingress nginx controller 抢占。如果依然选择使用此类型，请修改 sshd 服务默认端口为其他。
KOURIER_SERVICE_TYPE

默认 NodePort，使用 NodePort 服务类型暴露 Knative Serving 服务。
EDITION

默认ee, 安装 ee 版本 csghub helm chart（无 ee 许可证，功能同 ce）。
INSTALL_CN

默认 false, 设置为 true 则从阿里云拉取镜像。

标准部署

安装 Helm Chart

提示： 以下配置均针对单集群部署，多集群请联系工程师。

添加 helm 仓库

helm repo add csghub https://charts.opencsg.com/repository/csghub
helm repo update

部署 Helm Chart

默认安装 ee 版本。
```
helm upgrade --install csghub csghub/csghub \
  --namespace csghub \
  --create-namespace \
  --set global.ingress.domain="example.com" # 此处需要替换为自己的二级域名，程序会根据此二级域名生成需要的三级域名
```
以上命令中 192.168.18.10 仅为示例 IP 地址，真实地址需要安装后才可获得，因此如果要覆盖此设置您需要在首次安装后获得相关地址后再次执行下升级操作。

默认情况下global.deploy.autoConfigure=true会自动安装 Knative Serving，Lws，Argo Workflow，也可以手动安装。

如果从国内拉取镜像，请设置参数--set global.image.registry="opencsg-registry.cn-beijing.cr.aliyuncs.com"。

更多配置请参考：values.yaml。

登录 csghub

以上命令安装完成后会输出类似如下信息，根据一下命令登录 csghub 实例。

Release "csghub" has been upgraded. Happy Helming!
......
Visit CSGHub at the following address:

    Address: http://csghub.example.com
    Credentials: root/OTc1M2M0ZWMzYWIwNGU3MTMx
......
For more details, visit:
    https://github.com/OpenCSGs/csghub-charts

如何配置使用 NodePort 方式进行访问。

常见问题

1. 测试集群不支持 Dynamic Volume Provisioning

持久化卷说明

在测试集群不支持动态卷供应时，需要按照如下方式手动创建持久化卷，创建方式如下：

创建 PV

cat <<EOF | kubectl create -f -
apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-gitaly-0  # 可以自定义 PV 名称
spec:
  capacity:
    storage: 200Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Delete  # 通常建议使用 Retain or Delete
  storageClassName: hostpath
  hostPath:
    path: /data/hostpath/gitaly-0  			 # 需要替换为实际主机路径，需要确保路径在多节点间共享
  claimRef:
    namespace: csghub  									 # 替换为 PVC 所在的命名空间, 默认为 csghub
    name: data-csghub-gitaly-0					 # csghub 中 statefulset 会自动创建同名 PVC 并绑定
EOF

根据以上命令依次创建以下资源：

metadata.name	spec.capacity.storage	hostPath.path	claimRef.name
pv-gitaly-0	200Gi	/data/gitaly-0	data-csghub-gitaly-0
pv-gitlab-shell-0	1Gi	/data/gitlab-shell-0	data-csghub-gitlab-shell-0
pv-minio-0	500Gi	/data/minio-0	data-csghub-minio-0
pv-nats-0	10Gi	/data/nats-0	data-csghub-nats-0
pv-postgresql-0	50Gi	/data/postgresql-0	data-csghub-postgresql-0
pv-redis-0	10Gi	/data/redis-0	data-csghub-redis-0

gitaly和minio请根据实际定义存储容量。

查看资源
```
kubectl get pv
```

2. 如何配置使用 NodePort 进行访问

因为外部 URL 的访问不止暴露给用户，程序内部的内联调用也会用到，因此仅手动修改服务暴露类型为 NodePort 是无法保证实例正常工作的，需要通过以下方式进行配置。

以 NodePort 方式部署 csghub

helm upgrade --install csghub csghub/csghub \
  --namespace csghub \
  --create-namespace \
  --set global.ingress.domain="example.com" \
  --set global.ingress.service.type="NodePort" \
  --set ingress-nginx.controller.service.type="NodePort" \
  --set global.deploy.knative.serving.services[0].type="NodePort" \ 
  --set global.deploy.knative.serving.services[0].domain="app.internal" \
  --set global.deploy.knative.serving.services[0].host="192.168.18.10" \
  --set global.deploy.knative.serving.services[0].port="30213"

获取真实服务信息

# 如果为空说明没有成功分配地址，请排查集群相关服务。
# global.deploy.knative.serving.services[0].host
当前节点 IP 地址

# global.deploy.knative.serving.services[0].port 
kubectl get svc kourier -n kourier-system -o jsonpath='{.spec.ports[0].nodePort}'

更新配置

参考 Loadbalancer 方式的更新步骤即可。

3. 如何准备域名

Csghub helm chart 部署需要使用到域名，因为 Ingress 不支持使用 IP 地址进行路由转发。

域名类型

公有域名： 直接使用云解析。

自定义域名： 自行配置地址解析。

主要配置以下两个地方的域名解析：
- Kubernetes 集群的 CoreDNS 解析
- 客户端主机 hosts 解析
域名使用

如在安装时指定域名example.com。

Csghub helm chart 会将此域名作为父域名，创建如下子域名：
- csghub.example.com
  
  用于 csghub 主服务的访问入口。
  
  如果安装时指定--set global.ingress.useTop=true将使用 example.com 作为访问入口。
- casdoor.example.com
  
  用于访问 casdoor 统一登录系统。
- minio.example.com
  
  用于访问对象存储。
- registry.example.com
  
  用于访问容器镜像仓库。
- temporal.example.com
  
  用于访问计划任务系统，默认禁用。
- starship.example.com
  
  用于访问 starship 管理配置面板，默认禁用。
- starship-api.example.com
  
  用于访问 starship 管理控制台，主要用于配置 Codesouler 模型引擎。
- *.public.example.com
  
  用于访问所有 Knative 实例，此解析需要用到泛域名解析。
- loki.example.com
  
  用于访问 loki 实例，如果采用 runner 独立部署的方式，此域名会自动暴露。
- prometheus.example.com
  
  用于访问 prometheus 实例，如果存在外置的独立部署的 runner，需要启用此域名。
- runner.example.com
  
  当独立部署时，自动暴露此域名。
- dataflow.example.com
  
  当独立部署时，自动暴露此域名。

4. 持久化卷说明

CSGHub helm chart 存在多个组件需要持久化数据，组件如下：

组件 (Component)	默认存储 (Default Storage)	用途描述 (Purpose)
PostgreSQL	50 Gi	主应用数据库（用户、项目、元数据等）。
Redis	10 Gi	缓存、会话存储和临时任务队列。
Minio	500 Gi	对象存储（头像、LFS 文件、容器镜像）。
Gitaly	200 Gi	集中存储所有 Git 仓库数据。
Nats	10 Gi	消息流（JetStream）的持久化数据存储。
GitLab-Shell	1 Gi	存储 SSH 主机密钥对。
Dataflow	50 Gi	数据处理和工作流的临时数据集存储。
Label-Studio	10 Gi	标注项目配置和已标注数据集文件。
Loki	10 Gi	集中化日志存储（默认保留7天）。
Prometheus	8 Gi	监控指标和性能分析时序数据库。
MongoDB	10 Gi	为 AI 工具（如 CodeFuse）存储应用数据。

重要配置提示： 以上“默认”存储大小通常在 Helm Chart 的 values.yaml 文件中定义。实际存储消耗取决于您的具体使用情况。在部署前，必须根据团队的规模和预期增长来审查和配置这些值，尤其是对于 PostgreSQL、Gitaly 和 Minio 等核心组件，以避免因存储空间不足导致服务中断。

需要注意的是 csghub helm chart 并不会主动创建相关的 Persistent Volume，而是通过创建 Persistent Volume Claim 的方式自动申请 PV 资源，因此需要您的 Kubernetes 集群支持 Dynamic Volume Provisioning。如果是自部署集群可以通过模拟的方式实现动态管理。

详细参考：

5. 手动安装依赖资源

Knative Serving
Argo Workflow
LeaderWorkSet
Nvidia Device Plugin

标准部署时只能手动安装。

6. 如何减少命名空间（Namespace）的创建数量？

问题背景 默认安装csghub helm chart时（启用自动配置），会创建多达9个命名空间，其中4个来自第三方服务依赖。但在某些受限环境中：

可能存在命名空间数量限制
可能要求所有组件必须部署在单一命名空间内

解决方案 通过配置 Values.global.deploy.mergingNamespace 参数，可灵活控制命名空间数量：

模式	命名空间数量	适用场景	特点
Disable	9个	默认场景	保持原始命名空间结构
Multi	5个	需要适度精简的环境	合并部分非核心组件命名空间
Single	1个	严格受限环境/单命名空间要求	所有组件部署在同一命名空间

配置示例：

global:
  deploy:
    mergingNamespace: "Multi"  # 可选值：Disable/Multi/Single

7. Secret "csghub-docker-credential" in namespace "spaces" exists and cannot be imported into the current release

此问题是因为原 Secret csghub-docker-credential是通过 Job 创建在命名空间 Spaces 下面，但是因为现有的资源检测机制没有处理此文件的更新导致 Secret 发生变化后无法正常应用更新。现临时将 Secret 创建定义为正常的 helm resource 资源，于是出现了以上报错。解决方案如下：

kubectl delete secret csghub-docker-credential -n spaces

继续helm upgrade更新即可。

说明：以上为临时修改，后面会优化更好的适配方案。

问题反馈

如遇使用过程中遇到任何问题可以通过方式提交反馈：

Feedback

优势​

系统要求​

硬件要求​

Kubernetes 基础要求​

可选组件要求​

快速部署（仅测试用途）​

标准部署​

安装 Helm Chart​

登录 csghub​

常见问题​

1. 测试集群不支持 Dynamic Volume Provisioning​

2. 如何配置使用 NodePort 进行访问​

3. 如何准备域名​

4. 持久化卷说明​

5. 手动安装依赖资源​

6. 如何减少命名空间（Namespace）的创建数量？​

7. Secret "csghub-docker-credential" in namespace "spaces" exists and cannot be imported into the current release​

问题反馈​

优势