API och integrationer¶
BombVault har ett litet HTTP-API för skript, instrumentpaneler och hemautomation. Det läser samma saker som översikten visar och kan starta en säkerhetskopia. Allt annat, som återställningar, borttagning av kopior, inställningar och noder, stannar i webbgränssnittet.
Token¶
Varje förfrågan behöver ett API-token, även när inget inloggningslösenord är satt. Skapa ett under Inställningar, Integrationer, API-token:
- Skriv ett namn som säger var tokenet används, till exempel "Home Assistant" eller "Uptime Kuma".
- Slå på Tillåt att starta säkerhetskopior om tokenet ska kunna starta kopior. Utan det kan det bara läsa.
- Klicka på Skapa token. Tokenet visas en gång. BombVault sparar bara ett fingeravtryck av det, så kopiera det nu.
Skicka tokenet i ett huvud, antingen Authorization: Bearer <token> eller X-API-Key: <token>. Ett token börjar med bvapi_. Det öppnar bara API:t: en MCP-nyckel fungerar inte här, och ett token fungerar inte för MCP.
Varje token har en ruta med namnet, om det får starta kopior, de fyra sista tecknen, när och varifrån det senast användes och dagens anrop. I rutan kan du byta namn på det, ändra vad det får göra, byta ut det eller återkalla det. Logg visar kopiorna det startade och de senaste anropen. Återställer du BombVaults konfiguration från en kopia återkallas alla token, eftersom kopian kan innehålla token som du har återkallat sedan dess.
Utan inloggningslösenord kan alla som kan öppna webbgränssnittet också skapa ett token. Öppnar du BombVault under ett namn som ser offentligt ut och inget lösenord är satt, går det inte att skapa token från den adressen, samma regel som för MCP-nycklarna.
Slutpunkter¶
| Rutt | Vad den returnerar eller gör | Token |
|---|---|---|
GET /api/v1/health |
Version, instansnamn, om en kopia körs och vad det här tokenet får göra | läsa |
GET /api/v1/status |
Skyddsstatus per avsnitt: senaste lyckade kopia, förväntat intervall, kontroller, nästa schemalagda körningar | läsa |
GET /api/v1/activity |
Vad som körs just nu, med fas och procent | läsa |
GET /api/v1/items |
Varje skyddad post med schema, vad en kopia stoppar och senaste kopia. ?domain= för ett avsnitt |
läsa |
GET /api/v1/runs |
Körhistorik, nyast först. Filter limit, domain, item, status, kind, since |
läsa |
GET /api/v1/anomalies |
Avvikelser med en sammanfattning av de öppna. Filter state, severity, domain, limit |
läsa |
GET /api/v1/anomalies/{id} |
En avvikelse | läsa |
GET /api/v1/storage/{domain} |
Storlekshistorik, tillväxt per vecka och ledigt utrymme för varje repository i ett avsnitt | läsa |
POST /api/v1/backups |
Säkerhetskopierar en post ({"domain":"containers","item":"plex"}) eller ett helt avsnitt ({"domain":"vms"}) |
starta |
POST /api/v1/backups/everything |
Kör Total säkerhetskopia | starta |
POST /api/v1/runs/{id}/cancel |
Avbryter en pågående kopia som det här tokenet startade | starta |
Avsnitten heter containers, vms, files, zfs, flash och config. Tider är Unix-sekunder. Svaren är desamma som från MCP-verktygen med samma namn, så de två hänger ihop.
En kopia som startas här är samma kopia som webbgränssnittet startar: en körande container stoppas tills kopian är klar. Förfrågan svarar direkt, och /api/v1/activity och /api/v1/runs visar hur det går.
Exempel¶
# Hur går det för säkerhetskopiorna?
curl -s -H "Authorization: Bearer $BOMBVAULT_TOKEN" https://tower:3443/api/v1/status
# Säkerhetskopiera en container nu.
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
Med BombVaults eget självsignerade certifikat lägger du till --cacert bombvault-cert.pem (filen från Ladda ner certifikat på MCP-kortet) eller -k på ett nätverk du litar på.
Fel och gränser¶
Ett fel kommer tillbaka som {"error": {"code": "...", "message": "..."}} med motsvarande status:
| Status | Koder | Betydelse |
|---|---|---|
| 400 | invalid_argument, ambiguous |
Ett argument saknas eller är fel |
| 401 | no_token, invalid_token |
Inget token, eller inget aktivt |
| 403 | not_permitted, forbidden_origin |
Tokenet får bara läsa, eller det startade inte körningen, eller så kom begäran från en sida med ett annat ursprung |
| 404 | not_found |
Ingen sådan post, körning eller avvikelse |
| 409 | busy, domain_off, nothing_to_back_up, not_running |
Något annat körs, avsnittet är avstängt eller det finns inget att göra |
| 429 | throttled, rate_limited, cooldown, retention_guard |
En gräns håller tillbaka förfrågan. Retry-After säger när du kan försöka igen |
Starter följer samma gränser som starter via MCP: 12 i timmen per token, 15 minuter mellan två starter av samma post, högst 4 starter av en post på 24 timmar och lagringsskyddet. De tre sista räknar starter via MCP, via API:t och från Home Assistant tillsammans. Ett token får göra 120 förfrågningar i minuten. Fem misslyckade försök från en adress spärrar den i en minut.
OpenAPI¶
BombVault levererar en beskrivning av de här rutterna på /api/v1/openapi.json (OpenAPI 3.1). Den kräver inget token. Läs in den i Swagger UI, Postman eller en kodgenerator.
Noder¶
Rutterna som sköter noder hör till webbgränssnittet, inte till token-API:et ovan. Med ett inloggningslösenord satt kräver de en webbläsarsession från en inloggning på den här instansen. En API-token eller en MCP-nyckel öppnar ingen av dem, parkopplade telefoner når dem inte, och /api/v1/openapi.json beskriver dem inte. Att lägga till en nod, visa dess compose-fil igen och nå en nods egna rutter nekas tills ett inloggningslösenord är satt. Ett skript som ändrar något skickar Content-Type: application/json, som överallt i webbgränssnittet.
| Rutt | Vad den gör |
|---|---|
GET /api/nodes |
Varje nod med om den är online, dess version, vart dess säkerhetskopior går, schemat för varje avsnitt, dess senaste säkerhetskopia, dess fel och dess öppna avvikelser |
POST /api/nodes |
Lägger till en nod, som {"name":"vps-helsinki"}, och returnerar den med compose: MODE, APP_KEY, NODE_HOME och NODE_NAME |
POST /api/nodes/{id}/compose |
Returnerar samma compose-värden igen, för Ersätt |
POST /api/nodes/{id}/placement |
Skickar nodens säkerhetskopior till ett mål och svarar per avsnitt om noden nådde sitt repositorium, med en warning för ett lagringsmål |
PUT /api/nodes/{id}/schedule |
Ställer in scheman, som {"containers":"daily 03:00","files":"off"}. Ett avsnitt som utelämnas behåller sitt schema |
DELETE /api/nodes/{id} |
Släpper noden. told säger om den fick veta det nu eller får veta det när den är tillbaka |
GET /api/nodes/routes |
Listan över nodens egna rutter som hemmainstansen skickar vidare begäranden till |
GET, POST, PATCH /api/nodes/{id}/api/{path} |
Skickar vidare begäran till nodens rutt /api/{path} när den rutten finns på listan, och returnerar nodens JSON-svar |
PUT /api/receiver/node-address |
Ställer in mottagarserverns Adress för noder, som {"url":"https://backup.tower.example.org","caPem":""}. En tom url tar bort noderna från den |
De tre målen:
{"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"}
En begäran till /api/nodes/{id}/api/... bär högst 32 KiB. En rutt som inte finns på listan svarar 403, en nod som inte har svarat än eller som håller på att släppas 409 med koden node-not-adopted, och en nod som är borta 502 med koden node-away. Till exempel returnerar GET /api/nodes/{id}/api/runs?limit=20 nodens 20 senaste körningar, och POST /api/nodes/{id}/api/containers/nextcloud/backup säkerhetskopierar dess container nextcloud.
Home Assistant¶
BombVault kan dyka upp i Home Assistant som en enhet via MQTT-discovery. Home Assistant behöver sin MQTT-integration och en broker, till exempel tillägget Mosquitto. Ingen egen komponent behövs.
- Öppna Inställningar, Integrationer i BombVault och slå på Home Assistant på kortet Tjänster. Fälten för brokern visas under.
- Ange brokerns adress och port, och användarnamn och lösenord om den kräver det. Slå på Använd TLS om brokern använder TLS, oftast på port 8883. Dess certifikat måste gälla för adressen du angav. Om du ändrar adressen, porten eller användarnamnet måste du ange lösenordet igen: BombVault skickar inte det sparade vidare till en annan broker eller användare.
- Klicka på Spara. Raden visar när anslutningen är uppe.
Enheten heter BombVault, eller BombVault med instansnamnet inom parentes, och har de här entiteterna:
| Entitet | Vad den visar |
|---|---|
| Status | ok, warning, overdue, failed eller off, det sämsta av de påslagna avsnitten. Ett avsnitt som väntar på sin första säkerhetskopia räknas först när den skulle ha körts, och bara ett aktuellt avsnitt ger statusen ok. overdue betyder, som i översikten, att ett avsnitts senaste säkerhetskopia är äldre än två intervall |
| Running job | Vad som körs nu, eller idle |
| Open anomalies | Hur många avvikelser som är öppna |
| Next scheduled backup | När nästa schemalagda kopia startar |
| Avsnitt last backup | När avsnittets senaste lyckade kopia kördes |
| Avsnitt last result | Hur dess senaste kopia slutade |
| Avsnitt repository free space | Ledigt utrymme där dess primära repository ligger, om BombVault kan läsa det |
| Back up avsnitt | En knapp som säkerhetskopierar hela avsnittet |
Entiteternas namn är på engelska, eftersom Home Assistant tar dem som BombVault skickar dem. Varje påslaget avsnitt får egna entiteter, och ett avsnitt du stänger av förlorar dem. Knapparna dyker upp när du slår på Knappar startar säkerhetskopior, Den är avslagen i en ny installation. De följer samma gränser som starter via API:t. Dessutom tar BombVault emot ett tryck i taget per avsnitt och högst sex per minut, och bortser från ett tryck som brokern har sparat som retained-meddelande. Alla som får publicera på brokern kan trycka på dem, så ge brokern ett lösenord.
BombVault läser sin status var 15:e sekund och publicerar den när något har ändrats, som JSON under <prefix>/<nod>/state. Prefixet är bombvault så länge du inte ändrar det, och noden är ett kort id som BombVault väljer en gång. Discovery-meddelandena går till Home Assistants standardprefix homeassistant. Båda behålls (retained). En last will markerar enheten som otillgänglig om BombVault stannar utan att säga till. Stänger du av kopplingen tar BombVault bort enheten och dess entiteter från Home Assistant.
Exempel: ett kort och en avisering¶
Home Assistant gör entitets-id:n av namnen, så enheten BombVault får id:n som sensor.bombvault_status. Med ett instansnamn inom parentes bär id:n även det, så kontrollera dem först under Developer Tools, States. Ett kort för instrumentpanelen:
type: entities
title: Backups
entities:
- sensor.bombvault_status
- sensor.bombvault_running_job
- sensor.bombvault_open_anomalies
- sensor.bombvault_next_scheduled_backup
En automation som talar om för din telefon när statusen blir failed eller 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¶
Exponera /metrics på kortet Tjänster under Inställningar, Integrationer serverar säkerhetskopieringsstatus, storlekar och tidsstämplar för Prometheus, Grafana eller Uptime Kuma, på /metrics på webbgränssnittets port. Det är avstängt som standard. Scrape-token (valfritt) får skrapan att skicka en bearer-token. Etiketterna innehåller inga hemligheter och inga sökvägar.
Dashboard-widget¶
Kortet Dashboard-widget under Inställningar, Integrationer genererar en skrivskyddad token och ger dig en adress för vilken instrumentpanel som helst som visar en iframe, till exempel Homepage, Organizr eller Heimdall. Adressen öppnar en liten sida på /widget med bara den levande aktivitetsloggen. Token ger den loggen och inget annat, och Inaktivera återkallar den direkt. Den inbäddade sidan finns bara på engelska.
Hitta BombVault i nätverket¶
BombVault annonserar sitt webbgränssnitt i det lokala nätverket via mDNS, protokollet bakom Bonjour och Avahi. En webbläsare når det då som https://bombvault.local:3443, eller http://bombvault.local:3000 med HTTP_ONLY, och tjänstebläddrare listar det som webbtjänst med undertypen _bombvault. TXT-posterna innehåller versionen och sökvägen. Reglaget är Hitta i nätverket på kortet Tjänster under Inställningar, Integrationer och är på från början. Om en annan enhet redan använder namnet tar BombVault bombvault-2.local och så vidare, och kortet visar adressen det fick. När BombVault stannar eller du stänger av annonseringen säger det till nätverket, så att webbläsare tar bort posten direkt.
Om annonseringen når ditt nätverk beror på hur containern är ansluten:
- bridge, standard i Unraid-mallen: annonseringen stannar i Dockers nätverk och ingen på LAN:et ser den. Öppna BombVault på värdens adress som tidigare.
- br0 eller ett annat macvlan- eller ipvlan-nätverk: containern har en egen adress på LAN:et och annonseringen når dit.
- host: annonseringen går ut över värdens gränssnitt, bredvid Unraids egen. Docker- och libvirt-bryggorna hoppas över.
Bara IPv4-adresser annonseras.