nocobase-publish-manage

目標

現在の API CLI コマンド体系を使用して、NocoBase のバックアップ復元および移行のワークフローをオーケストレーションします。

このスキルは、ユーザーの意図を API 優先の公開コンテキストに変換し、生成された名前とローカルパスを手順間で引き継ぎます。また、復元や移行の実行によって対象データが変更される前に、明示的な確認を求めます。

対象範囲

• nb api backup によるバックアップの一覧表示、作成、ステータス確認、ダウンロード、削除、復元、復元用アップロード、復元ステータス確認。
• nb api migration による移行ファイルの一覧表示、取得、作成、ダウンロード、削除、確認、実行。
• nb api migration rules による移行ルールの一覧表示、取得、グローバルルールの作成。
• 診断のための nb api migration logs による移行ログの一覧表示、取得、ダウンロード。
• 同一環境および環境間のワークフロー。デフォルトのテストワークフローでは、source_env=dev と target_env=dev を使用します。
• コマンド出力に基づく計画、実行内容の説明、読み取り専用の検証、失敗の診断。

対象外

• このスキルの対象は、「対象範囲」に記載した API CLI コマンド体系です。
• パッケージとルールの選択は明示的に行います。
• 復元、実行、削除の操作には、実行確認ゲートを設けます。
• 失敗からの復旧では現在のコンテキストを保持し、新しいパッケージやルールを作成する前にユーザーの指示を待ちます。

入力仕様

入力	必須	デフォルト	検証	確認事項
action	はい	推定	plan、run、validate	「ワークフローの計画、実行、検証のどれを行いますか？」
method	run の場合は必須	推定	backup または migration	「バックアップの復元と移行の公開のどちらを使用しますか？」
source_env	条件付き	テストでは dev	空でない環境名	「ファイルを提供または生成する環境はどれですか？」
target_env	run の場合は必須	テストでは dev	空でない環境名	「ファイルを受け取り、実行する環境はどれですか？」
backup_name	任意	未設定	backup list/create で取得したバックアップファイル名	「復元またはダウンロードするサーバーバックアップはどれですか？」
migration_name	任意	未設定	migration list/create で取得した移行ファイル名	「ダウンロードするサーバー移行パッケージはどれですか？」
local_file	任意	未設定	読み取り可能なローカル .nbdata パス	「アップロードまたは実行するローカルパッケージファイルはどれですか？」
cli_home	任意	CLI のグローバルホーム	書き込み可能な CLI ホームディレクトリ	「ダウンロードしたリリースファイルを保存する CLI ホームはどれですか？」
rule_id	migration の作成時のみ	未設定	空でない ID	「使用する移行ルール ID はどれですか？」
migration_user_rule	migration rule の作成時のみ	schema-only	schema-only または overwrite	「ユーザー定義テーブルをどのように処理しますか？」
migration_system_rule	migration rule の作成時のみ	overwrite-first	overwrite-first または schema-only	「システムテーブルをどのように処理しますか？」
title	migration の作成時のみ	publish-<source>-to-<target>	空でないテキスト	「使用する移行タイトルはどれですか？」
execute_options	任意	安全な CLI デフォルト値	既知の nb api backup restore* または nb api migration execute のフラグ	「--skip-backup や --skip-revert-on-error など、リスクの高いフラグを指定しますか？」
confirm_publish_input	作成、ダウンロード、ルール作成、確認の前	未設定	明示的な承認	「パッケージを作成、ダウンロード、または確認する前に、選択した入力を承認してください。」
confirm_execute	復元、実行、削除の前	未設定	confirm であること	「対象環境で実行するには、confirm と入力してください。」

必須の確認ゲート

• 確認ラウンドは最大2回です。
• 1ラウンドにつき、短い質問は最大3つです。
• 変更を伴う手順には、method、source_env、target_env が確定している必要があります。
• 移行パッケージを作成するには、rule_id を選択するか、新たに作成する必要があります。
• 既存のパッケージ一覧を使うフローでは、ユーザーが特定のファイルを選択する必要があります。
• パッケージの作成、パッケージのダウンロード、移行ルールの作成、移行チェックでは、公開先の入力を確認する必要があります。
• バックアップの復元、バックアップの復元アップロード、バックアップの削除、移行の実行、移行の削除では、実行の確認が必要です。
• ユーザーが「お任せします」と言った場合は、読み取り専用の計画パスを選択します。

ワークフロー

1. 意図を backup または migration に振り分けます。
2. method、sourceEnv、targetEnv、cliHome、releaseDir、backupName、migrationName、localFile、downloadPath、ruleId、title、step を含むコンテキストを構築します。
3. 必要なコマンドグループに対して、読み取り専用の機能プローブを実行します。404、Not Found、不明なリソース、非アクティブなプラグイン、ライセンス機能エラーは unsupported_publish_env として扱います。
4. バックアップを復元する場合：
   • ローカルファイル：ファイルを確認してから、nb api backup restore-upload --file <localFile> -e <targetEnv> --force で復元します。
   • ターゲット上のサーバーバックアップ：バックアップ名を確認してから、nb api backup restore --name <backupName> -e <targetEnv> --force で復元します。
   • ソースからターゲットへの復元：sourceEnv でバックアップを作成するか選択し、<cliHome>/release/<sourceEnv>/<backupName> にダウンロードしてから、--force を付けてそのパスを targetEnv に復元アップロードします。
5. 移行する場合：
   • ローカルファイル：ファイルを確認し、targetEnv でチェックしてから、targetEnv で実行します。
   • サーバー上の移行パッケージ：sourceEnv から <cliHome>/release/<sourceEnv>/<migrationName> にダウンロードし、targetEnv でチェックしてから実行します。
   • 作成した移行パッケージ：グローバルルールを一覧表示するか作成し、sourceEnv で移行を作成します。生成されたパッケージの status=ok が報告されるまで migration get をポーリングし、<cliHome>/release/<sourceEnv>/<migrationName> にダウンロードしてから、targetEnv でチェックして実行します。
6. 必要に応じて、利用可能なコマンドでステータスをポーリングまたは確認します：backup status、backup restore-status --task <taskId>、migration get、migration logs。
7. 復元タスク ID は互換性のあるフィールドとして扱います。data.taskId または data.task から taskId を解析し、その値を backup restore-status --task に渡します。
8. 最終状態、実行または予定したコマンド、ファイル名、ローカルパス、失敗した手順、次に実行する確認コマンドを報告します。

正確なコマンドの構築方法と解析ルールについては、ランタイム契約を参照してください。

リファレンスの読み込みマップ

リファレンス	使用する場面
意図の振り分け	ユーザーの表現をバックアップ、移行、ファイルの再利用、環境の形式に対応付ける場合。
ランタイム契約	コマンドを構築し、手順間で名前、パス、ルール、ステータスを引き継ぐ場合。
テスト手順書	対応する API ワークフローやエラーケースを検証する場合。

セーフティゲート

影響の大きい操作：

• nb api backup restore
• nb api backup restore-upload
• nb api backup remove
• nb api migration execute
• nb api migration remove
• nb api migration rules create
• --skip-backup や --skip-revert-on-error など、対象のバックアップまたはロールバック動作をスキップするオプション

公開入力の確認テンプレート：

Confirm publish input: <method> from <source_env> to <target_env>. Package source: <existing server file | local file | create new>. Migration rule: <ruleId/name | create new with user-defined-rule/system-defined-rule | not applicable>. Reply `confirm input` to continue with package creation, download, or check.

実行確認テンプレート：

Confirm execution: <backup restore | migration execute> on <target_env> using <backupName | migrationName | localFile>. This may change target data. Reply `confirm` to continue.

失敗時のガイダンス：

• バックアップの復元に失敗した場合：data.taskId または data.task から復元タスク ID を取得できる場合は、nb api backup restore-status --task <taskId> -e <targetEnv> を確認します。
• 移行パッケージの作成時：migration get が status=in_progress を返した場合は、パッケージの生成中であることをユーザーに伝えて待機し、status=ok になるまで migration download を実行しないでください。
• 移行チェックに失敗した場合：チェックの出力を報告し、ローカルのパッケージパスを保持します。
• 移行の実行に失敗した場合：nb api migration logs list -e <targetEnv> と、関連する logs get/download の出力を確認します。
• 失敗後のパッケージまたはルールの再作成には、ユーザーの明示的な指示が必要です。
• ユーザーが正しいファイルまたはルールから再開できるよう、最終応答にコンテキストを保持します。

検証チェックリスト

• 公開操作では nb api backup と nb api migration のコマンドグループを使用します。
• デフォルトのテストコンテキストは sourceEnv=dev、targetEnv=dev です。
• 変更を加える前に、対象となる環境で読み取り専用コマンドのプローブに成功していることを確認します。
• 機能プローブの失敗は unsupported_publish_env として報告します。
• パッケージ一覧と移行ルール一覧を提示し、ユーザーに明示的な選択を求めます。
• 既存のローカルファイルがある場合、パッケージの作成をスキップします。
• 同じ対象環境内で復元する場合、既存のサーバーバックアップ名に対して backup restore --name を使用できます。
• 環境をまたぐバックアップの復元には、backup download の後に backup restore-upload --force を使用します。
• バックアップの復元およびアップロード復元のコマンドには、--force を直接含めます。
• ダウンロードしたバックアップ、移行ファイル、ログファイルは <cliHome>/release/<sourceEnv>/ の下に保存します。
• 移行の実行では、migration execute --file の前に、ローカルのパッケージファイルに対して migration check --file を実行します。
• 移行ファイルがない場合は、rule_id を尋ねるか作成する前に、移行ルール一覧を確認します。
• migration rules create ではグローバルルールオプションを使用します。
• 作成または選択した移行ルールは、可能な場合に migration rules get で検証します。
• ダウンロードコマンドには --output を含めます。
• 復元ステータスコマンドには --task <taskId> を含め、タスク ID が data.taskId または data.task として返された後にのみ実行します。
• 復元または実行では、追加の確認を待ちます。
• 失敗時の出力には、失敗した手順と関連する CLI の行を含めます。

参考資料

• 意図のルーティング
• ランタイム契約
• テスト手順書
• NocoBase 移行マネージャー：移行のリスクと公開関連の操作に関する公式情報です。［検証済み：2026-04-30］