API και ενσωματώσεις¶
Το BombVault έχει ένα μικρό HTTP API για σενάρια, πίνακες ελέγχου και οικιακό αυτοματισμό. Διαβάζει ό,τι δείχνει ο πίνακας ελέγχου και μπορεί να ξεκινήσει αντίγραφο. Όλα τα άλλα, όπως επαναφορές, διαγραφή αντιγράφων και ρυθμίσεις, μένουν στη διεπαφή.
Tokens¶
Κάθε αίτημα χρειάζεται token API, ακόμη κι αν δεν έχει οριστεί κωδικός εισόδου. Δημιούργησέ το στις Ρυθμίσεις, Ενσωματώσεις, Tokens API:
- Γράψε ένα όνομα που λέει πού χρησιμοποιείται το token, για παράδειγμα «Home Assistant» ή «Uptime Kuma».
- Ενεργοποίησε το Να επιτρέπεται η έναρξη αντιγράφων, αν το token πρέπει να ξεκινά αντίγραφα. Χωρίς αυτό μόνο διαβάζει.
- Πάτησε Δημιουργία 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 |
Εκτελεί το Πλήρες αντίγραφο ασφαλείας | έναρξη |
POST /api/v1/runs/{id}/cancel |
Ακυρώνει ένα αντίγραφο σε εξέλιξη που ξεκίνησε αυτό το token | έναρξη |
Οι τομείς είναι containers, vms, files, zfs, flash και config. Οι χρόνοι είναι δευτερόλεπτα Unix. Οι απαντήσεις είναι ίδιες με εκείνες των ομώνυμων εργαλείων MCP, ώστε να μένουν ευθυγραμμισμένες.
Ένα αντίγραφο που ξεκινά εδώ είναι το ίδιο με εκείνο της διεπαφής: ένα container που τρέχει σταματά μέχρι να τελειώσει το αντίγραφό του. Το αίτημα επιστρέφει αμέσως, και τα /api/v1/activity και /api/v1/runs δείχνουν την πρόοδο.
Παραδείγματα¶
# Πώς πάνε τα αντίγραφα;
curl -s -H "Authorization: Bearer $BOMBVAULT_TOKEN" https://tower:3443/api/v1/status
# Αντίγραφο ενός container τώρα.
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 ή γεννήτρια κώδικα.
Home Assistant¶
Το BombVault μπορεί να εμφανιστεί στο Home Assistant ως συσκευή, μέσω της ανακάλυψης MQTT. Το Home Assistant χρειάζεται την ενσωμάτωση MQTT και έναν broker, για παράδειγμα το πρόσθετο Mosquitto. Δεν χρειάζεται κάποιο δικό του στοιχείο.
- Στο BombVault άνοιξε Ρυθμίσεις, Ενσωματώσεις, Home Assistant.
- Γράψε τη διεύθυνση και τη θύρα του broker, και όνομα χρήστη και κωδικό αν τα ζητά. Ενεργοποίησε το Χρήση TLS αν ο broker χρησιμοποιεί TLS, συνήθως στη θύρα 8883· το πιστοποιητικό του πρέπει να ισχύει για τη διεύθυνση που έγραψες. Αν αλλάξεις τη διεύθυνση, τη θύρα ή το όνομα χρήστη, βάλε ξανά τον κωδικό: το BombVault δεν δίνει τον αποθηκευμένο σε άλλον broker ή χρήστη.
- Ενεργοποίησε το Σύνδεση με το Home Assistant και πάτησε Αποθήκευση. Η κάρτα δείχνει πότε η σύνδεση είναι ενεργή.
Η συσκευή λέγεται BombVault, ή BombVault με το όνομα της εγκατάστασης σε παρένθεση, και έχει αυτές τις οντότητες:
| Οντότητα | Τι δείχνει |
|---|---|
| Status | ok, warning, failed ή off, το χειρότερο από τους ενεργούς τομείς |
| Running job | Τι τρέχει τώρα, ή idle |
| Open anomalies | Πόσες ανωμαλίες είναι ανοιχτές |
| Next scheduled backup | Πότε ξεκινά το επόμενο προγραμματισμένο αντίγραφο |
| Τομέας last backup | Πότε έτρεξε το τελευταίο επιτυχημένο αντίγραφο του τομέα |
| Τομέας last result | Πώς τελείωσε το τελευταίο του αντίγραφο |
| Τομέας repository free space | Ο ελεύθερος χώρος εκεί όπου βρίσκεται το κύριο αποθετήριό του, αν το BombVault μπορεί να τον διαβάσει |
| Back up τομέας | Ένα κουμπί που παίρνει αντίγραφο όλου του τομέα |
Τα ονόματα των οντοτήτων είναι στα αγγλικά, γιατί το Home Assistant τα παίρνει όπως τα στέλνει το BombVault. Κάθε ενεργός τομέας παίρνει δικές του οντότητες, και ένας τομέας που απενεργοποιείς τις χάνει. Τα κουμπιά εμφανίζονται μόλις ενεργοποιήσεις το Τα κουμπιά ξεκινούν αντίγραφα, που σε νέα εγκατάσταση είναι ανενεργό. Ακολουθούν τα ίδια όρια με τις εκκινήσεις μέσω του API. Επιπλέον το BombVault δέχεται ένα πάτημα τη φορά ανά τομέα και το πολύ έξι το λεπτό, και αγνοεί ένα πάτημα που ο broker κράτησε ως retained μήνυμα. Όποιος μπορεί να δημοσιεύει στον broker μπορεί να τα πατήσει, οπότε βάλε κωδικό στον broker.
Το BombVault διαβάζει την κατάστασή του κάθε 15 δευτερόλεπτα και τη δημοσιεύει όταν κάτι άλλαξε, ως JSON στο <πρόθεμα>/<κόμβος>/state. Το πρόθεμα είναι bombvault όσο δεν το αλλάζεις, και ο κόμβος είναι ένα σύντομο αναγνωριστικό που το BombVault διαλέγει μία φορά. Τα μηνύματα ανακάλυψης πηγαίνουν στο προεπιλεγμένο πρόθεμα του Home Assistant, homeassistant. Και τα δύο διατηρούνται (retained). Μια τελευταία βούληση (last will) σημειώνει τη συσκευή ως μη διαθέσιμη αν το BombVault σταματήσει χωρίς να το πει. Αν απενεργοποιήσεις τη σύνδεση, το BombVault αφαιρεί τη συσκευή και τις οντότητές της από το Home Assistant.
Εύρεση του 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.