واجهة API والتكاملات¶
لدى BombVault واجهة HTTP API صغيرة للسكربتات ولوحات المراقبة وأتمتة المنزل. تقرأ ما تعرضه النظرة العامة ويمكنها بدء نسخة احتياطية. أما كل ما عدا ذلك، مثل الاستعادات وحذف النسخ والإعدادات والعُقد، فيبقى في واجهة الويب.
الرموز¶
يحتاج كل طلب إلى رمز API، حتى لو لم تُضبط كلمة مرور دخول. أنشئ واحدًا ضمن الإعدادات، التكاملات، رموز API:
- اكتب اسمًا يدل على المكان الذي يُستخدم فيه الرمز، مثل «Home Assistant» أو «Uptime Kuma».
- فعّل السماح ببدء النسخ الاحتياطي إذا كان الرمز سيبدأ نسخًا. بدونه يقرأ الرمز فقط.
- اضغط إنشاء رمز. يظهر الرمز مرة واحدة. يحتفظ 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. ولا يتدخل أي مكوّن مخصص.
- في BombVault افتح الإعدادات، التكاملات وفعّل Home Assistant في بطاقة الخدمات. تظهر حقول الوسيط تحته.
- أدخل عنوان الوسيط ومنفذه، واسم المستخدم وكلمة المرور إن طلبهما. فعّل استخدام TLS إن كان الوسيط يقبل TLS، وعادةً على المنفذ 8883. يجب أن تكون شهادته صالحة للعنوان الذي أدخلته. إذا غيّرت العنوان أو المنفذ أو اسم المستخدم فأدخل كلمة المرور من جديد: لا يمرّر BombVault كلمة المرور المخزنة إلى وسيط أو مستخدم آخر.
- اضغط حفظ. يعرض السطر متى يكون الاتصال قائمًا.
يسمى الجهاز 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.