API ושילובים

ל-BombVault יש API קטן של HTTP לסקריפטים, ללוחות מחוונים ולאוטומציה ביתית. הוא קורא את מה שלוח הבקרה מציג ויכול להתחיל גיבוי. כל השאר, כמו שחזורים, מחיקת גיבויים והגדרות, נשאר בממשק הרשת.

אסימונים

כל בקשה צריכה אסימון API, גם כשלא הוגדרה סיסמת כניסה. צור אותו ב-הגדרות, אינטגרציות, אסימוני API:

1. הקלד שם שאומר איפה משתמשים באסימון, למשל „Home Assistant” או „Uptime Kuma”.
2. הפעל את אפשר התחלת גיבויים אם האסימון צריך להתחיל גיבויים. בלי זה הוא יכול רק לקרוא.
3. לחץ צור אסימון. האסימון מוצג פעם אחת. 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 מראים איך הוא מתקדם.

דוגמאות

# מה מצב הגיבויים?
curl -s -H "Authorization: Bearer $BOMBVAULT_TOKEN" https://tower:3443/api/v1/status

# גיבוי של מכולה אחת עכשיו.
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 או למחולל קוד.

Home Assistant

BombVault יכול להופיע ב-Home Assistant כמכשיר, דרך גילוי MQTT. לשם כך Home Assistant צריך את שילוב ה-MQTT שלו ומתווך, למשל התוסף Mosquitto. אין צורך ברכיב משלו.

1. ב-BombVault פתח הגדרות, אינטגרציות, Home Assistant.
2. הזן את הכתובת והפורט של המתווך, ושם משתמש וסיסמה אם הוא מבקש. הפעל את השתמש ב-TLS אם המתווך משתמש ב-TLS, בדרך כלל בפורט 8883; האישור שלו צריך להיות תקף לכתובת שהזנת. אם אתה משנה את הכתובת, הפורט או שם המשתמש, הזן שוב את הסיסמה: BombVault לא מעביר את הסיסמה השמורה למתווך או משתמש אחר.
3. הפעל את התחבר ל-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 מקבל לחיצה אחת בכל פעם לכל תחום ולכל היותר שש בדקה, ומתעלם מלחיצה שהמתווך שמר כהודעה שמורה (retained). כל מי שיכול לפרסם במתווך יכול ללחוץ עליהם, אז הגן על המתווך בסיסמה.

BombVault קורא את המצב שלו כל 15 שניות ומפרסם אותו כשמשהו השתנה, כ-JSON תחת <קידומת>/<צומת>/state. הקידומת היא bombvault כל עוד לא שינית אותה, והצומת הוא מזהה קצר ש-BombVault בוחר פעם אחת. הודעות הגילוי הולכות לקידומת ברירת המחדל של Home Assistant, homeassistant. שתיהן נשמרות (retained). צוואה אחרונה (last will) מסמנת את המכשיר כלא זמין אם 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 נעצר או כשמכבים את ההכרזה, הוא מודיע על כך לרשת, ודפדפנים מסירים את הרשומה מיד.

אם ההכרזה מגיעה לרשת שלך תלוי באופן שבו המכולה מחוברת:

• bridge, ברירת המחדל בתבנית של Unraid: ההכרזה נשארת בתוך הרשת של Docker ואף אחד ברשת המקומית לא רואה אותה. פתח את BombVault דרך הכתובת של המארח כמו קודם.
• br0 או רשת macvlan או ipvlan אחרת: למכולה יש כתובת משלה ברשת המקומית, וההכרזה מגיעה אליה.
• host: ההכרזה יוצאת דרך הממשקים של המארח, לצד ההכרזה של Unraid עצמו. הגשרים של Docker ושל libvirt נשארים בחוץ.

רק כתובות IPv4 מוכרזות.