Saltar a contenido

API e integraciones

BombVault tiene una pequeña API HTTP para scripts, paneles y domótica. Lee lo mismo que muestra el resumen y puede iniciar una copia. Todo lo demás, como las restauraciones, el borrado de copias, los ajustes y los nodos, se queda en la interfaz web.

Tokens

Cada petición necesita un token de API, incluso cuando no hay contraseña de acceso. Crea uno en Ajustes, Integraciones, Tokens de API:

  1. Escribe un nombre que diga dónde se usa el token, por ejemplo "Home Assistant" o "Uptime Kuma".
  2. Activa Permitir iniciar copias si el token debe poder iniciar copias. Sin eso el token solo puede leer.
  3. Haz clic en Crear token. El token se muestra una sola vez. BombVault guarda únicamente una huella suya, así que cópialo ahora.

Envía el token en una cabecera, bien Authorization: Bearer <token> o bien X-API-Key: <token>. Un token empieza por bvapi_. Solo abre la API: una clave de MCP no sirve aquí, y un token no sirve para MCP.

Cada token tiene un mosaico con su nombre, si puede iniciar copias, los últimos cuatro caracteres, cuándo se usó por última vez y desde dónde, y sus llamadas de hoy. En el mosaico puedes renombrarlo, cambiar lo que puede hacer, sustituirlo o revocarlo. Registro muestra las copias que inició y sus llamadas recientes. Restaurar la configuración de BombVault desde una copia revoca todos los tokens, porque la copia puede contener tokens que revocaste más tarde.

Sin contraseña de acceso, cualquiera que pueda abrir la interfaz web también puede crear un token. Si abres BombVault con un nombre de aspecto público y no hay contraseña, no se pueden crear tokens desde esa dirección, la misma regla que para las claves de MCP.

Endpoints

Ruta Qué devuelve o hace Token
GET /api/v1/health Versión, nombre de la instancia, si hay una copia en curso y qué puede hacer este token lectura
GET /api/v1/status Estado de protección por sección: última copia correcta, intervalo esperado, comprobaciones, próximas ejecuciones programadas lectura
GET /api/v1/activity Lo que se está ejecutando ahora, con fase y porcentaje lectura
GET /api/v1/items Cada elemento protegido con su calendario, lo que detiene una copia y su última copia. ?domain= para una sección lectura
GET /api/v1/runs Historial de ejecuciones, las más recientes primero. Filtros limit, domain, item, status, kind, since lectura
GET /api/v1/anomalies Anomalías con un resumen de lo que está abierto. Filtros state, severity, domain, limit lectura
GET /api/v1/anomalies/{id} Una anomalía lectura
GET /api/v1/storage/{domain} Historial de tamaño, crecimiento por semana y espacio libre de cada repositorio de una sección lectura
POST /api/v1/backups Copia un elemento ({"domain":"containers","item":"plex"}) o una sección entera ({"domain":"vms"}) inicio
POST /api/v1/backups/everything Ejecuta la pasada de Copiar todo ahora inicio
POST /api/v1/runs/{id}/cancel Cancela una copia en curso que inició este token inicio

Las secciones son containers, vms, files, zfs, flash y config. Las horas son segundos unix. Las respuestas son las mismas que las de las herramientas MCP con los mismos nombres, así que ambas van a la par.

Una copia iniciada es la misma copia que inicia la interfaz web: un contenedor en ejecución se detiene hasta que termina su copia. La petición vuelve enseguida, y /api/v1/activity y /api/v1/runs muestran cómo va.

Ejemplos

# 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

Con el certificado autofirmado de BombVault, añade --cacert bombvault-cert.pem (el archivo que te da Descargar certificado en la tarjeta de MCP) o -k en una red de confianza.

Errores y límites

Un error vuelve como {"error": {"code": "...", "message": "..."}} con un estado acorde:

Estado Códigos Significado
400 invalid_argument, ambiguous Falta un argumento o es incorrecto
401 no_token, invalid_token No hay token, o no es uno activo
403 not_permitted, forbidden_origin El token solo puede leer, la ejecución no la inició él, o la petición vino de una página de otro origen
404 not_found No existe ese elemento, ejecución o anomalía
409 busy, domain_off, nothing_to_back_up, not_running Hay otra cosa en marcha, la sección está desactivada, o no hay nada que hacer
429 throttled, rate_limited, cooldown, retention_guard Un límite retiene la petición. Retry-After dice cuándo volver a intentarlo

Los inicios siguen los mismos límites que los inicios por MCP: 12 por hora y token, 15 minutos entre dos inicios del mismo elemento, como mucho 4 inicios de un elemento en 24 horas y la protección de retención. Los tres últimos cuentan juntos los inicios por MCP, por la API y por Home Assistant. Un token puede hacer 120 peticiones por minuto. Cinco intentos fallidos desde una dirección la bloquean durante un minuto.

OpenAPI

BombVault ofrece una descripción de estas rutas en /api/v1/openapi.json (OpenAPI 3.1). No necesita token. Cárgala en Swagger UI, Postman o un generador de código.

Nodos

Las rutas que gestionan los nodos pertenecen a la interfaz web, no a la API con token de arriba. Con una contraseña de acceso definida, necesitan una sesión de navegador iniciada en esta instancia. Un token de API o una clave MCP no abre ninguna, los teléfonos emparejados no llegan a ellas y /api/v1/openapi.json no las describe. Añadir un nodo, volver a mostrar su archivo compose y llegar a las rutas propias de un nodo se rechaza hasta que se define una contraseña de acceso. Un script que cambia algo envía Content-Type: application/json, como en toda la interfaz web.

Ruta Qué hace
GET /api/nodes Cada nodo con si está en línea, su versión, adónde van sus copias, el plan de cada sección, su última copia, sus errores y sus anomalías abiertas
POST /api/nodes Añade un nodo, como {"name":"vps-helsinki"}, y lo devuelve con compose: MODE, APP_KEY, NODE_HOME y NODE_NAME
POST /api/nodes/{id}/compose Devuelve otra vez los mismos valores de compose, para Reemplazar
POST /api/nodes/{id}/placement Envía las copias del nodo a un destino y responde por sección si el nodo llegó a su repositorio, con un warning en el caso de un destino
PUT /api/nodes/{id}/schedule Fija los planes, como {"containers":"daily 03:00","files":"off"}. Una sección que falta conserva su plan
DELETE /api/nodes/{id} Libera el nodo. told dice si se enteró ahora o se enterará cuando vuelva
GET /api/nodes/routes La lista de rutas propias del nodo a las que la instancia base pasa las solicitudes
GET, POST, PATCH /api/nodes/{id}/api/{path} Pasa la solicitud a la ruta /api/{path} del nodo cuando esa ruta está en la lista, y devuelve la respuesta JSON del nodo
PUT /api/receiver/node-address Fija la Dirección para nodos del servidor receptor, como {"url":"https://backup.tower.example.org","caPem":""}. Una url vacía quita los nodos del servidor

Los tres destinos:

{"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"}

Una solicitud a /api/nodes/{id}/api/... lleva como mucho 32 KiB. Una ruta que no está en la lista responde 403, un nodo que aún no ha respondido o que se está liberando, 409 con el código node-not-adopted, y un nodo que no está, 502 con el código node-away. Por ejemplo, GET /api/nodes/{id}/api/runs?limit=20 devuelve las últimas 20 ejecuciones del nodo, y POST /api/nodes/{id}/api/containers/nextcloud/backup copia su contenedor nextcloud.

Home Assistant

BombVault puede aparecer en Home Assistant como dispositivo, mediante el descubrimiento MQTT. Home Assistant necesita su integración MQTT y un broker, por ejemplo el complemento Mosquitto. No interviene ningún componente personalizado.

  1. En BombVault, abre Ajustes, Integraciones y activa Home Assistant en la tarjeta Servicios. Debajo aparecen los campos del broker.
  2. Introduce la dirección y el puerto del broker, y su nombre de usuario y contraseña si los pide. Activa Usar TLS si el broker acepta TLS, normalmente en el puerto 8883. Su certificado tiene que ser válido para la dirección que introdujiste. Si cambias la dirección, el puerto o el nombre de usuario, vuelve a introducir la contraseña: BombVault no pasa la guardada a otro broker o usuario.
  3. Haz clic en Guardar. La fila muestra cuándo está activa la conexión.

El dispositivo se llama BombVault, o BombVault con el nombre de la instancia entre paréntesis, y tiene estas entidades:

Entidad Qué muestra
Status ok, warning, overdue, failed u off, la peor de las secciones activadas. Una sección que espera su primera copia solo cuenta cuando esa copia ya tocaba, y solo una sección al día da el estado ok. overdue significa, como en la vista general, que la última copia de una sección tiene más de dos intervalos
Running job Lo que se ejecuta ahora, o idle
Open anomalies Cuántas anomalías están abiertas
Next scheduled backup Cuándo empieza la próxima copia programada
Domain last backup Cuándo se ejecutó la última copia correcta de la sección
Domain last result Cómo terminó su última copia
Domain repository free space Espacio libre donde está su repositorio primario, si BombVault puede leerlo
Back up domain Un botón que copia la sección entera

Cada sección activada tiene sus propias entidades, y una sección que desactives las pierde. Los botones aparecen cuando activas Los botones inician copias. Una instalación nueva lo tiene desactivado. Siguen los mismos límites que los inicios por la API. Además, BombVault atiende una pulsación por sección a la vez y no más de seis por minuto, e ignora una pulsación que el broker guardó como mensaje retenido. Cualquiera que pueda publicar en el broker puede pulsarlos, así que ponle una contraseña al broker.

BombVault lee su estado cada 15 segundos y lo publica cuando algo ha cambiado, como JSON bajo <prefix>/<node>/state. El prefijo es bombvault salvo que lo cambies, y el nodo es un identificador corto que BombVault elige una vez. Los mensajes de descubrimiento van al prefijo predeterminado de Home Assistant, homeassistant. Ambos son retenidos. Un último deseo marca el dispositivo como no disponible si BombVault se detiene sin avisar. Desactivar el enlace elimina el dispositivo y sus entidades de Home Assistant.

Ejemplo: una tarjeta y una alerta

Home Assistant forma los identificadores de entidad a partir de los nombres, así que el dispositivo BombVault recibe identificadores como sensor.bombvault_status. Con un nombre de instancia entre paréntesis los identificadores también lo llevan, así que compruébalos antes en Developer Tools, States. Una tarjeta para el panel:

type: entities
title: Backups
entities:
  - sensor.bombvault_status
  - sensor.bombvault_running_job
  - sensor.bombvault_open_anomalies
  - sensor.bombvault_next_scheduled_backup

Una automatización que avisa a tu teléfono cuando el estado pasa a failed o 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

Exponer /metrics en la tarjeta Servicios de Ajustes, Integraciones sirve el estado de las copias, los tamaños y las marcas de tiempo para Prometheus, Grafana o Uptime Kuma, en /metrics en el puerto de la interfaz web. Está desactivado de forma predeterminada. Token de scrape (opcional) hace que el recolector envíe un token bearer. Las etiquetas no llevan secretos ni rutas.

Widget de panel

La tarjeta Widget de panel de Ajustes, Integraciones genera un token de solo lectura y te da una dirección para cualquier panel que muestre un iframe, como Homepage, Organizr o Heimdall. La dirección abre una página pequeña en /widget con solo el registro de actividad en vivo. El token da acceso a ese registro y a nada más, y Desactivar lo revoca al instante. La página incrustada solo está en inglés.

Encontrar BombVault en la red

BombVault anuncia su interfaz web en la red local por mDNS, el protocolo que hay detrás de Bonjour y Avahi. Entonces un navegador llega a ella como https://bombvault.local:3443, o http://bombvault.local:3000 con HTTP_ONLY, y los exploradores de servicios la listan como un servicio web con el subtipo _bombvault. Sus registros TXT llevan la versión y la ruta. El interruptor es Encontrar en la red en la tarjeta Servicios de Ajustes, Integraciones y viene activado de forma predeterminada. Si otro dispositivo ya usa el nombre, BombVault toma bombvault-2.local y así sucesivamente, y la tarjeta muestra la dirección que obtuvo. Cuando BombVault se detiene o desactivas el anuncio, avisa a la red, así que los navegadores quitan la entrada al instante.

Que el anuncio llegue a tu red depende de cómo esté conectado el contenedor:

  • bridge, el valor predeterminado en la plantilla de Unraid: el anuncio se queda dentro de la red de Docker y nadie en la LAN lo ve. Abre BombVault por la dirección del host como antes.
  • br0 u otra red macvlan o ipvlan: el contenedor tiene su propia dirección en la LAN, y el anuncio llega a ella.
  • host: el anuncio sale por las interfaces del host, junto al propio de Unraid. Se salta los puentes de Docker y de libvirt.

Solo se anuncian direcciones IPv4.