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:
- Scrie un nume care spune unde se folosește tokenul, de exemplu „Home Assistant” sau „Uptime Kuma”.
- Pornește Permite pornirea copiilor dacă tokenul trebuie să poată porni copii. Fără asta poate doar să citească.
- 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.
- În BombVault, deschide Setări, Integrări și pornește Home Assistant în cardul Servicii. Câmpurile pentru broker apar dedesubt.
- 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.
- 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.