CSGShip 部署指南

📘 概述

CSGShip 是 CSGHub 平台的 智能编码助手后端服务，为 CodeSouler（IDE 插件） 提供智能补全、语义搜索、对话式编程、AI 代码生成与知识检索等能力。

该组件以独立服务形式部署，可单独扩展计算节点，支持多实例水平扩展，并可与主服务（CSGHUB Server）协同运行。

⚙️ 环境要求

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

软件依赖

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

🧩 安装步骤

1️⃣ 添加 Helm 仓库

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

2️⃣ 创建命名空间（可选）

kubectl create namespace csghub

3️⃣ 安装 CSGShip

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

domain

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

如果提供的域名是example.com，服务将暴露在runner.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。

helm install csgship csghub/csgship \
  --namespace csghub \
  --create-namespace \
  --set global.ingress.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>"

💡 建议： 将个性化配置（域名、镜像版本、数据库地址等）统一放在 custom-values.yaml 文件中，便于升级与回滚。

访问路径示例：

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

⚙️ 参数配置说明（基于 values.yaml）

🌍 全局配置（global）

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

🚢 CSGShip 服务配置

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

🔐 OAuth 登录配置

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

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

🗄️ 数据存储配置

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"

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"

🚀 验证部署

查看 Pod 运行状态：

kubectl get pods -n csghub

查看服务地址：

kubectl get svc -n csghub

🔄 升级与卸载

升级

helm upgrade csgship csghub/csgship -n csghub -f custom-values.yaml

卸载

helm uninstall csgship -n csghub

🧭 常见问题

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

📘 生产部署建议

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

📘 概述​

⚙️ 环境要求​

软件依赖​

🧩 安装步骤​

1️⃣ 添加 Helm 仓库​

2️⃣ 创建命名空间（可选）​

3️⃣ 安装 CSGShip​

⚙️ 参数配置说明（基于 values.yaml）​

🌍 全局配置（global）​

🚢 CSGShip 服务配置​

🔐 OAuth 登录配置​

🗄️ 数据存储配置​

PostgreSQL​

Redis​

🚀 验证部署​

🔄 升级与卸载​

升级​

卸载​

🧭 常见问题​

📘 生产部署建议​