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.minReplicas | HPA 最小副本数 | 1 |
app.autoscaling.maxReplicas | HPA 最大副本数 | 10 |
app.api.service.type | API Service 类型 | ClusterIP |
app.api.service.port | API 服务端口 | 3670 |
app.admin.service.type | Admin Service 类型 | ClusterIP |
app.admin.service.port | Admin 服务端口 | 3680 |
app.persistence.enabled | 是否启用持久化存储 | true |
app.persistence.size | 存储大小 | 10Gi |
app.persistence.accessMode | 存储访问模式 | ReadWriteOnce |
app.persistence.mountPath | 数据挂载路径 | /app/data |
app.api.ingress.enabled | 是否启用 API Ingress | true |
app.admin.ingress.enabled | 是否启用 Admin Ingress | true |
app.resources.limits.cpu | CPU 限制 | 500m |
app.resources.limits.memory | 内存限制 | 512Mi |
app.resources.requests.cpu | CPU 请求 | 100m |
app.resources.requests.memory | 内存请求 | 128Mi |
app.env.* | 环境变量配置 | 见下方环境变量说明 |
端口说明
本应用在单个容器中运行两个服务:
| 端口 | 服务 | 描述 |
|---|---|---|
| 3670 | API 服务 | RESTful API 接口 |
| 3680 | Admin 后台 | 管理后台界面 |
环境变量
通过 app.env 配置,以下为主要环境变量:
应用配置
| 环境变量 | 描述 |
|---|---|
API_URL | 管理后台访问 API 的地址 |
API_PORT | API 服务端口(默认 3670) |
ADMIN_PORT | Admin 后台端口(默认 3680) |
ADMIN_APP_NAME | 管理后台应用名称 |
ADMIN_APP_LOGO_URL | 管理后台 Logo URL |
ADMIN_BASE_PATH | 管理后台基础路径(默认 /) |
JWT_SECRET | JWT 密钥(⚠️ 必须替换) |
数据库配置
| 环境变量 | 描述 |
|---|---|
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 RAM | 1-2个 | 1 | 10-20GB |
| 50-200人 | 4 vCPU, 8GB RAM | 2-3个 | 1-2 | 20-50GB |
| 200-1000人 | 8 vCPU, 16GB RAM | 3-5个 | 2-3 | 50-100GB |
| 2000人以上 | 16 vCPU, 32GB RAM | 5+个 | 3-5 | 100GB+ |
Cherry Studio Enterprise 是轻量级应用(启动后内存约 100-150MB,CPU < 100m),小规格集群也能支撑较多用户。
数据库推荐:
- < 200人:单个 PostgreSQL 实例(2 vCPU, 4GB RAM)
- > 200人:PostgreSQL 主从复制,主要用于提高可用性
故障排除
-
Pod 一直处于 Pending 状态
- 检查节点资源是否充足
- 确认 PVC 能够正常创建和绑定
-
服务无法访问
- 检查 Service 和 Endpoints 是否正确
- 确认防火墙规则
-
数据丢失
- 确认 PVC 配置正确
- 检查存储类是否支持持久化
查看日志:
# 查看 Pod 日志
kubectl logs -l app.kubernetes.io/name=cherry-studio-enterprise
# 查看 Pod 详细信息
kubectl describe pod -l app.kubernetes.io/name=cherry-studio-enterprise注意事项
-
单实例运行:为保证数据一致性,建议设置
replicaCount: 1。如需高可用,请配置 PostgreSQL 主从复制。 -
数据持久化:确保集群支持持久化存储,否则数据会在 Pod 重启时丢失。
-
网络安全:生产环境建议使用 Ingress + TLS,限制网络访问权限,定期更新镜像版本。