API と連携¶
BombVault には、スクリプト、ダッシュボード、ホームオートメーション向けの小さな HTTP API があります。概要に表示されるものと同じ内容を読み取れ、バックアップを開始できます。復元、バックアップの削除、設定、ノードなど、それ以外はすべて Web 画面にとどまります。
トークン¶
ログインパスワードが設定されていなくても、すべてのリクエストに API トークンが必要です。トークンは 設定、連携、API トークン で作成します。
- トークンをどこで使うかが分かる名前を入力します。たとえば「Home Assistant」や「Uptime Kuma」です。
- トークンにバックアップの開始を許可したい場合は、バックアップの開始を許可をオンにします。オンにしないと、そのトークンは読み取りだけができます。
- トークンを作成をクリックします。トークンは一度だけ表示されます。BombVault はそのフィンガープリントしか保持しないので、今すぐコピーしてください。
トークンはヘッダーで送ります。Authorization: Bearer <token> か X-API-Key: <token> のどちらかです。トークンは bvapi_ で始まります。開けるのは API だけです。MCP キーはここでは使えず、トークンも MCP には使えません。
各トークンにはタイルがあり、名前、バックアップの開始を許可しているか、末尾 4 文字、最後に使われた日時と場所、今日の呼び出し回数が表示されます。タイルでは、名前の変更、できることの変更、トークンの置き換え、取り消しができます。ログには、そのトークンが開始したバックアップと最近の呼び出しが表示されます。バックアップから BombVault の設定を復元すると、すべてのトークンが取り消されます。バックアップには、あとから取り消したトークンが含まれている場合があるからです。
ログインパスワードがないと、Web 画面を開ける人なら誰でもトークンを作成できます。公開されているように見える名前で BombVault を開いていて、パスワードが設定されていない場合、そのアドレスからはトークンを作成できません。これは MCP キーと同じ規則です。
エンドポイント¶
| ルート | 返すもの、または動作 | トークン |
|---|---|---|
GET /api/v1/health |
バージョン、インスタンス名、バックアップが実行中かどうか、このトークンにできること | 読み取り |
GET /api/v1/status |
ドメインごとの保護ステータス:直近の成功したバックアップ、想定される間隔、チェック、次回のスケジュール実行 | 読み取り |
GET /api/v1/activity |
今実行中のもの。フェーズと進捗率つき | 読み取り |
GET /api/v1/items |
保護されているすべての項目と、そのスケジュール、バックアップが停止するもの、直近のバックアップ。?domain= で 1 つのドメインに絞れます |
読み取り |
GET /api/v1/runs |
実行履歴を新しい順に。フィルターは limit、domain、item、status、kind、since |
読み取り |
GET /api/v1/anomalies |
異常と、未処理のものの概要。フィルターは state、severity、domain、limit |
読み取り |
GET /api/v1/anomalies/{id} |
1 件の異常 | 読み取り |
GET /api/v1/storage/{domain} |
ドメインの各リポジトリのサイズ履歴、週あたりの増加、空き容量 | 読み取り |
POST /api/v1/backups |
1 つの項目({"domain":"containers","item":"plex"})またはドメイン全体({"domain":"vms"})をバックアップ |
開始 |
POST /api/v1/backups/everything |
「すべてバックアップ」のパスを実行 | 開始 |
POST /api/v1/runs/{id}/cancel |
このトークンが開始した実行中のバックアップを中止 | 開始 |
ドメインは containers、vms、files、zfs、flash、config です。時刻は UNIX 秒です。応答は、同じ名前の MCP ツールと同じなので、両者は歩調が合っています。
開始されたバックアップは、Web 画面が開始するバックアップと同じものです。実行中のコンテナは、バックアップが終わるまで停止します。リクエストはすぐに返り、進み具合は /api/v1/activity と /api/v1/runs で確認できます。
例¶
# How are the backups doing?
curl -s -H "Authorization: Bearer $BOMBVAULT_TOKEN" https://tower:3443/api/v1/status
# Back up one container now.
curl -s -X POST -H "Authorization: Bearer $BOMBVAULT_TOKEN" \
-H "Content-Type: application/json" -d '{"domain":"containers","item":"plex"}' \
https://tower:3443/api/v1/backups
BombVault 自身の自己署名証明書を使う場合は、--cacert bombvault-cert.pem(MCP カードの証明書をダウンロードで得られるファイル)を付けるか、信頼できるネットワークでは -k を付けます。
エラーと制限¶
エラーは {"error": {"code": "...", "message": "..."}} の形で、対応するステータスとともに返ります。
| ステータス | コード | 意味 |
|---|---|---|
| 400 | invalid_argument、ambiguous |
引数が足りないか、誤っている |
| 401 | no_token、invalid_token |
トークンがない、または有効でない |
| 403 | not_permitted、forbidden_origin |
トークンが読み取り専用、そのトークンが開始した実行ではない、または別のオリジンのページからのリクエスト |
| 404 | not_found |
そのような項目、実行、異常はない |
| 409 | busy、domain_off、nothing_to_back_up、not_running |
ほかのものが実行中、ドメインがオフ、またはやることがない |
| 429 | throttled、rate_limited、cooldown、retention_guard |
制限によりリクエストが止められている。Retry-After で、いつ再試行できるかが分かる |
開始には、MCP 経由の開始と同じ制限があります。トークンごとに 1 時間に 12 回、同じ項目の 2 回の開始のあいだは 15 分、1 つの項目は 24 時間に最大 4 回、そして保持ガードです。後ろの 3 つは、MCP、API、Home Assistant からの開始をまとめて数えます。トークンは 1 分に 120 回のリクエストができます。同じアドレスから 5 回失敗すると、1 分間ロックアウトされます。
OpenAPI¶
BombVault は、これらのルートの記述を /api/v1/openapi.json(OpenAPI 3.1)で提供します。トークンは不要です。Swagger UI、Postman、コードジェネレーターに読み込めます。
ノード¶
ノードを管理するルートは、上のトークン API ではなく Web 画面に属します。ログインパスワードが設定されている場合、このインスタンスでのサインインによるブラウザーのセッションが必要です。API トークンや MCP キーではどれも開けず、ペアリングしたスマートフォンも届かず、/api/v1/openapi.json にも記述されません。ノードの追加、compose ファイルの再表示、ノード自身のルートへの到達は、ログインパスワードが設定されるまで拒否されます。何かを変更するスクリプトは、Web 画面のどこでもそうであるように、Content-Type: application/json を送ります。
| ルート | 内容 |
|---|---|
GET /api/nodes |
すべてのノードと、オンラインかどうか、バージョン、バックアップの送り先、各セクションのプラン、最後のバックアップ、エラー、未処理の異常 |
POST /api/nodes |
{"name":"vps-helsinki"} のようにノードを追加し、compose 付きで返します。中身は MODE、APP_KEY、NODE_HOME、NODE_NAME です |
POST /api/nodes/{id}/compose |
置き換えのために、同じ compose の値をもう一度返します |
POST /api/nodes/{id}/placement |
ノードのバックアップの送り先を決め、ノードがリポジトリに届いたかをセクションごとに答えます。保存先の場合は warning が付きます |
PUT /api/nodes/{id}/schedule |
{"containers":"daily 03:00","files":"off"} のようにプランを設定します。省いたセクションはプランが変わりません |
DELETE /api/nodes/{id} |
ノードを解放します。told は、ノードがすぐに受け取ったか、戻ったときに受け取るかを示します |
GET /api/nodes/routes |
ホームインスタンスが要求を中継する、ノード自身のルートの一覧 |
GET、POST、PATCH /api/nodes/{id}/api/{path} |
そのルートが一覧にあれば、要求をノードのルート /api/{path} に中継し、ノードの JSON の答えを返します |
PUT /api/receiver/node-address |
受信サーバーのノード用のアドレスを設定します。たとえば {"url":"https://backup.tower.example.org","caPem":""} です。url を空にすると、ノードはそこを使わなくなります |
3 つの送り先:
{"kind": "receiver"}
{"kind": "location", "location": "<storage location id>", "signIn": "<sign-in id made for the node>"}
{"kind": "node", "address": "https://203.0.113.7:8443"}
/api/nodes/{id}/api/... への要求は最大 32 KiB です。一覧にないルートは 403 を、まだ応答していないノードや解放中のノードは 409 とコード node-not-adopted を、つながっていないノードは 502 とコード node-away を返します。たとえば GET /api/nodes/{id}/api/runs?limit=20 はノードの直近 20 件の実行を返し、POST /api/nodes/{id}/api/containers/nextcloud/backup はノードのコンテナ nextcloud をバックアップします。
Home Assistant¶
BombVault は、MQTT ディスカバリーを通じて、Home Assistant にデバイスとして現れます。Home Assistant には MQTT 連携とブローカーが必要です。たとえば Mosquitto アドオンです。カスタムコンポーネントは使いません。
- BombVault で 設定、連携 を開き、サービスカードの Home Assistant をオンにします。ブローカー用のフィールドがその下に現れます。
- ブローカーのアドレスとポート、そして必要ならユーザー名とパスワードを入力します。ブローカーが TLS に対応しているなら、TLS を使うをオンにします。通常はポート 8883 です。証明書は、入力したアドレスに対して有効である必要があります。アドレス、ポート、ユーザー名を変更したときは、パスワードをもう一度入力してください。BombVault は、保存済みのパスワードを別のブローカーやユーザーには渡しません。
- 保存をクリックします。接続が確立すると、その行に表示されます。
デバイスの名前は BombVault、またはインスタンス名を括弧に入れた BombVault で、次のエンティティを持ちます。
| エンティティ | 表示するもの |
|---|---|
| Status | ok、warning、overdue、failed、off のどれか。オンになっているドメインのうち最も悪いもの。最初のバックアップを待っているドメインは、そのバックアップの期限が来てから初めて数に入ります。ステータスが ok になるのは、最新の状態のドメインがある場合だけです。overdue は概要と同じく、ドメインの最後のバックアップが間隔の 2 倍より古いことを示します |
| Running job | 今実行中のもの、または idle |
| Open anomalies | 未処理の異常の数 |
| Next scheduled backup | 次のスケジュールされたバックアップが始まる時刻 |
| ドメイン last backup | そのドメインの直近の成功したバックアップが実行された時刻 |
| ドメイン last result | 直近のバックアップの終わり方 |
| ドメイン repository free space | プライマリリポジトリがある場所の空き容量(BombVault が読み取れる場合) |
| Back up ドメイン | ドメイン全体をバックアップするボタン |
オンになっているドメインごとに専用のエンティティができ、オフにしたドメインのエンティティは消えます。ボタンは、ボタンでバックアップを開始をオンにすると現れます。新規インストールではオフです。API 経由の開始と同じ制限に従います。それに加えて、BombVault はドメインごとに一度に 1 回の押下だけを扱い、1 分に 6 回までとし、ブローカーが保持メッセージとして残していた押下は無視します。ブローカーに発行できる人なら誰でもボタンを押せるので、ブローカーにはパスワードを設定してください。
BombVault は 15 秒ごとに状態を読み取り、変化があったときに、<prefix>/<node>/state の下に JSON として発行します。プレフィックスは変更しなければ bombvault、ノードは BombVault が一度だけ選ぶ短い ID です。ディスカバリーメッセージは、Home Assistant の標準プレフィックス homeassistant に送られます。どちらも保持されます。BombVault が何も言わずに停止した場合は、遺言メッセージ(last will)によってデバイスが利用不可になります。連携をオフにすると、デバイスとそのエンティティが Home Assistant から削除されます。
例:カードとアラート¶
Home Assistant は名前からエンティティ ID を作るので、BombVault のデバイスには sensor.bombvault_status のような ID が付きます。インスタンス名が括弧に入っている場合は、ID にもそれが含まれるので、先に Developer Tools, States で確認してください。ダッシュボード用のカードは次のとおりです。
type: entities
title: Backups
entities:
- sensor.bombvault_status
- sensor.bombvault_running_job
- sensor.bombvault_open_anomalies
- sensor.bombvault_next_scheduled_backup
ステータスが failed または overdue に変わったときにスマートフォンへ知らせるオートメーションです。
alias: BombVault needs you
trigger:
- platform: state
entity_id: sensor.bombvault_status
to:
- failed
- overdue
action:
- service: notify.mobile_app_my_phone
data:
message: "BombVault status: {{ trigger.to_state.state }}. Open the overview."
Prometheus¶
設定、連携 のサービスカードにある /metrics を公開は、Prometheus、Grafana、Uptime Kuma 向けに、バックアップの状態、サイズ、タイムスタンプを、Web 画面のポートの /metrics で提供します。標準ではオフです。スクレイプトークン(任意)を設定すると、スクレイパーはベアラートークンを送るようになります。ラベルにはシークレットもパスも含まれません。
ダッシュボードウィジェット¶
設定、連携 のダッシュボードウィジェットカードは、読み取り専用のトークンを生成し、Homepage、Organizr、Heimdall など iframe を表示するダッシュボード向けのアドレスを渡します。アドレスを開くと、/widget に、ライブのアクティビティログだけを表示する小さなページが開きます。トークンが許可するのはそのログだけで、無効化ですぐに取り消せます。埋め込まれるページは英語のみです。
ネットワーク上で BombVault を見つける¶
BombVault は、Bonjour や Avahi の基盤となるプロトコルである mDNS で、Web 画面をローカルネットワーク上に知らせます。ブラウザーからは https://bombvault.local:3443 で、HTTP_ONLY の場合は http://bombvault.local:3000 で届き、サービスブラウザーにはサブタイプ _bombvault の Web サービスとして一覧されます。TXT レコードには、バージョンとパスが入っています。スイッチは 設定、連携 のサービスカードにあるネットワークで見つけるで、標準ではオンです。同じ名前をすでにほかの機器が使っている場合、BombVault は bombvault-2.local のように別の名前を取り、カードには取得したアドレスが表示されます。BombVault が停止したときや、通知をオフにしたときは、ネットワークにそれを伝えるので、ブラウザーは項目をすぐに削除します。
通知があなたのネットワークに届くかどうかは、コンテナの接続方法によります。
- bridge(Unraid テンプレートの標準):通知は Docker のネットワークの中にとどまり、LAN の誰にも見えません。これまでどおり、ホストのアドレスで BombVault を開いてください。
- br0 またはほかの macvlan や ipvlan ネットワーク:コンテナが LAN 上に専用のアドレスを持ち、通知が届きます。
- host:通知は、Unraid 自身のものの隣で、ホストのインターフェースから出ます。Docker と libvirt のブリッジは除かれます。
通知されるのは IPv4 アドレスだけです。