# 查詢端點

本頁說明健康檢查、單台 VM 狀態與叢集 VM 清單三個唯讀端點。查詢端點不檢查 `ALLOW_IPS`。

## `GET /api/health`

```bash
curl http://192.168.0.11:8080/api/health
# ok
```

只確認行程存活，不檢查 Proxmox 或狀態檔。

## `GET /api/vm/:id/status`

```bash
curl http://192.168.0.11:8080/api/vm/120/status
# running
```

| 情況 | 回應 |
|---|---|
| 成功 | 文字，`qm status` 冒號後的值（`running`／`stopped`）；格式無法解析時為 `unknown` |
| `:id` 非數字 | `400` JSON `{"error": "invalid VM ID"}` |
| `qm status` 失敗 | `500 failed to get VM status: ...` |

只在主節點本機執行；查詢其他節點上的 VM 會失敗，請改用 `/vm/list`。

## `GET /api/vm/list`

```bash
curl "http://192.168.0.11:8080/api/vm/list?disable=0"
```

| `disable` | 回傳 |
|---|---|
| 省略 | 全部 VM，含停用清單 |
| `0` | 執行中且不在停用清單 |
| `1` | 已停止且不在停用清單 |

```json
{
  "count": 1,
  "list": [
    { "vmid": 120, "name": "web-120", "os": "debian", "running": true, "node": "pve1",
      "cpu": 2, "disk": 32, "memory": 4, "memory_used": 1 }
  ],
  "cluster": [
    { "node": "pve1", "max_cpu": 16, "max_memory": 62.7, "cpu": 12.5, "memory": 6.38,
      "memory_used": 1.59, "disk": 93.93, "running": true }
  ],
  "data": []
}
```

### `list[]`

| 欄位 | 說明 |
|---|---|
| `vmid` / `name` / `node` | 來自 `pvesh get /cluster/resources --type vm` |
| `os` | VM 的 Proxmox tag（本服務建立時寫入 `debian`／`ubuntu`／`rockylinux`）；停用清單項目為 `-` |
| `running` | `status == "running"`；停用清單項目固定 `true` |
| `cpu` | vCPU 數 |
| `disk` / `memory` / `memory_used` | GiB，整數截斷 |

依 `vmid` 遞增排序。

### `cluster[]`

| 欄位 | 說明 |
|---|---|
| `node` / `running` | 節點名稱與是否 `online` |
| `max_cpu` | 節點邏輯 CPU 數 |
| `max_memory` / `disk` | GiB，四捨五入到小數兩位 |
| `cpu` | 本次清單中 VM 的 vCPU 總和 ÷ `max_cpu`（%） |
| `memory` | 本次清單中 VM 的配置記憶體總和 ÷ `max_memory`（%） |
| `memory_used` | 本次清單中 VM 的實際使用記憶體總和 ÷ `max_memory`（%） |

百分比只計入通過 `disable` 篩選的 VM。依節點名稱排序。

### `data`

已棄用，內容與 `list` 相同，保留給舊版用戶端。