Skip to content
ドキュメント

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: 256Mi

JWT キーやデータベースパスワードなどの機密情報は 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:3680

http://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.enabledHPA オートスケールの有効化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.enabledAPI Ingress の有効化true
app.admin.ingress.enabledAdmin Ingress の有効化true
app.resources.limits.cpuCPU 上限500m
app.resources.limits.memoryメモリ上限512Mi
app.resources.requests.cpuCPU リクエスト100m
app.resources.requests.memoryメモリリクエスト128Mi
app.env.*環境変数下記参照

ポート説明

本アプリは 1 つのコンテナで 2 つのサービスを動作させます:

ポートサービス説明
3670API サービスRESTful API
3680管理コンソール管理 UI

環境変数

app.env で設定します。主な変数は以下の通りです:

アプリケーション設定

環境変数説明
API_URLAdmin から API へのアクセスアドレス
API_PORTAPI サービスポート(デフォルト 3670)
ADMIN_PORTAdmin ポート(デフォルト 3680)
ADMIN_APP_NAME管理コンソール名
ADMIN_APP_LOGO_URL管理コンソールのロゴ URL
ADMIN_BASE_PATH管理コンソールのベースパス(デフォルト /)
JWT_SECRETJWT 秘密鍵(⚠️ 必ず置き換え)

データベース設定

環境変数説明
DB_HOSTDB ホスト(⚠️ 必ず置き換え)
DB_PORTDB ポート(デフォルト 5432)
DB_USERNAMEDB ユーザー名(⚠️ 必ず置き換え)
DB_PASSWORDDB パスワード(⚠️ 必ず置き換え)
DB_NAMEDB 名(⚠️ 必ず置き換え)
DB_TYPEDB 種別(デフォルト postgres)
DB_SSLSSL 有効化(デフォルト 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 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 人:可用性向上のためのプライマリ/レプリカ構成

トラブルシューティング

  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 を推奨します。高可用性が必要な場合は、複数 Pod ではなく PostgreSQL のプライマリ/レプリカ構成を推奨します。

  2. データ永続化:クラスターが永続ストレージをサポートしていないと、Pod 再起動でデータが失われます。

  3. ネットワークセキュリティ:本番環境では Ingress + TLS を推奨、ネットワークアクセスを制限し、イメージを定期的に更新してください。