快速開始
最後更新
本頁帶你在 Proxmox VE 主節點上建置 QemuRun-pve,並以一次 API 呼叫建立第一台 VM。
前置需求
| 項目 | 要求 |
|---|---|
| 執行位置 | Proxmox VE 叢集的主節點,以 root 執行(需要 qm、pvesh、pvesm 與 /etc/pve/nodes 讀取權限) |
| Go | 1.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 下來的目錄執行。- git clone https://github.com/pardnchiu/QemuRun-pve.git
- cd QemuRun-pve
- cp .env.example .env
- touch .go_qemu_disabled
- go build -o QemuRun-pve ./cmd/api
- ./QemuRun-pve
啟動時會逐行印出已註冊路由,最後輸出
goQemu run at localhost:<PORT>。PORT 或 GATEWAY 未設定時直接結束;其餘變數見 環境變數。.go_qemu_disabled 即使沒有內容也必須存在,否則 VM 清單與所有需檢查 VM 狀態的端點都會失敗,詳見 狀態檔。確認服務
- curl http://192.168.0.11:8080/api/health
- # ok
- curl http://192.168.0.11:8080/api/vm/list
建立第一台 VM
-N 關閉 curl 緩衝,才能即時看到 SSE 進度。未帶 id 時自動配置 VMID 與 IP。- curl -N -X POST http://192.168.0.11:8080/api/vm/install \
- -H "Content-Type: application/json" \
- -d '{"os": "debian", "version": "12", "cpu": 2, "ram": 4096, "disk": "32G"}'
串流結尾會列出 VMID、IP 與登入使用者,接著以
event: close 結束:- data: {"step":"VM initialization > finalizing","status":"success","message":"[*] VMID: 120"}
- data: {"step":"VM initialization > finalizing","status":"success","message":"[*] IP: 192.168.0.120"}
- data: {"step":"VM initialization > finalizing","status":"success","message":"[*] User: debian"}
- event: close
- data: {}
此時可用主節點的 SSH 金鑰登入:
- ssh debian@192.168.0.120