CSGHub 企业版 v1.10.0

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

优势

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

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

系统要求

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+
Argo Workflow	v3.5.12+	模型评测和镜像构建工作流
LeaderWorkSet	v0.6.1	多机多卡分布式训练支持
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

• 创建 Secret

  kubectl create ns csghub 
  kubectl -n csghub create secret generic csghub-kube-configs --from-file=/root/.kube/

  为什么需要注入 kubeconfig。

• 部署 Helm Chart

  默认安装 ee 版本。

  helm upgrade --install csghub csghub/csghub \
    --namespace csghub \
    --create-namespace \
    --set global.ingress.domain="example.com" \
    --set global.deploy.knative.serving.services[0].type="LoadBalacner" \ 
    --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="80"

  以上命令中 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"。

• 获取 Knative Serving 服务配置

  # 如果为空说明没有成功分配地址，请排查集群相关服务。
  # global.deploy.knative.serving.services[0].host
  kubectl get svc kourier -n kourier-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
  
  # global.deploy.knative.serving.services[0].port 
  80

• 更新配置

  如果这里使用的是 LoadBalancer 配置方式，需要使用以下命令进行升级操作：

  • host: 10.6.0.10 （仅为示例 IP，实际以 Loadbalancer 分配的地址为准）
  • port: 80

  helm upgrade --install csghub csghub/csghub \
    --namespace csghub \
    --create-namespace \
    --set global.ingress.domain="example.com" \
    --set global.deploy.knative.serving.services[0].type="LoadBalancer" \ 
    --set global.deploy.knative.serving.services[0].domain="app.internal" \
    --set global.deploy.knative.serving.services[0].host="10.6.0.10" \
    --set global.deploy.knative.serving.services[0].port="80"

登录 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

• 持久化卷说明

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

1. 创建 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请根据实际定义存储容量。

2. 查看资源

   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 实例，此解析需要用到泛域名解析。

4. 为什么需要注入 kubeconfig

.kube/config文件作为访问 Kubernetes 集群的重要配置文件，在 csghub helm chart 部署过程中需要以 Secret 的方式提供给 csghub helm chart。因 CSGHub 跨集群功能特性的支持，服务账户（serviceAccount）并不能满足 CSGHub 的运行需求。此 .kube/config至少需要包含对目标集群部署实例所在的命名空间的完全读写权限，如果开启了 argo和 KnativeServing 的自动配置，还需要创建命名空间等更多权限。

5. 持久化卷说明

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

• PostgreSQL

  默认 50Gi，用于存储数据库数据文件。

• Redis

  默认 10Gi，用于存储 Redis AOF 转储文件。

• Minio

  默认 500Gi，用于存储 头像图像、LFS 文件，Docker Image 镜像文件。

• Gitaly

  默认 200Gi，用于存储 Git 仓库数据。

• Nats

  默认 10Gi，存储消息流相关数据。

• GitLab-Shell

  默认 1Gi，用于存储主机密钥对。

在实际部署过程中，需要根据使用情况调整 PVC 的大小，或者直接使用可扩展的 StorageClass。

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

详细参考：

• kubernetes-sigs/nfs-subdir-external-provisioner

• kubernetes-sigs/sig-storage-local-static-provisioner

6. 手动安装依赖资源

• Knative Serving

• Argo Workflow

• LeaderWorkSet

• Nvidia Device Plugin

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

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

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

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

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

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

配置示例：

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

8. 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