トラブルシューティング¶

短い FAQ です。SSH 経由の VM に関するホスト側トラブルシューティングの完全な表（permission-denied、ホスト鍵検証、テンプレート変数の欠落など）については、GitHub の SSH 経由の VM バックアップガイドを参照してください。

何かが正しく配線されていない¶

Web UI で /spike を開きます。ホスト統合チェックはすべてのマウントと CLI（Docker ソケット、libvirt、restic、qemu-img、rclone）をプローブし、欠けている部分を報告します。バグだと決めつける前に、まずここから始めてください: マウントの欠落や到達不能なホストはすぐに表示されます。

Web UI に到達できない¶

BombVault はデフォルトでポート 3443（自己署名証明書）で HTTPS を提供するため、https://<your-unraid-ip>:3443 を開いてください。自己署名証明書の警告を受け入れるか、独自の証明書を持つリバースプロキシの背後に BombVault を置いてください。HTTP_ONLY=true で実行している場合は、代わりにポート 3000 でプレーン HTTP を提供します（TLS を終端するプロキシの背後での使用向け）。

APP_KEY を失った¶

APP_KEY は restic リポジトリのパスワードを導出します。それ（および暗号化キー・リカバリーキット）がなければ、暗号化されたバックアップは復元できません。これが、ダッシュボードがリカバリーキットをダウンロードするようせがむ理由です。オフサイトと復旧を参照してください。openssl rand -hex 32 で鍵を生成し、バックアップに頼る前にサーバーとは別の場所に保管してください。

VM バックアップが接続できない¶

VM バックアップは、マウントではなく SSH 経由で libvirt と通信します。

ホストで SSH が有効になっていること、そして BombVault の公開鍵が /root/.ssh/authorized_keys で承認されていることを確認してください（設定、連携、ホスト SSH に鍵と 接続をテスト ボタンが表示されます）。
カスタムの br0.x ネットワークでは、LIBVIRT_HOST を Unraid の LAN IP に設定してください（そこではコンテナは host.docker.internal 経由でホストに到達できません）。Settings, Docker, Host access to custom networks を有効にしてください。
Unraid の SSH ポートを変更した場合は、LIBVIRT_SSH_PORT を一致させてください。
完全なステップバイステップの診断（到達性テスト、VLAN のルーティング、Permission denied (publickey)、Host key verification failed）は、SSH 経由の VM バックアップガイドにあります。

ライブ VM スナップショットが実行されなかった¶

ライブスナップショットには、VM 内にインストールされた qemu ゲストエージェントと、ディスクが /mnt/user ではなく /mnt/cache（または /mnt/diskX）にあることが必要です。シャットオフ状態の VM では、ライブは自動でグレースフルにフォールバックします。グレースフルバックアップは VM をシャットダウンし、ディスクをバックアップしてから再起動するため、常に一貫しています。

バックアップが "repository is already locked" で失敗した¶

これはたいてい、コンテナが操作の途中で更新または再起動されたときに残された、孤立した restic ロックです。BombVault は証明可能な孤立ロックを検出し、強制解除して一度だけ自動でリトライします。それでも続く場合は、影響を受けるドメインに対して 設定、整合性、ロック解除 を使って、古いロックを手動で削除してください。本当の問題は、隠される代わりにきちんと表面化します。再起動の後、BombVault はそのようなロックが 10 分間更新されなくなるまで待ちます。まだ動いている restic は、たとえば同じリポジトリを使う 2 台目の BombVault の中で、5 分ごとにロックを更新するためです。

バックアップの後にオフサイトコピーが行われなかった¶

オフサイト複製は設計上ベストエフォートのため、オフサイトの不調でローカルバックアップが失敗することはありません。そのドメインのオフサイトスケジュール（設定、スケジュール）を確認してください: 空欄のスケジュールは各ローカルバックアップの後に複製し、頻度を設定すると少ない頻度で送ります。オンデマンドの実行にはオフサイトページの 今すぐ複製 を使い、ダッシュボードの複製インジケーターを見てください。

復元が始まる前に中止された¶

何かを停止または削除する前に、復元はプリフライトの競合チェックを実行します: コンテナの静的 IP と公開ホストポートが空いていることを検証します。別のコンテナがすでにいずれかを保持している場合、途中で終わった復元を残す代わりに、明確で実行可能なメッセージとともに中止します。競合するポートまたは IP を空けてから、リトライしてください。

プレーンエクスポートがファイルを書き込む代わりに失敗した¶

age 暗号化がオン（設定）で、有効な受信者が設定されていない場合、エクスポートは平文を書き込む代わりに、明確なエラーで失敗します。有効な受信者（age 公開鍵または SSH 公開鍵）を追加するか、エクスポートを平文にするつもりなら暗号化をオフにしてください。機能を参照してください。

データベースのダンプが失敗した¶

ダンプが失敗しても、その周りのバックアップが失敗することはありません。ダンプ自体が失敗した実行として記録され、理由が何を直せばよいかを示します。

ログインを拒否された。 ダンプはコンテナ自身のパスワード変数（POSTGRES_PASSWORD、MARIADB_ROOT_PASSWORD、MYSQL_ROOT_PASSWORD、またはその _FILE 版）でログインします。データベースコンテナ側で確認してください。コンテナ自身のユーザーが読めないシークレットを指す _FILE 変数も同じように失敗します。
権限が足りない。 ランダムな root パスワードだと、ダンプはアプリ用ユーザーとしてしかログインできず、そのひとつのデータベースだけになります。MySQL 8.4 以降では完全に拒否されることもあります。コンテナに本物の root パスワードを与えるか、そのコンテナのダンプをオフにしてください。
システムテーブルのアップグレードが必要。 システムテーブルが古いバージョン由来だと、MariaDB はダンプを拒みます（エラー 1558）。変数 MARIADB_AUTO_UPGRADE=1 を追加してコンテナを再起動するか、コンテナ内で mariadb-upgrade を一度実行してください。
ダンプツールがない。 pg_dump、mysqldump、mariadb-dump のいずれも入っていない軽量イメージや自作イメージはダンプできません。公式イメージを使うか、ダンプをオフにしてください。
時間制限。 ダンプには DB_DUMP_MAX_HOURS（既定は 6）、その周りのバックアップには BACKUP_MAX_HOURS が効き、進まなくなったダンプは BACKUP_STALL_HOURS で打ち切られます。最後の場合、原因はたいていアプリケーションが握っているロックです。作動した方の制限を引き上げるか、アプリケーションが静かなときにダンプしてください。
コンテナが一時停止中か再起動中。 ダンプは稼働中のサーバーと話します。コンテナが再起動を繰り返すなら、その理由はコンテナ自身のログにあります。
壊れたダンプを削除できなかった。 BombVault は完了できなかったダンプを削除します。その削除が失敗すると、ダンプは破損として印が付いたまま一覧に残るので、そこから削除できます。

取り込みが失敗した¶

取り込みはコンテナを止め、そのデータフォルダーを脇へ寄せ、イメージに空のフォルダーを作らせます。取り込み自体より前の段階で失敗した場合、古いフォルダーは自動的に戻されます。取り込みで失敗した場合、コンテナには新しいフォルダーが残り、古い方は <データフォルダー>.bombvault-before-import-<タイムスタンプ> として隣に残ります。実行のエラーメッセージが正確なパスを示します。

手で戻すには、コンテナを止め、現在のデータフォルダーの名前を変えてどかし、残しておいたフォルダーを元の名前に戻してから、コンテナを起動します。Unraid では Shares タブのファイルマネージャーでできます。

ZFS データセットのバックアップが失敗した、またはデータセットがスキップされた¶

問題にはそれぞれ角かっこ付きの理由コードが付きます。ZFS データセットのページに、すべてのコードと対処法があります。よくあるのは次の 3 つです。

snapshot-loop：Host Data が新しいマウントを伝えないため、スナップショットが BombVault に届きませんでした。コンテナを編集して Host Data の Access Mode を Read/Write - Slave にし、BombVault を再起動してください。
key-not-loaded：鍵が読み込まれていない暗号化データセットはスキップされます。zfs load-key で鍵を読み込み、データセットをマウントしてください。次のバックアップから含まれます。
ssh-auth：サーバーが BombVault の鍵を拒否しました。ZFS ページの接続カードに鍵を許可するコマンドが表示されます。サーバーで一度実行してください。

項目が「学習中 N/10」のまま進まない¶

ほとんどの異常チェックは、項目のバックアップが 10 回成功してから始まります。想定どおりと印を付ける の後や、項目の選択を変えた後は、数え直しになります。スケジュールのない項目は学習せず、appdata のないコンテナには学習の材料がありません。そのことはバッジにも表示されます。

ある項目の古いバックアップを保持ポリシーが削除しなくなった¶

未解決の重大な異常がそれを止めています。項目のソースがほぼ空になった、大きく縮んだ、またはバックアップがデータの大部分を保存し直したという異常です。項目のバッジから異常を開いてください。データが欠けている、または暗号化されている場合は、まずリンクされた最後の正常なバックアップから復元します。その後で異常を確認済みにするか、変更が自分によるものなら想定どおりと印を付けると、次の実行から通常どおり整理されます。保持のプレビューでは、このような項目は保持と表示されます。ZFS 項目では、異常が名指しするデータセットだけが古いバックアップを保持し、ツリーのほかのデータセットはいつもどおり整理されます。

手動の整理で一部の項目が保持されたと表示される¶

原因は同じです。整理はこのような異常のある項目の古いバックアップに手を付けず、メッセージでその項目名を示します。それ以外はいつもどおり整理されます。

履歴の読み込みでリポジトリを読めなかったと表示される¶

アップデートの後、BombVault は各リポジトリから以前のバックアップのサイズを一度読み込みます。そのときに届かなかったリポジトリ (停止していたオフサイトの宛先や、マウントされていなかった共有など) は 設定、整合性 の異常カードに表示され、1 日に 1 回再試行されます。その間、そのリポジトリの項目は新しいバックアップから学習します。

ディスク容量の警告が Unraid のダッシュボードと合わない¶

Unraid のユーザー共有 (/mnt/user) では、空き容量は 1 台のディスクではなくアレイ全体のものです。リモートのリポジトリは、空き容量を報告する rclone リモート経由でしか測れません。S3、B2、REST、SFTP のリポジトリには値がなく、異常カードに未計測として表示されます。

AI アシスタントが接続できない¶

MCP サーバーのページに、MCP エンドポイントの各ステータスコードと各拒否の意味、そして対処法がまとめてあります。

コンテナが再起動を繰り返す、または unhealthy に見える¶

BombVault は自身の /api/health から healthy/unhealthy を報告します。auto-heal ツール（Autoheal など）は、エンジンが動かなくなった場合にそれを自動で再起動できます。根本原因については、コンテナログと /spike レポートを確認してください。

それでも解決しない？¶

完全な設定とオフサイトと復旧のページを読んでください。
Unraid サポートスレッドで質問してください。
GitHub issue を開いてください。