文件 v0.1.7
首頁 GitHub

生命週期端點

本頁說明開機、重開、關機、強制停止與刪除 VM 的五個端點。

一覽

端點 qm 指令 VM 狀態要求 回應
POST /api/vm/:id/start qm start 停止中 SSE，等到 SSH 可登入
POST /api/vm/:id/reboot qm reboot 執行中 SSE，等到 SSH 可登入
POST /api/vm/:id/shutdown qm shutdown 執行中 文字 ok
POST /api/vm/:id/stop qm stop 執行中 文字 ok
POST /api/vm/:id/destroy qm destroy 停止中 文字 ok

全部受 ALLOW_IPS 與停用清單限制，指令依 多節點調度 在 VM 所在節點執行。

start／reboot

curl -N -X POST http://192.168.0.11:8080/api/vm/120/start

data: {"step":"starting VM","status":"success","message":"[+] VM starting (1.12s)"}

data: {"step":"waiting for SSH","status":"success","message":"[+] VM is ready (24.37s)"}

data: {"step":"finalizing","status":"info","message":"[+] VM started successfully"}

event: close
data: {}
步驟 行為
執行 qm start／qm reboot 失敗時送出錯誤訊息並結束
waiting for SSH 依 VM 的 OS tag 決定登入使用者（debian／ubuntu／rocky），每 5 秒嘗試一次，最多 60 次
finalizing 等待 5 秒後送出 info 事件

VM 沒有 OS tag（不是由本服務建立）時，waiting for SSH 以 OS user not found 失敗；開機指令本身已執行完成。

shutdown／stop

curl -X POST http://192.168.0.11:8080/api/vm/120/shutdown
# ok

shutdown 送出 ACPI 關機訊號並等待 qm shutdown 結束；stop 立即切斷電源。

destroy

curl -X POST http://192.168.0.11:8080/api/vm/120/destroy
# ok

只接受已停止的 VM，執行 qm destroy <vmid>（不帶 --purge）。刪除後該 VMID 與 IP 可再次被 自動配置 使用。

錯誤回應

情況 同步端點 SSE 端點
來源 IP 不在 ALLOW_IPS 403 單行 data: 錯誤
VM 狀態不符或在停用清單 400 單行 data: 錯誤
qm 失敗 500 failed to ... VM: <輸出> data: 錯誤後結束
EN