API та інтеграції¶
У BombVault є невеликий HTTP API для скриптів, панелей і розумного дому. Він читає те саме, що показує огляд, і може запустити копіювання. Усе інше, наприклад відновлення, видалення копій, налаштування й вузли, залишається у вебінтерфейсі.
Токени¶
Кожному запиту потрібен токен API, навіть якщо пароль для входу не задано. Створіть його в розділі Налаштування, Інтеграції, Токени API:
- Введіть назву, за якою видно, де використовується токен, наприклад «Home Assistant» або «Uptime Kuma».
- Увімкніть Дозволити запуск копіювання, якщо токен має запускати копіювання. Без цього він може лише читати.
- Натисніть Створити токен. Токен показується один раз. 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 |
Токен може лише читати, запуск розпочав не він, або запит прийшов зі сторінки з іншого джерела (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 КіБ. Маршрут не зі списку відповідає 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 зупиниться без попередження. Якщо вимкнути зв'язок, 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_ONLY як http://bombvault.local:3000, і оглядачі сервісів показують його як вебсервіс з підтипом _bombvault. Його записи TXT містять версію та шлях. Перемикач Знайти в мережі розташований у картці Сервіси в розділі Налаштування, Інтеграції й типово ввімкнений. Якщо ім'я вже зайняте іншим пристроєм, BombVault бере bombvault-2.local і так далі, а картка показує отриману адресу. Коли BombVault зупиняється або ви вимикаєте оголошення, він повідомляє про це мережі, і браузери одразу прибирають запис.
Чи потрапить оголошення у вашу мережу, залежить від того, як підключено контейнер:
- bridge, стандартний варіант у шаблоні Unraid: оголошення лишається всередині мережі Docker, і в локальній мережі його ніхто не бачить. Відкривайте BombVault за адресою хоста, як і раніше.
- br0 або інша мережа macvlan чи ipvlan: у контейнера своя адреса в локальній мережі, і оголошення туди доходить.
- host: оголошення йде через інтерфейси хоста, поряд з оголошенням самого Unraid. Мости Docker і libvirt лишаються осторонь.
Оголошуються лише адреси IPv4.