API ושילובים¶
ל-BombVault יש API קטן ב-HTTP לסקריפטים, ללוחות מחוונים ולאוטומציית בית. הוא קורא את אותם דברים שהסקירה מציגה ויכול להתחיל גיבוי. כל השאר, כמו שחזורים, מחיקת גיבויים, הגדרות וצמתים, נשאר בממשק הרשת.
אסימונים¶
כל בקשה צריכה אסימון API, גם כשלא מוגדרת סיסמת התחברות. יוצרים אחד תחת הגדרות, אינטגרציות, אסימוני API:
- מקלידים שם שאומר היכן האסימון משמש, למשל "Home Assistant" או "Uptime Kuma".
- מפעילים אפשרות להתחיל גיבויים אם האסימון אמור להיות מסוגל להתחיל גיבויים. בלעדיה האסימון יכול רק לקרוא.
- לוחצים יצירת אסימון. האסימון מוצג פעם אחת. BombVault שומרת רק טביעת אצבע שלו, ולכן מעתיקים אותו עכשיו.
שולחים את האסימון בכותרת, או Authorization: Bearer <token> או X-API-Key: <token>. אסימון מתחיל ב-bvapi_. הוא פותח רק את ה-API: מפתח MCP לא עובד כאן, ואסימון לא עובד ל-MCP.
לכל אסימון יש אריח עם השם שלו, אם הוא רשאי להתחיל גיבויים, ארבעת התווים האחרונים, מתי נעשה בו שימוש לאחרונה ומאיפה, והקריאות שלו היום. באריח אפשר לשנות לו שם, לשנות מה הוא רשאי לעשות, להחליף אותו או לבטל אותו. יומן מציג את הגיבויים שהוא התחיל ואת הקריאות האחרונות שלו. שחזור התצורה של BombVault מגיבוי מבטל כל אסימון, כי הגיבוי עלול להחזיק אסימונים שביטלת מאוחר יותר.
בלי סיסמת התחברות, כל מי שיכול לפתוח את ממשק הרשת יכול גם ליצור אסימון. אם פותחים את BombVault תחת שם שנראה ציבורי ואין סיסמה, אי אפשר ליצור אסימונים מהכתובת הזו, אותו כלל כמו במפתחות MCP.
נקודות קצה¶
| נתיב | מה הוא מחזיר או עושה | אסימון |
|---|---|---|
GET /api/v1/health |
גרסה, שם המופע, אם גיבוי רץ, ומה האסימון הזה רשאי לעשות | קריאה |
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 |
מבטל גיבוי רץ שהאסימון הזה התחיל | התחלה |
התחומים הם containers, vms, files, zfs, flash ו-config. הזמנים הם בשניות unix. התשובות זהות לאלה של כלי MCP בעלי אותו שם, כך ששניהם נשארים מסונכרנים.
גיבוי שהתחיל הוא אותו גיבוי שממשק הרשת מתחיל: קונטיינר שרץ נעצר עד שהגיבוי שלו נגמר. הבקשה חוזרת מיד, ו-/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 |
אין אסימון, או שהוא לא פעיל |
| 403 | not_permitted, forbidden_origin |
האסימון רשאי רק לקרוא, הריצה לא התחילה על ידו, או שהבקשה באה מדף במקור אחר |
| 404 | not_found |
אין פריט, ריצה או חריגה כאלה |
| 409 | busy, domain_off, nothing_to_back_up, not_running |
משהו אחר רץ, התחום כבוי, או שאין מה לעשות |
| 429 | throttled, rate_limited, cooldown, retention_guard |
מגבלה עוצרת את הבקשה. Retry-After אומר מתי לנסות שוב |
התחלות כפופות לאותן מגבלות כמו התחלות דרך MCP: 12 לשעה לכל אסימון, 15 דקות בין שתי התחלות של אותו פריט, לכל היותר 4 התחלות של פריט אחד ב-24 שעות, ושומר השמירה. שלוש האחרונות סופרות יחד התחלות דרך MCP, ה-API ו-Home Assistant. אסימון יכול לבצע 120 בקשות בדקה. חמישה ניסיונות כושלים מכתובת אחת נועלים אותה לדקה.
OpenAPI¶
BombVault מגישה תיאור של הנתיבים האלה ב-/api/v1/openapi.json (OpenAPI 3.1). הוא לא צריך אסימון. טוענים אותו ל-Swagger UI, ל-Postman או למחולל קוד.
צמתים¶
הנתיבים שמטפלים בצמתים שייכים לממשק הרשת, לא ל-API של האסימונים שלמעלה. כשמוגדרת סיסמת התחברות הם צריכים הפעלת דפדפן מכניסה במופע הזה. אסימון 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 discovery. Home Assistant צריך את אינטגרציית ה-MQTT שלו ו-broker, למשל תוסף Mosquitto. אין רכיב מותאם.
- ב-BombVault פותחים הגדרות, אינטגרציות ומפעילים Home Assistant בכרטיס שירותים. השדות ל-broker מופיעים מתחתיו.
- מזינים את הכתובת והפורט של ה-broker, ואת שם המשתמש והסיסמה אם הוא מבקש אותם. מפעילים שימוש ב-TLS אם ה-broker לוקח TLS, בדרך כלל בפורט 8883. התעודה שלו חייבת להיות תקפה לכתובת שהזנת. אם משנים את הכתובת, הפורט או שם המשתמש, מזינים את הסיסמה שוב: BombVault לא מעבירה את השמורה ל-broker או למשתמש אחר.
- לוחצים שמירה. השורה מראה מתי החיבור פעיל.
ההתקן נקרא BombVault, או BombVault עם שם המופע בסוגריים, ויש לו את הישויות האלה:
| ישות | מה היא מציגה |
|---|---|
| סטטוס | ok, warning, overdue, failed או off, הגרוע מבין התחומים המופעלים. תחום שממתין לגיבוי הראשון שלו נספר רק אחרי שהגיע מועד הגיבוי הזה, ורק תחום עדכני נותן את הסטטוס ok. overdue פירושו, כמו בסקירה, שהגיבוי האחרון של תחום ישן משני מרווחים |
| עבודה רצה | מה רץ עכשיו, או idle |
| חריגות פתוחות | כמה חריגות פתוחות |
| הגיבוי המתוזמן הבא | מתי הגיבוי המתוזמן הבא מתחיל |
| הגיבוי האחרון של תחום | מתי רץ הגיבוי המוצלח האחרון של התחום |
| התוצאה האחרונה של תחום | איך הגיבוי האחרון שלו הסתיים |
| המקום הפנוי במאגר של תחום | מקום פנוי היכן שהמאגר הראשי שלו חי, אם BombVault יכולה לקרוא אותו |
| גיבוי תחום | כפתור שמגבה את התחום כולו |
כל תחום מופעל מקבל ישויות משלו, ותחום שמכבים מאבד אותן. הכפתורים מופיעים ברגע שהכפתורים מתחילים גיבויים מופעל. בהתקנה חדשה הוא כבוי. הם כפופים לאותן מגבלות כמו התחלות דרך ה-API. בנוסף BombVault מטפלת בלחיצה אחת לכל תחום בכל פעם ולא ביותר משש בדקה, ומתעלמת מלחיצה ש-broker שמר כהודעה retained. כל מי שיכול לפרסם ל-broker יכול ללחוץ עליהם, ולכן נותנים ל-broker סיסמה.
BombVault קוראת את המצב שלה כל 15 שניות ומפרסמת אותו כשמשהו השתנה, כ-JSON תחת <prefix>/<node>/state. ה-prefix הוא bombvault אלא אם משנים אותו, וה-node הוא מזהה קצר ש-BombVault בוחרת פעם אחת. הודעות ה-discovery הולכות ל-prefix ברירת המחדל של 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 (אופציונלי) גורם לאוסף לשלוח אסימון bearer. התוויות לא נושאות סודות ולא נתיבים.
וידג'ט ללוח מחוונים¶
הכרטיס וידג'ט ללוח מחוונים תחת הגדרות, אינטגרציות יוצר אסימון לקריאה בלבד ונותן לך כתובת לכל לוח מחוונים שמציג iframe, כמו Homepage, Organizr או Heimdall. הכתובת פותחת דף קטן ב-/widget עם יומן הפעילות החי בלבד. האסימון מעניק את היומן הזה ושום דבר אחר, והשבתה מבטלת אותו מיד. הדף המוטמע הוא באנגלית בלבד.
למצוא את BombVault ברשת¶
BombVault מכריזה על ממשק הרשת שלה ברשת המקומית דרך mDNS, הפרוטוקול שמאחורי Bonjour ו-Avahi. דפדפן מגיע אליה אז כ-https://bombvault.local:3443, או http://bombvault.local:3000 עם HTTP_ONLY, ודפדפני שירותים מציגים אותה כשירות רשת עם תת-הסוג _bombvault. רשומות ה-TXT שלה נושאות את הגרסה והנתיב. המתג הוא מציאה ברשת בכרטיס שירותים תחת הגדרות, אינטגרציות והוא מופעל כברירת מחדל. אם התקן אחר כבר משתמש בשם, BombVault לוקחת bombvault-2.local וכן הלאה, והכרטיס מציג את הכתובת שקיבלה. כש-BombVault נעצרת או כשמכבים את ההכרזה, היא מודיעה לרשת, כך שדפדפנים מסירים את הערך מיד.
אם ההכרזה מגיעה לרשת שלך תלוי באיך הקונטיינר מחובר:
- bridge, ברירת המחדל בתבנית של Unraid: ההכרזה נשארת בתוך הרשת של Docker ואף אחד ב-LAN לא רואה אותה. פותחים את BombVault לפי כתובת המארח כמו קודם.
- br0 או רשת macvlan או ipvlan אחרת: לקונטיינר יש כתובת משלו ב-LAN, וההכרזה מגיעה אליה.
- host: ההכרזה יוצאת על הממשקים של המארח, לצד זו של Unraid עצמו. היא מדלגת על הגשרים של Docker ושל libvirt.
מוכרזות רק כתובות IPv4.