Helm 導入
Helm Chart で Cherry Studio Enterprise を Kubernetes に導入します(API サービスと管理コンソールを含む)。
推奨:Cherry Studio Agent デプロイスキルを使えば、以下のすべてのステップを自動化できます。詳細は インストールとデプロイ → Agent ワンクリック導入 をご覧ください。
特長
- 二重サービス導入:API と Admin を同時に導入
- 独立設定:各サービスは個別に有効化/無効化・設定可能
- 自動スケール:HPA(Horizontal Pod Autoscaler)に対応
- ヘルスチェック:liveness と readiness プローブを含む
- Ingress 対応:各サービスに独立した Ingress ルールを設定
前提条件
- Kubernetes 1.16+
- Helm 3.0+
- クラスターで PVC を使用可能
- PostgreSQL データベースを準備済み(データベース設定を参照)
Docker イメージ
- Docker Hub:
cherrystudio/cherry-studio-enterprise-api - 中国国内ミラー(中国大陸のユーザー向け):
docker-registry.cherry-ai.com/public/cherry-studio-enterprise-api
導入手順
ステップ 1:Helm Chart の取得
以下のいずれかの方法で取得します:
方法 A:ZIP ダウンロード
wget https://github.com/CherryInternal/cherry-studio-enterprise-helm/archive/refs/heads/main.zip
unzip main.zip
cd cherry-studio-enterprise-helm-main方法 B:Git Clone
git clone https://github.com/CherryInternal/cherry-studio-enterprise-helm.git
cd cherry-studio-enterprise-helmステップ 2:設定ファイルの作成
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
# 管理コンソール 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: 256MiJWT キーやデータベースパスワードなどの機密情報は Kubernetes Secret での管理を推奨します。詳細は下記の本番環境の機密情報管理をご覧ください。
ステップ 3:インストール
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ステップ 4:導入の確認
# Pod の状態確認
kubectl get pods -l app.kubernetes.io/name=cherry-studio-enterprise
# Service の状態確認
kubectl get svc -l app.kubernetes.io/name=cherry-studio-enterprise
# PVC の確認
kubectl get pvc
# 接続テスト
helm test cherry-studio-enterprise以下を確認してください:
- すべての Pod が Running 状態
- Service が作成され Endpoint が存在
- PVC が PV にバインド済み
- Ingress 有効時は Ingress ルールが作成済み
アプリへのアクセス
Port-Forward(テスト環境)
# API サービス
kubectl port-forward svc/cherry-studio-enterprise-api 3670:3670
# 管理コンソール
kubectl port-forward svc/cherry-studio-enterprise-admin 3680:3680http://localhost:3670(API)と http://localhost:3680(Admin)にアクセスします。
Ingress(本番環境)
values-custom.yaml で設定したドメインでアクセスします:
- API サービス:
app.api.ingress.hostsで指定したドメイン - 管理コンソール:
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.* | 環境変数 | 下記参照 |
ポート説明
本アプリは 1 つのコンテナで 2 つのサービスを動作させます:
| ポート | サービス | 説明 |
|---|---|---|
| 3670 | API サービス | RESTful API |
| 3680 | 管理コンソール | 管理 UI |
環境変数
app.env で設定します。主な変数は以下の通りです:
アプリケーション設定
| 環境変数 | 説明 |
|---|---|
API_URL | Admin から API へのアクセスアドレス |
API_PORT | API サービスポート(デフォルト 3670) |
ADMIN_PORT | Admin ポート(デフォルト 3680) |
ADMIN_APP_NAME | 管理コンソール名 |
ADMIN_APP_LOGO_URL | 管理コンソールのロゴ URL |
ADMIN_BASE_PATH | 管理コンソールのベースパス(デフォルト /) |
JWT_SECRET | JWT 秘密鍵(⚠️ 必ず置き換え) |
データベース設定
| 環境変数 | 説明 |
|---|---|
DB_HOST | DB ホスト(⚠️ 必ず置き換え) |
DB_PORT | DB ポート(デフォルト 5432) |
DB_USERNAME | DB ユーザー名(⚠️ 必ず置き換え) |
DB_PASSWORD | DB パスワード(⚠️ 必ず置き換え) |
DB_NAME | DB 名(⚠️ 必ず置き換え) |
DB_TYPE | DB 種別(デフォルト postgres) |
DB_SSL | SSL 有効化(デフォルト false) |
本番環境の機密情報管理
JWT キーやデータベースパスワードは Kubernetes Secret での管理を推奨します:
# 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 人:可用性向上のためのプライマリ/レプリカ構成
トラブルシューティング
-
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を推奨します。高可用性が必要な場合は、複数 Pod ではなく PostgreSQL のプライマリ/レプリカ構成を推奨します。 -
データ永続化:クラスターが永続ストレージをサポートしていないと、Pod 再起動でデータが失われます。
-
ネットワークセキュリティ:本番環境では Ingress + TLS を推奨、ネットワークアクセスを制限し、イメージを定期的に更新してください。