NocoBase Core をアップグレードする

このガイドでは、アプリが使っている NocoBase Core のフレームワークと関連する依存関係をアップグレードする方法を説明します。アプリのソースのプロジェクトで作業し、結果を検証してから、既存のデプロイ方法でアプリをデプロイします。

アップグレードで変わるもの

create-app で生成したプロジェクトには、NocoBase のパッケージの依存関係と、アプリの入口、ルーティング、レイアウト、設定、テストツールなど、プロジェクトにコピーされたフレームワークのソースの両方が含まれています。アップグレードでは、作った機能を保ったまま、新しいテンプレートの変更をマージします。

すべての @nocobase/* パッケージを更新するだけでは不十分で、新しく生成したアプリで既存のプロジェクトを上書きしてもいけません。パッケージのバージョンはそれぞれ独立しています。対象のテンプレートが宣言している依存関係の組み合わせを使ってください。

アプリの package.json には、次のようなメタデータが含まれています。

{
  "nocobase": {
    "templateKind": "app",
    "templatePackage": "@nocobase/app-template-default",
    "defaultTemplateVersion": "1.0.0-beta.81"
  }
}

templatePackage は元のテンプレートを示します。defaultTemplateVersion は、アプリにすでにマージされているテンプレートのリリースを記録します。アプリ自身の version は業務アプリのリリースを示すもので、Core のバージョンではありません。メタデータを変えるだけでは、アップグレードは行われません。

始める前に

既存の変更を確認して Git にコミットし、現在のコミットを記録して、別のブランチでアップグレードします。
対象のリリースを特定し、Node.js、パッケージマネージャー、データベース、独自のプラグインの互換性の要件を含め、リリースノートを読みます。
復元可能なデータベースのバックアップを用意します。実行時の設定、シークレット、ファイルストレージ、対応する以前のアプリのビルドも保持します。
分離した検証用の環境でリハーサルします。既存のデータで試すには、そこにデータベースとファイルのバックアップを復元し、その環境が本番のデータベースに接続したり、実際の業務通知を送ったりできないようにします。

新しいアプリを起動すると、マイグレーションが自動で適用されることがあります。初回の起動の前に、バックアップ、マイグレーションの確認、必要なデータの準備を済ませてください。

次のどちらかの方法を選び、そのあとで共通の検証とデプロイの手順を行います。

エージェントを使う場合

アプリのルートでコーディングエージェントを開きます。アプリは .agents/skills/nocobase-app-upgrade/SKILL.md にアップグレードのガイダンスを持っており、依存関係のインストール時に同期されます。エージェントがそれと AGENTS.md を読めることを確認してください。依頼そのものは、アップグレードの対象、保つべき機能、検証に集中できます。

スキルがない場合は、プロジェクトのロックファイルを使って依存関係をインストールします。インストールのスクリプトが無効になっていた場合は、次を実行します。

pnpm nocobase skills sync

次のプロンプトを使います。必要に応じて、対象を明示的なバージョンに置き換えてください。

このアプリが使っている NocoBase Core を、現在のリリースチャネルの新しいリリースにアップグレードしてください。

まずプロジェクトを調べ、編集せずに具体的な計画を示してください：
- 現在のバージョンと対象のバージョンを示してください。すでに対象のバージョンなら、アップグレードは不要と伝え、ダウングレードはしないでください。
- 影響を受ける機能、依存関係、設定、プラグインと、私の判断が必要な変更を説明してください。
- 既存の業務機能、テーマ、権限、データをどう保つか、問題が起きたときにどう復旧するかを説明してください。
- 元に戻せないデータの変更や、修復が必要な過去の記録があれば、その原因と影響とともに示してください。

私が計画を確認したら、プロジェクトのアップグレードのガイダンスに従い、別のブランチで変更してください。
アプリを上書きしたり、データベースを空にしたり、バージョン番号の変更だけでアップグレードが完了したと扱ったりしないでください。
別のテスト環境で、既存のデータ、サインイン、一般ユーザーの権限、タスクの操作を検証してください。
変更前後のバージョン、調整した内容、検証結果、残っている作業を報告してください。
このタスクはアップグレードしたプロジェクトの準備と検証です。本番へのデプロイは別に確認してください。

計画を確認するときは、機能が保たれること、削除されるプラグインが不要になっていること、データベースを復旧できることを確かめます。デプロイの前に、実際の変更と検証結果を確認してください。

古いグローバルなプラグイン開発スキルを移行する

以前に nocobase-app-plugin-development をグローバルにインストールしていた場合は、その移行をアップグレードの計画に含めます。対象のリリースが、プロジェクトのスキルと互換性のある同期コマンドの両方を提供している必要があります。同じ名前のプロジェクトのスキルがグローバルなコピーを上書きするとは考えないでください。

対象のテンプレートに従って依存関係をアップグレードし、pnpm nocobase skills sync を実行します。
アプリの .agents/skills/nocobase-app-plugin-development/ に、完全なガイドと参照されるリソースが含まれていることを確認します。
使っているエージェントのグローバルな場所を調べ、この古いインストールそのものと、その検出用のリンクを削除します。独自の内容は、先にスキルの検出ディレクトリの外にバックアップします。グローバルなエントリーがプロジェクトやソースのチェックアウトを指している場合は、リンクを外すだけで、指し先は削除しないでください。
新しいエージェントのセッションを始め、プロジェクトのファイルが使われていることを確認します。

プロジェクトの代わりのスキルが使えない場合や同期が失敗した場合は、既存の完全なグローバルなインストールを残し、先にその前提条件を解決してください。グローバルなファイルはアプリの Git でのロールバックの対象外なので、バックアップと復旧を別に記録します。依存関係のインストールや同期で、それらが自動で削除されることはありません。すでにアップグレードしたアプリでも、バージョンを再び変えずに、漏れていた後片付けを完了できます。

エージェントを使わない場合

1. 基準と対象を特定する

アプリのソースのルートで次のコマンドを実行します。以降のコマンドは、同じ Bash セッションの変数を使います。

git status --short
git rev-parse HEAD
node -p "JSON.stringify(require('./package.json').nocobase, null, 2)"

TEMPLATE=$(node -p "require('./package.json').nocobase.templatePackage")
BASE=$(node -p "require('./package.json').nocobase.defaultTemplateVersion")
npm view "$TEMPLATE" dist-tags --json

先に未コミットの変更を確認してコミットします。テンプレートの取得元や基準がわからない場合は、続ける前にプロジェクトの履歴から確定させます。templateKind: app だけでは Default と Examples を区別できません。基準を推測しないでください。

ベータ版のアプリは通常 beta のまま、安定版のアプリは通常 latest を使います。latest タグが beta より新しいとも、安定版のリリースを指しているとも限りません。ほかのプレリリースのチャネルは個別に確認してください。

ベータ版のアプリでは、対象を一度だけ解決し、その正確なバージョンを保持します。

TARGET=$(npm view "$TEMPLATE@beta" version)
printf 'Template: %s\nBase: %s\nTarget: %s\n' "$TEMPLATE" "$BASE" "$TARGET"

明示的なリリースの場合は、確認済みの完全なバージョンを TARGET に代入します。バージョンはセマンティックバージョニングの順序で比較します。同じならアップグレードは不要で、古い場合は暗黙にダウングレードせずに止めます。新しい対象を確認できたら、ブランチを作成します。

git switch -c "chore/upgrade-core-$TARGET"

2. 両方のテンプレートのリリースを取得する

アプリのソースの外の一時ディレクトリにダウンロードします。

WORK=$(mktemp -d)

for VERSION in "$BASE" "$TARGET"; do
  ARCHIVE=$(npm pack "$TEMPLATE@$VERSION" --silent --pack-destination "$WORK")
  mkdir -p "$WORK/$VERSION"
  tar -xzf "$WORK/$ARCHIVE" -C "$WORK/$VERSION" --strip-components=1
done

diff -rq "$WORK/$BASE" "$WORK/$TARGET"

diff の終了コード 1 は差分が見つかったことを意味し、想定どおりです。まず公開された 2 つのテンプレートを比較します。アプリを新しいテンプレートと直接比較すると、自分の業務上の変更と上流の変更を区別できません。

3. ソースと依存関係を個別にマージする

変更されたファイルごとに、基準、対象、アプリのバージョンを読みます。たとえば、ルートの変更は次のように確認します。

diff -u "$WORK/$BASE/client/routes.ts" "$WORK/$TARGET/client/routes.ts"
diff -u "$WORK/$BASE/client/routes.ts" client/routes.ts

1 つ目の比較はテンプレートの変更を、2 つ目は既存のカスタマイズを示します。タスクのルート、設定の入口、権限の宣言などの業務コードを保ったまま、テンプレートの新しい動作を取り込みます。

内容	マージの方法
通常のフレームワークのファイル	カスタマイズしていないファイルは対象のものを採用し、両方で変更されたファイルは個別に調整する
`package.json`	対象の依存関係とスクリプトをマージし、アプリの名前、業務のバージョン、独自の依存関係とスクリプトは保つ。ファイル全体を置き換えない
プラグインの登録	`client/plugins.ts`、`server/plugins.ts`、`cli/plugins.ts` をまとめて確認し、アプリが使っているプラグインを保つ
設定とテーマ	設定の例とフレームワークの変更をマージし、実行時の設定、シークレット、アプリの識別情報、独自のテーマは保つ
マイグレーションとシード	実行済みのファイルは元のパスと内容のまま残す。修正には新しいマイグレーションを使う
エージェントのガイダンス	`AGENTS.md` と `.agents/rules/` のアプリ側のカスタマイズをマージする。`.agents/skills/` は同期コマンドで再生成する

対象で削除されたファイルや依存関係を削除する前に、業務コード、設定、テストで使われていないかを確認します。承認された NocoBase のパッケージの削除では、依存関係がまだ宣言されているうちに pnpm nocobase package remove <package-name> を実行し、依存関係、スキル、プラグインの登録をまとめて片付けます。業務上の参照は自分で扱う必要があります。古い CLI にこのコマンドがない場合は、プロジェクトのアップグレード用スキルの互換手順に従ってください。

パッケージの更新では、アプリのマイグレーションのファイルが変わらなくても、プラグインのマイグレーションが加わることがあります。影響を受けるパッケージのアップグレードの注意事項を読み、データの前提条件、API の変更、削除された機能の代替を確認します。

4. 依存関係をインストールしてスキルを同期する

ソースのマージを終えたら、nocobase.defaultTemplateVersion を固定した対象のバージョンに設定し、次を実行します。

pnpm install
pnpm dedupe
pnpm nocobase skills sync

ロックファイルの変更を確認して残します。pnpm dedupe は、互換性のある依存関係の解決をまとめます。競合は pnpm why <package-name> で調べ、対象のテンプレートの制約と独自の依存関係を調整します。ロックファイルを削除したり、すべての依存関係を最新のリリースに上げたりして、競合を回避しないでください。

5. データベースのマイグレーションを確認して適用する

まず次のセクションの静的チェックと自動テストを済ませます。設定が分離した検証用の環境を指していることを確認し、新しいバージョンを起動する前に、対象の CLI で読み取り専用のチェックを 2 つ実行します。

pnpm nocobase db apply --dry-run --json
pnpm nocobase db repair --dry-run --json

1 つ目のコマンドは、保留中のマイグレーションとシードを一覧表示します。2 つ目は、実行済みのタスクのチェックサムの変更を確認します。適用のプレビューはマイグレーションの本体を実行せず、チェックサムも確認しないため、これらのチェックは互いの代わりにはなりません。どちらも、指定しない限り既定の接続を使います。複数の接続がある場合は、関係する接続ごとに --connection <name> を付け、以降の実行も同じ範囲にそろえます。

チェックサムのプレビューで変更が提案された場合は、続ける前にそれぞれをリリースノートと照らし合わせます。実際の db repair は通常のアップグレードの手順ではありません。選んだ接続で一致しない記録済みのチェックサムをすべて更新しますが、マイグレーションを再実行したり、業務データを修復したりはしません。説明のつかない変更があれば止めて、アップグレード用スキルのデータベースのガイダンスに従ってください。過去のファイルを編集したり、データベースをリセットしたり、エラーを無視したりしないでください。

バックアップが復元可能で、チェックサムの確認が終わり、必要なデータの準備ができたら、分離した検証用の環境でマイグレーションを適用します。

pnpm nocobase db apply --json

本番のマイグレーションは、デプロイの手順で行います。開発用のチェックアウトを本番に向けてこれらのコマンドを実行しないでください。

アップグレードを検証する

Core のアップグレードはアプリ全体に影響する可能性があります。この例では、既存のプロジェクトのスクリプトを確認し、テストを使ってタスク機能の分離したテストを追加します。

pnpm typecheck
pnpm lint
pnpm format:check
pnpm test
pnpm build

これらのコマンドはソースのプロジェクトで実行し、テストには分離したデータベースを使います。新しいツールに合わせて既存のテストの設定を調整する必要がある場合は、網羅性を保ったまま修正します。失敗したテストをスキップしても、合格したことにはなりません。

データベースの準備ができたら pnpm dev を実行し、表示された Local: の URL で次を確認します。

管理者がサインインでき、タスクのページとシステム設定が動作し、言語と独自のテーマが期待どおりに動作する。
既存のタスクのタイトル、担当者、完了状態、期日が保たれている。作成、完了と再オープンの操作、絞り込み、ページネーションが引き続き動作する。
一般ユーザーは許可されたページとレコードにだけアクセスできる。閲覧専用ユーザーは、API を直接呼び出した場合も含め、引き続き書き込めない。
再読み込みや再起動のあとも、データが残っている。影響を受けるプラグインの機能、バックグラウンドジョブ、連携が、対応するチェックに合格する。

アプリが実際に実装している機能を検証してください。ブラウザーのテストには、別のテスト用アプリと認証情報を設定してから pnpm test:e2e を実行します。セットアップについてはテストを参照してください。pnpm test にはブラウザーのテストは含まれません。

デプロイと復旧

検証が終わったら、ソースとロックファイルの変更をコミットします。基準、対象、マージの判断、検証結果を記録します。既存のデプロイ方法でビルドし直して公開します。

以前のビルドに対応する設定とデータのバックアップを保持しておきます。コードをロールバックしても、データベースのマイグレーションは元に戻りません。以前のランタイムがアップグレード後のスキーマを使えない場合は、対応するデータベースとファイルのバックアップを復元し、そのバックアップ以降の業務の書き込みを考慮してください。

リリースノートで過去のチェックサムの修正が求められている場合は、バックアップ、修復、マイグレーション、失敗時の復旧を 1 つの保守の手順でまとめて行います。app-installer では、通常のアップグレードの自動復旧に頼る前に、db repair を単独で実行しないでください。インストーラーがあとで取るバックアップに新しいチェックサムがすでに含まれ、以前のランタイムがそれを拒否する可能性があります。外部のデータベースには、それぞれのバックアップと復旧の手配も必要です。

検証の範囲

このガイドでは、テンプレートのマージとアップグレードのチェックを説明しています。現在の入門のサンプルは、npmjs.org で公開されている 1.0.0-beta.81 のテンプレートの依存関係と照合され、テストとビルドに合格しています。これは、すべての古いバージョンからのアップグレードの道筋を保証するものではありません。実際のアップグレードのたびに、リリース固有の変更、既存のデータ、権限、復旧を分離した環境で検証してください。