Sari la conținut

API și integrări

BombVault are un mic API HTTP pentru scripturi, panouri și automatizarea casei. Citește aceleași lucruri pe care le arată prezentarea și poate porni o copie. Tot restul, cum ar fi restaurările, ștergerea copiilor, setările și nodurile, rămâne în interfața web.

Tokenuri

Fiecare cerere are nevoie de un token API, chiar și fără parolă de conectare. Creează unul în Setări, Integrări, Tokenuri API:

  1. Scrie un nume care spune unde se folosește tokenul, de exemplu „Home Assistant” sau „Uptime Kuma”.
  2. Pornește Permite pornirea copiilor dacă tokenul trebuie să poată porni copii. Fără asta poate doar să citească.
  3. Apasă Creează tokenul. Tokenul apare o singură dată. BombVault păstrează doar o amprentă a lui, așa că copiază-l acum.

Trimite tokenul într-un antet, fie Authorization: Bearer <token>, fie X-API-Key: <token>. Un token începe cu bvapi_. Deschide doar API-ul: o cheie MCP nu funcționează aici, iar un token nu funcționează pentru MCP.

Fiecare token are o casetă cu numele, dacă poate porni copii, ultimele patru caractere, când și de unde a fost folosit ultima dată și apelurile de azi. Din casetă îl poți redenumi, îi poți schimba drepturile, îl poți înlocui sau revoca. Jurnal arată copiile pe care le-a pornit și ultimele apeluri. Restaurarea configurației BombVault dintr-o copie revocă toate tokenurile, pentru că acea copie poate conține tokenuri revocate între timp.

Fără parolă de conectare, oricine poate deschide interfața web poate crea și un token. Dacă deschizi BombVault sub un nume care pare public și nu e setată nicio parolă, de la acea adresă nu se pot crea tokenuri, la fel ca la cheile MCP.

Puncte de acces

Rută Ce returnează sau face Token
GET /api/v1/health Versiunea, numele instanței, dacă rulează o copie și ce poate face acest token citire
GET /api/v1/status Starea protecției pe secțiuni: ultima copie reușită, intervalul așteptat, verificările, următoarele rulări planificate citire
GET /api/v1/activity Ce rulează acum, cu fază și procent citire
GET /api/v1/items Fiecare element protejat cu programul, ce oprește o copie și ultima copie. ?domain= pentru o secțiune citire
GET /api/v1/runs Istoricul rulărilor, cele mai noi primele. Filtre limit, domain, item, status, kind, since citire
GET /api/v1/anomalies Anomalii cu un rezumat al celor deschise. Filtre state, severity, domain, limit citire
GET /api/v1/anomalies/{id} O anomalie citire
GET /api/v1/storage/{domain} Istoricul mărimii, creșterea pe săptămână și spațiul liber al fiecărui depozit dintr-o secțiune citire
POST /api/v1/backups Copiază un element ({"domain":"containers","item":"plex"}) sau o secțiune întreagă ({"domain":"vms"}) pornire
POST /api/v1/backups/everything Rulează Backupul total pornire
POST /api/v1/runs/{id}/cancel Anulează o copie în curs pornită de acest token pornire

Secțiunile sunt containers, vms, files, zfs, flash și config. Timpii sunt secunde Unix. Răspunsurile sunt aceleași ca la instrumentele MCP cu același nume, așa că cele două rămân la fel.

O copie pornită aici este aceeași pe care o pornește interfața web: un container care rulează e oprit până se termină copia lui. Cererea se întoarce imediat, iar /api/v1/activity și /api/v1/runs arată cum merge.

Exemple

# Cum stau copiile?
curl -s -H "Authorization: Bearer $BOMBVAULT_TOKEN" https://tower:3443/api/v1/status

# Copiază un container acum.
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

Cu certificatul autosemnat propriu al BombVault, adaugă --cacert bombvault-cert.pem (fișierul primit prin Descarcă certificatul pe cardul MCP) sau -k într-o rețea de încredere.

Erori și limite

O eroare se întoarce ca {"error": {"code": "...", "message": "..."}}, cu starea potrivită:

Stare Coduri Înțeles
400 invalid_argument, ambiguous Un argument lipsește sau e greșit
401 no_token, invalid_token Niciun token, sau nu unul activ
403 not_permitted, forbidden_origin Tokenul poate doar citi, sau nu el a pornit rularea, sau cererea a venit de pe o pagină cu altă origine
404 not_found Nu există acel element, acea rulare sau anomalie
409 busy, domain_off, nothing_to_back_up, not_running Rulează deja altceva, secțiunea e oprită sau nu e nimic de făcut
429 throttled, rate_limited, cooldown, retention_guard O limită reține cererea. Retry-After spune când poți încerca din nou

Pornirile respectă aceleași limite ca pornirile prin MCP: 12 pe oră per token, 15 minute între două porniri ale aceluiași element, cel mult 4 porniri ale unui element în 24 de ore și protecția de retenție. Ultimele trei numără împreună pornirile prin MCP, prin API și din Home Assistant. Un token poate face 120 de cereri pe minut. Cinci încercări eșuate de la o adresă o blochează un minut.

OpenAPI

BombVault servește o descriere a acestor rute la /api/v1/openapi.json (OpenAPI 3.1). Nu cere token. Încarc-o în Swagger UI, Postman sau un generator de cod.

Noduri

Rutele care se ocupă de noduri țin de interfața web, nu de API-ul cu tokenuri de mai sus. Cu o parolă de conectare setată, cer o sesiune de browser obținută printr-o autentificare pe această instanță. Un token API sau o cheie MCP nu deschide niciuna dintre ele, telefoanele împerecheate nu ajung la ele, iar /api/v1/openapi.json nu le descrie. Adăugarea unui nod, afișarea din nou a fișierului lui compose și accesul la rutele proprii ale unui nod sunt refuzate până când se setează o parolă de conectare. Un script care schimbă ceva trimite Content-Type: application/json, ca peste tot în interfața web.

Rută Ce face
GET /api/nodes Fiecare nod, cu starea online, versiunea, unde merg copiile lui, planul fiecărei secțiuni, ultima copie, erorile și anomaliile deschise
POST /api/nodes Adaugă un nod, de exemplu {"name":"vps-helsinki"}, și îl returnează cu compose: MODE, APP_KEY, NODE_HOME și NODE_NAME
POST /api/nodes/{id}/compose Returnează din nou aceleași valori compose, pentru Înlocuiește
POST /api/nodes/{id}/placement Trimite copiile nodului într-un loc și răspunde pe secțiune dacă nodul a ajuns la depozitul lui, cu un warning pentru o destinație
PUT /api/nodes/{id}/schedule Setează planurile, de exemplu {"containers":"daily 03:00","files":"off"}. O secțiune omisă își păstrează planul
DELETE /api/nodes/{id} Eliberează nodul. told spune dacă nodul a aflat acum sau află când revine
GET /api/nodes/routes Lista rutelor proprii ale nodului spre care instanța-mamă transmite cereri
GET, POST, PATCH /api/nodes/{id}/api/{path} Transmite cererea către ruta nodului /api/{path} când acea rută este pe listă și returnează răspunsul JSON al nodului
PUT /api/receiver/node-address Setează Adresă pentru noduri a serverului receptor, de exemplu {"url":"https://backup.tower.example.org","caPem":""}. Un url gol închide serverul pentru noduri

Cele trei destinații:

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

O cerere către /api/nodes/{id}/api/... poartă cel mult 32 KiB. O rută care nu e pe listă răspunde 403, un nod care nu a răspuns încă sau care este eliberat 409 cu codul node-not-adopted, iar un nod care lipsește 502 cu codul node-away. De exemplu, GET /api/nodes/{id}/api/runs?limit=20 returnează ultimele 20 de rulări ale nodului, iar POST /api/nodes/{id}/api/containers/nextcloud/backup face o copie a containerului lui nextcloud.

Home Assistant

BombVault poate apărea în Home Assistant ca dispozitiv, prin descoperirea MQTT. Home Assistant are nevoie de integrarea sa MQTT și de un broker, de exemplu add-on-ul Mosquitto. Nu e nevoie de nicio componentă proprie.

  1. În BombVault, deschide Setări, Integrări și pornește Home Assistant în cardul Servicii. Câmpurile pentru broker apar dedesubt.
  2. Introdu adresa și portul brokerului, iar utilizatorul și parola dacă le cere. Pornește Folosește TLS dacă brokerul folosește TLS, de obicei pe portul 8883. Certificatul lui trebuie să fie valid pentru adresa introdusă. Dacă schimbi adresa, portul sau numele de utilizator, introdu din nou parola: BombVault nu dă parola salvată mai departe unui alt broker sau utilizator.
  3. Apasă Salvare. Rândul arată când conexiunea e activă.

Dispozitivul se numește BombVault, sau BombVault cu numele instanței între paranteze, și are aceste entități:

Entitate Ce arată
Status ok, warning, overdue, failed sau off, cel mai rău dintre secțiunile pornite. O secțiune care așteaptă prima copie contează abia după ce a venit termenul acelei copii, și doar o secțiune cu o copie curentă face ca statusul să fie ok. overdue înseamnă, ca în prezentarea generală, că ultima copie a unei secțiuni e mai veche de două intervale
Running job Ce rulează acum, sau idle
Open anomalies Câte anomalii sunt deschise
Next scheduled backup Când începe următoarea copie planificată
Secțiune last backup Când a rulat ultima copie reușită a secțiunii
Secțiune last result Cum s-a încheiat ultima sa copie
Secțiune repository free space Spațiul liber acolo unde se află depozitul său principal, dacă BombVault îl poate citi
Back up secțiune Un buton care copiază toată secțiunea

Numele entităților sunt în engleză, pentru că Home Assistant le preia așa cum le trimite BombVault. Fiecare secțiune pornită primește entități proprii, iar una pe care o oprești le pierde. Butoanele apar după ce pornești Butoanele pornesc copii, iar la o instalare nouă este oprit. Respectă aceleași limite ca pornirile prin API. În plus, BombVault primește o singură apăsare odată pentru fiecare secțiune și cel mult șase pe minut, și ignoră o apăsare pe care brokerul a păstrat-o ca mesaj retained. Oricine poate publica pe broker le poate apăsa, așa că pune o parolă brokerului.

BombVault își citește starea la fiecare 15 secunde și o publică atunci când s-a schimbat ceva, ca JSON sub <prefix>/<nod>/state. Prefixul este bombvault cât timp nu îl schimbi, iar nodul este un identificator scurt pe care BombVault îl alege o dată. Mesajele de descoperire merg la prefixul implicit al Home Assistant, homeassistant. Ambele sunt păstrate (retained). Un ultim mesaj (last will) marchează dispozitivul ca indisponibil dacă BombVault se oprește fără să anunțe. Dacă oprești legătura, BombVault scoate dispozitivul și entitățile lui din Home Assistant.

Exemplu: un card și o alertă

Home Assistant creează id-urile entităților din nume, așa că dispozitivul BombVault primește id-uri precum sensor.bombvault_status. Dacă numele instanței apare între paranteze, id-urile îl conțin și pe el, așa că verifică-le mai întâi la Developer Tools, States. Un card pentru dashboard:

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

O automatizare care îți anunță telefonul când starea devine failed sau 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

Expune /metrics din cardul Servicii, la Setări, Integrări, oferă starea copiilor, dimensiunile și orele pentru Prometheus, Grafana sau Uptime Kuma, la /metrics pe portul interfeței web. Este oprit implicit. Token de scrape (opțional) face ca instrumentul de colectare să trimită un token bearer. Etichetele nu conțin secrete și nicio cale.

Widget pentru dashboard

Cardul Widget pentru dashboard de la Setări, Integrări generează un token doar pentru citire și îți dă o adresă pentru orice dashboard care afișează un iframe, precum Homepage, Organizr sau Heimdall. Adresa deschide o pagină mică la /widget, doar cu jurnalul de activitate în direct. Tokenul permite acest jurnal și nimic altceva, iar Dezactivează îl revocă pe loc. Pagina încorporată este doar în engleză.

Găsirea BombVault în rețea

BombVault își anunță interfața web în rețeaua locală prin mDNS, protocolul din spatele Bonjour și Avahi. Un browser ajunge atunci la el ca https://bombvault.local:3443, sau http://bombvault.local:3000 cu HTTP_ONLY, iar browserele de servicii îl afișează ca serviciu web cu subtipul _bombvault. Înregistrările sale TXT conțin versiunea și calea. Comutatorul este Găsește în rețea, în cardul Servicii de la Setări, Integrări, și e pornit implicit. Dacă alt dispozitiv folosește deja numele, BombVault ia bombvault-2.local și așa mai departe, iar cardul arată adresa primită. Când BombVault se oprește sau oprești anunțul, anunță rețeaua, iar browserele scot imediat intrarea.

Dacă anunțul ajunge în rețeaua ta depinde de felul în care e conectat containerul:

  • bridge, valoarea implicită din șablonul Unraid: anunțul rămâne în rețeaua Docker și nimeni din rețeaua locală nu îl vede. Deschide BombVault prin adresa gazdei, ca până acum.
  • br0 sau altă rețea macvlan ori ipvlan: containerul are propria adresă în rețeaua locală, iar anunțul ajunge acolo.
  • host: anunțul iese prin interfețele gazdei, alături de cel al Unraid. Punțile Docker și libvirt sunt lăsate deoparte.

Se anunță doar adrese IPv4.