v0.1.7

快速開始

最後更新


本頁帶你在 Proxmox VE 主節點上建置 QemuRun-pve,並以一次 API 呼叫建立第一台 VM。

前置需求


項目要求
執行位置Proxmox VE 叢集的主節點,以 root 執行(需要 qm、pvesh、pvesm 與 /etc/pve/nodes 讀取權限)
Go1.25 以上(go.mod),僅自原始碼建置時需要
節點間 SSH主節點可用金鑰以 root 免密碼 SSH 到其他所有節點
網段/24,VM 的 IP 末段等於 VMID,因此 VMID 需落在 100–254
儲存池啟用中、類型為 dir/zfspool/lvmthin/nfs,且可建立 cloudinit 磁碟
對外連線主節點可下載 Debian、Rocky Linux、Ubuntu 官方 Cloud Image

建置與啟動


服務以工作目錄為基準讀取 .env、sh/ 與 .go_qemu_* 狀態檔,因此直接在 clone 下來的目錄執行。
  1. git clone https://github.com/pardnchiu/QemuRun-pve.git
  2. cd QemuRun-pve
  3. cp .env.example .env
  4. touch .go_qemu_disabled
  5. go build -o QemuRun-pve ./cmd/api
  6. ./QemuRun-pve

啟動時會逐行印出已註冊路由,最後輸出 goQemu run at localhost:<PORT>。PORT 或 GATEWAY 未設定時直接結束;其餘變數見 環境變數。
.go_qemu_disabled 即使沒有內容也必須存在,否則 VM 清單與所有需檢查 VM 狀態的端點都會失敗,詳見 狀態檔。

確認服務


  1. curl http://192.168.0.11:8080/api/health
  2. # ok
  3. curl http://192.168.0.11:8080/api/vm/list

建立第一台 VM


-N 關閉 curl 緩衝,才能即時看到 SSE 進度。未帶 id 時自動配置 VMID 與 IP。
  1. curl -N -X POST http://192.168.0.11:8080/api/vm/install \
  2. -H "Content-Type: application/json" \
  3. -d '{"os": "debian", "version": "12", "cpu": 2, "ram": 4096, "disk": "32G"}'

串流結尾會列出 VMID、IP 與登入使用者,接著以 event: close 結束:
  1. data: {"step":"VM initialization > finalizing","status":"success","message":"[*] VMID: 120"}
  2. data: {"step":"VM initialization > finalizing","status":"success","message":"[*] IP: 192.168.0.120"}
  3. data: {"step":"VM initialization > finalizing","status":"success","message":"[*] User: debian"}
  4. event: close
  5. data: {}

此時可用主節點的 SSH 金鑰登入:
  1. ssh debian@192.168.0.120

下一步


EN