バックアップとリストア

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

バックアップの内容

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

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

バックアップを取る

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

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

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

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

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 つあります。

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

トラブルシューティング

• 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 と表示される：スクリプトは意図的に停止し、アプリを起動していません。表示されたボリュームを確認し、原因（多くの場合、停止したコンテナか空きのないディスク）を取り除いてから、リストアをもう一度実行してください。何度実行しても安全です。