クラスターデプロイ

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

前提条件

複数のサーバー（少なくとも2台、1マスター・複数スレーブアーキテクチャ）
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つのマスターデータベース N個のスレーブデータベース	マスターデータベースが書き込みを処理スレーブデータベースが読み取りを処理マスター・スレーブデータは自動的に同期	マスターデータベースアドレスを `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-newapi-domain> # フロントエンドのベース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-newapi-domain> # マスターノードと同じである必要があります
    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-newapi-domain>;

    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設定が正しく、アクセス可能であることを確認します。
クライアントがCookieを正しく処理しているかを確認します。