לדלג לתוכן

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 מראים איך זה מתקדם.

דוגמאות

# 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. אין רכיב מותאם.

  1. ב-BombVault פותחים הגדרות, אינטגרציות ומפעילים Home Assistant בכרטיס שירותים. השדות ל-broker מופיעים מתחתיו.
  2. מזינים את הכתובת והפורט של ה-broker, ואת שם המשתמש והסיסמה אם הוא מבקש אותם. מפעילים שימוש ב-TLS אם ה-broker לוקח TLS, בדרך כלל בפורט 8883. התעודה שלו חייבת להיות תקפה לכתובת שהזנת. אם משנים את הכתובת, הפורט או שם המשתמש, מזינים את הסיסמה שוב: BombVault לא מעבירה את השמורה ל-broker או למשתמש אחר.
  3. לוחצים שמירה. השורה מראה מתי החיבור פעיל.

ההתקן נקרא 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.