より多くの CPU コアを活用する、リクエストを分散する、あるいは 1 つのインスタンスを停止してもサービスを継続するには、同じアプリを複数のインスタンスで実行し、リバースプロキシでリクエストを振り分けます。各インスタンスは同じ業務データベースと公開 URL を使います。互いに独立した別々のアプリを用意するわけではありません。
プロセスを増やすだけでは十分ではありません。ログイン状態、バックグラウンドタスク、リアルタイム通知が各プロセス内に保存されたままだと、次のリクエストが別のインスタンスに届いたときに結果が変わることがあります。共有が必要な状態を整えてから、インスタンス数を増やします。
以下では 2 つのインスタンスを例に説明します。PM2 と Docker Compose の例は、どちらも 1 台のサーバーで実行します。複数の CPU コアを活用できますが、サーバー全体の障害には対応できません。複数のサーバーに配置する場合は、共有サービスの可用性と負荷分散も検討してください。既存アプリの基本的なビルドとデプロイ手順は、PM2 でデプロイすると Docker でデプロイするを参照してください。
スケールアウト前に共有が必要な機能を確認する
インストール済みのパッケージだけで変更範囲を決めないでください。アプリの依存関係、server/plugins.ts、server/config/、本番設定、業務処理が実際に呼び出すサービスを確認します。業務コードが直接使っていない機能でも、認証、メール、通知プラグインを通じて間接的に使っている場合があります。
| 機能 | 主な用途 | 複数インスタンスでローカル実装を使い続けた場合 |
|---|---|---|
| Jobs | リクエストとは別に通知を送信する、ドキュメントを処理する、メールを同期する、指定時刻にタスクを実行する | 未処理タスクが特定のプロセスに属するため、別のインスタンスが引き継げません。同じスケジュールを各インスタンスが個別に実行する可能性があります。異常終了時には、永続化されていないタスクが失われることもあります。 |
| Queue | 遅延、優先度、レート制限、メッセージ配信を伴う処理 | メッセージ、重複排除の記録、レート制限のカウンターが共有されず、同じキューから複数インスタンスで処理を引き受けられません。 |
| Caching | クエリ結果、認証用の一時的な状態、共有カウンターのキャッシュ | あるインスタンスで書き込んだり削除したりした状態が、別のインスタンスには見えません。ログイン関連の操作、キャッシュ更新、回数制限の動作が不一致になる可能性があります。 |
| Realtime | 新着メッセージ、タスクの進捗、一覧の更新をユーザーに通知する | イベントは同じインスタンスに接続したブラウザーにしか届かず、別のインスタンスに接続したユーザーは更新を受け取れません。 |
| Concurrency | 同じ在庫集計を同時に更新するなど、複数のリクエストが同じリソースを同時処理することを防ぐ | ローカルロックが制御できるのは自分のプロセスだけです。2 つのインスタンスがそれぞれロックを取得しても、同じリソースを同時に操作できてしまいます。 |
| ID Generator(Snowflake) | レコードの数値 ID を生成する | 複数のプロセスが同じ workerId を使うと、重複した ID が生成され、書き込みの失敗やデータの競合につながる可能性があります。 |
たとえば、認証プラグインを有効にしているアプリでは、そのプラグインが使う Caching を確認します。通知、メール、Scheduler、ナレッジのインデックス作成は Jobs を使う場合があり、アプリ内メッセージやタスクの進捗は Realtime に依存する場合があります。Queue と Jobs は別の機能であり、一方を設定しても他方の設定は変わりません。
業務機能が個別の設定を選択しているかも確認します。たとえば、scheduler.jobs、notification.jobs、mail.jobs、knowledge.jobs では、名前付きの Jobs バックエンドを選択できます。jobs.default を変更しても、これらの機能は元のローカルバックエンドを使い続ける可能性があります。キャッシュ、キュー、排他制御の呼び出しでも、設定名を明示的に指定している場合があります。
確認後には、どの業務機能がインスタンス間の連携を必要とし、現在どのバックエンドを使い、どの設定を変更するかを整理できる状態にします。使っていない機能はそのままで構いません。共有状態を持たず、プロセス内の最適化だけに使うキャッシュも、すべて移行する必要はありません。
共有サービスと実行設定を準備する
アプリを変更する前に、各インスタンスが共通で使うリソースを準備します。
- 業務データベース:すべてのインスタンスを同じデータベースに接続し、同じテーブル構造を使います。単一インスタンスの例にある SQLite ファイルを 2 つのコンテナにコピーしても、共有データベースにはなりません。既存アプリが SQLite を使っている場合は、複数インスタンスからのアクセスに適したデータベースへ先に移行し、ビルド前に対応するドライバーをインストールします。接続パラメーターはデータベースの互換性を参照してください。
- Redis:共有が必要な Jobs、Queue、Caching、Realtime、Concurrency からアクセスできる Redis を用意します。Jobs と Queue では永続化を有効にし、
maxmemory-policy noevictionを使って、メモリー不足によるデータの追い出しで未処理タスクが失われることを防ぎます。ポートに接続できることだけでなく、容量、バックアップ、アクセス制御も設定してください。 - ファイルストレージ:インスタンス A からアップロードしたファイルを、インスタンス B からダウンロードできる必要があります。アプリが対応するオブジェクトストレージまたは共有ファイルシステムを選び、既存のファイルコレクションが実際に選択しているストレージディスクを確認します。デフォルトのストレージを変えるだけでは、既存ファイルは移動せず、明示的に選択されたディスクも一括では変わりません。バックグラウンドタスクが読む添付ファイルやインポートファイルなども、リクエストを受けたインスタンスだけに保存しないでください。
- 鍵と公開 URL:各インスタンスで同じ
secrets.keysと既存の認証・セッション用の鍵を引き継ぎ、同じAPP_PUBLIC_ORIGINとAPP_BASE_PATHを使います。インスタンスごとに設定を初期化し直さないでください。待ち受けポートは異なっていても、公開 URL はhttps://apps.example.com/main/などの同じアドレスを使います。
以下の Redis 設定例では、すべてのインスタンスからアクセスできるアドレスとして redis.internal:6379 を使います。実際のアドレスに置き換えてください。コンテナ内の 127.0.0.1 はそのコンテナ自身を指すため、別のマシンやコンテナの Redis には接続できません。
同じアプリの全インスタンスで、同じ名前空間とキャッシュプレフィックスを使います。テスト、ステージング、本番環境では、それぞれ別の値を設定してください。名前空間はデータの混在を防ぎますが、Redis アカウントの権限やネットワーク分離を代替するものではありません。
以下の config.yml はすべて本番環境の実行設定を指します。必要な部分を既存の設定にマージし、データベース、鍵、業務設定を保持してください。例の断片でファイル全体を上書きしないでください。読み取り権限をサービスアカウントに限定し、コードリポジトリにはコミットしません。環境変数がファイルの値を上書きする場合があるため、実際のプロセスと同じ環境で確認します。${REDIS_PASSWORD} をそのまま記述しても、パスワードには自動置換されません。機密値の指定方法は設定リファレンスを参照してください。
アプリが別途 @nocobase/session のセッションストレージを使っている場合は、session.default も確認し、インスタンス間で共有するセッションには共有ストレージを選択します。これは認証プラグインが Caching を通じて保持する状態とは別の設定です。Caching Redis を設定しても、自動では変更されません。
Agent を使ってアプリを変更しデプロイする
アプリのソースディレクトリで開発 Agent を使います。対象サーバー、データベース、Redis、ファイルストレージ、必要な商用プラグインへのアクセス権を事前に用意してください。認証情報は安全な方法で渡し、プロンプトには含めません。アプリの開発・デプロイ用 Skills と、インストール後に同期されるプラグインの Skills に、各バージョンに対応した導入手順があります。
既存アプリを確認する
まずはファイルを変更せず、確認だけを Agent に依頼できます。
このアプリを、1 つの公開 URL を共有する 2 つのインスタンスとしてデプロイしたいです。
まず、既存の業務機能と有効なプラグインを確認してください。バックグラウンドタスク、キャッシュ、リアルタイムメッセージ、同時実行の制御のうち、インスタンス間で共有が必要なものと、レコード ID の生成に変更が必要かを調べてください。
現在の設定のままだとどの機能に影響があるか、どの共有サービスと商用プラグインを準備すべきかを教えてください。まだ変更やデプロイはしないでください。結果を見るときは、パッケージ名の一覧だけでなく、実際の業務動作が確認されているかを重視します。たとえば、定期通知が二重送信されないか、ログイン後のリクエストが別のインスタンスに移っても有効か、アップロードしたファイルやタスクの進捗を別のインスタンスから参照できるかを確認します。未処理タスクやローカルファイルがある場合は、その保持方法と移行方法も明確にしてください。
複数インスタンスを設定してデプロイする
変更範囲を確認したら、デプロイ先を伝えます。以下は PM2 の例です。コンテナを使う場合は Docker Compose に変更し、イメージレジストリまたはイメージファイルによる転送方法を指定してください。
先ほど確認した方針に沿って、このアプリを 2 つのインスタンスで動かせるように変更し、PM2 でデプロイしてください。
サーバー:<SSH ユーザーとアドレス>
デプロイ先ディレクトリ:<サーバー上の絶対パス>
公開 URL:<例:https://apps.example.com/main/>
共有データベース、Redis、ファイルストレージ:<準備済みのサービスと認証情報の取得方法>
許容停止時間:<メンテナンス時間帯>
既存のユーザー、業務データ、ファイル、鍵を保持してください。共有が必要な機能に対応する商用プラグインを導入し、2 つのインスタンスが連携できることを確認してから本番のアクセスを切り替えてください。
ログイン、バックグラウンド処理、リアルタイム更新、ファイルアクセスを確認し、一方のインスタンスを止めても他方でリクエストを処理できるか検証してください。結果と、私が対応する必要のある問題を教えてください。互換性のある商用プラグインを取得できない場合や、サーバーに接続できない場合でも、Agent はコードと設定の準備を進められます。ただし、それだけで本番インスタンスを増やすことはできません。設定ファイルやプロセスの起動画面だけでなく、実際の検証結果が提示されていることを確認してください。
分散プラグインと設定
必要な商用プラグインをインストールして登録する
依存関係とプラグイン登録の変更はアプリのソースディレクトリで行い、その後に再ビルドします。本番コンテナやインストーラーの release ディレクトリ内に直接プラグインをインストールしないでください。
| 変更する機能 | 商用プラグイン |
|---|---|
| Jobs | @nocobase/app-plugin-jobs-redis |
| Queue | @nocobase/app-plugin-queue-redis |
| Caching | @nocobase/app-plugin-caching-redis |
| Realtime | @nocobase/app-plugin-realtime-redis |
| Concurrency | @nocobase/app-plugin-concurrency-redis |
| Snowflake ワーカー ID の自動割り当て | @nocobase/app-plugin-snowflake-worker |
対象パッケージのダウンロード権限を持つアカウントの読み取りトークンで <read-token> を置き換え、商用パッケージレジストリを設定します。コマンドはユーザーの ~/.npmrc に書き込み、npm と pnpm の両方がこのファイルを読み取ります。有効な設定がある場合は省略できます。
npm config set "@nocobase:registry" "https://pkg-v3.nocobase.com/"
npm config set "//pkg-v3.nocobase.com/:_authToken" "<read-token>"確認結果に応じて、必要なプラグインを 1 つずつ登録します。Jobs の例では、まず利用可能なバージョンと依存条件を確認し、<compatible-version> を現在のアプリに対応するバージョンに置き換えます。
pnpm view @nocobase/app-plugin-jobs-redis versions --json
pnpm view '@nocobase/app-plugin-jobs-redis@<compatible-version>' peerDependencies --json
pnpm nocobase plugin register @nocobase/app-plugin-jobs-redis --version '<compatible-version>'他のプラグインも、表にある完全なパッケージ名で同じ操作を行います。すべてのプラグインのバージョン番号が同じとは限らず、ダウンロードできただけでは互換性を確認できません。アプリのフレームワーク、商用プラグイン、以下の設定構造が対応している必要があります。古いアプリでは、先に NocoBase Core のアップグレードに従って互換性を確認してください。
ここで変更するのは業務機能が使うバックエンドです。通常、既存のオープンソースサービスをアンインストールする必要はありません。
server/app.tsにある Caching、Jobs、Queue、ID Generator などの既存のサービスプロバイダーを保持します。- オープンソースの
@nocobase/app-plugin-concurrencyを保持し、その後にapp-plugin-concurrency-redisを登録します。 server/plugins.tsの順序を確認し、商用バックエンドのプラグインを、それを使う業務プラグインより前に配置します。特に Caching Redis は、認証など起動時にキャッシュへアクセスするプラグインより前に配置してください。- 表の最初の 5 つの商用プラグインは Server 側の登録だけが必要です。Snowflake worker は、さらに
cli/plugins.tsで CLI 側の登録が必要です。登録コマンドの結果を確認し、手動変更の指示があれば対応してください。
登録後に Skills を同期し、依存関係、ロックファイル、登録ファイルの変更を確認します。
pnpm nocobase skills sync
pnpm nocobase plugin inspect @nocobase/app-plugin-jobs-redis --jsonplugin inspect のパッケージ名も、必要に応じて変更してください。続いて各バックエンドを選択します。インストールと登録だけでは、メモリー上の設定が自動的に Redis に切り替わるわけではありません。
Jobs:バックグラウンドタスクと定期タスクを連携させる
Jobs は、通知送信やドキュメント処理などの単発のバックグラウンド処理と、定期タスクを扱います。共有バックエンドを使うと、各インスタンスが個別にタスク一覧を管理するのではなく、同じ未処理タスクの集合から処理を引き受けられます。
本番設定に shared バックエンドを追加し、それを選択します。
jobs:
default: shared
backends:
shared:
adapter: redis
namespace: my-app-production
connection:
host: redis.internal
port: 6379
db: 0
concurrency: 2
attempts: 1concurrency: 2 は、各インスタンス上の各実行器の並列数です。アプリ全体で同時実行できるタスクが 2 つという意味ではありません。インスタンスを増やすときは、データベースやメールサービスなどが処理できる負荷も再確認してください。
scheduler.jobs、notification.jobs、mail.jobs、knowledge.jobs を確認します。未指定なら jobs.default を使えますが、memory を明示的に選択している場合は shared に変更するか、専用の Redis バックエンドを設定します。デフォルト値を変えても、明示的な選択は上書きされません。
Scheduler は既存のプラグインを引き続き使い、Redis 用の Scheduler を別途インストールする必要はありません。Scheduler が使う Jobs 設定では attempts を 1 に保ち、他の業務機能のリトライはそれぞれの要件に合わせて設定します。障害復旧時にはタスクが再実行される可能性があるため、二重請求や二重出荷などが発生しないよう、業務ロジックで対処してください。
Queue:複数インスタンスでキューメッセージを処理する
遅延実行、優先度、共通のレート制限が必要な場合、アプリは Queue を使うことがあります。たとえば、送信待ちメッセージをキューに入れ、送信速度を制御できます。Jobs とは設定を共有しないため、実際に Queue を使っているアプリだけで対応が必要です。
queue:
default: shared
backends:
shared:
adapter: redis
namespace: my-app-production
connection:
host: redis.internal
port: 6379
db: 0
concurrency: 2
attempts: 3
backoff:
type: exponential
delay: 1000複数のインスタンスが同じキューからメッセージを取得して処理します。各インスタンスがすべてのメッセージを 1 回ずつ実行するわけではありません。各インスタンスで互換性のあるコードと処理ロジックを実行し、新しいバージョンが投入したメッセージを、対応していない古いバージョンが取得しないようにしてください。
キューの並列数もインスタンスごとに計算されます。一方、業務処理で rateLimit を使う場合は、同じ共有キューを使う全インスタンスに共通の制限となります。既存の Redis キューでは、接続先、名前空間、キュー名を保持し、新しいインスタンスが空のキューに接続しないようにします。初期化し直すために既存のキューを空にしないでください。
Jobs と Queue のメモリー状態ファイルは、同じディレクトリをマウントしても共有キューにはなりません。Redis へ切り替えても、これらのファイルは自動でインポートされません。まず新しいタスクの投入を止め、既存タスクの完了を待つか、業務に応じた移行と補償処理を計画してください。
Caching:キャッシュ、ログイン状態、カウンターを共有する
キャッシュはクエリを高速化するためだけのものではありません。認証プラグインも認証関連の状態やカウンターを保存するために使います。そのため、ページが開けるだけでは、各インスタンスでログイン処理が一貫しているとは判断できません。
Redis provider を新しく追加します。既存の memory 項目の driver を直接変更すると、maxSize や useClone などメモリー専用の設定まで Redis に引き継いでしまうため、避けてください。
caching:
default: shared
providers:
shared:
driver: redis
connection:
host: redis.internal
port: 6379
db: 0
keyPrefix: my-app-production
defaultTtl: 5m
connectTimeoutMs: 2000
commandTimeoutMs: 5000
shutdownTimeoutMs: 30000各インスタンスで同じ keyPrefix を使い、他の環境では別のプレフィックスを使います。業務コードが memory provider を明示的に選択している場合は、呼び出しごとに shared へ変更すべきかを判断します。providers に設定を追加するだけでは、デフォルトのキャッシュは変わりません。
Redis キャッシュは JSON データを保存します。これまで Date、Buffer、クラスのインスタンスをメモリーにキャッシュしていた業務処理では、保存に適した形式に変換し、読み取り時に必要なデータ型へ戻す必要があります。有効期限も業務に合わせて設定し、アプリ全体のキャッシュを永続データとして扱わないでください。
共有キャッシュは分散ロックではありません。キャッシュの読み込み処理が重複リクエストをまとめるのは同じプロセス内だけで、別のインスタンスによる同時読み込みは防ぎません。インスタンス間の排他制御が必要な操作には Concurrency を使います。
Realtime:異なるインスタンスに接続したユーザーへ更新を届ける
インスタンス A でバックグラウンドタスクが完了し、ブラウザーがインスタンス B に接続している場合、Realtime の Redis バックエンドが更新を届けます。既存のページの購読処理や業務メッセージを、別の API に変更する必要はありません。
realtime:
namespace: my-app-production
broker:
adapter: redis
setupTimeoutMs: 5000
connection:
host: redis.internal
port: 6379
db: 0古いアプリに server/config/realtime.ts がない場合は、設定ファクトリーを追加し、server/config/index.ts で realtime をインポートして登録します。
import { defineRealtimeConfig } from '@nocobase/app-server/realtime';
export default defineRealtimeConfig();すべてのインスタンスで同じ realtime.namespace を使います。Redis Pub/Sub はデータベース番号でメッセージを分離しません。テスト環境で db: 0、本番環境で db: 1 を使っていても、名前空間は分ける必要があります。
リアルタイムメッセージは、オフライン中のメッセージを保存する仕組みではありません。ブラウザーが切断されている間の更新は自動再送されないため、再接続後に業務データを読み直してください。デプロイやインスタンスの停止でも WebSocket 接続は切れるため、再接続とデータ更新が正常に動くか確認します。
Concurrency:複数インスタンスによる同じ操作の同時実行を防ぐ
たとえば、同じ在庫集計をロックで保護する場合、インスタンス A が更新中なら、インスタンス B は待機するか処理中の応答を返す必要があります。それぞれがローカルロックを取得して、同時に変更できてはいけません。
既存の Concurrency プラグインと業務コードの呼び出しを保持し、実際に選択するバックエンドだけを切り替えます。
concurrency:
default: shared
backends:
shared:
adapter: redis
namespace: my-app-production
ttl: 10000
connection:
host: redis.internal
port: 6379
db: 0
connectTimeout: 1000
commandTimeout: 1000同じロックを取り合うには、各インスタンスで同じ Redis データベース、名前空間、業務ロック名を使う必要があります。業務コードが別の設定名を明示的に選択している場合は、その設定も変更してください。
ttl はミリ秒単位のロック有効期間で、プラグインが自動的に延長します。業務処理の最大実行時間ではなく、期限が来ても処理を強制終了しません。ネットワーク障害時のデータの正しさをロックだけに頼ることはできません。重要な書き込みには、データベースの制約、トランザクション、重複処理の防止も必要です。
Snowflake:各インスタンスに異なるワーカー ID を割り当てる
Snowflake はローカルで ID を生成し、その中に生成元のプロセスを区別する workerId を含めます。オープンソース実装も複数インスタンスで使えますが、同時に ID を生成する全プロセスに重複しない番号を手動で割り当て、再起動と番号の再利用を適切に管理する必要があります。PM2 のプロセス番号やコンテナ名が、自動的に Snowflake の番号になるわけではありません。
自動割り当てを使う場合は、app-plugin-snowflake-worker の Server と CLI のエントリーを登録し、既存の server/config/snowflake.ts を次の内容に置き換えます。
import { defineSnowflakeWorkerConfig } from '@nocobase/app-plugin-snowflake-worker/config';
export default defineSnowflakeWorkerConfig();server/config/index.ts にある既存の snowflake 設定項目と、server/app.ts にある元の IdGeneratorProvider は保持します。古い Snowflake 設定ファクトリーを重ねて登録しないでください。
続いて、自動割り当てを有効にします。
snowflake:
mode: auto
releasePolicy:
strategy: manualmode: auto を設定すると、プラグインがアプリのデフォルトデータベースを使って、各プロセスに異なる workerId(プロセス識別番号)を割り当てます。レコード ID 自体は、引き続き各プロセス内で生成されます。すべてのインスタンスを同じ番号割り当て用データベースに接続してください。SQLite は自動割り当てに対応しておらず、手動モードに戻ります。
デプロイ時には、次の点に注意してください。
- 番号の数:割り当て可能な番号は 32 個(
0~31)です。稼働中のインスタンス、ローリング更新中にまだ終了していない旧インスタンス、ID の生成が必要な管理コマンドのプロセスも、それぞれ番号を使用します。 - 番号の解放:正常終了時には番号が返却されます。例の
manualポリシーでは、異常終了したプロセスの割り当ては自動解放されません。snowflake-worker listで割り当て状況を、snowflake-worker inspect <worker-id>で詳細を確認できます。対象プロセスが恒久的に停止し、自動再起動しないことを確認してから、snowflake-worker release <worker-id>で解放してください。このコマンドはデフォルトではプレビューのみで、実行には必要な確認パラメーターと--applyが必要です。 - 時刻同期:時刻の巻き戻りが ID 生成に影響しないよう、各サーバーの時計を同期してください。
複数のインスタンスを起動する
マルチインスタンスデプロイでは、同じアプリを複数のプロセスまたはコンテナで実行します。ユーザーは共通の URL にアクセスし、リバースプロキシがリクエストを振り分けます。すべてのインスタンスは同じ業務データベースに接続し、必要に応じて同じ Redis バックエンドを使い、同じ業務ファイルにアクセスします。PM2 と Docker Compose はプロセスの管理方法を変えるもので、この共有構成は変わりません。
以下では 1 台のサーバー上の 2 つのインスタンスを使い、公開 URL を https://apps.example.com/main/ とします。デプロイ前に、共有するものとインスタンスごとに分けるものを整理してください。
| 項目 | インスタンス間の関係 |
|---|---|
| アプリのコード | 同じバージョンを実行し、同じプラグインと業務ロジックを使います。 |
| データベース | 同じ業務データベースに接続します。インスタンスごとにコピーを作りません。 |
| Redis | 前述の共有バックエンドを使います。同じ業務機能では、接続先、名前空間、キャッシュプレフィックスをそろえます。 |
| 業務ファイル | 同じオブジェクトストレージまたは共有ファイルシステムを使い、どのインスタンスからもアップロードファイルやタスクの添付ファイルにアクセスできるようにします。 |
| 本番設定 | config.yml 内のデータベース、Redis、ファイルストレージ、鍵、業務設定を共有します。公開ドメインとアプリのパスも同じ値を使います。 |
| インスタンスの実行パラメーター | インスタンス識別子とローカルデータ領域は分け、ホスト側ポートの競合を避けます。Snowflake の番号には、前述の自動割り当てか、重複しない手動番号を使います。 |
各インスタンスのローカルデータディレクトリは、共有アップロードディレクトリではありません。業務ファイルには上表の共有ストレージを使います。設定ファイルが同じでも、インスタンス内のファイルが自動同期されるわけではありません。
共通のリリース手順
どちらのデプロイ方法でも、次の順序で進めます。
- 同じバージョンのデプロイ成果物、本番設定、インスタンス用ディレクトリを準備し、すべてのインスタンスが共有サービスにアクセスできることを確認します。
- バックアップを完了し、初回の切り替え時には旧インスタンスへの新しい処理の受付を止め、残っているタスクに対応します。
- データベース更新は 1 回だけ実行し、テーブル作成、フィールド追加、必要なデータ変更を適用します。各インスタンスの起動時に個別に実行しないでください。
- データベース更新が成功したら全インスタンスを起動し、ヘルスチェックを行ってから、共通の公開 URL からアクセスできるようにして業務動作を検証します。
データベース更新をインスタンスの起動から切り離すため、本番設定で更新対象の各データベース接続の自動実行を無効にします。以下は main 接続の例です。既存の接続設定にこれらの項目を追加し、接続先や認証情報を上書きしないでください。
database:
connections:
main:
migrations:
autoRun: false
seeds:
autoRun: falseデータベース更新はリリース手順の中でまとめて実行します。具体的なコマンドは、以下の選択したデプロイ方法を参照してください。例の main はデータベース接続名です。アプリが他のデータベースのテーブル構造も管理する場合は、接続ごとに 1 回ずつ実行します。更新が失敗したら、新しいインスタンスは起動しないでください。バックアップ、変更内容の確認、ロールバックの要件はアプリの新しいバージョンをリリースするを参照してください。
PM2 を使う
サーバーに Node.js 24 とグローバルの PM2 をインストールし、以下のコマンドはすべて同じサービスアカウントで実行します。ここでは PM2 の cluster モードを使います。1 つのアプリ定義から複数の worker(ワーカープロセス)を起動し、全 worker がポート 13000 を共有して、PM2 が接続を振り分けます。実行数は pm2 scale で調整できます。
全 worker が同じ本番設定を読み込み、前述の共有サービスと Snowflake の自動割り当てを使います。リバースプロキシは 127.0.0.1:13000 に接続します。worker 数が変わっても、この接続先は変わりません。
1. デプロイ先ディレクトリを準備する
デプロイアーカイブのビルドとアップロードに従い、サーバーのプラットフォームに合う完全な成果物を用意します。サービスアカウントが書き込める場所に、たとえば /srv/my-app というデプロイ先ディレクトリを作成し、アーカイブを展開します。
mkdir -p /srv/my-app
cd /srv/my-app
tar -xzf /tmp/my-app.tar.gz
mkdir -p storage/cli logs準備済みの本番設定を config.yml に配置し、読み取り権限をサービスアカウントに限定します。ディレクトリ内のファイルの用途は次のとおりです。2 つの .cjs ファイルは次の手順で作成します。
パス(/srv/my-app/ からの相対パス) | 用途 |
|---|---|
dist/ | 全 worker が共有するビルド成果物と本番用の依存パッケージ。 |
config.yml | 全 worker が共有する本番設定。 |
pm2-entry.cjs | PM2 がアプリを起動するためのエントリーポイント。 |
ecosystem.config.cjs | アプリ名、実行モード、worker 数、環境変数。 |
storage/ | 各 worker のローカル作業ディレクトリと、管理コマンド用の cli/ ディレクトリ。 |
logs/ | PM2 が保存するプロセスログ。 |
2. 起動エントリーとプロセス管理を設定する
pm2-entry.cjs を作成します。PM2 が割り当てる NODE_APP_INSTANCE を使って worker ごとのローカルディレクトリを準備し、ビルド成果物がエクスポートする startServer() を呼び出してアプリを起動します。
const { mkdirSync } = require('node:fs');
const path = require('node:path');
const worker = process.env.NODE_APP_INSTANCE ?? '0';
process.env.APP_STORAGE_DIR = path.join(__dirname, 'storage', `worker-${worker}`);
mkdirSync(process.env.APP_STORAGE_DIR, { recursive: true });
import('./dist/server/standalone.js')
.then(({ startServer }) => startServer())
.catch((error) => {
console.error(error);
process.exit(1);
});ecosystem.config.cjs を作成し、ドメインとアプリのパスを実際の値に置き換えます。
module.exports = {
apps: [
{
name: 'my-app',
cwd: __dirname,
script: './pm2-entry.cjs',
exec_mode: 'cluster',
instances: 2,
autorestart: true,
kill_timeout: 60000,
time: true,
out_file: './logs/app.out.log',
error_file: './logs/app.err.log',
env: {
NODE_ENV: 'production',
NOCOBASE_STRICT_STARTUP: 'true',
APP_CONFIG_FILE: `${__dirname}/config.yml`,
APP_SERVER_HOST: '127.0.0.1',
APP_SERVER_PORT: '13000',
APP_PUBLIC_ORIGIN: 'https://apps.example.com',
APP_BASE_PATH: '/main',
APP_SAMPLE_DATA: 'false',
},
},
],
};exec_mode: 'cluster' で cluster モードを有効にし、instances: 2 で初期 worker 数を指定します。全 worker は同じ設定ファイル、公開 URL、待ち受けポートを使い、ローカルディレクトリは起動エントリーで個別に設定します。PM2 の worker 番号はこれらのディレクトリを区別するためのもので、レコード ID は引き続き Snowflake サービスが生成します。
3. 設定を確認してデータベースを更新する
デプロイ先ディレクトリのターミナルで、アプリと同じ環境変数を設定してから、設定を確認します。
export NODE_ENV=production
export APP_CONFIG_FILE="$PWD/config.yml"
export APP_STORAGE_DIR="$PWD/storage/cli"
export APP_PUBLIC_ORIGIN=https://apps.example.com
export APP_BASE_PATH=/main
export APP_SAMPLE_DATA=false
node dist/cli/index.js config check --connect確認とバックアップが完了したら、メンテナンス時間帯に旧デプロイを停止し、同じターミナルでデータベースを更新します。
node dist/cli/index.js db apply --connection main --json4. アプリを起動して worker 数を調整する
データベース更新が成功したら、アプリを起動して状態を確認します。
pm2 start ecosystem.config.cjs
pm2 statuspm2 status に、名前が my-app、状態が online の worker が 2 つ表示されます。各 worker のログで起動完了を確認してから、ヘルスチェックのエンドポイントを確認します。
curl --fail http://127.0.0.1:13000/main/api/healthzヘルスチェックが成功したら、共通の公開 URL から業務機能へのアクセスを検証し、pm2 save で現在のプロセス一覧を保存します。
worker を 4 つに増やす場合は、次を実行します。
pm2 scale my-app 4
pm2 status2 つに戻す場合は pm2 scale my-app 2 を実行します。調整後は各 worker のログと業務機能へのアクセスを確認し、次回以降のデプロイ用に ecosystem.config.cjs の instances も同じ数に更新します。その後、pm2 save で現在のプロセス一覧を保存してください。
OS 起動時の自動復旧を初めて設定する場合は、pm2 startup を実行し、出力されたシステム設定コマンドを実行してから、プロセス一覧を再保存します。スケールイン時には停止する worker 上の WebSocket 接続が切れるため、クライアントが再接続できる必要があります。
Docker Compose を使う
サーバーに Docker と Docker Compose をインストールします。以下ではアプリを app サービスとして定義し、同じイメージから 2 つのレプリカを起動します。レプリカ数は --scale で調整します。
全レプリカが同じ本番設定を読み込みます。前述の共有サービスと Snowflake の自動割り当てを設定すると、レプリカ間で業務処理を連携させ、それぞれ異なる Snowflake のプロセス識別番号を取得できます。
1. イメージとデプロイ先ディレクトリを準備する
開発マシンまたはビルド環境で、商用プラグインのダウンロード権限を持つアカウントを使ってアプリをビルドし、その後イメージを作成します。以下のコマンドは Linux x64、Node.js 24 向けです。他のプラットフォームでは対象サーバーに合わせて変更してください。
pnpm build --target linux-x64 --node-version 24
docker build --platform linux/amd64 --build-arg DIST=prebuilt -t my-app:multi-instance .イメージの転送手順に従って、イメージをサーバーに転送します。サービスアカウントが書き込める場所にデプロイ先ディレクトリを作成します。
mkdir -p /srv/my-app
cd /srv/my-app準備済みの本番設定をこのディレクトリに配置します。ファイル構成は次のとおりです。compose.yml は次の手順で作成します。
パス(/srv/my-app/ からの相対パス) | 用途 |
|---|---|
compose.yml | アプリサービスの定義。 |
config.yml | 全レプリカが共有する本番設定。 |
コンテナ内の /app/storage は、各レプリカのローカル作業ファイルを保存します。これらのファイルはコンテナを再作成すると失われます。アップロードファイルやタスクの添付ファイルなど、永続化が必要な内容には、前述のオブジェクトストレージまたは共有ファイルシステムを使ってください。共有ファイルシステムを使う場合は、以下の Compose 設定に業務ファイル用ディレクトリのマウントを追加します。
テンプレートのイメージは UID 1000 のユーザーで実行されます。デプロイ先ディレクトリで、このユーザーが本番設定を読み取れるように権限を設定します。
sudo chown 1000:1000 config.yml
sudo chmod 600 config.yml2. スケール可能なアプリサービスを設定する
デプロイ先ディレクトリに compose.yml を作成し、イメージ名、ドメイン、アプリのパスを実際の値に置き換えます。
services:
app:
image: my-app:multi-instance
init: true
restart: unless-stopped
stop_grace_period: 60s
environment:
APP_CONFIG_FILE: /app/config.yml
APP_STORAGE_DIR: /app/storage
APP_SERVER_HOST: 0.0.0.0
APP_SERVER_PORT: '13000'
APP_PUBLIC_ORIGIN: https://apps.example.com
APP_BASE_PATH: /main
APP_SAMPLE_DATA: 'false'
ports:
- target: 13000
host_ip: 127.0.0.1
volumes:
- ./config.yml:/app/config.yml:ro各レプリカはコンテナ内のポート 13000 で待ち受け、Docker がそれぞれに異なるホスト側ポートを自動割り当てします。host_ip: 127.0.0.1 は、これらのポートへのアクセスを同じホスト内に限定し、同じホスト上のリバースプロキシから接続できるようにします。全レプリカは同じ config.yml を読み取り専用でマウントします。
Compose 設定を確認します。
docker compose -p my-app config --quiet3. データベースを更新する
デプロイ先ディレクトリで次のコマンドを実行します。Compose は app のイメージと本番設定で一時コンテナを起動し、データベース更新が完了するとそのコンテナを削除します。
docker compose -p my-app run --rm --no-deps app \
node dist/cli/index.js db apply --connection main --json4. 起動してレプリカ数を調整する
データベース更新が成功したら、アプリのレプリカを 2 つ起動します。
docker compose -p my-app up -d --scale app=2 --wait --wait-timeout 180
docker compose -p my-app ps--scale app=2 はレプリカ数を 2 に指定し、--wait はヘルスチェックが成功するまで最大 180 秒待機します。コマンドが成功すると、ps に正常な app レプリカが 2 つ表示され、PORTS 列に各レプリカのホスト側ポートが表示されます。これらのアドレスを既存のリバースプロキシに登録してから、業務機能へのアクセスを検証します。
レプリカを 4 つにする場合は、数を 4 に設定します。
docker compose -p my-app up -d --scale app=4 --wait --wait-timeout 1802 つに戻す場合は --scale app=2 を使います。次回以降のデプロイでも、必要なレプリカ数を指定してください。
レプリカ数の変更やコンテナの再作成後は、各レプリカの状態と実際のポートを確認し、リバースプロキシの接続先一覧を更新してから、業務機能へのアクセスを検証します。スケールイン時には停止するレプリカ上の WebSocket 接続が切れるため、クライアントが再接続できる必要があります。
インスタンス間のアクセスと業務処理を検証する
設定チェックの成功は、設定とチェック対象の接続でエラーがなかったことを示すだけです。ヘルスチェックの成功も、インスタンスが起動したことを示すだけで、タスク、メッセージ、状態がインスタンス間で共有されていることまでは確認できません。
まずテスト環境で 2 つのインスタンスを使い、以下を確認します。バックエンドのポートが個別なら、一時的にプロキシの転送先を A だけにして操作を行い、その後 B だけに切り替えられます。PM2 cluster のようにポートを共有する場合は、各 worker のリクエストログで、異なるプロセスがリクエストを処理していることを確認します。検証中は同じアクセス先 URL とブラウザーセッションを使ってください。
| 確認項目 | 期待する結果 |
|---|---|
| ログインと権限 | A でログインした後、リクエストが B に切り替わってもアクセスできます。一般ユーザーへの制限は変わらず、ログアウト後は他のインスタンスも無効なセッションを受け付けません。 |
| キャッシュとカウンター | A で更新または無効化した共有状態が B に反映されます。共通の制限が必要な操作で、インスタンスを切り替えても別枠の利用回数を得られません。 |
| Jobs と Queue | あるインスタンスから投入したテスト用の処理を、別のインスタンスで実行できます。インスタンスが 2 つあるという理由だけで、定期タスクが個別に 2 回実行されません。投入の成功だけでなく、業務処理の結果を確認します。 |
| Realtime | B に接続したブラウザーに、A で発生した通知や進捗更新が届きます。切断後に再接続すると、ページが最新の状態を読み直せます。 |
| Concurrency | 両インスタンスから同じ保護対象のリソースへ同時にリクエストしても、排他的に実行すべき処理に同時に入りません。待機、処理中の応答、リトライが業務の想定どおりに動きます。 |
| Snowflake | 自動モードで稼働中の各インスタンスが異なる番号を取得し、レコードの同時作成で ID の競合が発生しません。 |
| ファイル | A からアップロードしたファイルを B からダウンロードでき、権限チェックも有効です。バックグラウンドタスクも必要なファイルを読み取れます。 |