Перейти до змісту

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 показують, як ідуть справи.

Приклади

# 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. Окремий компонент не потрібен.

  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 зупиниться без попередження. Якщо вимкнути зв'язок, 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.