Μετάβαση στο περιεχόμενο

API και ενσωματώσεις

Το BombVault έχει ένα μικρό HTTP API για σενάρια, πίνακες ελέγχου και οικιακό αυτοματισμό. Διαβάζει ό,τι δείχνει η Επισκόπηση και μπορεί να ξεκινήσει ένα αντίγραφο ασφαλείας. Όλα τα υπόλοιπα, όπως οι επαναφορές, η διαγραφή αντιγράφων, οι ρυθμίσεις και οι κόμβοι, μένουν στη διεπαφή ιστού.

Tokens

Κάθε αίτημα χρειάζεται ένα token API, ακόμη κι αν δεν έχει οριστεί κωδικός εισόδου. Δημιουργήστε ένα στις Ρυθμίσεις, Ενσωματώσεις, Tokens API:

  1. Γράψτε ένα όνομα που λέει πού χρησιμοποιείται το token, για παράδειγμα «Home Assistant» ή «Uptime Kuma».
  2. Ενεργοποιήστε το Να επιτρέπεται η έναρξη αντιγράφων, αν το token πρέπει να μπορεί να ξεκινά αντίγραφα. Χωρίς αυτό το token μπορεί μόνο να διαβάζει.
  3. Πατήστε Δημιουργία token. Το token εμφανίζεται μία φορά. Το BombVault κρατά μόνο ένα αποτύπωμά του, οπότε αντιγράψτε το τώρα.

Στείλτε το token σε κεφαλίδα, είτε ως Authorization: Bearer <token> είτε ως X-API-Key: <token>. Ένα token ξεκινά με bvapi_. Ανοίγει μόνο το API: ένα κλειδί MCP δεν λειτουργεί εδώ και ένα token δεν λειτουργεί για MCP.

Κάθε token έχει ένα πλακίδιο με το όνομά του, αν επιτρέπεται να ξεκινά αντίγραφα, τους τέσσερις τελευταίους χαρακτήρες, πότε και από πού χρησιμοποιήθηκε τελευταία φορά και τις σημερινές κλήσεις του. Στο πλακίδιο μπορείτε να το μετονομάσετε, να αλλάξετε τι επιτρέπεται, να το αντικαταστήσετε ή να το ανακαλέσετε. Το Αρχείο δείχνει τα αντίγραφα που ξεκίνησε και τις πρόσφατες κλήσεις του. Η επαναφορά της διαμόρφωσης του BombVault από αντίγραφο ανακαλεί όλα τα tokens, επειδή το αντίγραφο μπορεί να περιέχει tokens που ανακαλέσατε αργότερα.

Αν δεν υπάρχει κωδικός εισόδου, όποιος μπορεί να ανοίξει τη διεπαφή ιστού μπορεί να δημιουργήσει και token. Αν ανοίγετε το BombVault με όνομα που μοιάζει δημόσιο και δεν υπάρχει κωδικός, δεν μπορούν να δημιουργηθούν tokens από αυτή τη διεύθυνση, με τον ίδιο κανόνα όπως για τα κλειδιά MCP.

Σημεία πρόσβασης

Διαδρομή Τι επιστρέφει ή κάνει Token
GET /api/v1/health Έκδοση, όνομα εγκατάστασης, αν τρέχει κάποιο αντίγραφο και τι επιτρέπεται σε αυτό το token ανάγνωση
GET /api/v1/status Κατάσταση προστασίας ανά τομέα: τελευταίο επιτυχημένο αντίγραφο, αναμενόμενο διάστημα, έλεγχοι, επόμενες προγραμματισμένες εκτελέσεις ανάγνωση
GET /api/v1/activity Τι τρέχει αυτή τη στιγμή, με φάση και ποσοστό ανάγνωση
GET /api/v1/items Κάθε προστατευμένο στοιχείο με το πρόγραμμά του, τι σταματά ένα αντίγραφο και το τελευταίο του αντίγραφο. ?domain= για έναν τομέα ανάγνωση
GET /api/v1/runs Ιστορικό εκτελέσεων, οι νεότερες πρώτα. Φίλτρα limit, domain, item, status, kind, since ανάγνωση
GET /api/v1/anomalies Ανωμαλίες με σύνοψη των ανοιχτών. Φίλτρα state, severity, domain, limit ανάγνωση
GET /api/v1/anomalies/{id} Μία ανωμαλία ανάγνωση
GET /api/v1/storage/{domain} Ιστορικό μεγέθους, αύξηση ανά εβδομάδα και ελεύθερος χώρος κάθε αποθετηρίου ενός τομέα ανάγνωση
POST /api/v1/backups Παίρνει αντίγραφο ενός στοιχείου ({"domain":"containers","item":"plex"}) ή ολόκληρου τομέα ({"domain":"vms"}) έναρξη
POST /api/v1/backups/everything Εκτελεί το πέρασμα «Αντίγραφο για όλα» (Backup Everything) έναρξη
POST /api/v1/runs/{id}/cancel Ακυρώνει ένα αντίγραφο σε εξέλιξη που ξεκίνησε αυτό το token έναρξη

Οι τομείς είναι containers, vms, files, zfs, flash και config. Οι χρόνοι είναι δευτερόλεπτα Unix. Οι απαντήσεις είναι ίδιες με εκείνες των εργαλείων MCP με τα ίδια ονόματα, ώστε και τα δύο να μένουν ευθυγραμμισμένα.

Ένα αντίγραφο που ξεκινά από εδώ είναι το ίδιο αντίγραφο που ξεκινά η διεπαφή ιστού: ένα container που τρέχει σταματά μέχρι να τελειώσει το αντίγραφό του. Το αίτημα επιστρέφει αμέσως, και τα /api/v1/activity και /api/v1/runs δείχνουν πώς πάει.

Παραδείγματα

# 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

Με το αυτο-υπογεγραμμένο πιστοποιητικό του BombVault προσθέστε --cacert bombvault-cert.pem (το αρχείο που δίνει το Λήψη πιστοποιητικού στην κάρτα MCP) ή -k σε δίκτυο που εμπιστεύεστε.

Σφάλματα και όρια

Ένα σφάλμα επιστρέφει ως {"error": {"code": "...", "message": "..."}} με την αντίστοιχη κατάσταση:

Κατάσταση Κωδικοί Σημασία
400 invalid_argument, ambiguous Ένα όρισμα λείπει ή είναι λάθος
401 no_token, invalid_token Δεν υπάρχει token, ή δεν είναι ενεργό
403 not_permitted, forbidden_origin Το token μπορεί μόνο να διαβάζει, η εκτέλεση δεν ξεκίνησε από αυτό, ή το αίτημα ήρθε από σελίδα άλλης προέλευσης
404 not_found Δεν υπάρχει τέτοιο στοιχείο, εκτέλεση ή ανωμαλία
409 busy, domain_off, nothing_to_back_up, not_running Τρέχει κάτι άλλο, ο τομέας είναι ανενεργός ή δεν υπάρχει τίποτα να γίνει
429 throttled, rate_limited, cooldown, retention_guard Ένα όριο κρατά πίσω το αίτημα. Το Retry-After λέει πότε να ξαναδοκιμάσετε

Οι εκκινήσεις ακολουθούν τα ίδια όρια με τις εκκινήσεις μέσω MCP: 12 την ώρα ανά token, 15 λεπτά ανάμεσα σε δύο εκκινήσεις του ίδιου στοιχείου, το πολύ 4 εκκινήσεις ενός στοιχείου σε 24 ώρες και η προστασία διατήρησης. Τα τρία τελευταία μετρούν μαζί τις εκκινήσεις μέσω MCP, μέσω API και από το Home Assistant. Ένα token μπορεί να κάνει 120 αιτήματα το λεπτό. Πέντε αποτυχημένες απόπειρες από μία διεύθυνση τη μπλοκάρουν για ένα λεπτό.

OpenAPI

Το BombVault σερβίρει μια περιγραφή αυτών των διαδρομών στο /api/v1/openapi.json (OpenAPI 3.1). Δεν χρειάζεται token. Φορτώστε την σε Swagger UI, Postman ή σε γεννήτρια κώδικα.

Κόμβοι

Οι διαδρομές που διαχειρίζονται τους κόμβους ανήκουν στη διεπαφή ιστού, όχι στο API με tokens παραπάνω. Με ορισμένο κωδικό εισόδου χρειάζονται μια συνεδρία browser από σύνδεση σε αυτή την εγκατάσταση. Ένα token API ή ένα κλειδί MCP δεν ανοίγει καμία από αυτές, τα κινητά σε σύζευξη δεν τις φτάνουν, και το /api/v1/openapi.json δεν τις περιγράφει. Η προσθήκη κόμβου, η νέα εμφάνιση του αρχείου compose του και η πρόσβαση στις δικές διαδρομές ενός κόμβου απορρίπτονται μέχρι να οριστεί κωδικός εισόδου. Ένα σενάριο που αλλάζει κάτι στέλνει Content-Type: application/json, όπως παντού στη διεπαφή ιστού.

Διαδρομή Τι κάνει
GET /api/nodes Κάθε κόμβος, με το αν είναι συνδεδεμένος, την έκδοσή του, πού πηγαίνουν τα αντίγραφά του, το χρονοδιάγραμμα κάθε τομέα, το τελευταίο αντίγραφο, τα σφάλματα και τις ανοιχτές ανωμαλίες του
POST /api/nodes Προσθέτει έναν κόμβο, όπως {"name":"vps-helsinki"}, και τον επιστρέφει με compose: MODE, APP_KEY, NODE_HOME και NODE_NAME
POST /api/nodes/{id}/compose Επιστρέφει ξανά τις ίδιες τιμές compose, για την Αντικατάσταση
POST /api/nodes/{id}/placement Στέλνει τα αντίγραφα του κόμβου κάπου και απαντά ανά τομέα αν ο κόμβος έφτασε το αποθετήριό του, με ένα warning για προορισμό
PUT /api/nodes/{id}/schedule Ορίζει τα χρονοδιαγράμματα, όπως {"containers":"daily 03:00","files":"off"}. Ένας τομέας που παραλείπεται κρατά το χρονοδιάγραμμά του
DELETE /api/nodes/{id} Αποδεσμεύει τον κόμβο. Το told λέει αν ο κόμβος το έμαθε τώρα ή θα το μάθει μόλις επιστρέψει
GET /api/nodes/routes Η λίστα με τις δικές διαδρομές του κόμβου στις οποίες η μητρική προωθεί αιτήματα
GET, POST, PATCH /api/nodes/{id}/api/{path} Προωθεί το αίτημα στη διαδρομή /api/{path} του κόμβου όταν αυτή είναι στη λίστα, και επιστρέφει την απάντηση JSON του κόμβου
PUT /api/receiver/node-address Ορίζει τη Διεύθυνση για κόμβους του διακομιστή λήψης, όπως {"url":"https://backup.tower.example.org","caPem":""}. Ένα κενό url κλείνει τον διακομιστή για τους κόμβους

Οι τρεις προορισμοί:

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

Ένα αίτημα προς /api/nodes/{id}/api/... μεταφέρει το πολύ 32 KiB. Μια διαδρομή εκτός λίστας απαντά 403, ένας κόμβος που δεν έχει απαντήσει ακόμη ή αποδεσμεύεται 409 με τον κωδικό node-not-adopted, και ένας κόμβος που λείπει 502 με τον κωδικό node-away. Για παράδειγμα, το GET /api/nodes/{id}/api/runs?limit=20 επιστρέφει τις τελευταίες 20 εκτελέσεις του κόμβου, και το POST /api/nodes/{id}/api/containers/nextcloud/backup δημιουργεί αντίγραφο του κοντέινερ του nextcloud.

Home Assistant

Το BombVault μπορεί να εμφανιστεί στο Home Assistant ως συσκευή, μέσω της ανακάλυψης MQTT. Το Home Assistant χρειάζεται την ενσωμάτωση MQTT και έναν broker, για παράδειγμα το πρόσθετο Mosquitto. Δεν εμπλέκεται κανένα προσαρμοσμένο στοιχείο.

  1. Στο BombVault ανοίξτε Ρυθμίσεις, Ενσωματώσεις και ενεργοποιήστε το Home Assistant στην κάρτα Υπηρεσίες. Τα πεδία για τον broker εμφανίζονται από κάτω.
  2. Γράψτε τη διεύθυνση και τη θύρα του broker, και το όνομα χρήστη και τον κωδικό του αν τα ζητά. Ενεργοποιήστε το Χρήση TLS αν ο broker δέχεται TLS, συνήθως στη θύρα 8883. Το πιστοποιητικό του πρέπει να ισχύει για τη διεύθυνση που γράψατε. Αν αλλάξετε τη διεύθυνση, τη θύρα ή το όνομα χρήστη, γράψτε ξανά τον κωδικό: το BombVault δεν περνά τον αποθηκευμένο κωδικό σε άλλον broker ή χρήστη.
  3. Πατήστε Αποθήκευση. Η γραμμή δείχνει πότε η σύνδεση είναι ενεργή.

Η συσκευή λέγεται BombVault, ή BombVault με το όνομα της εγκατάστασης σε παρένθεση, και έχει αυτές τις οντότητες:

Οντότητα Τι δείχνει
Status ok, warning, overdue, failed ή off, το χειρότερο από τους τομείς που είναι ενεργοί. Ένας τομέας που περιμένει το πρώτο του αντίγραφο μετρά μόνο αφού έχει φτάσει η ώρα αυτού του αντιγράφου, και μόνο ένας ενημερωμένος τομέας κάνει την κατάσταση ok. Το overdue σημαίνει, όπως και στην επισκόπηση, ότι το τελευταίο αντίγραφο ενός τομέα είναι παλαιότερο από δύο διαστήματα
Running job Τι τρέχει τώρα, ή idle
Open anomalies Πόσες ανωμαλίες είναι ανοιχτές
Next scheduled backup Πότε ξεκινά το επόμενο προγραμματισμένο αντίγραφο
Τομέας last backup Πότε έτρεξε το τελευταίο επιτυχημένο αντίγραφο του τομέα
Τομέας last result Πώς τελείωσε το τελευταίο του αντίγραφο
Τομέας repository free space Ο ελεύθερος χώρος εκεί όπου βρίσκεται το κύριο αποθετήριό του, αν το BombVault μπορεί να τον διαβάσει
Back up τομέας Ένα κουμπί που παίρνει αντίγραφο ολόκληρου του τομέα

Κάθε ενεργός τομέας παίρνει δικές του οντότητες, και ένας τομέας που απενεργοποιείτε τις χάνει. Τα κουμπιά εμφανίζονται μόλις ενεργοποιήσετε το Τα κουμπιά ξεκινούν αντίγραφα. Σε μια νέα εγκατάσταση είναι απενεργοποιημένο. Ακολουθούν τα ίδια όρια με τις εκκινήσεις μέσω του API. Επιπλέον, το BombVault διεκπεραιώνει ένα πάτημα τη φορά ανά τομέα και όχι περισσότερα από έξι το λεπτό, και αγνοεί ένα πάτημα που ο broker κράτησε ως retained μήνυμα. Όποιος μπορεί να δημοσιεύσει στον broker μπορεί να τα πατήσει, γι' αυτό βάλτε κωδικό στον broker.

Το BombVault διαβάζει την κατάστασή του κάθε 15 δευτερόλεπτα και τη δημοσιεύει όταν κάτι άλλαξε, ως JSON στο <πρόθεμα>/<κόμβος>/state. Το πρόθεμα είναι bombvault, εκτός αν το αλλάξετε, και ο κόμβος είναι ένα σύντομο αναγνωριστικό που διαλέγει το BombVault μία φορά. Τα μηνύματα ανακάλυψης πηγαίνουν στο προεπιλεγμένο πρόθεμα του Home Assistant, homeassistant. Και τα δύο διατηρούνται (retained). Ένα last will σημειώνει τη συσκευή ως μη διαθέσιμη αν το BombVault σταματήσει χωρίς προειδοποίηση. Αν απενεργοποιήσετε τη σύνδεση, αφαιρούνται η συσκευή και οι οντότητές της από το Home Assistant.

Παράδειγμα: μια κάρτα και μια ειδοποίηση

Το Home Assistant φτιάχνει τα αναγνωριστικά των οντοτήτων από τα ονόματα, οπότε η συσκευή BombVault παίρνει αναγνωριστικά όπως sensor.bombvault_status. Με όνομα εγκατάστασης σε παρένθεση, τα αναγνωριστικά το περιέχουν κι αυτό, γι' αυτό ελέγξτε τα πρώτα στα Developer Tools, States. Μια κάρτα για τον πίνακα ελέγχου:

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

Ένας αυτοματισμός που ειδοποιεί το κινητό σας όταν η κατάσταση γίνει failed ή 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

Το Έκθεση /metrics στην κάρτα Υπηρεσίες κάτω από τις Ρυθμίσεις, Ενσωματώσεις σερβίρει κατάσταση αντιγράφων, μεγέθη και χρονοσφραγίδες για Prometheus, Grafana ή Uptime Kuma, στο /metrics στη θύρα της διεπαφής ιστού. Είναι απενεργοποιημένο από προεπιλογή. Το Διακριτικό scrape (προαιρετικό) κάνει τον scraper να στέλνει ένα bearer token. Οι ετικέτες δεν περιέχουν μυστικά ούτε διαδρομές.

Widget πίνακα

Η κάρτα Widget πίνακα κάτω από τις Ρυθμίσεις, Ενσωματώσεις δημιουργεί ένα token μόνο για ανάγνωση και σας δίνει μια διεύθυνση για κάθε πίνακα που δείχνει iframe, όπως το Homepage, το Organizr ή το Heimdall. Η διεύθυνση ανοίγει μια μικρή σελίδα στο /widget με μόνο το ζωντανό αρχείο δραστηριότητας. Το token δίνει πρόσβαση σε αυτό το αρχείο και σε τίποτε άλλο, και το Απενεργοποίηση το ανακαλεί αμέσως. Η ενσωματωμένη σελίδα είναι μόνο στα αγγλικά.

Εύρεση του BombVault στο δίκτυο

Το BombVault ανακοινώνει τη διεπαφή ιστού του στο τοπικό δίκτυο μέσω mDNS, του πρωτοκόλλου πίσω από το Bonjour και το Avahi. Ένας φυλλομετρητής το βρίσκει τότε ως https://bombvault.local:3443, ή ως http://bombvault.local:3000 με HTTP_ONLY, και οι περιηγητές υπηρεσιών το εμφανίζουν ως υπηρεσία ιστού με τον υποτύπο _bombvault. Οι εγγραφές TXT του φέρουν την έκδοση και τη διαδρομή. Ο διακόπτης είναι το Εύρεση στο δίκτυο στην κάρτα Υπηρεσίες κάτω από τις Ρυθμίσεις, Ενσωματώσεις και είναι ενεργός από προεπιλογή. Αν μια άλλη συσκευή χρησιμοποιεί ήδη το όνομα, το BombVault παίρνει το bombvault-2.local και ούτω καθεξής, και η κάρτα δείχνει τη διεύθυνση που πήρε. Όταν το BombVault σταματά ή απενεργοποιήσετε την ανακοίνωση, το λέει στο δίκτυο, ώστε οι φυλλομετρητές να αφαιρούν αμέσως την εγγραφή.

Το αν η ανακοίνωση φτάνει στο δίκτυό σας εξαρτάται από το πώς είναι συνδεδεμένο το container:

  • bridge, η προεπιλογή στο πρότυπο του Unraid: η ανακοίνωση μένει μέσα στο δίκτυο του Docker και κανείς στο τοπικό δίκτυο δεν τη βλέπει. Ανοίξτε το BombVault από τη διεύθυνση του host, όπως πριν.
  • br0 ή άλλο δίκτυο macvlan ή ipvlan: το container έχει δική του διεύθυνση στο τοπικό δίκτυο και η ανακοίνωση φτάνει εκεί.
  • host: η ανακοίνωση βγαίνει από τις διεπαφές του host, δίπλα σε εκείνη του ίδιου του Unraid. Παραλείπει τις γέφυρες του Docker και του libvirt.

Ανακοινώνονται μόνο διευθύνσεις IPv4.