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.32+	集群环境
Helm	3.12+	Chart 管理工具
PostgreSQL / Redis	可选（外部）	可使用外部托管资源

3. 开始安装

添加 Helm 仓库

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

创建命名空间（可选）
```
kubectl create namespace csghub
```

安装 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

💡 提示：建议将自定义配置写入 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>"

国内部署（使用国内镜像仓库加速拉取镜像）：

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>" \
  --set global.image.registry="registry.opencsg.com" \
  --set global.imageRegistry="registry.opencsg.com/opencsghq"

访问路径示例

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

4. 参数配置说明

4.1 全局配置

参数	默认值	说明
global.gateway.external.domain	csghub.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-web	主镜像仓库
image.pullPolicy	IfNotPresent	镜像拉取策略

4.3 OAuth 登录配置

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

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

4.4 数据存储配置

4.4.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	disable	SSL 模式
global.postgresql.existingSecret	""	引用已有 Secret 提供连接信息（见下方说明），仅在 `enabled=false` 时生效

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

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

💡 也可以通过 existingSecret 引用一个已存在的 Secret 来提供外部连接信息（无需把账号密码写进 values.yaml）。该 Secret 必须提前在 release 命名空间内创建，键名（需 base64 编码）支持：

POSTGRES_HOST（必填）— 数据库主机地址

POSTGRES_PORT — 数据库端口（默认 5432）

POSTGRES_USER — 用户名

POSTGRES_PASSWORD — 密码

POSTGRES_SSLMODE — SSL 模式（disable / require / verify-full 等）

示例：
global:
  postgresql:
    enabled: false
    existingSecret: "my-pg-secret"

4.4.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.existingSecret	""	引用已有 Secret 提供连接信息（见下方说明），仅在 `enabled=false` 时生效

外部模式示例：

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

💡 也可以通过 existingSecret 引用一个已存在的 Secret。Secret 必须提前创建，支持的键名（base64 编码）：

REDIS_HOST（必填）— Redis 主机地址

REDIS_PORT — Redis 端口（默认 6379）

REDIS_PASSWORD — 认证密码

REDIS_USER — 用户名（如启用了 ACL）

REDIS_DATABASE — 数据库编号（默认 0）

示例：
global:
  redis:
    enabled: false
    existingSecret: "my-redis-secret"

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. 生产部署建议

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

1. 概述​

2. 环境要求​

软件依赖​

3. 开始安装​

4. 参数配置说明​

4.1 全局配置​

4.2 服务配置​

4.3 OAuth 登录配置​

4.4 数据存储配置​

4.4.1 PostgreSQL​

4.4.2 Redis​

5. 验证部署​

6. 升级与卸载​

6.1 升级​

6.2 卸载​

7. 常见问题​

8. 生产部署建议​