Przejdź do treści

API i integracje

BombVault ma małe API HTTP dla skryptów, pulpitów i automatyki domowej. Odczytuje to samo, co pokazuje przegląd, i może uruchomić kopię. Wszystko inne, jak przywracanie, usuwanie kopii, ustawienia i węzły, zostaje w interfejsie WWW.

Tokeny

Każde żądanie potrzebuje tokenu API, nawet gdy nie ustawiono hasła logowania. Utwórz go w Ustawienia, Integracje, Tokeny API:

  1. Wpisz nazwę, która mówi, gdzie token jest używany, na przykład „Home Assistant” albo „Uptime Kuma”.
  2. Włącz Pozwól uruchamiać kopie, jeśli token ma uruchamiać kopie. Bez tego może tylko czytać.
  3. Kliknij Utwórz token. Token pokazuje się tylko raz. BombVault przechowuje jedynie jego odcisk, więc skopiuj go teraz.

Wysyłaj token w nagłówku: Authorization: Bearer <token> albo X-API-Key: <token>. Token zaczyna się od bvapi_. Otwiera tylko API: klucz MCP tu nie działa, a token nie działa dla MCP.

Każdy token ma kafelek z nazwą, informacją, czy może uruchamiać kopie, ostatnimi czterema znakami, tym, kiedy i skąd był ostatnio użyty, oraz dzisiejszymi wywołaniami. Na kafelku możesz zmienić jego nazwę i uprawnienia, wymienić go albo unieważnić. Dziennik pokazuje kopie, które uruchomił, i jego ostatnie wywołania. Przywrócenie konfiguracji BombVault z kopii unieważnia wszystkie tokeny, bo kopia może zawierać tokeny, które później unieważniłeś.

Bez hasła logowania każdy, kto może otworzyć interfejs WWW, może też utworzyć token. Jeśli otworzysz BombVault pod nazwą wyglądającą na publiczną i nie ma hasła, z tego adresu nie da się tworzyć tokenów, tak samo jak kluczy MCP.

Punkty końcowe

Trasa Co zwraca lub robi Token
GET /api/v1/health Wersja, nazwa instancji, czy trwa kopia i co może ten token odczyt
GET /api/v1/status Stan ochrony według sekcji: ostatnia udana kopia, oczekiwany odstęp, kontrole, najbliższe zaplanowane przebiegi odczyt
GET /api/v1/activity Co działa w tej chwili, z fazą i procentem odczyt
GET /api/v1/items Każdy chroniony element z harmonogramem, tym, co zatrzymuje kopia, i ostatnią kopią; ?domain= dla jednej sekcji odczyt
GET /api/v1/runs Historia przebiegów, najnowsze najpierw; filtry limit, domain, item, status, kind, since odczyt
GET /api/v1/anomalies Anomalie z podsumowaniem otwartych; filtry state, severity, domain, limit odczyt
GET /api/v1/anomalies/{id} Jedna anomalia odczyt
GET /api/v1/storage/{domain} Historia rozmiaru, przyrost tygodniowy i wolne miejsce każdego repozytorium sekcji odczyt
POST /api/v1/backups Tworzy kopię jednego elementu ({"domain":"containers","item":"plex"}) albo całej sekcji ({"domain":"vms"}) uruchamianie
POST /api/v1/backups/everything Uruchamia Pełną kopię uruchamianie
POST /api/v1/runs/{id}/cancel Przerywa trwającą kopię uruchomioną przez ten token uruchamianie

Obszary to containers, vms, files, zfs, flash i config. Czasy są w sekundach Unix. Odpowiedzi są takie same jak z narzędzi MCP o tej samej nazwie, więc oba pozostają zgodne.

Kopia uruchomiona tutaj to ta sama kopia, którą uruchamia interfejs WWW: działający kontener jest zatrzymywany do końca swojej kopii. Żądanie wraca od razu, a /api/v1/activity i /api/v1/runs pokazują postęp.

Przykłady

# Jak mają się kopie?
curl -s -H "Authorization: Bearer $BOMBVAULT_TOKEN" https://tower:3443/api/v1/status

# Kopia jednego kontenera teraz.
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

Z własnym samopodpisanym certyfikatem BombVault dodaj --cacert bombvault-cert.pem (plik z przycisku Pobierz certyfikat na karcie MCP) albo -k w zaufanej sieci.

Błędy i limity

Błąd wraca jako {"error": {"code": "...", "message": "..."}} z odpowiednim statusem:

Status Kody Znaczenie
400 invalid_argument, ambiguous Brakuje argumentu albo jest błędny
401 no_token, invalid_token Brak tokenu albo token nieaktywny
403 not_permitted, forbidden_origin Token może tylko czytać albo nie uruchomił tego przebiegu, albo żądanie przyszło ze strony o innym pochodzeniu
404 not_found Nie ma takiego elementu, przebiegu ani anomalii
409 busy, domain_off, nothing_to_back_up, not_running Coś innego już działa, sekcja jest wyłączona albo nie ma nic do zrobienia
429 throttled, rate_limited, cooldown, retention_guard Limit wstrzymuje żądanie; Retry-After mówi, kiedy spróbować ponownie

Uruchomienia podlegają tym samym limitom co uruchomienia przez MCP: 12 na godzinę na token, 15 minut między dwoma uruchomieniami tego samego elementu, najwyżej 4 uruchomienia elementu w ciągu 24 godzin oraz ochrona retencji. Ostatnie trzy liczą razem uruchomienia przez MCP, przez API i z Home Assistant. Token może wysłać 120 żądań na minutę. Pięć nieudanych prób z jednego adresu blokuje go na minutę.

OpenAPI

BombVault udostępnia opis tych tras pod /api/v1/openapi.json (OpenAPI 3.1). Nie potrzeba do tego tokenu. Wczytaj go do Swagger UI, Postmana albo generatora kodu.

Węzły

Trasy, które obsługują węzły, należą do interfejsu WWW, a nie do opisanego wyżej API z tokenami. Przy ustawionym haśle logowania wymagają sesji przeglądarki z zalogowania na tej instancji. Token API ani klucz MCP nie otwiera żadnej z nich, sparowane telefony do nich nie sięgają, a /api/v1/openapi.json ich nie opisuje. Dodanie węzła, ponowne pokazanie jego pliku compose i dostęp do własnych tras węzła są odrzucane, dopóki nie ustawiono hasła logowania. Skrypt, który coś zmienia, wysyła Content-Type: application/json, jak wszędzie w interfejsie WWW.

Trasa Co robi
GET /api/nodes Każdy węzeł z informacją, czy jest online, jego wersją, miejscem docelowym kopii, planem każdej sekcji, ostatnią kopią, błędami i otwartymi anomaliami
POST /api/nodes Dodaje węzeł, na przykład {"name":"vps-helsinki"}, i zwraca go z compose: MODE, APP_KEY, NODE_HOME i NODE_NAME
POST /api/nodes/{id}/compose Zwraca ponownie te same wartości compose, dla Zastąp
POST /api/nodes/{id}/placement Kieruje kopie węzła w wybrane miejsce i odpowiada dla każdej sekcji, czy węzeł dotarł do swojego repozytorium, z warning dla miejsca docelowego
PUT /api/nodes/{id}/schedule Ustawia plany, na przykład {"containers":"daily 03:00","files":"off"}. Pominięta sekcja zachowuje swój plan
DELETE /api/nodes/{id} Zwalnia węzeł. told mówi, czy węzeł dowiedział się o tym od razu, czy dowie się po powrocie
GET /api/nodes/routes Lista własnych tras węzła, do których instancja domowa przekazuje żądania
GET, POST, PATCH /api/nodes/{id}/api/{path} Przekazuje żądanie do trasy węzła /api/{path}, gdy ta trasa jest na liście, i zwraca odpowiedź JSON węzła
PUT /api/receiver/node-address Ustawia Adres dla węzłów serwera odbiorczego, na przykład {"url":"https://backup.tower.example.org","caPem":""}. Pusty url zamyka serwer dla węzłów

Trzy miejsca docelowe:

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

Żądanie do /api/nodes/{id}/api/... może mieć najwyżej 32 KiB. Trasa spoza listy odpowiada 403, węzeł, który jeszcze nie odpowiedział albo jest zwalniany, 409 z kodem node-not-adopted, a węzeł, którego nie ma, 502 z kodem node-away. Na przykład GET /api/nodes/{id}/api/runs?limit=20 zwraca 20 ostatnich przebiegów węzła, a POST /api/nodes/{id}/api/containers/nextcloud/backup robi kopię jego kontenera nextcloud.

Home Assistant

BombVault może pojawić się w Home Assistant jako urządzenie dzięki wykrywaniu MQTT. Home Assistant potrzebuje do tego swojej integracji MQTT i brokera, na przykład dodatku Mosquitto. Żaden własny komponent nie jest potrzebny.

  1. W BombVault otwórz Ustawienia, Integracje i włącz Home Assistant w karcie Usługi. Pola brokera pojawiają się pod nim.
  2. Wpisz adres i port brokera, a także nazwę użytkownika i hasło, jeśli ich wymaga. Włącz Użyj TLS, jeśli broker używa TLS, zwykle na porcie 8883; jego certyfikat musi być ważny dla wpisanego adresu. Jeśli zmienisz adres, port albo nazwę użytkownika, wpisz hasło ponownie: BombVault nie przekazuje zapisanego hasła innemu brokerowi ani innemu użytkownikowi.
  3. Kliknij Zapisz. Wiersz pokazuje, kiedy połączenie działa.

Urządzenie nazywa się BombVault albo BombVault z nazwą instancji w nawiasie i ma takie encje:

Encja Co pokazuje
Status ok, warning, overdue, failed lub off, najgorszy stan spośród włączonych sekcji. Sekcja czekająca na pierwszą kopię liczy się dopiero po jej terminie, a stan ok daje tylko sekcja z aktualną kopią. overdue oznacza, tak jak w przeglądzie, że ostatnia kopia sekcji jest starsza niż dwa interwały
Running job Co teraz działa, albo idle
Open anomalies Ile anomalii jest otwartych
Next scheduled backup Kiedy zaczyna się następna zaplanowana kopia
Sekcja last backup Kiedy wykonano ostatnią udaną kopię sekcji
Sekcja last result Jak zakończyła się jej ostatnia kopia
Sekcja repository free space Wolne miejsce tam, gdzie leży jej główne repozytorium, jeśli BombVault może je odczytać
Back up sekcja Przycisk, który kopiuje całą sekcję

Każda włączona sekcja dostaje własne encje, a wyłączona je traci. Przyciski pojawiają się, gdy włączysz Przyciski uruchamiają kopie. W nowej instalacji jest to wyłączone. Podlegają tym samym limitom co uruchomienia przez API. Do tego BombVault przyjmuje naraz tylko jedno naciśnięcie na sekcję i najwyżej sześć na minutę, a naciśnięcie, które broker zachował jako wiadomość retained, pomija. Nacisnąć je może każdy, kto może publikować w brokerze, więc zabezpiecz broker hasłem.

BombVault odczytuje swój stan co 15 sekund i publikuje go, gdy coś się zmieniło, jako JSON pod <prefiks>/<węzeł>/state. Prefiks to bombvault, dopóki go nie zmienisz, a węzeł to krótki identyfikator, który BombVault wybiera raz. Komunikaty wykrywania trafiają pod domyślny prefiks Home Assistant, homeassistant. Oba są zachowywane (retained). Ostatnia wola (last will) oznacza urządzenie jako niedostępne, jeśli BombVault zatrzyma się bez uprzedzenia. Wyłączenie połączenia usuwa urządzenie i jego encje z Home Assistant.

Przykład: karta i alert

Home Assistant tworzy identyfikatory encji z nazw, więc urządzenie BombVault dostaje identyfikatory takie jak sensor.bombvault_status. Z nazwą instancji w nawiasie identyfikatory też ją niosą, więc najpierw sprawdź je w Developer Tools, States. Karta na pulpit:

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

Automatyzacja, która powiadamia telefon, gdy status zmieni się na failed lub 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

Udostępnij /metrics w karcie Usługi w Ustawienia, Integracje serwuje stan kopii, rozmiary i znaczniki czasu dla Prometheusa, Grafany lub Uptime Kuma, pod /metrics na porcie interfejsu WWW. Domyślnie jest wyłączone. Token scrapowania (opcjonalnie) sprawia, że scraper wysyła token typu bearer. Etykiety nie niosą sekretów ani ścieżek.

Widżet pulpitu

Karta Widżet pulpitu w Ustawienia, Integracje generuje token tylko do odczytu i daje adres dla dowolnego pulpitu pokazującego iframe, jak Homepage, Organizr czy Heimdall. Adres otwiera małą stronę pod /widget z samym dziennikiem aktywności na żywo. Token daje ten dziennik i nic więcej, a Wyłącz unieważnia go od razu. Osadzona strona jest tylko po angielsku.

Znajdowanie BombVault w sieci

BombVault ogłasza swój interfejs WWW w sieci lokalnej przez mDNS, protokół stojący za Bonjour i Avahi. Przeglądarka otwiera go wtedy jako https://bombvault.local:3443, a z HTTP_ONLY jako http://bombvault.local:3000, a przeglądarki usług pokazują go jako usługę WWW z podtypem _bombvault. Rekordy TXT zawierają wersję i ścieżkę. Przełącznik Znajdź w sieci jest w karcie Usługi w Ustawienia, Integracje i domyślnie jest włączony. Jeśli inne urządzenie używa już tej nazwy, BombVault bierze bombvault-2.local i tak dalej, a karta pokazuje otrzymany adres. Gdy BombVault się zatrzymuje albo wyłączysz ogłaszanie, informuje o tym sieć, a przeglądarki od razu usuwają wpis.

To, czy ogłoszenie dotrze do twojej sieci, zależy od tego, jak podłączony jest kontener:

  • bridge, domyślne ustawienie w szablonie Unraid: ogłoszenie zostaje w sieci Dockera i nikt w sieci lokalnej go nie widzi. Otwieraj BombVault przez adres hosta jak dotąd.
  • br0 albo inna sieć macvlan lub ipvlan: kontener ma własny adres w sieci lokalnej i ogłoszenie tam dociera.
  • host: ogłoszenie wychodzi przez interfejsy hosta, obok ogłoszenia samego Unraida. Mosty Dockera i libvirt są pomijane.

Ogłaszane są tylko adresy IPv4.