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.