v0.1.7

建立 VM 端點

最後更新


本頁說明 POST /api/vm/install 的請求欄位、預設值與回應。

請求


  1. curl -N -X POST http://192.168.0.11:8080/api/vm/install \
  2. -H "Content-Type: application/json" \
  3. -d '{
  4. "name": "web",
  5. "os": "ubuntu",
  6. "version": "24.04",
  7. "cpu": 2,
  8. "ram": 4096,
  9. "disk": "32G",
  10. "node": "pve2",
  11. "pubkey": "ssh-ed25519 AAAA... user@laptop"
  12. }'

欄位


欄位型別必要預設規則
osstring是—debian/ubuntu/rockylinux
versionstring是—見 支援版本
idint否自動配置指定時直接使用,不檢查是否占用;同時決定 IP 末段
namestring否VMID實際名稱為 <name>-<vmid>
nodestring否主節點建立後遷移到此節點再開機
cpuint否1≤ 0 → 1;上限 VM_MAX_CPU
ramint否512MB;< 512 → 512;上限 VM_MAX_RAM
diskstring否16G解析去掉 G 的數字;< 16 → 16G;≥ VM_MAX_DISK → 上限值
userstring否依 OSCloud-Init 使用者;預設 debian/ubuntu/rocky
passwdstring否passwdCloud-Init 使用者密碼
pubkeystring否—追加注入的 SSH 公鑰

ip、gateway、storage 由伺服器依 VMID、GATEWAY、ASSIGN_STORAGE 覆寫,傳入無效。
SSH 就緒檢查固定以 OS 預設使用者(debian/ubuntu/rocky)登入,初始化腳本則以 user 登入;自訂 user 時,兩個帳號都必須能以主節點金鑰登入。

回應


情況回應
JSON 解析或 os/version 驗證失敗400 JSON:{"success": false, "message": "please check your input:..."}
來源 IP 不在 ALLOW_IPS200 單行 data: 錯誤訊息
其他SSE 串流,逐步回報 佈建流程 各階段,最後 event: close

成功時最後四個事件:
  1. data: {"step":"VM initialization > finalizing","status":"success","message":"[+] VM installation completed in 182.41s"}
  2. data: {"step":"VM initialization > finalizing","status":"success","message":"[*] VMID: 120"}
  3. data: {"step":"VM initialization > finalizing","status":"success","message":"[*] IP: 192.168.0.120"}
  4. data: {"step":"VM initialization > finalizing","status":"success","message":"[*] User: ubuntu"}

SSE 串流一律回 HTTP 200;是否成功要看是否出現 status: "error" 的事件。
EN