水平スケーリング
フロントエンドは自分の状態を持たず、リクエストのあいだに何も残さないので、自由にスケールできます。デプロイにあるようにリバースプロキシが /api/* をバックエンドへ直接振り分けていれば、チャットのストリームはフロントエンドをまったく通りません。以下はすべてバックエンドの話です。
2 レプリカ以上で動かすための要件
| 要件 | 理由 |
|---|---|
| PostgreSQL | SQLite はシングルライター、シングルプロセスです。全レプリカが 1 つのデータベースを共有し、レプリカを協調させるのもそのデータベースです |
SKILLS_DIR の共有 | 全レプリカが同じエージェントスキルストアをマウントする必要があります(ReadWriteMany)。実行は開始時のスキルのリビジョンに固定され、その実行の次のリクエストはどのレプリカに届くか分かりません |
| トランザクションプーリングのプロキシを挟まない | 後述のコネクションプーリングを参照してください |
MCP_PROXY_TLS_DIR の共有 | 各レプリカは MCP プロキシに対する自分の身元を示す資材をそこに書き、そこから読みます。プロキシも同じディレクトリを読みます。レプリカごとに別の場所を持つと、プロキシが見たことのない資材を発行することになります |
| スティッキーセッション | 不要です。ルーティングのアフィニティに求めたい役割は、後述のアドバイザリロックが果たします |
MCP プロキシ自体は別の理屈でスケールします。呼び出しのあいだに持つのはダウンロードのキャッシュだけなので、レプリカ間の協調は一切不要です。MCP_SANDBOX_DIR はレプリカ間で共有しても、それぞれが別に持ってもかまいません。バックエンドのレプリカ数ではなく、同時に走るツール呼び出しの数に合わせて増やしてください。
1 つの会話につき 1 つのドライバー
1 つの会話への書き込みは、レプリカをまたいでもすでに安全です。セッションサービスが、追記トランザクションの全体にわたって追記先の行に SELECT ... FOR UPDATE を掛けるので、追記は直列化され、会話の状態もイベントの行も失われません。
手当てが要るのは読み取りのほうです。エージェントのランタイムは 1 回の呼び出しのあいだ、メモリ上のセッションを 1 つ抱えます。そのため、そのあいだに別のレプリカが追記したイベントは届かず、実行の残りは欠けた会話をもとに考えることになります。書き込みを直列化してもこれは直りません。直せるのは、1 つのセッションを同時に 1 つのドライバーに限ることだけです。
そこで各エージェント実行(POST /api/v1/workflow-executions/{id}/agent、POST /api/v1/workflows/{id}/agent)は、PostgreSQL のセッションレベルのアドバイザリロックを取り、SSE ストリームの全体にわたって保持します。
同じセッションの 2 つ目の同時実行は、静かにずれていくのではなく、SSE のヘッダーを送る前に拒否されます。異なるセッションどうしが競合することはありません。ロックはあきらめる前に少しだけ待つので、ストリームを中断してすぐ再試行したクライアントが、放棄された実行の後始末中に拒否されることもありません。
人が介在する処理には影響しません。フロントエンドのツール呼び出しは実行を終わらせてストリームを閉じ、ロックを解放します。承認は新しいターンとして再開し、これはどのレプリカで動いてもかまいません。
各レプリカはセッションランナーも動かします。これは、ブラウザが動かさないターン、つまり実行のキックオフと承認後の再開を行うものです。同じロックを待たずに取りにいくので、すでに別のレプリカが動かしているセッションはそのレプリカに任せます。停止したレプリカがやりかけにしたターンも引き継ぎます。1 つのレプリカが同時に動かすターンの数は SESSION_RUNNER_CONCURRENCY で決まります(設定リファレンス)。
ロールアウト中のスキーママイグレーション
各レプリカは起動時に未適用のスキーママイグレーションを適用し、空のデータベースであれば初期アカウントと設定も作成します。複数のレプリカを同時にロールアウトすると全員が一度にこれを行おうとするので、順番に処理されます。最初に起動したレプリカが作業を行い、残りのレプリカは最大 10 分までその完了を待ってから、やることが残っていない状態で起動を続けます。10 分を過ぎても待っているレプリカは停止し、オーケストレーターがそれを再起動します。
コネクションプーリング
このロックはトランザクションレベルではなくセッションレベルなので、アプリと PostgreSQL のあいだにトランザクションプーリングのプロキシ(transaction モードの PgBouncer や、大半のサーバーレス PostgreSQL のプーラー)を挟んではいけません。ロックがステートメントをまたいで残らないからです。チャットのライブ更新も同じです。バックエンドの各プロセスは、ほかのレプリカで書き込まれたターンを知るための接続を 1 本開いたままにしていて、あるレプリカで開いているチャットに、別のレプリカで進むターンをその場で表示します。セッションレベルのプーリング、または直結が必要です。
接続数の見積もり
バックエンドの各プロセスは、次の用途でデータベースに接続します。
| 用途 | 接続数 |
|---|---|
| API リクエストを処理するプール | 最大 DB_POOL_SIZE + DB_MAX_OVERFLOW |
| 会話履歴のためのプール | 最大 DB_POOL_SIZE + DB_MAX_OVERFLOW |
進行中のエージェント実行 1 つごと(ブラウザで開いているチャット、またはサーバーが自分で動かすターン。後者は同時に最大 SESSION_RUNNER_CONCURRENCY 個) | 実行のあいだ 1 |
| 通知メールの送信者と、スキルのプルやナレッジベースの取り込みといったバックグラウンド処理 | 動いているあいだ、それぞれ 1 |
| ほかのレプリカからのチャットのライブ更新 | 常に 1 |
既定値では、1 プロセスあたりプールの接続が最大 30、それにライブ更新用の 1 本と、進行中の実行の数が加わります。PostgreSQL 自体の max_connections の既定値は 100 なので、忙しいレプリカが 4〜5 個あれば上限に届きます。レプリカを増やす前に、サーバーの max_connections を上げるか、DB_POOL_SIZE と DB_MAX_OVERFLOW を下げてください(設定リファレンス)。それでも足りなければ、PostgreSQL の前に session モードの PgBouncer を置いてください。
通知メール
送信メールのワーカーについて、こちらで調整することはありません。API プロセスの中で動いていても専用プロセスであっても、email-queue アドバイザリロックがデプロイ全体でちょうど 1 つの送信者を選ぶので、レプリカが二重に送ることはなく、設定したレート制限も正確なままです。ワーカーのレプリカを増やして得られるのはフェイルオーバーで、スループットではありません。プロセス構成を参照してください。