• 日本語

      • インストールとアップグレード移行ガイド：NocoBase CLI を使用する

      Danger

      CLI のインストールおよびアプリケーション保守機能は現在も開発中です。現時点では、ローカル開発、テスト環境、AI Agent 接続のシナリオにより適しており、本番環境でのインストール、アップグレード、運用保守に直接使用することは推奨されません。

      新しい NocoBase CLI (nb) は、インストール、接続、起動、停止、ログ確認、アップグレード、クリーンアップなどの操作を 1 つのコマンド体系に統合します。旧ドキュメントで Docker、create-nocobase-app、Git ソースコードごとに分かれていたワークフローと比べて、CLI はローカル開発、テスト環境の保守、および AI Agent の接続と協調により適しています。

      この記事は、次のようなシナリオに適用されます。

      • 旧ドキュメントに従って NocoBase をインストールまたはアップグレードしており、新しい CLI 方式に切り替えたい。
      • すでに旧方式でデプロイされた NocoBase があり、それを CLI で管理または接続したい。
      • AI Agent 向けに、接続可能で保守可能な NocoBase 環境を用意したい。

      旧方式と新方式の違い

      旧方式では、インストール元ごとにドキュメントが分かれており、それぞれでダウンロード、設定、インストール、起動、アップグレードのコマンドを個別に実行する必要があります。

      旧インストールドキュメント

      旧アップグレードドキュメント

      新方式では nb init を入口とし、CLI env にアプリのソース、実行ディレクトリ、storage ディレクトリ、データベース、および API 接続情報を記録します。その後は、ソースが Docker、npm、Git のいずれであっても、可能な限り同じ nb app、nb source、nb db コマンド群で保守します。

      シナリオ旧方式新 CLI 方式
      インストール入口docker compose、create-nocobase-app、git clonenb init または nb init --ui
      アプリ実行管理ディレクトリ切り替え、compose 修正、yarn/pm2 コマンド実行nb app start/stop/restart/logs、nb env remove
      アップグレードインストール方式ごとに別のコマンドnb app upgrade -e <env>
      開発モードyarn devnb source dev -e <env>
      データベース状態コンテナまたは DB サービスを手動確認nb db ps -e <env>
      環境状態と詳細の確認パス、ポート、アクセス URL を手動記録nb env list、nb env info <env>
      既存アプリの接続旧インストールドキュメントでは統一してカバーされていないnb init --ui または nb init --api-base-url

      CLI のインストール

      npm install -g @nocobase/cli@beta
nb --version

      インストール後、ヘルプを確認できます。

      nb --help
nb init --help

      新しい方法で NocoBase をインストールする

      推奨：ビジュアルウィザードを使用する

      nb init --ui

      ウィザードでは次を選択できます。

      • 新しいアプリを作成するか、既存アプリに接続するか
      • インストール元：Docker、npm、Git
      • NocoBase バージョン
      • 内蔵データベースを使用するか、外部データベースを使用するか
      • 管理者アカウントとパスワード

      ターミナルの対話型ウィザードを使用する

      nb init

      非対話コマンドを使用する

      デフォルトのインストール方式は Docker で、内蔵 PostgreSQL データベースを使用します。

      nb init --yes --env app1

      Docker で指定バージョンをインストールする：

      nb init --yes --env app1 --source docker --version beta

      npm でインストールする：

      nb init --yes --env app1 --source npm --version beta --app-port 13080

      Git ソースコードからインストールする：

      nb init --yes --env app1 --source git --version beta

      Git ソースコードを使用し、内蔵データベースの種類を指定する：

      nb init --yes --env app1 --source git --version beta --db-dialect mysql

      既存の NocoBase アプリケーションに接続する：

      # デフォルトでは OAuth 認証を使用
nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api

# token 認証を使用
nb init --yes --env app1 \
  --api-base-url=http://next.v2.test.nocobase.com/nocobase/api \
  --auth-type=token \
  --access-token=<token>
      Tip

      --env は CLI 内の環境名です。以後の起動、アップグレード、ログ確認などのコマンドでは、-e app1 で対象アプリケーションを指定できます。

      新しい方法でアップグレードする

      旧方式では Docker、create-nocobase-app、Git ソースコードでアップグレードコマンドが異なっていましたが、新しい CLI では次のように統一されています。

      nb app upgrade -e app1

      すでにダウンロード済みのソースコードまたはイメージだけを使ってアップグレード処理を実行し、新しいコードやイメージを取得しない場合：

      nb app upgrade -e app1 --skip-code-update

      または短縮形を使用します：

      nb app upgrade -e app1 -s

      よく使う保守コマンド

      操作コマンド
      アプリを起動nb app start -e app1
      アプリを停止nb app stop -e app1
      アプリを再起動nb app restart -e app1
      ログを確認nb app logs -e app1
      env と API 認証状態を確認nb env list
      env の詳細を確認nb env info app1
      内蔵データベースの状態を確認nb db ps -e app1
      アプリをアップグレードnb app upgrade -e app1
      アプリと内蔵データベースを停止nb app stop -e app1 --with-db
      env とローカルでホストされるリソースを完全削除nb env remove app1 --purge --force

      アプリと CLI が管理する内蔵データベースを一緒に停止したいだけなら、通常は nb app stop -e app1 --with-db をそのまま使えば十分です。

      その env がもう不要であることが確実な場合のみ、nb env remove app1 --purge --force を使ってください。これにより、管理されている実行リソース、storage データ、および該当する場合は CLI がダウンロードして管理しているローカル app ファイルが削除されます。

      日常開発コマンド

      nb source はローカルソースコードプロジェクトの管理に使用され、主に npm および Git source env に適しています。

      操作コマンド
      開発モードでアプリを実行nb source dev -e app1
      ソースコードをビルドnb source build --cwd /your/workspace/app1/source
      テストを実行nb source test --cwd /your/workspace/app1/source
      ソースコード／イメージをダウンロードまたは更新nb source download --source git --version beta
      Tip

      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 によって生成されるファイルは通常次の場所にあります。

      ~
├── .nocobase
│   └── config.json
└── app1
    ├── source
    └── storage

      NB_CLI_ROOT を明示的に指定することもできます。

      export NB_CLI_ROOT=/your/workspace

      設定後は、設定ファイルとデフォルトのアプリケーションディレクトリはいずれもそのディレクトリ配下に配置されます。

      /your/workspace
├── .nocobase
│   └── config.json
└── app1
    ├── source
    └── storage

      このうち：

      • .nocobase/config.json には env、現在の環境、API アドレス、ソースコードパス、storage パス、データベース設定などの情報が保存されます。
      • <envName>/source は CLI が管理するソースコードまたはアプリケーションディレクトリです。
      • <envName>/storage は CLI が管理するアプリケーションのストレージディレクトリです。
      Warning

      同じアプリケーションを初期化した後は、同じ NB_CLI_ROOT を使い続けてください。あとで NB_CLI_ROOT を変更すると、CLI は新しいディレクトリで .nocobase/config.json を探し、相対パス形式の appRootPath や storagePath も新しいディレクトリ基準で解決されるため、アプリケーションが見つからなくなったり、誤ったディレクトリに読み書きしたりする可能性があります。

      CLI は現在、グローバル設定スコープのみを使用します。設定とローカルアプリケーションファイルの保存場所を変更したい場合は、NB_CLI_ROOT を設定してください。

      アプリケーションの確認と特定には、nb env list と nb env info を優先して使用してください。

      # 設定済み env と API 認証状態を確認
nb env list

# 特定 env の詳細情報を確認
nb env info app1

      nb env list は素早い全体確認向けです。この中の App Status は、保存済みの Token/OAuth 認証情報でアプリケーション API にアクセスして得られた認証状態を示し、データベース状態は表示しなくなりました。内蔵データベースの稼働状態を確認する必要がある場合は、次を使用してください。

      nb db ps -e app1

      デフォルト env を切り替える必要がある場合にのみ、次を使用してください。

      nb env use app1

      旧方式から CLI へ移行する

      移行には 2 つの戦略があります。既存アプリケーションに接続する、または ローカルアプリケーションディレクトリを CLI 管理下に置く 方法です。旧アプリケーションがすでに安定稼働している場合は、リスクが最も低い「既存アプリケーションに接続する」を先に使うことを推奨します。

      方法 1：既存アプリケーションに接続する

      Docker、create-nocobase-app、Git ソースコード、またはサーバーデプロイで稼働している NocoBase に適しています。

      # デフォルトでは OAuth 認証を使用
nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api

# token 認証を使用
nb init --yes --env "app$RANDOM" \
  --api-base-url=http://next.v2.test.nocobase.com/nocobase/api \
  --auth-type=token \
  --access-token=<token>

      この方式では API 接続のみを保存します。CLI は旧アプリケーションの起動、停止、アップグレード、ソースコードディレクトリ、storage ディレクトリの管理を引き継ぎません。AI Agent や CLI API コマンドから既存アプリケーションに接続する用途に適しています。

      認証を更新する必要がある場合：

      nb env auth app1

      方法 2：新しい CLI env を作成してからファイルを移行する

      その後 nb app と nb source を使ってローカルアプリケーションを管理したいシナリオに適しています。

      移行前に、まず次を完了してください。

      1. 旧アプリケーションを停止する。
      2. 旧データベースをバックアップする。
      3. 旧 storage ディレクトリをバックアップする。
      4. APP_KEY、TZ、DB_*、DB_UNDERSCORED など、旧アプリケーションの重要な環境変数を記録する。

      旧 Docker インストールからの移行

      旧 Docker 方式では、通常アプリケーションデータはプロジェクトディレクトリの storage に置かれています。

      /old-docker-project
├── docker-compose.yml
└── storage

      まず新しい NB_CLI_ROOT を決め、その後 CLI で新しい Docker env を作成することを推奨します。以下の例では NB_CLI_ROOT が /your/workspace であると仮定します。

      export NB_CLI_ROOT=/your/workspace
nb init --yes --env app2 --source docker --version beta
nb app stop -e app2

      新しい env はデフォルトで次のディレクトリを使用します。

      /your/workspace
└── app2
    ├── source
    └── storage

      次に、旧 storage を /your/workspace/app2/storage にコピーし、データベース接続や APP_KEY などの設定が旧環境と一致していることを確認してください。

      コピー完了後、データベース設定を確認したら、アプリケーションを起動します。

      nb app start -e app2
nb app logs -e app2

      旧 create-nocobase-app または Git ソースコードインストールからの移行

      旧 npm/Git 方式では、通常ソースコード、.env、storage は同じプロジェクトディレクトリにあります。

      /old-nocobase
├── .env
├── package.json
├── packages
└── storage

      まず新しい NB_CLI_ROOT を決め、その後新しい npm または Git env を作成することを推奨します。以下の例では NB_CLI_ROOT が /your/workspace であると仮定します。

      export NB_CLI_ROOT=/your/workspace
nb init --yes --env app3 --source git --version beta
nb app stop -e app3

      その後、必要に応じて移行します。

      • 旧プロジェクト内のカスタムプラグインソースコードを /your/workspace/app3/source の対応ディレクトリへ移行する。
      • 旧プロジェクト内の storage を /your/workspace/app3/storage にコピーする。
      • 旧 .env の重要な設定を CLI env 設定または初期化パラメータに同期する。
      • 元のデータベースを使用する場合は、初期化時に内蔵データベースを無効にし、旧データベース接続情報を入力する。

      外部データベースで初期化する例：

      nb init --yes --env app3 --source git --version beta \
  --no-builtin-db \
  --db-dialect postgres \
  --db-host 127.0.0.1 \
  --db-port 5432 \
  --db-database nocobase \
  --db-user nocobase \
  --db-password nocobase

      移行完了後、起動してログを確認します。

      nb app start -e app3
nb app logs -e app3
      Warning

      バックアップなしで source や storage を直接上書きしたり、本番データベースに接続してアップグレードを実行したりしないでください。本格移行の前に、まずテスト環境で一度完全にリハーサルすることを推奨します。

      旧コマンド移行クイックリファレンス

      旧コマンド新 CLI コマンド
      docker compose up -d appnb app start -e app1
      docker compose stop appnb app stop -e app1
      docker compose logs -f appnb app logs -e app1
      docker compose pull app && docker compose up -d appnb app upgrade -e app1
      yarn create nocobase-app my-nocobase-app ...nb init --yes --env app1 --source npm --version beta
      npx create-nocobase-app@beta my-nocobase-app ...nb init --yes --env app1 --source npm --version beta
      git clone ... -b next --depth=1 my-nocobasenb init --yes --env app1 --source git --version beta
      git clone ... -b develop --depth=1 my-nocobasenb init --yes --env app1 --source git --version alpha
      yarn devnb source dev -e app1
      yarn nocobase upgradenb app upgrade -e app1
      yarn nocobase upgrade --skip-code-updatenb app upgrade -e app1 -s
      複数アプリケーションのアドレスを手動で記録nb env list、nb env info app1
      既存アプリケーションへ手動接続nb init --yes --env app1 --api-base-url=http://next.v2.test.nocobase.com/nocobase/api

      関連リンク