快速開始
本頁帶你在 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