# 生命週期端點

本頁說明開機、重開、關機、強制停止與刪除 VM 的五個端點。

## 一覽

| 端點 | `qm` 指令 | VM 狀態要求 | 回應 |
|---|---|---|---|
| `POST /api/vm/:id/start` | `qm start` | 停止中 | SSE，等到 SSH 可登入 |
| `POST /api/vm/:id/reboot` | `qm reboot` | 執行中 | SSE，等到 SSH 可登入 |
| `POST /api/vm/:id/shutdown` | `qm shutdown` | 執行中 | 文字 `ok` |
| `POST /api/vm/:id/stop` | `qm stop` | 執行中 | 文字 `ok` |
| `POST /api/vm/:id/destroy` | `qm destroy` | 停止中 | 文字 `ok` |

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

## start／reboot

```bash
curl -N -X POST http://192.168.0.11:8080/api/vm/120/start
```

```text
data: {"step":"starting VM","status":"success","message":"[+] VM starting (1.12s)"}

data: {"step":"waiting for SSH","status":"success","message":"[+] VM is ready (24.37s)"}

data: {"step":"finalizing","status":"info","message":"[+] VM started successfully"}

event: close
data: {}
```

| 步驟 | 行為 |
|---|---|
| 執行 `qm start`／`qm reboot` | 失敗時送出錯誤訊息並結束 |
| `waiting for SSH` | 依 VM 的 OS tag 決定登入使用者（`debian`／`ubuntu`／`rocky`），每 5 秒嘗試一次，最多 60 次 |
| `finalizing` | 等待 5 秒後送出 `info` 事件 |

VM 沒有 OS tag（不是由本服務建立）時，`waiting for SSH` 以 `OS user not found` 失敗；開機指令本身已執行完成。

## shutdown／stop

```bash
curl -X POST http://192.168.0.11:8080/api/vm/120/shutdown
# ok
```

`shutdown` 送出 ACPI 關機訊號並等待 `qm shutdown` 結束；`stop` 立即切斷電源。

## destroy

```bash
curl -X POST http://192.168.0.11:8080/api/vm/120/destroy
# ok
```

只接受已停止的 VM，執行 `qm destroy <vmid>`（不帶 `--purge`）。刪除後該 VMID 與 IP 可再次被 [自動配置](/zh/vmid-ip-allocation) 使用。

## 錯誤回應

| 情況 | 同步端點 | SSE 端點 |
|---|---|---|
| 來源 IP 不在 `ALLOW_IPS` | `403` | 單行 `data:` 錯誤 |
| VM 狀態不符或在停用清單 | `400` | 單行 `data:` 錯誤 |
| `qm` 失敗 | `500 failed to ... VM: <輸出>` | `data:` 錯誤後結束 |