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

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

الرموز

يحتاج كل طلب إلى رمز 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 دون إعلام. إذا أطفأت الربط، يزيل 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.