CSGShip

1. 概述

CSGShip 是 CSGHub 平台的 智能编码助手后端服务，为 CodeSouler（IDE 插件） 提供智能补全、语义搜索、对话式编程、AI 代码生成与知识检索等能力。该组件以独立服务形式部署，可单独扩展计算节点，支持多实例水平扩展，并可与主服务（CSGHUB Server）协同运行。

2. 环境要求

资源项	最低配置	推荐配置
CPU / 内存	4C / 8 GB	8C / 16 GB
磁盘空间	10 GB	50 GB+
架构支持	AMD64 / ARM64	支持多架构部署

软件依赖

组件	版本要求	说明
Kubernetes	1.28+	集群环境
Helm	3.12+	Chart 管理工具
PostgreSQL / Redis	可选（外部）	可使用外部托管资源

3. 开始安装

1. 添加 Helm 仓库

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

2. 创建命名空间（可选）

   kubectl create namespace csghub

3. 安装 CSGShip

   以下信息从 CSGHub 主服务处获取：

   • domain

     这里需要提供一个二级域名用于暴露 runner 服务。

     如果提供的域名是example.com，服务将暴露在csgship.example.com和csgship-api.example.com下。

   • externalUrl

     helm get notes csghub -n csghub | grep -A 6 'Access your CSGHub'

     获取 CSGHub 对应的URL。

   • hubAPIToken

     kubectl get cm csghub-core -o yaml -n csghub | grep 'API_TOKEN' | awk '{print $NF}'

   • nats

     kubectl get secret -n csghub csghub-nats \
         -o jsonpath='{.data.NATS_USERNAME}' | base64 -d && \
       echo -n " / " && \
       kubectl get secret -n csghub csghub-nats \
         -o jsonpath='{.data.NATS_PASSWORD}' | base64 -d

     • 以上命令提供 user, password
     • host目前仅支持使用服务名（即和 CSGHub 同集群部署，也可自行暴露服务）
     • port 固定值 4222

     这是一个自定义的参数，用来标识集群的区域，例如cn-north。

     💡 提示：

     • 国内部署添加：
       • --set global.image.registry="opencsg-registry.cn-beijing.cr.aliyuncs.com"
       • --set global.imageRegistry="opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq"

     注意：建议将自定义配置写入 custom-values.yaml，方便后续升级与版本管理。

     helm install csgship csghub/csgship \
       --namespace csghub \
       --create-namespace \
       --set global.gateway.external.domain="example.com" \
       --set externalUrl="<csghub externalUrl>" \
       --set hubAPIToken="<csghub hub_api_token>" \
       --set billing.nats.host="<csghub nats service>" \
       --set billing.nats.port=4222 \
       --set billing.nats.user="<csghub nats username>" \
       --set billing.nats.password="<csghub nats password>"

4. 访问路径示例

服务	地址	说明
CSGShip 前端	http://csgship.example.com	安装时需要配置--set web.oauth，见问问
CSGShip API	http://csgship-api.example.com

4. 参数配置说明

4.1 全局配置

参数	默认值	说明
global.edition	ee	版本类型：ce 社区版 / ee 企业版
global.gateway.external.domain	example.com	平台访问域名
global.gateway.tls.enabled	false	是否启用 HTTPS / TLS
global.persistence.size	10Gi	默认持久化卷大小
global.postgresql.enabled	true	启用内置 PostgreSQL
global.redis.enabled	true	启用内置 Redis
global.chartContext.isBuiltIn	false	是否作为主 Chart 子模块安装

4.2 服务配置

参数	默认值	说明
externalUrl	https://csghub.example.com	连接的 CSGHub 主服务地址
image.repository	opencsghq/csgship	主镜像仓库
image.pullPolicy	IfNotPresent	镜像拉取策略

4.2 OAuth 登录配置

CSGShip 支持通过 GitLab OAuth 登录，需在 values.yaml 或命令行中设置：

web:
  oauth:
    issuer: "https://gitlab.example.com"
    clientId: "<your-client-id>"
    clientSecret: "<your-client-secret>"

4.3 数据存储配置

4.3.1 PostgreSQL

参数	默认值	说明
global.postgresql.enabled	true	启用内置数据库
global.postgresql.external.host	无	外部数据库主机地址
global.postgresql.external.port	5432	外部数据库端口
global.postgresql.external.user	csghub	用户名
global.postgresql.external.password	""	密码
global.postgresql.external.sslmode	prefer	SSL 模式

💡 若生产环境中使用外部数据库，请设置：

global:
  postgresql:
    enabled: false
    external:
      host: "pg.example.com"
      port: 5432
      user: "csghub"
      password: "StrongPassword"

4.3.2 Redis

参数	默认值	说明
global.redis.enabled	true	启用内置 Redis
global.redis.external.host	无	外部 Redis 主机地址
global.redis.external.port	6379	外部 Redis 端口
global.redis.external.password	""	外部 Redis 密码

外部模式示例：

global:
  redis:
    enabled: false
    external:
      host: "redis.example.com"
      port: 6379
      password: "RedisStrongPassword"

5. 验证部署

查看 Pod 运行状态：

kubectl get pods -n csghub

查看服务地址：

kubectl get svc -n csghub

6. 升级与卸载

6.1 升级

helm upgrade csgship csghub/csgship \
  --namespace csghub \
  --create-namespace \
  --set global.gateway.external.domain="example.com" \
  --set externalUrl="<csghub externalUrl>" \
  --set hubAPIToken="<csghub hub_api_token>" \
  --set billing.nats.host="<csghub nats service>" \
  --set billing.nats.port=4222 \
  --set billing.nats.user="<csghub nats username>" \
  --set billing.nats.password="<csghub nats password>"

6.2 卸载

helm uninstall csgship -n csghub

7. 常见问题

问题	原因	解决方案
无法连接主服务	externalUrl 配置错误	检查域名与协议是否正确（需使用 HTTPS）
启动失败	数据库或缓存配置错误	检查 PostgreSQL / Redis 地址与密码
镜像拉取失败	私有镜像仓库认证问题	配置 image.pullSecrets

8. 生产部署建议

1. 启用外部 PostgreSQL 与 Redis，减少本地状态依赖。
2. 开启 TLS / HTTPS 访问，提升通信安全性。
3. 设置合适的 resources.requests 与 limits，防止节点资源竞争。