# 資源調整端點

本頁說明調整已停止 VM 的 vCPU、記憶體、磁碟與所在節點的四個端點。

全部端點要求 VM 為停止狀態，並受 `ALLOW_IPS` 與停用清單限制；指令依 [多節點調度](/zh/multi-node-dispatch) 在 VM 所在節點執行。

## 一覽

| 端點 | 欄位 | 驗證 | `qm` 指令 | 回應 |
|---|---|---|---|---|
| `POST /api/vm/:id/set/cpu` | `cpu` int | 必填，1–32 | `qm set --cores` | 文字 `ok` |
| `POST /api/vm/:id/set/memory` | `memory` int | 必填，512–32768（MB） | `qm set --memory` | 文字 `ok` |
| `POST /api/vm/:id/set/disk` | `disk` string | 無 | `qm disk resize scsi0 +<disk>` | 文字 `ok` |
| `POST /api/vm/:id/set/node` | `node` string | 必填 | `qm migrate --with-local-disks` | SSE |

這些端點的上限固定在程式中，不受 `VM_MAX_CPU`／`VM_MAX_RAM`／`VM_MAX_DISK` 影響。

## vCPU

```bash
curl -X POST http://192.168.0.11:8080/api/vm/120/set/cpu \
  -H "Content-Type: application/json" -d '{"cpu": 4}'
# ok
```

## 記憶體

```bash
curl -X POST http://192.168.0.11:8080/api/vm/120/set/memory \
  -H "Content-Type: application/json" -d '{"memory": 8192}'
# ok
```

設定 `VM_BALLOON_MIN` 且 `memory` ≥ `VM_BALLOON_MIN` + 1024 時，會一併送出 `--numa 1 --balloon <memory − VM_BALLOON_MIN>`。低於門檻時不送 `--balloon`，VM 既有的 Balloon 設定維持不變。

## 磁碟

```bash
curl -X POST http://192.168.0.11:8080/api/vm/120/set/disk \
  -H "Content-Type: application/json" -d '{"disk": "16G"}'
# ok
```

`disk` 是**增量**：上例讓 `scsi0` 增加 16G。Proxmox 不支援縮小磁碟；值會原樣傳給 `qm`，格式錯誤時回 `500` 並附上 `qm` 輸出。擴充後需在 VM 內自行擴展分割區與檔案系統。

## 遷移節點

```bash
curl -N -X POST http://192.168.0.11:8080/api/vm/120/set/node \
  -H "Content-Type: application/json" -d '{"node": "pve2"}'
```

`qm migrate` 的輸出逐行以 SSE 回傳，`step` 為 `migrating`，完成後 `event: close`。目標節點的 CPU 指令集需涵蓋 VM 的 CPU 類型，見 [CPU 基準](/zh/cpu-baseline)。

## 錯誤回應

| 情況 | 回應 |
|---|---|
| 來源 IP 不在 `ALLOW_IPS` | `403`（`set/node` 為單行 `data:`） |
| VM 執行中或在停用清單 | `400`（`set/node` 為單行 `data:`） |
| 欄位驗證失敗 | `400 invalid request body: ...` |
| `qm` 失敗 | `500`（`set/node` 為 `data:` 錯誤） |