Vai al contenuto

API e integrazioni

BombVault ha una piccola API HTTP per script, dashboard e domotica. Legge le stesse cose che mostra la panoramica e può avviare un backup. Tutto il resto, come i ripristini, l'eliminazione dei backup, le impostazioni e i nodi, resta nell'interfaccia web.

Token

Ogni richiesta ha bisogno di un token API, anche quando non è impostata alcuna password di accesso. Creane uno in Impostazioni, Integrazioni, Token API:

  1. Scrivi un nome che dica dove viene usato il token, per esempio "Home Assistant" o "Uptime Kuma".
  2. Attiva Consenti di avviare backup se il token deve poter avviare backup. Senza, il token può solo leggere.
  3. Clicca Crea token. Il token viene mostrato una volta sola. BombVault ne conserva solo un'impronta, quindi copialo subito.

Invia il token in un header, come Authorization: Bearer <token> oppure come X-API-Key: <token>. Un token inizia con bvapi_. Apre solo l'API: una chiave MCP qui non funziona, e un token non funziona per MCP.

Ogni token ha un riquadro con il suo nome, se può avviare backup, gli ultimi quattro caratteri, quando è stato usato l'ultima volta e da dove, e le sue chiamate di oggi. Sul riquadro puoi rinominarlo, cambiare ciò che può fare, sostituirlo o revocarlo. Registro mostra i backup che ha avviato e le sue chiamate recenti. Ripristinare la configurazione di BombVault da un backup revoca ogni token, perché il backup potrebbe contenere token che hai revocato dopo.

Senza una password di accesso, chiunque riesca ad aprire l'interfaccia web può anche creare un token. Se apri BombVault con un nome che sembra pubblico e non è impostata alcuna password, da quell'indirizzo non si possono creare token, la stessa regola valida per le chiavi MCP.

Endpoint

Route Cosa restituisce o fa Token
GET /api/v1/health Versione, nome dell'istanza, se è in corso un backup e cosa può fare questo token lettura
GET /api/v1/status Stato di protezione per dominio: ultimo backup riuscito, intervallo previsto, controlli, prossime esecuzioni pianificate lettura
GET /api/v1/activity Cosa è in corso in questo momento, con fase e percentuale lettura
GET /api/v1/items Ogni elemento protetto con la sua pianificazione, ciò che un backup ferma e il suo ultimo backup. ?domain= per un solo dominio lettura
GET /api/v1/runs Cronologia delle esecuzioni, la più recente per prima. Filtri limit, domain, item, status, kind, since lettura
GET /api/v1/anomalies Anomalie con un riepilogo di ciò che è aperto. Filtri state, severity, domain, limit lettura
GET /api/v1/anomalies/{id} Un'anomalia lettura
GET /api/v1/storage/{domain} Storico delle dimensioni, crescita a settimana e spazio libero di ogni repository di un dominio lettura
POST /api/v1/backups Salva un elemento ({"domain":"containers","item":"plex"}) o un intero dominio ({"domain":"vms"}) avvio
POST /api/v1/backups/everything Esegue il passaggio Esegui il backup di tutto ora avvio
POST /api/v1/runs/{id}/cancel Annulla un backup in corso avviato da questo token avvio

I domini sono containers, vms, files, zfs, flash e config. Gli orari sono secondi unix. Le risposte sono le stesse degli strumenti MCP con gli stessi nomi, così restano allineate.

Un backup avviato è lo stesso backup che avvia l'interfaccia web: un container in esecuzione viene fermato finché il suo backup non è finito. La richiesta ritorna subito, e /api/v1/activity e /api/v1/runs mostrano come procede.

Esempi

# 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

Con il certificato autofirmato di BombVault aggiungi --cacert bombvault-cert.pem (il file che ti dà Scarica certificato nella scheda MCP) oppure -k su una rete di cui ti fidi.

Errori e limiti

Un errore torna come {"error": {"code": "...", "message": "..."}} con uno stato corrispondente:

Stato Codici Significato
400 invalid_argument, ambiguous Un argomento manca o è sbagliato
401 no_token, invalid_token Nessun token, o non uno attivo
403 not_permitted, forbidden_origin Il token può solo leggere, l'esecuzione non è stata avviata da lui, oppure la richiesta arriva da una pagina di un'altra origine
404 not_found Nessun elemento, esecuzione o anomalia di questo tipo
409 busy, domain_off, nothing_to_back_up, not_running Sta già girando altro, il dominio è disattivato oppure non c'è nulla da fare
429 throttled, rate_limited, cooldown, retention_guard Un limite trattiene la richiesta. Retry-After dice quando riprovare

Gli avvii seguono gli stessi limiti degli avvii tramite MCP: 12 all'ora per token, 15 minuti tra due avvii dello stesso elemento, al massimo 4 avvii di un elemento in 24 ore e la protezione della conservazione. Gli ultimi tre contano insieme gli avvii tramite MCP, API e Home Assistant. Un token può fare 120 richieste al minuto. Cinque tentativi falliti dallo stesso indirizzo lo bloccano per un minuto.

OpenAPI

BombVault pubblica una descrizione di queste route in /api/v1/openapi.json (OpenAPI 3.1). Non richiede alcun token. Caricala in Swagger UI, in Postman o in un generatore di codice.

Nodi

I percorsi che gestiscono i nodi fanno parte dell'interfaccia web, non dell'API a token descritta sopra. Con una password di accesso impostata richiedono una sessione del browser nata da un accesso su questa istanza. Un token API o una chiave MCP non ne apre nessuno, i telefoni associati non li raggiungono e /api/v1/openapi.json non li descrive. Aggiungere un nodo, mostrare di nuovo il suo file compose e raggiungere i percorsi di un nodo vengono rifiutati finché non è impostata una password di accesso. Uno script che cambia qualcosa invia Content-Type: application/json, come ovunque nell'interfaccia web.

Route Cosa fa
GET /api/nodes Ogni nodo con l'indicazione se è online, la sua versione, dove vanno i suoi backup, il piano di ogni sezione, l'ultimo backup, gli errori e le anomalie aperte
POST /api/nodes Aggiunge un nodo, per esempio {"name":"vps-helsinki"}, e lo restituisce con compose: MODE, APP_KEY, NODE_HOME e NODE_NAME
POST /api/nodes/{id}/compose Restituisce di nuovo gli stessi valori di compose, per Sostituisci
POST /api/nodes/{id}/placement Manda i backup del nodo in una destinazione e risponde per sezione se il nodo ha raggiunto il suo repository, con un warning nel caso di una destinazione
PUT /api/nodes/{id}/schedule Imposta i piani, per esempio {"containers":"daily 03:00","files":"off"}. Una sezione omessa mantiene il suo piano
DELETE /api/nodes/{id} Rilascia il nodo. told dice se il nodo lo ha saputo subito o lo saprà al suo ritorno
GET /api/nodes/routes L'elenco dei percorsi del nodo a cui l'istanza madre inoltra le richieste
GET, POST, PATCH /api/nodes/{id}/api/{path} Inoltra la richiesta al percorso /api/{path} del nodo quando quel percorso è nell'elenco, e restituisce la risposta JSON del nodo
PUT /api/receiver/node-address Imposta l'Indirizzo per i nodi del server ricevente, per esempio {"url":"https://backup.tower.example.org","caPem":""}. Una url vuota toglie i nodi dal server

Le tre destinazioni:

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

Una richiesta a /api/nodes/{id}/api/... porta al massimo 32 KiB. Un percorso che non è nell'elenco risponde 403, un nodo che non ha ancora risposto o che è in fase di rilascio 409 con il codice node-not-adopted, e un nodo assente 502 con il codice node-away. Per esempio, GET /api/nodes/{id}/api/runs?limit=20 restituisce le ultime 20 esecuzioni del nodo, e POST /api/nodes/{id}/api/containers/nextcloud/backup fa il backup del suo container nextcloud.

Home Assistant

BombVault può comparire in Home Assistant come dispositivo, tramite MQTT discovery. Home Assistant ha bisogno della sua integrazione MQTT e di un broker, per esempio l'add-on Mosquitto. Non è coinvolto alcun componente personalizzato.

  1. In BombVault apri Impostazioni, Integrazioni e attiva Home Assistant nella scheda Servizi. Sotto compaiono i campi per il broker.
  2. Inserisci l'indirizzo e la porta del broker, e il nome utente e la password se li richiede. Attiva Usa TLS se il broker accetta TLS, di solito sulla porta 8883. Il suo certificato deve essere valido per l'indirizzo che hai inserito. Se cambi l'indirizzo, la porta o il nome utente, inserisci di nuovo la password: BombVault non passa quella salvata a un altro broker o utente.
  3. Clicca Salva. La riga mostra quando la connessione è attiva.

Il dispositivo si chiama BombVault, oppure BombVault con il nome dell'istanza tra parentesi, e ha queste entità:

Entità Cosa mostra
Status ok, warning, overdue, failed oppure off, il peggiore tra i domini attivati. Un dominio in attesa del primo backup conta solo quando quel backup era previsto, e solo un dominio aggiornato rende lo stato ok. overdue significa, come nella panoramica, che l'ultimo backup di un dominio è più vecchio di due intervalli
Running job Cosa gira ora, oppure idle
Open anomalies Quante anomalie sono aperte
Next scheduled backup Quando parte il prossimo backup pianificato
Domain last backup Quando è stato eseguito l'ultimo backup riuscito del dominio
Domain last result Come si è concluso il suo ultimo backup
Domain repository free space Lo spazio libero dove si trova il suo repository primario, se BombVault riesce a leggerlo
Back up domain Un pulsante che salva l'intero dominio

Ogni dominio attivato ottiene entità proprie, e un dominio che disattivi le perde. I pulsanti compaiono quando attivi I pulsanti avviano backup. In una nuova installazione è disattivato. Seguono gli stessi limiti degli avvii tramite l'API. In più BombVault gestisce una pressione per dominio alla volta e non più di sei al minuto, e ignora una pressione che il broker ha conservato come messaggio retained. Chiunque possa pubblicare sul broker può premerli, quindi proteggi il broker con una password.

BombVault legge il proprio stato ogni 15 secondi e lo pubblica quando qualcosa è cambiato, come JSON sotto <prefix>/<node>/state. Il prefisso è bombvault finché non lo cambi, e il nodo è un breve id che BombVault sceglie una volta. I messaggi di discovery vanno al prefisso predefinito di Home Assistant, homeassistant. Entrambi sono retained. Un last will segna il dispositivo come non disponibile se BombVault si ferma senza avvisare. Disattivare il collegamento rimuove da Home Assistant il dispositivo e le sue entità.

Esempio: una scheda e un avviso

Home Assistant ricava gli id delle entità dai nomi, quindi il dispositivo BombVault ottiene id come sensor.bombvault_status. Con un nome di istanza tra parentesi anche gli id lo contengono, perciò controllali prima in Developer Tools, States. Una scheda per la dashboard:

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

Un'automazione che avvisa il telefono quando lo stato diventa failed oppure 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

Esponi /metrics nella scheda Servizi in Impostazioni, Integrazioni pubblica stato dei backup, dimensioni e timestamp per Prometheus, Grafana o Uptime Kuma, in /metrics sulla porta dell'interfaccia web. È disattivato di default. Token di scrape (facoltativo) fa inviare allo scraper un bearer token. Le label non contengono segreti né percorsi.

Widget per dashboard

La scheda Widget per dashboard in Impostazioni, Integrazioni genera un token di sola lettura e ti dà un indirizzo per qualsiasi dashboard che mostri un iframe, come Homepage, Organizr o Heimdall. L'indirizzo apre una piccola pagina in /widget con solo il registro attività in tempo reale. Il token concede quel registro e nient'altro, e Disattiva lo revoca subito. La pagina incorporata è solo in inglese.

Trovare BombVault in rete

BombVault annuncia la sua interfaccia web sulla rete locale tramite mDNS, il protocollo dietro Bonjour e Avahi. Un browser lo raggiunge allora come https://bombvault.local:3443, oppure http://bombvault.local:3000 con HTTP_ONLY, e i browser di servizi lo elencano come servizio web con il sottotipo _bombvault. I suoi record TXT portano la versione e il percorso. L'interruttore è Trova in rete nella scheda Servizi in Impostazioni, Integrazioni ed è attivo di default. Se un altro dispositivo usa già il nome, BombVault prende bombvault-2.local e così via, e la scheda mostra l'indirizzo ottenuto. Quando BombVault si ferma o disattivi l'annuncio, lo comunica alla rete, così i browser tolgono subito la voce.

Se l'annuncio raggiunge la tua rete dipende da come è collegato il container:

  • bridge, il valore predefinito nel template Unraid: l'annuncio resta dentro la rete di Docker e nessuno nella LAN lo vede. Apri BombVault con l'indirizzo dell'host come prima.
  • br0 o un'altra rete macvlan o ipvlan: il container ha un proprio indirizzo nella LAN e l'annuncio lo raggiunge.
  • host: l'annuncio esce dalle interfacce dell'host, accanto a quello di Unraid. Salta i bridge di Docker e libvirt.

Vengono annunciati solo indirizzi IPv4.