انتقل إلى المحتوى

واجهة API والتكاملات

لدى BombVault واجهة HTTP API صغيرة للسكربتات ولوحات المراقبة وأتمتة المنزل. تقرأ ما تعرضه النظرة العامة ويمكنها بدء نسخة احتياطية. أما كل ما عدا ذلك، مثل الاستعادات وحذف النسخ والإعدادات والعُقد، فيبقى في واجهة الويب.

الرموز

يحتاج كل طلب إلى رمز API، حتى لو لم تُضبط كلمة مرور دخول. أنشئ واحدًا ضمن الإعدادات، التكاملات، رموز API:

  1. اكتب اسمًا يدل على المكان الذي يُستخدم فيه الرمز، مثل «Home Assistant» أو «Uptime Kuma».
  2. فعّل السماح ببدء النسخ الاحتياطي إذا كان الرمز سيبدأ نسخًا. بدونه يقرأ الرمز فقط.
  3. اضغط إنشاء رمز. يظهر الرمز مرة واحدة. يحتفظ BombVault ببصمته فقط، فانسخه الآن.

أرسل الرمز في ترويسة: Authorization: Bearer <token> أو X-API-Key: <token>. يبدأ الرمز بـ bvapi_. وهو يفتح الواجهة فقط: مفتاح 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 الرمز للقراءة فقط، أو التشغيل لم يبدأه هو، أو جاء الطلب من صفحة على مصدر (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 ولا مفتاح 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 ووسيط، مثل إضافة Mosquitto. ولا يتدخل أي مكوّن مخصص.

  1. في BombVault افتح الإعدادات، التكاملات وفعّل Home Assistant في بطاقة الخدمات. تظهر حقول الوسيط تحته.
  2. أدخل عنوان الوسيط ومنفذه، واسم المستخدم وكلمة المرور إن طلبهما. فعّل استخدام TLS إن كان الوسيط يقبل TLS، وعادةً على المنفذ 8883. يجب أن تكون شهادته صالحة للعنوان الذي أدخلته. إذا غيّرت العنوان أو المنفذ أو اسم المستخدم فأدخل كلمة المرور من جديد: لا يمرّر BombVault كلمة المرور المخزنة إلى وسيط أو مستخدم آخر.
  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 ضغطة واحدة لكل قسم في كل مرة وما لا يزيد على ست في الدقيقة، ويتجاهل ضغطة احتفظ بها الوسيط كرسالة retained. يستطيع كل من يمكنه النشر إلى الوسيط الضغط عليها، فضع كلمة مرور للوسيط.

يقرأ BombVault حالته كل 15 ثانية وينشرها حين يتغير شيء، بصيغة JSON تحت <prefix>/<node>/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 عبر منفذ واجهة الويب. هو معطّل افتراضيًا. يجعل رمز الاستخلاص (اختياري) المستخلِص يرسل رمز 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 ولا يراه أحد في الشبكة المحلية. افتح BombVault بعنوان المضيف كما كان.
  • br0 أو شبكة macvlan أو ipvlan أخرى: للحاوية عنوان خاص بها في الشبكة المحلية، ويصلها الإعلان.
  • host: يخرج الإعلان عبر واجهات المضيف، بجانب إعلان Unraid نفسه. ويتخطى جسور Docker وlibvirt.

لا تُعلن إلا عناوين IPv4.