nocobase-app-installer

app-installer で NocoBase 3 をインストールして実行する

この Skill は、すでにビルド済みの NocoBase をインストールします。マシン上で開発は行わず、実行するだけです。@nocobase/app-installer は各リリースを releases/<version>_<build time>/app の下に配置し、pm2 で実行します。config.yml、app.env、storage/、backups/、logs/ はリリースの隣に置かれ、アップグレードのたびに維持されます。アプリケーションプロジェクトでビルドされたデプロイ用アーカイブを --archive からインストールします。この Skill は、いつ使うか、また報告された内容にどう対応するかを判断します。すべてのフラグについては --help を参照してください。

実行する

レジストリを指定して --json を付け、エージェントが作業するマシン上でインストーラーを実行します。SSH でデプロイする場合は、サーバーではなくローカルマシン上で実行します。

npx --yes --registry="${NOCOBASE_REGISTRY:-https://registry.npmjs.org}" @nocobase/app-installer@beta <command> … --json

公開されているインストーラーには @beta を使ってください。タグを指定しない呼び出しや @latest に切り替えてはいけません。既存のインストールで必要なバージョンや、ユーザーが指定したバージョンはそのまま維持し、未公開のローカルレジストリをテストする場合はスナップショットタグを使います。

NocoBase 3 は公開 npm レジストリに公開されています。NOCOBASE_REGISTRY が設定されるのは、未公開のスナップショットなど、誰かがシェルの接続先を別のレジストリに変更した場合だけです。インストーラーはレジストリを installer.json に記録し、そのレジストリから実行するコマンドを提示します。パッケージの前にある --yes は npx 自体のオプションで、確認を求めずにインストーラーをダウンロードします。コマンドの後にあるインストーラーの --yes は別のオプションで、ユーザーだけが指定します。

ユーザーが正確なバージョンを指定しない限り、公開されている beta チャネルを使います。未公開のスナップショットレジストリではパッケージに latest タグが付けられます。そのようなレジストリをテストする場合に限り、そのタグを使ってください。デプロイ前に --help を確認し、選択したバージョンが deploy と --ssh に対応していることを確かめます。

--json は stdout に 1 つのドキュメントを、stderr に進捗状況を出力します。形式は pnpm nocobase … --json と同じです。終了コードだけでなく、ドキュメントを読み取ってください。確認する項目は ok、status（success、success-noop、または failure）、result、および失敗時の error.code、error.message、error.suggestions、error.details です。各提案には message と、該当する場合は { command, args } 形式の run が含まれます。これは実行ファイルとその引数であり、シェルを介さず、指定されたとおりに実行します。app-installer 0.1.0-beta.1 以前のバージョンでは、そのバージョンを指定した提案コマンドが実行するのは引き続きこれらのバージョンです。これらのバージョンは status に error を出力し、run をそのまま実行できるシェルの 1 行として出力するため、成功か失敗かは ok で判断してください。

終了コード	意味
0	完了、または実行する作業がありません（success-noop）。
1	失敗しました。すでに実行中のアプリケーションには手を加えていません。
2	使用方法が無効、事前チェックに失敗、または確認が必要です。何も書き込まれていません。
3	切り替え後のアップグレードに失敗し、ロールバックされました。以前のリリースが実行中です。
4	ロールバックにも失敗しました。アプリケーションは停止しています。

インストール方法を選択する

プロジェクトとは、誰かが変更するソースコードであり、nocobase-create-app で作成してローカルで開発するものです。インストールとは、ビルド済みの NocoBase であり、この Skill で作成して実行のみを行うもので、通常は本番環境で使用します。何かをインストールする前に、方法を決めてください。

ユーザーの依頼	方法
NocoBase をインストール、作成、または試して開発する	nocobase-create-app Skill
アプリケーションを本番環境またはサーバーにデプロイする	アプリケーションのデプロイアーカイブを使って、この Skill と --archive を使用する
Docker で実行する	アプリケーションの nocobase-deployment Skill と Docker 設定

• プロジェクトもアーカイブもない状態で「このサーバーに NocoBase をインストールして」と頼まれた場合、まだ方法は決まっていません。ユーザー自身のアプリケーションを実行するには、nocobase-create-app でローカルに作成し、アーカイブをビルドしてから、--archive を使ってこのサーバーにインストールします。サーバー上でプロジェクトを作成し、pnpm dev で実行してはいけません。これは開発モードであり、デプロイではありません。
• source.kind が template の installer.json は、以前の app-installer によって公開済み Hub テンプレートからインストールされたものです。現在の app-installer はこれを STATE_UNSUPPORTED で拒否します。インストール時に使用したバージョンの app-installer で引き続き管理してください。
• 作業ディレクトリにすでに installer.json がある場合、インストールは完了しています。まず status を実行してください。

インストーラーの実行場所を選択する

ユーザーから SSH サーバーの指定があった場合、Agent、この Skill、インストーラーはローカルマシンに置いたままにしてください。先にリモートデプロイを読んでください。ローカルでのオーケストレーション、オフラインでの実行、復旧について説明しています。サーバーに Agent、Skill、npm へのアクセスは不要です。以下の install、status、upgrade、rollback の手順でライフサイクルを定義します。リモート操作は、同じ SSH オプションと絶対パスのリモート --dir を指定して実行してください。

Agent がすでにアプリケーションサーバー上にある場合は、以下のローカルコマンドを使用してください。アーカイブは本番環境のインストール先ではなく、ソースがある場所でビルドします。ソースプロジェクトをローカルで利用できる場合は、その AGENTS.md と nocobase-deployment Skill に従ってビルドしてください。利用できない場合は、ユーザーまたは CI からアーカイブを入手してください。本番サーバー上で開発プロジェクトをビルドしたり実行したりしてはいけません。

アーカイブをビルドする

アプリケーションプロジェクトでは、ビルド手順の根拠となるのは、そのプロジェクト独自の AGENTS.md と nocobase-deployment Skill です。

APP_BASE_PATH=/crm pnpm build --target linux-x64 --node-version 24 --tar

• --target と --node-version で指定するのはビルドマシンではなく、実行マシンの情報です。実行マシン上で node -p "process.platform + '-' + process.arch" と node --version を実行してください。Alpine の場合は -musl を付けたターゲットを指定します。インストーラーは別のマシン向けにビルドされたアーカイブを拒否し、適切なコマンドを表示します。
• APP_BASE_PATH はクライアントにコンパイルされます。未設定の場合は /main です。アプリケーションはこのパスで提供されるため、以降のアーカイブもすべて同じパス向けにビルドする必要があります。
• SQLite 以外のデータベースを使う場合は、ビルド前にプロジェクトへドライバーを追加する必要があります。例：pnpm add @nocobase/db-postgres@beta。アーカイブに含まれるのは、ビルド時に使用したドライバーのみです。

アーカイブは storage/exports/dist.tar.gz に作成されます。ユーザーはこれを NocoBase の実行マシンにコピーします。例：scp storage/exports/dist.tar.gz user@server:/tmp/crm.tar.gz。ARCHIVE_TOO_OLD または STORAGE_IN_RELEASE は、プロジェクトの NocoBase パッケージがインストーラーの要件より古いことを示しています。パッケージをアップグレードして再度ビルドし、その後もう一度実行してください。

インストール

すべてのインストール

1. マシンの状態を確認します。node --version（24 以降）と、デーモンを起動せずに pm2 を探す command -v pm2 を実行します。pm2 4.3 以降をグローバルにインストールする必要があります（npm install -g pm2）。npx で取得したコピーでは pm2 startup が正常に動作しません。不足しているものがあれば、それをインストールするコマンドとともに報告し、ユーザーから依頼されない限り、グローバルには何もインストールしません。Windows の場合は、WSL で作業します。
2. ユーザーと次の内容を確認します。新規または空のターゲットディレクトリ（例：/srv/nocobase/crm）、ベースパスを含まないパブリックオリジン（例：https://apps.example.com。http://127.0.0.1:<port> だけでアクセスするマシンの場合は省略できます）、リバースプロキシの有無、ポート（デフォルトは 13000。同じマシン上のインストールごとに異なるポートが必要です）、データベース（デフォルトは SQLite）。
3. リバースプロキシが同じマシン上にある場合に適するよう、127.0.0.1 でリッスンします。http://<address>:<port> で直接アクセスする場合は、--host 0.0.0.0 を追加し、そのアドレスをオリジンとして使用します。別のデータベースを使う場合は、--dialect <dialect> と、接続先を --set database.connections.main.host=… などで指定し、ユーザーが環境変数をエクスポートした後に、パスワードを --set-from-env database.connections.main.password=<VARIABLE> で指定します。パスワードをコマンドラインに記述してはいけません。
4. PORT_IN_USE の場合、使用可能なポートが error.details.freePort に示されます。黙ってポートを選ばず、そのポートを提案してください。

実行

install <dir> --archive <file> --origin <origin> --json を実行します。pnpm は不要で、1、2 分で完了します。アーカイブには --dialect に対応するドライバーが含まれている必要があります。含まれていない場合、インストールは DRIVER_MISSING で停止し、解決するためのビルドコマンドが示されます。

成功した場合

result.started が true の場合、インストールのヘルスチェックは成功しています。ユーザーには次のことを伝えてください。

• result.url と、初回サインインに使う result.initialAdmin.username またはその email。パスワードは config.yml の users.initialAdmin にあります。result.initialAdmin.defaultPassword が true の場合、パスワードはまだ config.example.yml にある admin123 のままなので、サインイン後に変更する必要があります。それ以外の場合は、ユーザーが設定したパスワードです。結果にパスワードが含まれることはなく、config.yml が読み込まれることもありません。
• result.nextCommands にある各コマンド。pm2 startup は sudo で一度実行するコマンドを出力します。その後、pm2 はインストーラーが保存したプロセスリストを復元するため、再起動後もインストールが再開します。
• リバースプロキシがある場合は、WebSocket のアップグレードヘッダーを付けてインストールのポートに転送します。同じオリジンの背後に複数のインストールがある場合は、ベースパスでルーティングします。
• warnings にあるすべての内容。

切り替え前にインストールが失敗した場合、ターゲットは元の状態のままです。失敗した手順の内容は error.details にあります。リリースの展開時は output に、リリース独自の CLI が結果を出力しなかった場合は stderr と stdout にあります。CLI 自体が報告する失敗では、CONFIG_INVALID など、CLI 独自のコードが保持され、問題の内容は error.message と error.suggestions に示されます。START_FAILED はインストール済みだが起動していないことを意味します。error.details.log を表示してください。

1 台のマシンで複数のインストールを行う

各アプリケーションは、それぞれ専用のディレクトリに一度だけインストールし、個別の --port を指定します。pm2 のプロセス名はデフォルトで nocobase-<directory name> となるため、ディレクトリ名が異なれば名前は重複しません。同じ名前の 2 つのディレクトリがある場合、何も書き込む前に PM2_NAME_IN_USE が報告されます。2 つ目には --name で別の名前を指定してください。

ステータス

status --dir <root> --json は何も変更しません。アプリケーションと version、current（リリース ID）、endpoints.url、health.ok、process、および warnings の内容を報告してください。node.matches: false は、リリースのビルド後にマシンの Node のメジャーバージョンが変わったことを意味します。このマシン用にビルドされたリリースに置き換えるまで、ネイティブモジュールは読み込まれません。警告には、再ビルドしたアーカイブと upgrade --archive という手順が示されます。いずれも、アップグレード時と同じ停止、バックアップ、確認の手順で進めてください。pending が null 以外の場合は、操作が中断されています。以下を参照してください。

アップグレードとロールバック

既存のデータベースをアップグレードする前に、対象アプリケーションおよび登録済みプラグインの、該当リリース固有のアップグレードノートを確認してください。文書化されているチェックサムの変更、データの前提条件、取り消せないマイグレーションを復旧計画に含めてください。インストーラーがアプリケーションを停止する前に、サポート対象の CLI とデプロイ設定を使用して、対象アプリケーションの db repair --dry-run --json の出力を確認してください。過去に修正が文書化されていない場合も同様です。これは読み取り専用のチェックサム確認です。インストーラー独自の db apply --dry-run では保留中のタスクを検出できますが、厳格なチェックサムポリシーが適用されていてもチェックサムは検証されません。選択したインストーラーで必要な確認または準備を実行できない場合は、アップグレードを進める前に、サポートされているメンテナンス手順を確立してください。

チェックサムのプレビューで変更が提案された場合は、実際に修復する前に、マイグレーションまたはシードのチェックサムの差異をすべて説明してください。変更が提案されない場合は、修復をスキップしてください。インストーラーはマイグレーションを適用しますが、変更された過去のチェックサムを自動的に承認することはありません。修復で更新されるのは履歴のチェックサムのみです。スキーマの変更、部分的に作成されたテーブルの修正、前方マイグレーションの代替は行いません。マイグレーションポリシーを変更したり、同じアーカイブを繰り返し再試行したりして、ドリフトを隠さないでください。

通常のインストーラーによるアップグレードの前に、実際の修復を実行しないでください。SQLite のバックアップはアプリケーションの停止後に作成されるため、すでに新しいチェックサムが含まれます。アップグレードがロールバックされた場合、onChecksumMismatch: error の設定では、以前のランタイムがこのチェックサムを拒否する可能性があります。修復手順では、書き込み元を停止し、元の履歴をバックアップして、確認済みの修復とマイグレーションを実行する必要があります。失敗した場合は、古いランタイムを再起動する前に、修復前に作成した同じバックアップを復元してください。手動バックアップを追加で作成しても、自動ロールバックで復元されるバックアップは変わりません。選択したインストーラーでこの手順を調整できない場合は、読み取り専用の確認のみを完了し、まずサポートされているメンテナンス手順を確立してください。

どちらもアプリケーションを停止するため、ユーザーの判断が必要です。

1. アップグレードでは新しいアーカイブを指定します：upgrade --dir <root> --archive <file> --json。同じベースパス向けにビルドされた同じアプリケーションである必要があり、古いバージョンを指定することはできません。同じバージョンを再ビルドしたものも新しいリリースとなり、通常どおりデプロイされます。
2. --yes を付けずに実行します。CONFIRMATION_REQUIRED とともに error.details.notes が返されます。ここには、停止するもの、バックアップされるもの、Node のメジャーバージョンの変更があればその内容が記載されています。これらの注意事項をユーザーに伝え、明確な承認を得てから、--yes を付けて再度実行してください。success-noop は、そのリリースがすでに稼働中であることを意味します。
3. インストーラーは、config.yml で宣言されているすべての SQLite データベースと、config.yml および app.env をバックアップします。それ以外のデータベースはバックアップしません。該当する接続名は BACKUP_REQUIRED に表示されます。先にユーザーにバックアップしてもらい、その後 --backup-done を追加してください。
4. アップグレードでは、新しいリリースと、その元となったリリースを常に含む3つのリリースを保持し、成功するとそれより古いリリースは削除されます。ロールバック用にさらに多くのリリースを保持したい場合は、--keep <n> を指定してください。
5. 結果を確認します。
   • 終了コード 0：新しいリリースのヘルスチェックに合格しました。result.fromVersion、result.toVersion、リリース ID の result.to、result.migrations、result.backup を報告し、result.pruned に含まれる、ロールバックできなくなったリリースがあればその名前も伝えてください。
   • 終了コード 3：以前のリリースが再び稼働しています。error.message、error.details.log、データベースが復元されたかどうかを報告してください。外部データベースには、失敗したアップグレードによる変更が残っている可能性があります。原因が判明したら、次の試行はユーザーに委ねてください。
   • 終了コード 4：アプリケーションが停止しています。error.suggestions の内容を、ユーザーと一緒に一つずつ確認してください。 rollback --dir <root> --json は、直前のアップグレード元のリリース、または --to <release id or version> で指定したリリースに戻します。そのアップグレードで SQLite データベースが移行され、インストーラーがそのバックアップを保持している場合、ロールバックするとバックアップが復元され、それ以降に保存されたデータは失われます。確認メッセージにはその旨が記載され、同じ中継と確認の手順が適用されます。外部データベースの復元には別の手順が必要です。--backup-done を指定しても、インストーラーは外部データベースを復元しません。元に戻せない移行によってスキーマが以前のランタイムと互換性を失った場合、そのランタイムに戻すには、互換性のあるデータベースのバックアップも必要です。--no-restore を指定すると現在のデータベースが保持されます。選択したランタイムとの互換性が確認できている場合にのみ使用してください。

中断された操作を復旧する

upgrade で OPERATION_INTERRUPTED が返された場合、または status で pending と表示された場合は、アプリケーションの停止中に以前の実行が中断されたことを意味します。通常の rollback を実行すると、同じ確認手順を経て復旧します。中断されたアップグレードを取り消してデータベースを復元し、中断されたロールバックを完了します。

オリジンまたはポートを変更する

app-installer にそのためのコマンドはありません。オリジン、アドレス、ポートは app.env の APP_PUBLIC_ORIGIN、APP_SERVER_HOST、APP_SERVER_PORT に設定されています。変更する前に、ユーザーに次のことを伝えてください。

• アプリケーションは、新しいオリジンとベースパスで利用できるようになります。
• 再起動の間、アプリケーションは一時的に停止します。
• 新しいポートは空いている必要があります。空いていないと、アプリケーションはクラッシュループに陥り、その原因は logs/app.err.log でしか確認できません。また、前段のリバースプロキシからアプリケーションに転送する必要があります。
• APP_BASE_PATH はこの方法では変更できません。クライアントにコンパイルされているためです。

ユーザーの同意を得たら、該当する3行だけを編集し、それ以外は変更せずに、pm2 restart <name> を実行します。ここで <name> は status の name です。pm2 は launcher.mjs を介してアプリケーションを起動し、起動するたびに app.env を読み込むため、再登録は不要です。その後の status では、新しい endpoints が報告され、app.env に記載されたアドレスでヘルスチェックが行われます。オリジンを変更した場合は、ユーザーに endpoints.url を開いてもらってください。

データをそのまま保つ

ルートには、アプリケーションの設定、シークレット、データの唯一のコピーが保存されています。上記の app.env の3行を除き、ルート内の変更はすべて app-installer を通じて行い、何かを削除するかどうかはユーザーに委ねてください。シークレットを含む config.yml の内容を会話に含めないでください。