NodaroAccount
Nodaro ドキュメント
ドキュメントノードリファレンスモデルテンプレートAI エージェント(MCP)開発者向けセルフホスティングリサーチ比較

バックアップとリストア

セルフホスティングの Nodaro を 1 つのコマンドでバックアップし、別のコマンドでリストアして、安全にダウングレードする方法です。アーカイブの中身と、そのキーの守り方も説明します。

セルフホスティングの Nodaro は、1 つのコマンドでバックアップし、もう 1 つのコマンドでリストアします。バックアップのアーカイブには、スタックが作り直せないものがすべて入ります。データベース、メディア、インスタンスの暗号化キー、.env です。データベースのマイグレーションは前方向にしか進まないため、リストアはダウングレードの唯一の方法でもあります。以前のバージョンに戻すには、アップデートの前に取ったバックアップをリストアします。

バックアップの内容

tools/community-backup.sh は、1 つの tar.gz アーカイブを書き出します。

アーカイブ内のファイル内容
db.dumppg_dump のカスタム形式による Postgres のデータです。ワークフロー、ユーザー、ジョブ、メディアのレコードが含まれます
minio-data.tar生成したメディアです。画像、動画、オーディオが含まれます
encryption-keyプロバイダーキーと SNS のログイントークンを暗号化する、インスタンスのキーです。このキーなしでリストアしたデータベースには、誰にも読めない行が残ります。
env.env です。プロバイダーキーとシークレットが含まれます
manifest.jsonアプリのバージョンとバックアップの日時です。リストア用のスクリプトが使います

Redis は意図的に含めていません。Redis が保持するのは、一時的なジョブの状態だけだからです。

アーカイブは認証情報そのものです

アーカイブには、.env と暗号化キーが含まれます。スクリプトは、ファイルのアクセス権を所有者だけに制限します(chmod 600)。この設定を変えずに、アーカイブはパスワードと同じように保管してください。Windows では、chmod は実質的に効果がありません。ファイルを同期フォルダーや共有ドライブに置かないでください。ほかの人もそのコンピューターを使う場合は、NTFS のアクセス許可で制限してください。

バックアップを取る

スタックを起動したまま、docker-compose.community.yml があるインストールディレクトリで、次を実行します。

tools/community-backup.sh
# -> ./backups/nodaro-backup-<date>-v<version>.tar.gz
オプション動作
tools/community-backup.sh /path/to/backupsアーカイブを別のディレクトリに書き出します
COMPOSE_FILE=my-compose.yml tools/community-backup.sh別の名前の Compose ファイルを使います

スクリプトは、アーカイブに入れたものを表示します。暗号化キーが見つからない場合は、そのことを目立つように表示し、エラーで終了するので、スケジュール実行のジョブでも気付けます。そのアーカイブでは、プロバイダーキーをリストアできません。

データベースのダンプは、常に整合性が保たれています。一方、バックアップの実行中に書き込まれたメディアは、アーカイブに入らないことがあります。メディアのスナップショットの整合性を確実に保つには、先にアプリを停止します。

docker compose -f docker-compose.community.yml stop nodaro

Windows では、Git for Windows がインストールするシェル、Git Bash からスクリプトを実行してください。PowerShell や WSL の bash では、コンテナのパスが壊れます。

バックアップのタイミング

メジャーバージョンのアップデート(最初の数字が変わるもの)の前には、必ずバックアップを取ります。それとは別に、データの重要度に見合ったスケジュールでも取ってください。次の cron の設定は、そのまま使えます。

0 3 * * * cd /path/to/install && tools/community-backup.sh >> backup.log 2>&1

バックアップをリストアする

tools/community-restore.sh backups/nodaro-backup-<date>-v<version>.tar.gz

リストアは、データベースとメディアをアーカイブの内容で置き換えます。そのため、何かに手を付ける前に、RESTORE と入力するよう求めます。そのあと、次の処理を行います。

  1. アプリと、データベースのクライアントである auth と rest を停止します。これらが開いている接続があると、リストアが妨げられるためです。
  2. Postgres をリストアし、終了コードを当てにせず、実際に動作することを確認します。Supabase のイメージから無害なメッセージがいくつか出力されますが、これは想定どおりです。
  3. メディアをリストアし、バケットが元に戻り、MinIO が正常に動いていることを確認します。次に暗号化キーをリストアし、ボリューム上のサイズを確認します。続いて、既存の .env があれば別の場所に退避してから、.env をリストアします。確認に失敗すると、スクリプトはアプリを起動する前に止まります。正しいキーがないままアプリを起動すると、新しいキーが作られ、リストアしたプロバイダーキーはすべて二度と読めなくなるためです。
  4. すべてを再び起動し、アプリ自身のヘルスチェックを待ちます。スクリプトが成功を報告するのは、アプリが起動してからです。起動しなかった場合は、エラーで終了します。

完了したら、http://localhost:3000/setup を開きます。すべてのカードが緑になっているはずです。

バージョンをダウングレードする

マイグレーションのロールバックはありません。以前のバージョンに戻すには、次の手順を実行します。

  1. 上記の手順で、アップデートの前に取ったバックアップをリストアします。
  2. NODARO_IMAGE か docker-compose.community.yml で、古いイメージ(たとえば ghcr.io/nodaroai/nodaro-community:v1.25.1)に固定します。vX.Y.Z 形式の厳密なタグが指すイメージは、変わることがありません。
  3. docker compose -f docker-compose.community.yml up -d nodaro を実行します。

タグについては、アップデートを参照してください。

マネージド構成のバックアップ

Compose スタックを使わない構成では、状態を持つものが 4 つあります。

対象保護の方法
Supabase の Postgres:ワークフロー、プロフィール、ジョブ、メディアのレコード有料プランで使える Supabase のポイントインタイムリカバリを使うか、定期的に pg_dump を実行します。これが最も重要なバックアップです。
ストレージのバケット:生成した画像、動画、オーディオバケットのバージョニングと、保持期間の長いライフサイクルルールを有効にして、削除したファイルを復元できるようにします。災害復旧が必要な場合は、リージョン間レプリケーションも追加します。
Redisバックアップするものはありません。Redis が保持するのは、一時的なジョブの状態だけです。Redis を失うと実行中の処理は失敗しますが、それ以外はすべて、次の起動時に Postgres から復旧します。
インスタンスの暗号化キー(NODARO_ENCRYPTION_KEY)Postgres のバックアップと一緒に保管します。このキーがないと、リストアした行のうち、プロバイダーキー、SNS のログイントークン、Webhook 出力の認証情報を読めません。その場合、タイルには missing(未設定)と表示され、キーを入力し直す必要があります。ほかに壊れるものはありません。

マイグレーションや復旧の最中に Postgres が停止していると、API はデータベースに接続できるまで再起動を繰り返します。Postgres が復旧したら、Nodaro のコンテナを再起動してください。

新しい Supabase プロジェクトにリストアする

新しい Supabase プロジェクトにリストアすると、データベースの権限は保たれません。サーバー専用の関数が、ブラウザーのロールである anon と authenticated から呼び出せる状態に戻ることがあります。マイグレーションで閉じたテーブルや列が、読み取りや書き込みのできる状態に戻ることもあります。リストアの後は必ず、これらのロールが実行できる SECURITY DEFINER 関数を一覧表示してください。

SELECT p.oid::regprocedure AS function,
       has_function_privilege('anon', p.oid, 'EXECUTE') AS anon,
       has_function_privilege('authenticated', p.oid, 'EXECUTE') AS authenticated
  FROM pg_proc p
 WHERE p.pronamespace = 'public'::regnamespace
   AND p.prosecdef
   AND p.prorettype NOT IN ('trigger'::regtype, 'event_trigger'::regtype)
   AND (has_function_privilege('anon', p.oid, 'EXECUTE')
        OR has_function_privilege('authenticated', p.oid, 'EXECUTE'))
 ORDER BY 1;

結果に含まれてよいのは、リポジトリのテストファイル supabase/tests/server-only-function-privileges.behavior.sql の browser_callable に載っている関数だけです。それ以外の関数はすべて閉じてください。anon と authenticated は PUBLIC のデフォルトの EXECUTE を引き継ぐので、PUBLIC も指定します。

REVOKE EXECUTE ON FUNCTION public.<name>(<args>) FROM PUBLIC, anon, authenticated;
GRANT EXECUTE ON FUNCTION public.<name>(<args>) TO service_role;

supabase/migrations/ のマイグレーション 598 は、サーバー専用の関数を閉じ、それまでのマイグレーションが設定したテーブルと列の権限を元に戻します。何度実行しても安全です。リストアしたデータベースを想定どおりの権限と照らし合わせるには、psql でテストファイルを実行します。テストファイルは自身をロールバックし、開いているものが最初に見つかった時点で停止します。

psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f supabase/tests/server-only-function-privileges.behavior.sql

トラブルシューティング

  • the db service is not running と表示される:先にスタックを起動します。docker compose -f docker-compose.community.yml up -d を実行してください。
  • リストア後、プロバイダーキーが missing(未設定)と表示される:データベースが、対応する encryption-key なしで、または別のキーでリストアされています。キーを含むアーカイブからリストアするか、/setup でキーを入力し直してください。
  • リストアの検証に失敗した:スクリプトは、中途半端にリストアされたデータベースを黙って残すことはしません。リストアをもう一度実行してください。何度も失敗する場合は、アーカイブが途中で切れている可能性があります。元のファイルとサイズを比べてください。
  • Windows でのバックアップ中に could not read the encryption key と表示される:Git Bash を使っていないか、アプリのコンテナが動いていません。スタックを起動した状態で、Git Bash からもう一度バックアップを実行してください。スクリプトが警告したアーカイブは、バックアップとして使えません。
  • media restore verification FAILED または encryption key verification FAILED と表示される:スクリプトは意図的に停止し、アプリを起動していません。表示されたボリュームを確認し、原因(多くの場合、停止したコンテナか空きのないディスク)を取り除いてから、リストアをもう一度実行してください。何度実行しても安全です。

よくある質問

セルフホスティングの Nodaro は、どのようにバックアップしますか?

スタックを起動したまま、インストールディレクトリで tools/community-backup.sh を実行します。データベース、メディア、インスタンスの暗号化キー、.env を含む 1 つのアーカイブが ./backups に書き出されます。

バックアップは、どのようにリストアしますか?

アーカイブのパスを指定して tools/community-restore.sh を実行します。リストアは既存のデータを置き換えるため、最初に RESTORE と入力するよう求められます。アプリを再び起動する前に、データベース、メディア、暗号化キーを検証します。

リストア後、プロバイダーキーが「missing」(未設定)と表示されるのはなぜですか?

データベースが、対応する暗号化キーなしでリストアされたためです。キーを含むアーカイブからリストアするか、/setup でキーを入力し直してください。ほかに壊れるものはありません。

Redis をバックアップする必要はありますか?

いいえ。Redis が保持するのは、一時的なジョブの状態だけです。Redis を失うと実行中の処理は失敗しますが、それ以外はすべて、次の起動時にデータベースから復旧します。

バックアップのスクリプトは Windows で実行できますか?

はい。Git for Windows がインストールするシェル、Git Bash から実行してください。PowerShell や WSL の bash ではコンテナのパスが壊れ、暗号化キーがアーカイブに含まれなくなります。

最終更新

目次