API và tích hợp¶
BombVault có một HTTP API nhỏ dành cho script, bảng điều khiển và tự động hóa nhà thông minh. Nó đọc những gì Tổng quan hiển thị và có thể bắt đầu một bản sao lưu. Mọi thứ khác, như khôi phục, xóa bản sao lưu, cài đặt và node, vẫn nằm trong giao diện web.
Mã thông báo¶
Mỗi yêu cầu cần một mã thông báo API, kể cả khi chưa đặt mật khẩu đăng nhập. Tạo mã tại Cài đặt, Tích hợp, Mã thông báo API:
- Nhập một cái tên cho biết mã được dùng ở đâu, ví dụ "Home Assistant" hoặc "Uptime Kuma".
- Bật Cho phép bắt đầu sao lưu nếu mã cần bắt đầu sao lưu. Nếu không, mã chỉ đọc được.
- Bấm Tạo mã thông báo. Mã chỉ hiện một lần. BombVault chỉ giữ dấu vân tay của nó, nên hãy sao chép ngay.
Gửi mã trong một tiêu đề, Authorization: Bearer <token> hoặc X-API-Key: <token>. Mã bắt đầu bằng bvapi_. Nó chỉ mở API: khóa MCP không dùng được ở đây, và mã thông báo không dùng được cho MCP.
Mỗi mã có một ô hiển thị tên, có được bắt đầu sao lưu không, bốn ký tự cuối, thời điểm và nơi dùng gần nhất, và số lượt gọi hôm nay. Trên ô, bạn có thể đổi tên, đổi quyền, thay hoặc thu hồi mã. Nhật ký hiển thị các bản sao lưu mã đã bắt đầu và các lượt gọi gần đây. Khôi phục cấu hình BombVault từ bản sao lưu sẽ thu hồi mọi mã, vì bản sao lưu có thể chứa mã bạn đã thu hồi sau đó.
Khi chưa có mật khẩu đăng nhập, ai mở được giao diện web cũng tạo được mã. Nếu bạn mở BombVault bằng một tên trông như công khai và chưa có mật khẩu, không thể tạo mã từ địa chỉ đó, giống như với khóa MCP.
Điểm cuối¶
| Tuyến | Trả về hoặc làm gì | Mã |
|---|---|---|
GET /api/v1/health |
Phiên bản, tên phiên bản chạy, có bản sao lưu đang chạy không và mã này được làm gì | đọc |
GET /api/v1/status |
Trạng thái bảo vệ theo phần: bản sao lưu thành công gần nhất, khoảng thời gian dự kiến, kiểm tra, lần chạy theo lịch tiếp theo | đọc |
GET /api/v1/activity |
Những gì đang chạy lúc này, kèm giai đoạn và phần trăm | đọc |
GET /api/v1/items |
Mọi mục được bảo vệ với lịch, những gì một bản sao lưu dừng và bản sao lưu gần nhất. ?domain= cho một phần |
đọc |
GET /api/v1/runs |
Lịch sử chạy, mới nhất trước. Bộ lọc limit, domain, item, status, kind, since |
đọc |
GET /api/v1/anomalies |
Bất thường kèm tóm tắt những mục còn mở. Bộ lọc state, severity, domain, limit |
đọc |
GET /api/v1/anomalies/{id} |
Một bất thường | đọc |
GET /api/v1/storage/{domain} |
Lịch sử dung lượng, mức tăng mỗi tuần và dung lượng trống của từng kho trong một phần | đọc |
POST /api/v1/backups |
Sao lưu một mục ({"domain":"containers","item":"plex"}) hoặc cả phần ({"domain":"vms"}) |
bắt đầu |
POST /api/v1/backups/everything |
Chạy Sao lưu toàn bộ | bắt đầu |
POST /api/v1/runs/{id}/cancel |
Hủy một bản sao lưu đang chạy do mã này bắt đầu | bắt đầu |
Các phần là containers, vms, files, zfs, flash và config. Thời gian tính bằng giây Unix. Câu trả lời giống với công cụ MCP cùng tên, nên hai bên luôn khớp nhau.
Bản sao lưu bắt đầu từ đây giống bản sao lưu mà giao diện web bắt đầu: container đang chạy sẽ dừng cho tới khi bản sao lưu xong. Yêu cầu trả về ngay, và /api/v1/activity cùng /api/v1/runs cho thấy tiến trình.
Ví dụ¶
# Các bản sao lưu thế nào rồi?
curl -s -H "Authorization: Bearer $BOMBVAULT_TOKEN" https://tower:3443/api/v1/status
# Sao lưu một container ngay bây giờ.
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
Với chứng chỉ tự ký của BombVault, thêm --cacert bombvault-cert.pem (tệp lấy từ Tải chứng chỉ trên thẻ MCP) hoặc -k trên mạng bạn tin cậy.
Lỗi và giới hạn¶
Lỗi trả về dưới dạng {"error": {"code": "...", "message": "..."}} kèm trạng thái tương ứng:
| Trạng thái | Mã lỗi | Ý nghĩa |
|---|---|---|
| 400 | invalid_argument, ambiguous |
Thiếu tham số hoặc tham số sai |
| 401 | no_token, invalid_token |
Không có mã, hoặc mã không còn hoạt động |
| 403 | not_permitted, forbidden_origin |
Mã chỉ được đọc, hoặc không phải mã đã bắt đầu lần chạy đó, hoặc yêu cầu đến từ một trang có nguồn gốc (origin) khác |
| 404 | not_found |
Không có mục, lần chạy hoặc bất thường đó |
| 409 | busy, domain_off, nothing_to_back_up, not_running |
Đã có việc khác đang chạy, phần đang tắt, hoặc không có gì để làm |
| 429 | throttled, rate_limited, cooldown, retention_guard |
Một giới hạn giữ yêu cầu lại. Retry-After cho biết khi nào thử lại |
Việc bắt đầu tuân theo cùng giới hạn như bắt đầu qua MCP: 12 lần mỗi giờ cho mỗi mã, cách nhau 15 phút giữa hai lần bắt đầu cùng một mục, tối đa 4 lần cho một mục trong 24 giờ, và cơ chế bảo vệ lưu giữ. Ba giới hạn sau tính chung các lần bắt đầu qua MCP, qua API và từ Home Assistant. Một mã được gửi 120 yêu cầu mỗi phút. Năm lần thử thất bại từ một địa chỉ sẽ khóa địa chỉ đó trong một phút.
OpenAPI¶
BombVault cung cấp mô tả các tuyến này tại /api/v1/openapi.json (OpenAPI 3.1). Không cần mã thông báo. Hãy nạp nó vào Swagger UI, Postman hoặc một trình tạo mã.
Node¶
Các route chăm sóc node thuộc về giao diện web, không thuộc API dùng token ở trên. Khi đã đặt mật khẩu đăng nhập, chúng cần một phiên trình duyệt từ lần đăng nhập tại phiên bản này. Token API hay khóa MCP không mở được route nào trong số đó, điện thoại đã ghép nối không tới được chúng, và /api/v1/openapi.json không mô tả chúng. Thêm node, hiện lại tệp compose của nó và tới các route riêng của node đều bị từ chối cho đến khi đặt mật khẩu đăng nhập. Một script thay đổi gì đó sẽ gửi Content-Type: application/json, như ở mọi nơi trong giao diện web.
| Route | Tác dụng |
|---|---|
GET /api/nodes |
Mọi node cùng việc nó có trực tuyến không, phiên bản, nơi gửi bản sao lưu, kế hoạch của từng phần, bản sao lưu gần nhất, lỗi và các bất thường còn mở |
POST /api/nodes |
Thêm một node, như {"name":"vps-helsinki"}, và trả nó về kèm compose: MODE, APP_KEY, NODE_HOME và NODE_NAME |
POST /api/nodes/{id}/compose |
Trả lại cùng các giá trị compose, cho Thay thế |
POST /api/nodes/{id}/placement |
Gửi bản sao lưu của node tới một nơi và trả lời theo từng phần xem node có tới được kho của nó không, kèm một warning cho đích sao lưu |
PUT /api/nodes/{id}/schedule |
Đặt kế hoạch, như {"containers":"daily 03:00","files":"off"}. Phần nào không có trong đó thì giữ kế hoạch cũ |
DELETE /api/nodes/{id} |
Giải phóng node. told cho biết node đã nghe ngay hay sẽ nghe khi quay lại |
GET /api/nodes/routes |
Danh sách các route riêng của node mà phiên bản chủ chuyển yêu cầu tới |
GET, POST, PATCH /api/nodes/{id}/api/{path} |
Chuyển yêu cầu tới route /api/{path} của node khi route đó có trong danh sách, và trả về câu trả lời JSON của node |
PUT /api/receiver/node-address |
Đặt Địa chỉ cho node của máy chủ nhận, như {"url":"https://backup.tower.example.org","caPem":""}. Một url trống sẽ đưa các node ra khỏi đó |
Ba loại đích:
{"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"}
Một yêu cầu tới /api/nodes/{id}/api/... mang tối đa 32 KiB. Một route không có trong danh sách trả 403, một node chưa trả lời hoặc đang được giải phóng trả 409 với mã node-not-adopted, và một node đang vắng mặt trả 502 với mã node-away. Ví dụ, GET /api/nodes/{id}/api/runs?limit=20 trả về 20 lượt chạy gần nhất của node, và POST /api/nodes/{id}/api/containers/nextcloud/backup sao lưu container nextcloud của nó.
Home Assistant¶
BombVault có thể xuất hiện trong Home Assistant như một thiết bị, nhờ cơ chế khám phá MQTT. Home Assistant cần tích hợp MQTT của nó và một broker, ví dụ tiện ích bổ sung Mosquitto. Không cần thành phần riêng nào.
- Trong BombVault, mở Cài đặt, Tích hợp và bật Home Assistant trong thẻ Dịch vụ. Các trường cho broker hiện bên dưới nó.
- Nhập địa chỉ và cổng của broker, cùng tên người dùng và mật khẩu nếu broker yêu cầu. Bật Dùng TLS nếu broker dùng TLS, thường ở cổng 8883. Chứng chỉ của broker phải hợp lệ cho địa chỉ bạn nhập. Nếu bạn đổi địa chỉ, cổng hoặc tên người dùng, hãy nhập lại mật khẩu: BombVault không chuyển mật khẩu đã lưu sang broker hay người dùng khác.
- Bấm Lưu. Hàng sẽ cho biết khi kết nối đã thông.
Thiết bị có tên BombVault, hoặc BombVault kèm tên phiên bản chạy trong ngoặc, và có các thực thể sau:
| Thực thể | Hiển thị gì |
|---|---|
| Status | ok, warning, overdue, failed hoặc off, trạng thái tệ nhất trong các phần đang bật. Phần đang chờ bản sao lưu đầu tiên chỉ được tính sau khi đến hạn của bản đó, và trạng thái chỉ là ok khi có một phần còn mới. overdue nghĩa là, như ở trang tổng quan, bản sao lưu gần nhất của một phần đã cũ hơn hai chu kỳ |
| Running job | Việc đang chạy, hoặc idle |
| Open anomalies | Số bất thường còn mở |
| Next scheduled backup | Khi nào bản sao lưu theo lịch tiếp theo bắt đầu |
| Phần last backup | Khi nào bản sao lưu thành công gần nhất của phần chạy |
| Phần last result | Bản sao lưu gần nhất kết thúc ra sao |
| Phần repository free space | Dung lượng trống nơi đặt kho chính của phần, nếu BombVault đọc được |
| Back up phần | Nút sao lưu cả phần |
Tên thực thể bằng tiếng Anh, vì Home Assistant dùng đúng tên BombVault gửi. Mỗi phần đang bật có thực thể riêng, và phần bạn tắt sẽ mất chúng. Các nút xuất hiện khi bạn bật Nút bấm bắt đầu sao lưu, mục này tắt khi mới cài đặt. Các nút tuân theo cùng giới hạn như bắt đầu qua API. Ngoài ra BombVault chỉ nhận mỗi lần một lần bấm cho mỗi phần và tối đa sáu lần mỗi phút, đồng thời bỏ qua lần bấm mà broker giữ lại dưới dạng tin nhắn retained. Ai công bố được lên broker đều bấm được, nên hãy đặt mật khẩu cho broker.
BombVault đọc trạng thái của mình mỗi 15 giây và công bố khi có thay đổi, dạng JSON tại <tiền tố>/<nút>/state. Tiền tố là bombvault nếu bạn không đổi, còn nút là một mã ngắn BombVault chọn một lần. Các thông điệp khám phá đi tới tiền tố mặc định của Home Assistant là homeassistant. Cả hai đều được giữ lại (retained). Thông điệp di chúc (last will) đánh dấu thiết bị là không khả dụng nếu BombVault dừng mà không báo trước. Khi tắt liên kết, BombVault gỡ thiết bị và các thực thể của nó khỏi Home Assistant.
Ví dụ: một thẻ và một cảnh báo¶
Home Assistant tạo id thực thể từ tên, nên thiết bị BombVault nhận các id như sensor.bombvault_status. Khi tên phiên bản đứng trong ngoặc, các id cũng mang tên đó, vì vậy hãy xem chúng trước dưới Developer Tools, States. Một thẻ cho bảng điều khiển:
type: entities
title: Backups
entities:
- sensor.bombvault_status
- sensor.bombvault_running_job
- sensor.bombvault_open_anomalies
- sensor.bombvault_next_scheduled_backup
Một automation báo cho điện thoại của bạn khi trạng thái chuyển sang failed hoặc 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¶
Cung cấp /metrics trong thẻ Dịch vụ dưới Cài đặt, Tích hợp phục vụ trạng thái sao lưu, dung lượng và dấu thời gian cho Prometheus, Grafana hoặc Uptime Kuma, tại /metrics trên cổng của giao diện web. Tùy chọn này tắt theo mặc định. Token scrape (tùy chọn) khiến bộ scrape gửi một bearer token. Các nhãn không chứa bí mật hay đường dẫn nào.
Widget bảng điều khiển¶
Thẻ Widget bảng điều khiển dưới Cài đặt, Tích hợp tạo một token chỉ đọc và đưa cho bạn một địa chỉ dùng cho bất kỳ bảng điều khiển nào hiển thị iframe, như Homepage, Organizr hoặc Heimdall. Địa chỉ đó mở một trang nhỏ tại /widget chỉ với nhật ký hoạt động trực tiếp. Token chỉ cấp quyền cho nhật ký đó và không gì khác, và Tắt thu hồi nó ngay lập tức. Trang được nhúng chỉ có tiếng Anh.
Tìm BombVault trên mạng¶
BombVault quảng bá giao diện web của mình trên mạng cục bộ qua mDNS, giao thức đứng sau Bonjour và Avahi. Khi đó trình duyệt vào được bằng https://bombvault.local:3443, hoặc http://bombvault.local:3000 khi dùng HTTP_ONLY, và các trình duyệt dịch vụ liệt kê nó là dịch vụ web với kiểu con _bombvault. Các bản ghi TXT chứa phiên bản và đường dẫn. Công tắc là Tìm trên mạng trong thẻ Dịch vụ dưới Cài đặt, Tích hợp và được bật sẵn. Nếu thiết bị khác đã dùng tên này, BombVault lấy bombvault-2.local và cứ thế tiếp tục, còn thẻ hiện địa chỉ nó nhận được. Khi BombVault dừng hoặc bạn tắt quảng bá, nó báo cho mạng biết, nên trình duyệt gỡ mục đó ngay.
Lời quảng bá có tới được mạng của bạn hay không tùy vào cách container được kết nối:
- bridge, mặc định trong mẫu Unraid: lời quảng bá chỉ ở trong mạng của Docker và không ai trên LAN thấy. Hãy mở BombVault bằng địa chỉ của máy chủ như trước.
- br0 hoặc một mạng macvlan hay ipvlan khác: container có địa chỉ riêng trên LAN và lời quảng bá tới được đó.
- host: lời quảng bá đi ra qua các giao diện của máy chủ, bên cạnh lời quảng bá của chính Unraid. Các cầu nối của Docker và libvirt bị bỏ qua.
Chỉ quảng bá địa chỉ IPv4.