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