Перейти к содержанию

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.