インストールとアップグレードの移行ガイド：NocoBase CLI の使用
CLI のインストールとアプリケーション管理機能はまだ開発中です。現時点ではローカル開発、テスト環境、AI Agent 接続シーンに適しており、本番環境のインストール・アップグレード・運用保 守に直接使用することは推奨しません。
新しい NocoBase CLI (nb) は、インストール、接続、起動、停止、ログ確認、アップグレード、クリーンアップなどの操作を統一のコマンド体系にまとめています。旧ドキュメントで Docker、create-nocobase-app、Git ソースコードごとに個別に維持していたフローと比較して、CLI はローカル開発、テスト環境の保守、AI Agent の接続と連携により適しています。
本ドキュメントは以下のシーンに適用されます：
- 旧ドキュメントに従って NocoBase をインストール・アップグレードしていて、新しい CLI 方式に切り替えたい場合。
- 旧方式でデプロイ済みの NocoBase があり、CLI で管理・接続したい場合。
- AI Agent 用に接続・管理可能な NocoBase 環境を準備する必要がある場合。
旧方式と新方式の違い
旧方式ではインストールソースごとにドキュメントが分かれており、各ソースでダウンロード、設定、インストール、起動、アップグレードのコマンドを個別に実行する必要がありました。
旧インストールドキュメント
旧アップグレードドキュメント
新方式では nb init をエントリポイントとし、1 つの CLI env でアプリケーションのソース、実行ディレクトリ、ストレージディレクトリ、データベース、API 接続情報を記録します。以降は Docker、npm、Git いずれのソースでも、同じ nb app、nb source、nb db コマンドで管理できます。
CLI のインストール
インストール後にヘルプを確認できます：
新しい方式で NocoBase をインストールする
推奨：ビジュアルウィザードの使用
ウィザードが以下の選択を案内します：
- 新規アプリケーションの作成または既存アプリケーションへの接続
- インストールソース：Docker、npm、Git
- NocoBase バージョン
- 組み込みデータベースまたは外部データベースの使用
- 管理者アカウントとパスワード
ターミナル対話式ウィザードの使用
非対話式コマンドの使用
デフォルトのインストール方式は Docker で、組み込みの PostgreSQL データベースを使用します：
Docker で特定バージョンを指定してインストール：
npm でインストール：
Git ソースコードでインストール：
Git ソースコードで組み込みデータベースの種類を指定してインストール：
既存の NocoBase アプリケーションに接続：
--env は CLI 内の環境名です。以降の起動、アップグレード、ログ確認などのコマンドで -e app1 を指定して対象アプリケーションを選択できます。
新しい方式でアップグレードする
旧方式では Docker、create-nocobase-app、Git ソースコードのアップグレードコマンドが異なっていましたが、新しい CLI では統一されています：
現在ダウンロード済みのソースコードまたはイメージのみでアップグレードプロセスを実行し、新しい コードやイメージを取得しない場合：
または省略形：
よく使うメンテナンスコマンド
nb app down はデフォルトでアプリケーションを停止し、CLI が管理する実行コンテナとローカルアプリケーションファイルを削除しますが、storage データと env 設定は保持されます。すべてを削除する場合は明示的な確認が必要です：
--all --yes を指定すると、この env の storage データと CLI env 設定が削除されます。バックアップ済みで、この環境が不要であることを確認した場合にのみ使用してください。
日常の開発コマンド
nb source はローカルソースコードプロジェクトの管理に使用され、主に npm と Git ソースの env に適用されます。
Docker env は通常 nb app start、nb app logs、nb app upgrade で管理し、nb source dev は使用しません。
NB_CLI_ROOT とディレクトリ構造
CLI は NB_CLI_ROOT に対応するディレクトリにグローバル設定とローカルアプリケーションファイルを保存します。
デフォルトでは NB_CLI_ROOT は現在のユーザーのホームディレクトリ、つまり Node.js の os.homedir() が返すパスです。例えば macOS では通常 /Users/<user> です。したがって、追加の設定をしない場合、nb init --yes --env app1 で生成されるファイルは通常以下の場所に配置されます：
NB_CLI_ROOT を明示的に指定することもできます：
設定後、設定ファイルとデフォルトのアプリケーションディレクトリはすべてこのディレクトリに配置されます：
各項目の説明：
.nocobase/config.jsonには env、現在の環境、API アドレス、ソースコードパス、storage パス、データベース設定などの情報が保存されます。<envName>/sourceは CLI が管理するソースコードまたはアプリケーションディレクトリです。<envName>/storageは CLI が管理するアプリケーションストレージディレクトリです。
アプリケーションの初期化後は、同じ NB_CLI_ROOT を使い続けてください。後から NB_CLI_ROOT を変更すると、CLI は新しいディレクトリで .nocobase/config.json を検索し、相対パス形式の appRootPath や storagePath も新しいディレクトリを基準に解決されるため、アプリケーションが見つからなかったり、誤ったディレクトリに読み書きされる可能性があります。
CLI は現在グローバル設定スコープのみを使用しています。設定やローカルアプリケーションファイルの保存場所を変更する必要がある場合は、NB_CLI_ROOT を設定してください。
アプリケーションの確認と特定には、nb env list と nb env info を優先的に使用してください：
nb env list は概要の確認に使用します。App Status は保存済みの Token/OAuth 認証情報でアプリケーション API にアクセスした結果の認証状態を表示し、データベース状態は表示しません。組み込みデータベースの実行状態を確認するには、以下を使用してください：
デフォルトの env を切り替える場合にのみ、以下を使用します：
旧方式から CLI への移行
移行には 2 つの戦略があります：既存アプリケーションへの接続、または ローカルアプリケーションディレクトリを CLI 管理下に置く。旧アプリケーションがすでに安定稼働している場合は、リスクが最も低い「既存アプリケーションへの接続」を先に使用することを推奨します。
方式 1：既存アプリケーションへの接続
Docker、create-nocobase-app、Git ソースコード、またはサーバーデプロイで稼働中の NocoBase に適用されます。
この方式では API 接続のみを保存し、CLI は旧アプリケーションの起動、停止、アップグレード、ソースコードディレクトリ、storage ディレクトリを引き継ぎま せん。AI Agent や CLI API コマンドから既存アプリケーションに接続する用途に適しています。
認証を更新する必要がある場合：
方式 2：新規 CLI env を作成してファイルを移行
以降 nb app と nb source でローカルアプリケーションを管理したいシーンに適用されます。
移行前に以下を完了してください：
- 旧アプリケーションを停止する。
- 旧データベースをバックアップする。
- 旧
storageディレクトリをバックアップする。 - 旧アプリケーションの重要な環境変数を記録する。例：
APP_KEY、TZ、DB_*、DB_UNDERSCORED。
旧 Docker インストールからの移行
旧 Docker 方式では通常、アプリケーションデータはプロジェクトディレクトリの storage に配置されます：
まず新しい NB_CLI_ROOT を決定し、CLI で新しい Docker env を作成することを推奨します。以下の例では NB_CLI_ROOT を /your/workspace とします。
新しい env はデフォルトで以下のディレクトリを使用します：
次に旧 storage を /your/workspace/app2/storage にコピーし、データベース接続と APP_KEY などの設定が旧環境と一致していることを確認します。
コピーが完了しデータベース設定を確認したら、アプリケーションを起動します：
旧 create-nocobase-app または Git ソースコードインストールからの移行
旧 npm/Git 方式では通常、ソースコード、.env、storage が同じプロジェクトディレクトリに配置されます：
まず新しい NB_CLI_ROOT を決定し、新しい npm または Git env を作成することを推奨します。以下の例では NB_CLI_ROOT を /your/workspace とします。
次に必要に応じて移行します：
- 旧プロジェクトのカスタムプラグインソースコードを
/your/workspace/app3/sourceの対応するディレクトリに移行する。 - 旧プロジェクトの
storageを/your/workspace/app3/storageにコピーする。 - 旧
.envの重要な設定を CLI env の設定または初期化パラメータに同期する。 - 元のデータベースを使用する場合は、初期化時に組み込みデータベースを無効にし、旧データベースの接続情報を入力する。
外部データベースで初期化する例：
移行完了後、起動してログを確認します：
バックアップなしで source、storage を直接上書きしたり、本番データベースに接続してアップグレードを実行しないでください。正式な移行の前に、テスト環境で一通りリハーサルすることを推奨します。