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 จะแสดงความคืบหน้า

ตัวอย่าง

# การสำรองข้อมูลเป็นอย่างไรบ้าง
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 ไม่ต้องใช้คอมโพเนนต์เฉพาะ

1. ใน BombVault เปิด การตั้งค่า, การเชื่อมต่อ, Home Assistant
2. ใส่ที่อยู่และพอร์ตของโบรกเกอร์ รวมถึงชื่อผู้ใช้และรหัสผ่านหากโบรกเกอร์ต้องการ เปิด ใช้ TLS หากโบรกเกอร์ใช้ TLS ซึ่งปกติอยู่ที่พอร์ต 8883 ใบรับรองของโบรกเกอร์ต้องใช้ได้กับที่อยู่ที่คุณใส่ ถ้าเปลี่ยนที่อยู่ พอร์ต หรือชื่อผู้ใช้ ให้ใส่รหัสผ่านใหม่อีกครั้ง BombVault จะไม่ส่งรหัสผ่านที่บันทึกไว้ต่อให้โบรกเกอร์หรือผู้ใช้อื่น
3. เปิด เชื่อมต่อกับ 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://bombvault.local:3000 เมื่อใช้ HTTP_ONLY และเครื่องมือค้นหาบริการจะแสดงเป็นเว็บเซอร์วิสที่มีชนิดย่อย _bombvault ระเบียน TXT มีเวอร์ชันและพาธ สวิตช์อยู่ที่ การตั้งค่า, การเชื่อมต่อ, ค้นหาในเครือข่าย และเปิดไว้ตั้งแต่แรก หากอุปกรณ์อื่นใช้ชื่อนี้อยู่แล้ว BombVault จะใช้ bombvault-2.local และถัดไปตามลำดับ โดยการ์ดจะแสดงที่อยู่ที่ได้ เมื่อ BombVault หยุดหรือคุณปิดการประกาศ BombVault จะแจ้งเครือข่าย เบราว์เซอร์จึงลบรายการออกทันที

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

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

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