クラスターデプロイ

このドキュメントでは、New API クラスターデプロイの詳細な設定手順とベストプラクティスを提供し、高可用性で負荷分散された分散システムの構築を支援します。

前提条件

複数のサーバー（最低2台、マスター・スレーブアーキテクチャ）
Docker および Docker Compose がインストール済みであること
共有の MySQL データベース（マスター・スレーブノードは同じデータベースにアクセスする必要があります）
共有の Redis サービス（ノード間のデータ同期とキャッシュに使用）
オプション：ロードバランサー（Nginx、HAProxy、またはクラウドプロバイダーが提供するロードバランシングサービスなど）

クラスターアーキテクチャの概要

New API クラスターはマスター・スレーブアーキテクチャを採用しています：

マスターノード：すべての書き込み操作と一部の読み取り操作を処理します
スレーブノード：主に読み取り操作を処理し、システム全体の処理能力を向上させます

クラスターアーキテクチャ

クラスターデプロイの主要な設定

クラスターデプロイの鍵は、すべてのノードが以下を満たすことです：

同じデータベースを共有する：すべてのノードが同じ MySQL データベースにアクセスします
同じ Redis を共有する：キャッシュとノード間通信に使用します
同じキーを使用する：SESSION_SECRET と CRYPTO_SECRET はすべてのノードで同じである必要があります
ノードタイプを正しく設定する：マスターノードは master、スレーブノードは slave

デプロイ手順

ステップ1：共有データベースと Redis の準備

まず、共有の MySQL データベースと Redis サービスを準備する必要があります。これには以下が考えられます：

個別にデプロイされた高可用性 MySQL および Redis サービス
クラウドプロバイダーが提供するマネージドデータベースおよびキャッシュサービス
独立したサーバーで実行される MySQL および Redis

MySQL データベースについては、以下のアーキテクチャを選択できます：

アーキテクチャタイプ	コンポーネント構成	動作方式	アプリケーション設定方法
マスター・スレーブレプリケーションアーキテクチャ	1つのマスターDB N個のスレーブDB	マスターDBが書き込みを処理スレーブDBが読み取りを処理マスター・スレーブデータは自動同期	マスターDBアドレスを `SQL_DSN` として設定
データベースクラスターアーキテクチャ	複数のピアノードプロキシ層(ProxySQL/MySQL Router)	すべてのノードが読み書き可能プロキシ層を介して負荷分散を実現自動フェイルオーバー	プロキシ層アドレスを `SQL_DSN` として設定

重要事項

どのアーキテクチャを選択しても、アプリケーションの SQL_DSN 設定は単一の統一されたエントリポイントアドレスのみが必要です。

これらのサービスがすべてのノードからアクセス可能であり、十分なパフォーマンスと信頼性を備えていることを確認してください。

ステップ2：マスターノードの設定

マスターノードサーバーで docker-compose.yml ファイルを作成します：

services:
  new-api-master:
    image: calciumion/new-api:latest
    container_name: new-api-master
    restart: always
    ports:
      - '3000:3000'
    environment:
      - SQL_DSN=root:password@tcp(your-db-host:3306)/new-api
      - REDIS_CONN_STRING=redis://default:password@your-redis-host:6379
      - SESSION_SECRET=your_unique_session_secret
      - CRYPTO_SECRET=your_unique_crypto_secret
      - TZ=Asia/Shanghai
      # 以下はオプション設定
      - SYNC_FREQUENCY=60 # 同期頻度、単位は秒
      - FRONTEND_BASE_URL=https://your-domain.com # フロントエンドのベースURL、メール通知などの機能に使用
    volumes:
      - ./data:/data
      - ./logs:/app/logs

セキュリティに関する注意

上記の構成例の値を、強力なパスワードとランダムに生成されたキー文字列に置き換えてください。

マスターノードを起動します：

docker compose up -d

ステップ3：スレーブノードの設定

各スレーブノードサーバーで docker-compose.yml ファイルを作成します：

services:
  new-api-slave:
    image: calciumion/new-api:latest
    container_name: new-api-slave
    restart: always
    ports:
      - '3000:3000' # 異なるサーバー上にあるため、マスターノードと同じポートを使用できます
    environment:
      - SQL_DSN=root:password@tcp(your-db-host:3306)/new-api # マスターノードと同じ
      - REDIS_CONN_STRING=redis://default:password@your-redis-host:6379 # マスターノードと同じ
      - SESSION_SECRET=your_unique_session_secret # マスターノードと同じである必要があります
      - CRYPTO_SECRET=your_unique_crypto_secret # マスターノードと同じである必要があります
      - NODE_TYPE=slave # 重要な設定、スレーブノードとして指定
      - SYNC_FREQUENCY=60 # スレーブノードとマスターノードの同期頻度、単位は秒
      - TZ=Asia/Shanghai
      # 以下はオプション設定
      - FRONTEND_BASE_URL=https://your-domain.com # マスターノードと同じである必要があります
    volumes:
      - ./data:/data
      - ./logs:/app/logs

スレーブノードを起動します：

docker compose up -d

この手順を各スレーブノードサーバーで繰り返します。

ステップ4：ロードバランサーの設定

トラフィックの均等な分散を実現するために、ロードバランサーを設定する必要があります。以下は、Nginx をロードバランサーとして使用する場合の設定例です：

upstream new_api_cluster {
    server master-node-ip:3000 weight=3;
    server slave-node1-ip:3000 weight=5;
    server slave-node2-ip:3000 weight=5;
    # さらにスレーブノードを追加可能
}

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

    location / {
        proxy_pass http://new_api_cluster;
        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;
    }
}

この設定では、マスターノードの重みが3、スレーブノードの重みが5に設定されており、スレーブノードがより多くのリクエストを処理することを意味します。これらの重みは、実際の要件に応じて調整できます。

高度な設定オプション

データ同期設定

クラスターノード間のデータ同期は、以下の環境変数に依存します：

環境変数	説明	推奨値
`SYNC_FREQUENCY`	ノード同期頻度（秒）	`60`
`BATCH_UPDATE_ENABLED`	バッチ更新を有効にする	`true`
`BATCH_UPDATE_INTERVAL`	バッチ更新間隔（秒）	`5`

Redis 高可用性設定

Redis の可用性を向上させるために、Redis クラスターまたは Sentinel モードを設定できます：

environment:
  - REDIS_CONN_STRING=redis://your-redis-host:6379
  - REDIS_PASSWORD=your_redis_password
  - REDIS_MASTER_NAME=mymaster # Sentinel モードでのマスターノード名
  - REDIS_CONN_POOL_SIZE=10 # Redis 接続プールサイズ

セッションセキュリティ設定

クラスター内のすべてのノードが同じセッションおよび暗号化キーを使用していることを確認してください：

environment:
  - SESSION_SECRET=your_unique_session_secret # すべてのノードで同じである必要があります
  - CRYPTO_SECRET=your_unique_crypto_secret # すべてのノードで同じである必要があります

監視とメンテナンス

ヘルスチェック

ノードの状態を監視するために定期的なヘルスチェックを設定します：

healthcheck:
  test:
    [
      'CMD-SHELL',
      "wget -q -O - http://localhost:3000/api/status | grep -o '\"success\":\\s*true' | awk -F: '{print $$2}'",
    ]
  interval: 30s
  timeout: 10s
  retries: 3

ログ管理

大規模なクラスターの場合、集中型ログ管理システムの使用をお勧めします：

environment:
  - LOG_SQL_DSN=root:password@tcp(log-db-host:3306)/new_api_logs # 独立したログデータベース

スケールアウトガイド

ビジネスの成長に伴い、クラスターの規模を拡張する必要があるかもしれません。スケールアウトの手順は以下の通りです：

新しいサーバーを準備する：Docker および Docker Compose をインストールする
スレーブノードを設定する：「ステップ3：スレーブノードの設定」の説明に従って、新しいスレーブノードを設定します
ロードバランサーの設定を更新する：新しいノードをロードバランサーの設定に追加します
新しいノードをテストする：新しいノードが正常に動作し、負荷分散に参加していることを確認します

ベストプラクティス

定期的にデータベースをバックアップする：クラスター環境であっても、データベースを定期的にバックアップする必要があります
リソース使用状況を監視する：CPU、メモリ、ディスクの使用状況を注意深く監視する
ローリングアップデート戦略を採用する：更新時には、まずスレーブノードを更新し、安定していることを確認してからマスターノードを更新します
アラートシステムを設定する：ノードの状態を監視し、問題が発生した場合は速やかに管理者に通知します
地理的に分散してデプロイする：可能であれば、異なる地理的場所にノードをデプロイして可用性を向上させます

トラブルシューティング

ノードがデータを同期できない

Redis 接続が正常か確認する
SESSION_SECRET および CRYPTO_SECRET がすべてのノードで同じであるか確認する
データベース接続設定が正しいか検証する

負荷の不均衡

ロードバランサーの設定と重み設定を確認する
各ノードのリソース使用状況を監視し、過負荷になっているノードがないことを確認する
ノードの重みを調整するか、さらにノードを追加する必要があるかもしれません

セッション消失の問題

すべてのノードが同じ SESSION_SECRET を使用していることを確認する
Redis 設定が正しく、アクセス可能であることを検証する
クライアントがクッキーを正しく処理しているか確認する