# 快速開始

本頁帶你在 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 下來的目錄執行。

```bash
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` 未設定時直接結束；其餘變數見 [環境變數](/zh/configuration)。

`.go_qemu_disabled` 即使沒有內容也必須存在，否則 VM 清單與所有需檢查 VM 狀態的端點都會失敗，詳見 [狀態檔](/zh/state-files)。

## 確認服務

```bash
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。

```bash
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` 結束：

```text
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 金鑰登入：

```bash
ssh debian@192.168.0.120
```

## 下一步

- 常駐執行與 Release 執行檔：[部署](/zh/deployment)
- 每個階段在做什麼：[佈建流程](/zh/provisioning-pipeline)
- 完整請求欄位：[建立 VM 端點](/zh/api-install)