跳转至

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 令牌只能读取、这次运行不是由它启动的,或请求来自另一个来源的页面
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 分钟,同一个条目 24 小时内最多启动 4 次,以及保留保护。后三项把通过 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 KiB。不在列表上的路由返回 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 可以通过 MQTT 发现,作为一台设备出现在 Home Assistant 里。Home Assistant 需要它的 MQTT 集成和一个代理,例如 Mosquitto 加载项。不涉及任何自定义组件。

  1. 在 BombVault 里打开设置、集成,在服务卡片里开启 Home Assistant。代理的字段会出现在它下面。
  2. 输入代理的地址和端口,如果它要求,再输入用户名和密码。如果代理支持 TLS,就开启使用 TLS,通常是 8883 端口。它的证书必须对你输入的地址有效。如果你更改了地址、端口或用户名,请重新输入密码:BombVault 不会把保存的密码传给另一个代理或用户。
  3. 点击保存。连接建立后,这一行会显示出来。

设备叫 BombVault,或者在括号里带上实例名称,有这些实体:

实体 显示什么
状态 ok、warning、overdue、failed 或 off,取开启的领域里最差的那个。等待首次备份的领域,只有在那次备份到期后才计入,而且只有处于最新状态的领域才会让状态变为 ok。overdue 与概览中一致,表示某个领域的最近一次备份已超过两个间隔
正在运行的作业 现在在运行什么,或 idle
未处理的异常 有多少异常未处理
下一次计划备份 下一次计划备份何时开始
领域上次备份 该领域上次成功备份的时间
领域上次结果 它上次备份如何结束
领域仓库可用空间 它的主仓库所在位置的可用空间,如果 BombVault 能读取的话
备份领域 一个按钮,备份整个领域

每个开启的领域都有自己的实体,关闭一个领域就会失去它们。开启按钮启动备份之后才会出现这些按钮。新安装时它是关闭的。它们遵循和通过 API 启动相同的限制。除此之外,BombVault 每个领域一次只处理一次按下,每分钟不超过六次,并忽略代理当作保留消息保存的按下。任何能向代理发布消息的人都可以按下它们,所以请给代理设置密码。

BombVault 每 15 秒读取一次自己的状态,有变化时就以 JSON 发布到 <prefix>/<node>/state 下。前缀是 bombvault,除非你更改,节点是 BombVault 选定一次的短 ID。发现消息发往 Home Assistant 的默认前缀 homeassistant。两者都是保留消息。如果 BombVault 没打招呼就停止,遗嘱消息会把设备标记为不可用。关闭这个连接会从 Home Assistant 中移除设备及其实体。

示例:一张卡片和一个提醒

Home Assistant 根据名称生成实体 ID,所以 BombVault 设备的 ID 形如 sensor.bombvault_status。如果括号里有实例名称,ID 里也会带上,所以请先在 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会在网页界面端口的 /metrics 上,为 Prometheus、Grafana 或 Uptime Kuma 提供备份状态、大小和时间戳。默认是关闭的。抓取令牌(可选)会让抓取程序发送一个 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 地址。