Gå till innehållet

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:

  1. Skriv ett namn som säger var tokenet används, till exempel "Home Assistant" eller "Uptime Kuma".
  2. Slå på Tillåt att starta säkerhetskopior om tokenet ska kunna starta kopior. Utan det kan det bara läsa.
  3. 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.

  1. Öppna Inställningar, Integrationer i BombVault och slå på Home Assistant på kortet Tjänster. Fälten för brokern visas under.
  2. 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.
  3. 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.