Skip to content
文档

Helm 部署

使用 Helm Chart 将 Cherry Studio Enterprise 部署到 Kubernetes 集群,包括 API 服务和管理后台。

推荐:使用 Cherry Studio Agent 部署技能可以自动完成以下所有步骤。详见 安装与部署 → Agent 一键部署。

特性

  • 双服务部署:同时部署 API 服务和管理后台(Admin)
  • 独立配置:每个服务可独立启用/禁用和配置
  • 自动扩展:支持 HPA(水平 Pod 自动扩展)
  • 健康检查:包含 liveness 和 readiness 探针
  • Ingress 支持:为每个服务配置独立的 Ingress 规则

前置条件

  • Kubernetes 1.16+
  • Helm 3.0+
  • 集群中需要支持 PVC
  • 已准备好 PostgreSQL 数据库(参考 数据库配置)

镜像地址

  • Docker Hub: cherrystudio/cherry-studio-enterprise-api
  • 国内镜像(推荐中国大陆用户使用): docker-registry.cherry-ai.com/public/cherry-studio-enterprise-api

部署步骤

第一步:获取 Helm Chart

选择以下任一方式:

方式一:下载 ZIP

wget https://github.com/CherryInternal/cherry-studio-enterprise-helm/archive/refs/heads/main.zip
unzip main.zip
cd cherry-studio-enterprise-helm-main

方式二:Git Clone

git clone https://github.com/CherryInternal/cherry-studio-enterprise-helm.git
cd cherry-studio-enterprise-helm

第二步:创建配置文件

Chart 默认的镜像版本、数据库连接和 JWT 密钥均为测试用值,不能直接用于部署。必须创建 values-custom.yaml 覆盖这些配置。

创建 values-custom.yaml,根据你的实际环境修改以下内容:

app:
  # 镜像版本(必须显式指定,否则会部署过时的 v0.1.3)
  image:
    tag: v0.4.10
    # 国内用户可切换为国内镜像:
    # repository: docker-registry.cherry-ai.com/public/cherry-studio-enterprise-api

  # 副本与自动扩展
  replicaCount: 1  # 推荐设置为 1 以保证数据一致性
  autoscaling:
    enabled: false  # 如需自动扩展,可设为 true

  # API 服务 Ingress
  api:
    ingress:
      enabled: true
      annotations:
        nginx.ingress.kubernetes.io/proxy-body-size: '20m'
      hosts:
        - host: api.your-domain.com          # ← 替换为你的 API 域名
          paths:
            - path: /
              pathType: ImplementationSpecific

  # Admin 后台 Ingress
  admin:
    ingress:
      enabled: true
      annotations:
        nginx.ingress.kubernetes.io/proxy-body-size: '20m'
      hosts:
        - host: admin.your-domain.com        # ← 替换为你的 Admin 域名
          paths:
            - path: /
              pathType: ImplementationSpecific

  # 存储配置
  persistence:
    size: 20Gi

  # 环境变量
  env:
    # 管理后台访问 API 的地址:
    #   - 使用 Ingress 时,填写 API 的外部域名(如 https://api.your-domain.com)
    #   - 仅集群内部通信时,填写 K8s Service 地址(如 http://cherry-studio-enterprise-api:3670)
    API_URL: https://api.your-domain.com     # ← 替换为你的 API 地址
    JWT_SECRET: 'your-secure-jwt-secret'     # ← 替换为强随机字符串(至少 32 字符)
    DB_HOST: your-postgres-host              # ← 替换为数据库地址
    DB_PORT: '5432'
    DB_USERNAME: your-username               # ← 替换为数据库用户名
    DB_PASSWORD: your-password               # ← 替换为数据库密码
    DB_NAME: your-database                   # ← 替换为数据库名称
    DB_TYPE: postgres

  # 资源配置(可选)
  resources:
    limits:
      cpu: 1000m
      memory: 1Gi
    requests:
      cpu: 200m
      memory: 256Mi

建议使用 Kubernetes Secret 管理 JWT 密钥和数据库密码等敏感信息,详见下方生产环境敏感信息管理。

第三步:安装

helm install cherry-studio-enterprise ./helm -f values-custom.yaml

# 或指定命名空间
helm install cherry-studio-enterprise ./helm -f values-custom.yaml \
  --namespace cherry-studio --create-namespace

第四步:验证部署

# 检查 Pod 状态
kubectl get pods -l app.kubernetes.io/name=cherry-studio-enterprise

# 检查 Service 状态
kubectl get svc -l app.kubernetes.io/name=cherry-studio-enterprise

# 检查持久化卷
kubectl get pvc

# 运行连接测试
helm test cherry-studio-enterprise

确认以下检查项:

  • 所有 Pod 都处于 Running 状态
  • Service 正常创建并有对应的 Endpoints
  • PVC 已绑定到可用的 PV
  • 如启用了 Ingress,检查 Ingress 规则是否正常创建

访问应用

使用 Port-Forward(测试环境)

# API 服务
kubectl port-forward svc/cherry-studio-enterprise-api 3670:3670

# Admin 后台
kubectl port-forward svc/cherry-studio-enterprise-admin 3680:3680

访问 http://localhost:3670(API)和 http://localhost:3680(Admin)。

使用 Ingress(生产环境)

通过 values-custom.yaml 中配置的域名直接访问:

  • API 服务:app.api.ingress.hosts 中配置的域名
  • Admin 后台:app.admin.ingress.hosts 中配置的域名

升级

修改 values-custom.yaml 中的 app.image.tag 为目标版本后执行:

helm upgrade cherry-studio-enterprise ./helm -f values-custom.yaml

卸载

# 卸载 Chart
helm uninstall cherry-studio-enterprise

# 手动删除 PVC(如需要)
kubectl delete pvc cherry-studio-enterprise-data

配置参考

应用服务参数

参数描述默认值
app.enabled是否启用应用服务true
app.replicaCount副本数量2
app.image.repository镜像仓库cherrystudio/cherry-studio-enterprise-api
app.image.tag镜像标签(⚠️ 未设置时回退到 Chart appVersion v0.1.3)未设置
app.autoscaling.enabled是否启用 HPA 自动扩展true
app.autoscaling.minReplicasHPA 最小副本数1
app.autoscaling.maxReplicasHPA 最大副本数10
app.api.service.typeAPI Service 类型ClusterIP
app.api.service.portAPI 服务端口3670
app.admin.service.typeAdmin Service 类型ClusterIP
app.admin.service.portAdmin 服务端口3680
app.persistence.enabled是否启用持久化存储true
app.persistence.size存储大小10Gi
app.persistence.accessMode存储访问模式ReadWriteOnce
app.persistence.mountPath数据挂载路径/app/data
app.api.ingress.enabled是否启用 API Ingresstrue
app.admin.ingress.enabled是否启用 Admin Ingresstrue
app.resources.limits.cpuCPU 限制500m
app.resources.limits.memory内存限制512Mi
app.resources.requests.cpuCPU 请求100m
app.resources.requests.memory内存请求128Mi
app.env.*环境变量配置见下方环境变量说明

端口说明

本应用在单个容器中运行两个服务:

端口服务描述
3670API 服务RESTful API 接口
3680Admin 后台管理后台界面

环境变量

通过 app.env 配置,以下为主要环境变量:

应用配置

环境变量描述
API_URL管理后台访问 API 的地址
API_PORTAPI 服务端口(默认 3670)
ADMIN_PORTAdmin 后台端口(默认 3680)
ADMIN_APP_NAME管理后台应用名称
ADMIN_APP_LOGO_URL管理后台 Logo URL
ADMIN_BASE_PATH管理后台基础路径(默认 /)
JWT_SECRETJWT 密钥(⚠️ 必须替换)

数据库配置

环境变量描述
DB_HOST数据库主机地址(⚠️ 必须替换)
DB_PORT数据库端口(默认 5432)
DB_USERNAME数据库用户名(⚠️ 必须替换)
DB_PASSWORD数据库密码(⚠️ 必须替换)
DB_NAME数据库名称(⚠️ 必须替换)
DB_TYPE数据库类型(默认 postgres)
DB_SSL是否启用 SSL(默认 false)

生产环境敏感信息管理

建议使用 Kubernetes Secret 管理 JWT 密钥和数据库密码:

# 创建 Secret
apiVersion: v1
kind: Secret
metadata:
  name: cherry-studio-jwt-secret
type: Opaque
data:
  jwt-secret: <base64-encoded-strong-random-string>
---
# 在 values-custom.yaml 中引用
app:
  env:
    JWT_SECRET:
      valueFrom:
        secretKeyRef:
          name: cherry-studio-jwt-secret
          key: jwt-secret

集群规格建议

用户规模节点配置节点数量Pod 副本数存储容量
0-50人2 vCPU, 4GB RAM1-2个110-20GB
50-200人4 vCPU, 8GB RAM2-3个1-220-50GB
200-1000人8 vCPU, 16GB RAM3-5个2-350-100GB
2000人以上16 vCPU, 32GB RAM5+个3-5100GB+

Cherry Studio Enterprise 是轻量级应用(启动后内存约 100-150MB,CPU < 100m),小规格集群也能支撑较多用户。

数据库推荐:

  • < 200人:单个 PostgreSQL 实例(2 vCPU, 4GB RAM)
  • > 200人:PostgreSQL 主从复制,主要用于提高可用性

故障排除

  1. Pod 一直处于 Pending 状态

    • 检查节点资源是否充足
    • 确认 PVC 能够正常创建和绑定
  2. 服务无法访问

    • 检查 Service 和 Endpoints 是否正确
    • 确认防火墙规则
  3. 数据丢失

    • 确认 PVC 配置正确
    • 检查存储类是否支持持久化

查看日志:

# 查看 Pod 日志
kubectl logs -l app.kubernetes.io/name=cherry-studio-enterprise

# 查看 Pod 详细信息
kubectl describe pod -l app.kubernetes.io/name=cherry-studio-enterprise

注意事项

  1. 单实例运行:为保证数据一致性,建议设置 replicaCount: 1。如需高可用,请配置 PostgreSQL 主从复制。

  2. 数据持久化:确保集群支持持久化存储,否则数据会在 Pod 重启时丢失。

  3. 网络安全:生产环境建议使用 Ingress + TLS,限制网络访问权限,定期更新镜像版本。