ข้ามไปที่เนื้อหา

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

Endpoint

เส้นทาง ส่งคืนหรือทำอะไร โทเคน
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 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 ปรากฏใน Home Assistant เป็นอุปกรณ์ได้ ผ่าน MQTT discovery Home Assistant ต้องมีอินทิเกรชัน MQTT และโบรกเกอร์ เช่นแอดออน Mosquitto ไม่ต้องใช้คอมโพเนนต์กำหนดเอง

  1. ใน BombVault เปิด การตั้งค่า, การเชื่อมต่อ แล้วเปิด Home Assistant ในการ์ด บริการ ฟิลด์สำหรับโบรกเกอร์จะปรากฏด้านล่าง
  2. กรอกที่อยู่และพอร์ตของโบรกเกอร์ และชื่อผู้ใช้กับรหัสผ่านถ้ามันขอ เปิด ใช้ TLS ถ้าโบรกเกอร์รับ TLS ซึ่งมักอยู่ที่พอร์ต 8883 ใบรับรองของมันต้องใช้ได้กับที่อยู่ที่คุณกรอก ถ้าคุณเปลี่ยนที่อยู่ พอร์ต หรือชื่อผู้ใช้ ให้กรอกรหัสผ่านอีกครั้ง BombVault จะไม่ส่งรหัสผ่านที่เก็บไว้ไปยังโบรกเกอร์หรือผู้ใช้อื่น
  3. คลิก บันทึก แถวจะแสดงเมื่อการเชื่อมต่อพร้อม

อุปกรณ์ชื่อ 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 prefix คือ bombvault เว้นแต่คุณเปลี่ยน และ node คือ id สั้น ๆ ที่ BombVault เลือกครั้งเดียว ข้อความ discovery ไปที่ prefix เริ่มต้นของ Home Assistant คือ homeassistant ทั้งสองแบบ retained ข้อความ last will ทำเครื่องหมายอุปกรณ์ว่าไม่พร้อมใช้งานถ้า 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 ในการ์ด บริการ ใต้ การตั้งค่า, การเชื่อมต่อ ให้สถานะการสำรองข้อมูล ขนาด และเวลาสำหรับ Prometheus, Grafana หรือ Uptime Kuma ที่ /metrics บนพอร์ตของหน้าเว็บ ปิดอยู่โดยค่าเริ่มต้น โทเค็น scrape (ไม่บังคับ) ให้ตัว scrape ส่ง bearer token ป้ายกำกับไม่มีความลับและไม่มีพาธ

วิดเจ็ตแดชบอร์ด

การ์ด วิดเจ็ตแดชบอร์ด ใต้ การตั้งค่า, การเชื่อมต่อ สร้างโทเคนแบบอ่านอย่างเดียวและให้ที่อยู่สำหรับแดชบอร์ดใดก็ได้ที่แสดง iframe เช่น Homepage, Organizr หรือ Heimdall ที่อยู่นั้นเปิดหน้าเล็ก ๆ ที่ /widget ซึ่งมีเพียงบันทึกกิจกรรมสด โทเคนให้สิทธิ์เฉพาะบันทึกนั้นและไม่มีอย่างอื่น และ ปิดใช้งาน เพิกถอนทันที หน้าที่ฝังเป็นภาษาอังกฤษเท่านั้น

ค้นหา BombVault ในเครือข่าย

BombVault ประกาศหน้าเว็บของตัวเองในเครือข่ายภายในผ่าน mDNS ซึ่งเป็นโปรโตคอลเบื้องหลัง Bonjour และ Avahi เบราว์เซอร์จึงเข้าถึงมันเป็น https://bombvault.local:3443 หรือ http://bombvault.local:3000 เมื่อใช้ HTTP_ONLY และตัวเรียกดูบริการลิสต์มันเป็นบริการเว็บที่มี subtype _bombvault เรกคอร์ด TXT ของมันมีเวอร์ชันและพาธ สวิตช์คือ ค้นหาในเครือข่าย ในการ์ด บริการ ใต้ การตั้งค่า, การเชื่อมต่อ และเปิดอยู่โดยค่าเริ่มต้น ถ้าอุปกรณ์อื่นใช้ชื่อนี้อยู่แล้ว BombVault จะใช้ bombvault-2.local และต่อไปเรื่อย ๆ และการ์ดแสดงที่อยู่ที่ได้ เมื่อ BombVault หยุดหรือคุณปิดการประกาศ มันจะบอกเครือข่าย เบราว์เซอร์จึงเอารายการออกทันที

การประกาศไปถึงเครือข่ายของคุณหรือไม่ขึ้นกับวิธีเชื่อมต่อคอนเทนเนอร์

  • bridge ค่าเริ่มต้นในเทมเพลต Unraid: การประกาศอยู่ภายในเครือข่ายของ Docker และไม่มีใครบน LAN เห็น เปิด BombVault ด้วยที่อยู่ของโฮสต์เหมือนเดิม
  • br0 หรือเครือข่าย macvlan หรือ ipvlan อื่น: คอนเทนเนอร์มีที่อยู่ของตัวเองบน LAN และการประกาศไปถึง
  • host: การประกาศออกไปทางอินเทอร์เฟซของโฮสต์ ถัดจากของ Unraid เอง และข้ามบริดจ์ของ Docker และ libvirt

ประกาศเฉพาะที่อยู่ IPv4