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.