Skip to content
ドキュメント

Docker 導入

Docker と Docker Compose で Cherry Studio Enterprise を導入。デュアルサービス統合、データ永続化、ヘルスチェックに対応します。

推奨:Cherry Studio Agent デプロイスキルを使えば、以下のすべてのステップを自動化できます。詳細は インストールとデプロイ → Agent ワンクリック導入 をご覧ください。

イメージレジストリ

中国国内ミラー(中国大陸のユーザー向け):

docker-registry.cherry-ai.com/public/cherry-studio-enterprise-api

Docker Hub(海外ユーザー):

cherrystudio/cherry-studio-enterprise-api

中国大陸のユーザーは、より高速で安定したイメージ取得のため、中国国内ミラーの使用を推奨します。

特長

  • 二重サービス統合:1 つのコンテナで API(3670)と管理コンソール(3680)を同時に実行
  • データ永続化:ボリュームマウントに対応し、データを安全に保持
  • 環境設定:柔軟な環境変数設定
  • ヘルスチェック:内蔵のヘルスチェック機構
  • 自動再起動:コンテナの自動再起動ポリシーをサポート

クイックスタート

前提条件

  • Docker 20.10+
  • Docker Compose 2.0+(任意)
  • PostgreSQL データベース(本番環境)

Docker Compose を使用

services:
  api:
    image: cherrystudio/cherry-studio-enterprise-api:v0.4.10
    container_name: cherry-studio-enterprise
    ports:
      - '3670:3670'
      - '3680:3680'
    environment:
      - API_URL=https://api.demo.cherry-ai.com
      - JWT_SECRET=your-secure-jwt-secret-at-least-32-characters
      - DB_HOST=1Panel-postgresql-UmXp
      - DB_PORT=5432
      - DB_USERNAME=cherry-studio-enterprise
      - DB_PASSWORD=${DB_PASSWORD}
      - DB_NAME=cherry-studio-enterprise
      - DB_TYPE=postgres
      - DB_SSL=false
    volumes:
      - ./data:/app/data
    restart: unless-stopped

本番環境の完全構成(DB 付き)

services:
  # PostgreSQL データベース
  postgres:
    image: postgres:15-alpine
    container_name: cherry-studio-enterprise-postgres
    environment:
      POSTGRES_USER: cherry-studio-enterprise
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: cherry-studio-enterprise
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - '5432:5432'
    restart: unless-stopped
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U cherry-studio-enterprise']
      interval: 10s
      timeout: 5s
      retries: 5

  # Cherry Studio API
  api:
    image: cherrystudio/cherry-studio-enterprise-api:v0.4.10
    container_name: cherry-studio-enterprise
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - '3670:3670'
      - '3680:3680'
    environment:
      # サービス設定
      - API_URL=https://api.your-domain.com
      - ADMIN_APP_NAME=Cherry Studio Enterprise

      # セキュリティ設定
      - JWT_SECRET=${JWT_SECRET:-your-secure-jwt-secret-at-least-32-characters}

      # データベース設定
      - DB_TYPE=postgres
      - DB_HOST=postgres
      - DB_PORT=5432
      - DB_USERNAME=cherry-studio-enterprise
      - DB_PASSWORD=${POSTGRES_PASSWORD}
      - DB_NAME=cherry-studio-enterprise
      - DB_SSL=false

    volumes:
      - ./data:/app/data
      - ./logs:/app/logs

    restart: unless-stopped

    healthcheck:
      test: ['CMD', 'wget', '--quiet', '--tries=1', '--spider', 'http://localhost:3670/health']
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

volumes:
  postgres_data:
    driver: local

起動と管理

# サービス起動
docker-compose up -d

# ログ表示
docker-compose logs -f

# サービス停止
docker-compose down

# 停止してボリューム削除(危険)
docker-compose down -v

設定説明

ポートマッピング

コンテナポートサービス説明
3670API サービスクライアントが呼び出す RESTful API
3680管理コンソールシステム設定・管理の Web UI

環境変数

コア設定

変数説明デフォルト必須
API_PORTAPI サービスのポート3670いいえ
ADMIN_PORT管理コンソールのポート3680いいえ
API_URLAPI ベース URL-はい
JWT_SECRETJWT 秘密鍵-はい
ADMIN_APP_NAME管理コンソール名Cherry Studioいいえ
ADMIN_APP_LOGO_URL管理コンソールのロゴ URL-いいえ
ADMIN_BASE_PATH管理コンソールのベースパス/いいえ

データベース設定

変数説明デフォルト備考
DB_TYPEデータベース種別postgrespostgres のみ対応
DB_HOSTデータベースホスト-PostgreSQL 必須
DB_PORTデータベースポート5432PostgreSQL 既定ポート
DB_USERNAMEデータベースユーザー名-PostgreSQL 必須
DB_PASSWORDデータベースパスワード-PostgreSQL 必須
DB_NAMEデータベース名-PostgreSQL 必須
DB_SSLSSL 有効化falsePostgreSQL SSL 接続

Casdoor SSO の設定は SSO 設定 を参照してください。

データ永続化

アプリケーションデータは /app/data に保存されます:

  • アップロードされたファイル
  • 知識ベースデータ
  • アプリ設定

永続化のため、ホストにマウントすることを推奨します:

volumes:
  - ./data:/app/data # アプリデータ
  - ./logs:/app/logs # ログ(任意)

導入のベストプラクティス

セキュリティ設定

JWT 秘密鍵の管理:

# 強力なランダム文字列を生成
openssl rand -base64 32

ネットワーク設定

カスタムネットワークを使用:

services:
  api:
    networks:
      - cherry-network

networks:
  cherry-network:
    driver: bridge

リバースプロキシ(Nginx)の設定:

server {
    listen 80;
    server_name api.your-domain.com;

    location / {
        proxy_pass http://localhost:3670;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name admin.your-domain.com;

    location / {
        proxy_pass http://localhost:3680;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

パフォーマンス最適化

リソース制限:

services:
  api:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '0.5'
          memory: 512M

ヘルスチェック設定:

healthcheck:
  test: ['CMD', 'curl', '-f', 'http://localhost:3670/health']
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

ログ管理

ログドライバ設定:

services:
  api:
    logging:
      driver: 'json-file'
      options:
        max-size: '10m'
        max-file: '3'

監視とメンテナンス

ログの確認

# リアルタイムでログを表示
docker logs -f cherry-studio-enterprise

# 直近 100 行を表示
docker logs --tail 100 cherry-studio-enterprise

# 期間を指定してログを表示
docker logs --since 2024-01-01 --until 2024-01-02 cherry-studio-enterprise

パフォーマンス監視

# コンテナのリソース使用状況
docker stats cherry-studio-enterprise

# コンテナの詳細情報
docker inspect cherry-studio-enterprise

# コンテナに入ってデバッグ
docker exec -it cherry-studio-enterprise sh

更新とアップグレード

# 最新イメージを取得
docker-compose pull

# サービス停止と再起動
docker-compose down
docker-compose up -d

トラブルシューティング

よくある問題

1. コンテナが起動しない

# コンテナログを確認
docker logs cherry-studio-enterprise

# ポート競合を確認
netstat -tulpn | grep -E '3670|3680'

# Docker デーモンを確認
systemctl status docker

2. データベース接続に失敗

  • データベースサービスが起動しているか確認
  • ネットワーク接続とファイアウォールを確認
  • データベース認証情報を確認
  • データベースが作成済みで権限が正しいか確認

3. 権限の問題

# データディレクトリ権限を修正
sudo chown -R 1000:1000 ./data

# もしくはコンテナ内で修正
docker exec cherry-studio-enterprise \
  chown -R node:node /app/data

4. メモリ不足

# Docker のメモリ上限を増加
docker update --memory 4g cherry-studio-enterprise

# または docker-compose.yml で設定
deploy:
  resources:
    limits:
      memory: 4G

注意事項

  1. 本番環境のセキュリティ:

    • 既定の JWT_SECRET を必ず変更
    • データベースは強力なパスワードで保護
    • HTTPS/TLS を有効化
    • イメージを定期的に更新
  2. データ永続化:

    • 常にデータボリュームをホストにマウント
  3. 性能面の考慮:

    • 負荷に応じてリソース制限を調整
    • 外部 PostgreSQL を使用すると性能向上
    • ヘルスチェックのパラメータを適切に設定
  4. ネットワークセキュリティ:

    • 必要なポートのみ公開
    • ファイアウォールでアクセスを制限
    • 本番環境ではリバースプロキシを使用

関連ドキュメント