Přeskočit obsah

API a integrace

BombVault má malé HTTP API pro skripty, dashboardy a domácí automatizaci. Čte totéž, co ukazuje Přehled, a umí spustit zálohu. Všechno ostatní, jako obnovy, mazání záloh, nastavení a uzly, zůstává ve webovém rozhraní.

Tokeny

Každý požadavek potřebuje token API, i když není nastavené přihlašovací heslo. Vytvoříš ho v Nastavení, Integrace, Tokeny API:

  1. Napiš název, který říká, kde se token používá, třeba „Home Assistant“ nebo „Uptime Kuma“.
  2. Zapni Povolit spouštění záloh, pokud má token spouštět zálohy. Bez toho může jen číst.
  3. Klikni na Vytvořit token. Token se ukáže jen jednou. BombVault si ponechá jen jeho otisk, takže ho zkopíruj hned.

Token posílej v hlavičce, buď Authorization: Bearer <token>, nebo X-API-Key: <token>. Token začíná na bvapi_. Otevírá jen API: klíč MCP tu nefunguje a token nefunguje pro MCP.

Každý token má dlaždici s názvem, informací, zda smí spouštět zálohy, posledními čtyřmi znaky, časem a místem posledního použití a dnešními voláními. Na dlaždici ho můžeš přejmenovat, změnit, co smí, nahradit ho nebo zneplatnit. Protokol ukáže zálohy, které spustil, a jeho poslední volání. Obnova konfigurace BombVault ze zálohy zneplatní všechny tokeny, protože záloha může obsahovat tokeny, které jsi později zneplatnil.

Bez přihlašovacího hesla může token vytvořit každý, kdo otevře webové rozhraní. Když BombVault otevřeš pod jménem, které vypadá veřejně, a heslo není nastavené, z této adresy tokeny vytvořit nejde, stejně jako klíče MCP.

Koncové body

Cesta Co vrací nebo dělá Token
GET /api/v1/health Verze, název instance, zda běží záloha a co tento token smí čtení
GET /api/v1/status Stav ochrany podle sekce: poslední úspěšná záloha, očekávaný interval, kontroly, příští plánované běhy čtení
GET /api/v1/activity Co právě běží, s fází a procenty čtení
GET /api/v1/items Každá chráněná položka s plánem, tím, co záloha zastaví, a poslední zálohou. ?domain= pro jednu sekci čtení
GET /api/v1/runs Historie běhů, nejnovější první. Filtry limit, domain, item, status, kind, since čtení
GET /api/v1/anomalies Anomálie s přehledem otevřených. Filtry state, severity, domain, limit čtení
GET /api/v1/anomalies/{id} Jedna anomálie čtení
GET /api/v1/storage/{domain} Vývoj velikosti, týdenní růst a volné místo každého repozitáře sekce čtení
POST /api/v1/backups Zálohuje jednu položku ({"domain":"containers","item":"plex"}) nebo celou sekci ({"domain":"vms"}) spouštění
POST /api/v1/backups/everything Spustí Zálohu všeho spouštění
POST /api/v1/runs/{id}/cancel Zruší běžící zálohu, kterou spustil tento token spouštění

Sekce jsou containers, vms, files, zfs, flash a config. Časy jsou v unixových sekundách. Odpovědi jsou stejné jako u nástrojů MCP stejného jména, takže obojí zůstává v souladu.

Záloha spuštěná tady je stejná jako ta z webového rozhraní: běžící kontejner se zastaví, dokud jeho záloha neskončí. Požadavek se vrátí hned a /api/v1/activity a /api/v1/runs ukážou, jak to jde.

Příklady

# Jak jsou na tom zálohy?
curl -s -H "Authorization: Bearer $BOMBVAULT_TOKEN" https://tower:3443/api/v1/status

# Zálohovat jeden kontejner hned.
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

S vlastním certifikátem BombVault podepsaným sám sebou přidej --cacert bombvault-cert.pem (soubor z tlačítka Stáhnout certifikát na kartě MCP), nebo v síti, které věříš, -k.

Chyby a limity

Chyba se vrátí jako {"error": {"code": "...", "message": "..."}} s odpovídajícím stavem:

Stav Kódy Význam
400 invalid_argument, ambiguous Argument chybí nebo je špatně
401 no_token, invalid_token Žádný token, nebo ne aktivní
403 not_permitted, forbidden_origin Token smí jen číst, nebo ten běh nespustil, nebo požadavek přišel ze stránky s jiným původem
404 not_found Taková položka, běh nebo anomálie neexistuje
409 busy, domain_off, nothing_to_back_up, not_running Už něco běží, sekce je vypnutá, nebo není co dělat
429 throttled, rate_limited, cooldown, retention_guard Limit požadavek zdrží. Retry-After říká, kdy to zkusit znovu

Spuštění mají stejné limity jako spuštění přes MCP: 12 za hodinu na token, 15 minut mezi dvěma spuštěními téže položky, nejvýše 4 spuštění jedné položky za 24 hodin a ochrana uchovávání. Poslední tři počítají spuštění přes MCP, přes API a z Home Assistant dohromady. Token smí poslat 120 požadavků za minutu. Pět neúspěšných pokusů z jedné adresy ji na minutu zablokuje.

OpenAPI

BombVault poskytuje popis těchto cest na /api/v1/openapi.json (OpenAPI 3.1). Nepotřebuje token. Načti ho do Swagger UI, Postmanu nebo generátoru kódu.

Uzly

Cesty, které se starají o uzly, patří k webovému rozhraní, ne k tokenovému API výše. S nastaveným přihlašovacím heslem vyžadují relaci prohlížeče z přihlášení na této instanci. Token API ani klíč MCP žádnou z nich neotevře, spárované telefony na ně nedosáhnou a /api/v1/openapi.json je nepopisuje. Přidání uzlu, opětovné zobrazení jeho souboru compose a přístup k vlastním cestám uzlu jsou odmítnuty, dokud není nastaveno přihlašovací heslo. Skript, který něco mění, posílá Content-Type: application/json, jako všude ve webovém rozhraní.

Cesta Co dělá
GET /api/nodes Každý uzel s tím, zda je online, jeho verzí, cílem jeho záloh, plánem každé sekce, poslední zálohou, chybami a otevřenými anomáliemi
POST /api/nodes Přidá uzel, například {"name":"vps-helsinki"}, a vrátí ho s compose: MODE, APP_KEY, NODE_HOME a NODE_NAME
POST /api/nodes/{id}/compose Vrátí znovu stejné hodnoty compose, pro Nahradit
POST /api/nodes/{id}/placement Pošle zálohy uzlu na určité místo a pro každou sekci odpoví, zda uzel dosáhl na svůj repozitář, u cíle s warning
PUT /api/nodes/{id}/schedule Nastaví plány, například {"containers":"daily 03:00","files":"off"}. Vynechaná sekce si ponechá svůj plán
DELETE /api/nodes/{id} Uvolní uzel. told říká, zda se to uzel dozvěděl hned, nebo se to dozví, až se vrátí
GET /api/nodes/routes Seznam vlastních cest uzlu, na které domovská instance předává požadavky
GET, POST, PATCH /api/nodes/{id}/api/{path} Předá požadavek na cestu uzlu /api/{path}, když je ta cesta na seznamu, a vrátí odpověď uzlu v JSON
PUT /api/receiver/node-address Nastaví Adresa pro uzly přijímacího serveru, například {"url":"https://backup.tower.example.org","caPem":""}. Prázdné url server pro uzly uzavře

Tři cíle:

{"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"}

Požadavek na /api/nodes/{id}/api/... nese nejvýš 32 KiB. Cesta, která není na seznamu, odpoví 403, uzel, který ještě neodpověděl nebo se uvolňuje, 409 s kódem node-not-adopted a uzel, který je pryč, 502 s kódem node-away. Například GET /api/nodes/{id}/api/runs?limit=20 vrátí posledních 20 běhů uzlu a POST /api/nodes/{id}/api/containers/nextcloud/backup zazálohuje jeho kontejner nextcloud.

Home Assistant

BombVault se může v Home Assistant objevit jako zařízení díky zjišťování MQTT. Home Assistant k tomu potřebuje svou integraci MQTT a broker, třeba doplněk Mosquitto. Žádná vlastní komponenta není potřeba.

  1. V BombVault otevři Nastavení, Integrace a zapni Home Assistant v kartě Služby. Pod ním se objeví pole pro broker.
  2. Zadej adresu a port brokeru, a pokud je vyžaduje, i uživatelské jméno a heslo. Zapni Použít TLS, pokud broker používá TLS, obvykle na portu 8883. Jeho certifikát musí platit pro zadanou adresu. Když změníš adresu, port nebo uživatelské jméno, zadej heslo znovu: BombVault uložené heslo jinému brokeru ani uživateli nepředá.
  3. Klikni na Uložit. Řádek ukáže, až spojení naběhne.

Zařízení se jmenuje BombVault, případně BombVault s názvem instance v závorce, a má tyto entity:

Entita Co ukazuje
Status ok, warning, overdue, failed nebo off, nejhorší ze zapnutých sekcí. Sekce čekající na první zálohu se počítá až po termínu této zálohy a stav ok dává jen sekce s aktuální zálohou. overdue znamená, stejně jako v přehledu, že poslední záloha sekce je starší než dva intervaly
Running job Co právě běží, nebo idle
Open anomalies Kolik anomálií je otevřených
Next scheduled backup Kdy začne další plánovaná záloha
Sekce last backup Kdy proběhla poslední úspěšná záloha sekce
Sekce last result Jak skončila její poslední záloha
Sekce repository free space Volné místo tam, kde leží její hlavní repozitář, pokud ho BombVault umí přečíst
Back up sekce Tlačítko, které zálohuje celou sekci

Názvy entit jsou anglicky, protože Home Assistant je přebírá tak, jak je BombVault posílá. Každá zapnutá sekce dostane vlastní entity a vypnutá o ně přijde. Tlačítka se objeví, jakmile zapneš Tlačítka spouštějí zálohy. Nová instalace to má vypnuté. Mají stejné limity jako spuštění přes API. Navíc BombVault bere pro každou sekci jen jedno stisknutí najednou a nejvýš šest za minutu a stisknutí, které broker uchoval jako retained zprávu, ignoruje. Stisknout je může každý, kdo smí do brokeru publikovat, proto brokeru dej heslo.

BombVault čte svůj stav každých 15 sekund a zveřejní ho, když se něco změnilo, jako JSON pod <předpona>/<uzel>/state. Předpona je bombvault, dokud ji nezměníš, a uzel je krátký identifikátor, který si BombVault jednou zvolí. Zprávy zjišťování jdou pod výchozí předponu Home Assistant homeassistant. Obojí se uchovává (retained). Poslední vůle (last will) označí zařízení jako nedostupné, když se BombVault zastaví bez ohlášení. Vypnutím propojení BombVault zařízení i jeho entity z Home Assistant odstraní.

Příklad: karta a upozornění

Home Assistant vyrábí id entit z jmen, takže zařízení BombVault dostane id jako sensor.bombvault_status. S názvem instance v závorce nesou id i ten, proto je nejdřív zkontroluj v Developer Tools, States. Karta pro dashboard:

type: entities
title: Backups
entities:
  - sensor.bombvault_status
  - sensor.bombvault_running_job
  - sensor.bombvault_open_anomalies
  - sensor.bombvault_next_scheduled_backup

Automatizace, která dá vědět do telefonu, když se stav změní na failed nebo 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

Zpřístupnit /metrics v kartě Služby pod Nastavení, Integrace poskytuje stav záloh, velikosti a časové značky pro Prometheus, Grafanu nebo Uptime Kuma, na /metrics na portu webového rozhraní. Ve výchozím stavu je vypnuto. Scrape token (volitelné) přiměje scraper posílat bearer token. Štítky neobsahují žádná tajemství ani cesty.

Widget pro dashboard

Karta Widget pro dashboard pod Nastavení, Integrace vytvoří token jen pro čtení a dá ti adresu pro libovolný dashboard, který umí zobrazit iframe, například Homepage, Organizr nebo Heimdall. Adresa otevře malou stránku na /widget jen s živým protokolem aktivity. Token dává přístup k tomuto protokolu a ničemu jinému a Zakázat ho okamžitě odvolá. Vložená stránka je jen anglicky.

Najít BombVault v síti

BombVault ohlašuje své webové rozhraní v místní síti přes mDNS, protokol, na kterém stojí Bonjour a Avahi. Prohlížeč ho pak najde jako https://bombvault.local:3443, s HTTP_ONLY jako http://bombvault.local:3000, a prohlížeče služeb ho vypíšou jako webovou službu s podtypem _bombvault. Jeho záznamy TXT nesou verzi a cestu. Přepínač je Najít v síti v kartě Služby v části Nastavení, Integrace a ve výchozím stavu je zapnutý. Pokud název už používá jiné zařízení, BombVault si vezme bombvault-2.local a tak dál a karta ukáže adresu, kterou dostal. Když se BombVault zastaví nebo ohlašování vypneš, dá o tom síti vědět a prohlížeče záznam hned odstraní.

Zda ohlášení doputuje do tvé sítě, záleží na tom, jak je kontejner připojený:

  • bridge, výchozí volba v šabloně Unraid: ohlášení zůstane v síti Dockeru a v místní síti ho nikdo neuvidí. BombVault otevírej jako dosud přes adresu hostitele.
  • br0 nebo jiná síť macvlan či ipvlan: kontejner má vlastní adresu v místní síti a ohlášení se tam dostane.
  • host: ohlášení jde ven přes rozhraní hostitele, vedle ohlášení samotného Unraidu. Mosty Dockeru a libvirtu vynechává.

Ohlašují se jen adresy IPv4.