# Proxmox VE API 筆記

## 環境資訊

| 項目 | 值 |
|---|---|
| **PVE 版本** | 8.4.16 |
| **主機 IP（API 入口）** | 192.168.88.247（pve-002） |
| **叢集名稱** | PVECluster |
| **節點** | pve-000 (.73)、pve-001 (.249)、pve-002 (.247) |
| **VM/容器數量** | 25（13 VM + 12 LXC） |

> 三節點任一個 IP 都可以當 API 入口（同一管理介面）。

## API Token

| 項目 | 值 |
|---|---|
| **Token ID** | `root@pam!claude` |
| **Secret** | `17e96169-a32f-4e2d-951e-859c77770306` |
| **權限** | privsep=0（繼承 root 完整權限） |
| **到期** | 永不過期 |

另有舊 token `root@pam!monitor`（privsep=0），secret 已遺失。

## API 基本格式

```
https://192.168.88.247:8006/api2/json/<路徑>
```

## 認證方式

### API Token（推薦）

```bash
curl -sk https://192.168.88.247:8006/api2/json/<端點> \
  -H "Authorization: PVEAPIToken=root@pam!claude=17e96169-a32f-4e2d-951e-859c77770306"
```

### Ticket（帳密登入，2 小時過期）

```bash
# 1. 取得 ticket
curl -sk https://192.168.88.247:8006/api2/json/access/ticket \
  -d "username=root@pam&password=25915525"

# 回傳 ticket 和 CSRFPreventionToken

# 2. GET 請求
curl -sk https://192.168.88.247:8006/api2/json/<端點> \
  -b "PVEAuthCookie=<ticket>"

# 3. POST/PUT/DELETE 請求需額外帶 CSRF header
curl -sk -X POST https://192.168.88.247:8006/api2/json/<端點> \
  -b "PVEAuthCookie=<ticket>" \
  -H "CSRFPreventionToken: <csrf-token>" \
  -d "參數=值"
```

## 常用 API 端點

### 叢集與節點

| 用途 | 方法 | 端點 |
|---|---|---|
| API 版本 | GET | `/version` |
| 叢集狀態 | GET | `/cluster/status` |
| 叢集資源總覽 | GET | `/cluster/resources` |
| 僅 VM/容器 | GET | `/cluster/resources?type=vm` |
| 僅儲存 | GET | `/cluster/resources?type=storage` |
| 節點清單 | GET | `/nodes` |
| 單一節點狀態 | GET | `/nodes/{node}/status` |

### 虛擬機（QEMU）

| 用途 | 方法 | 端點 |
|---|---|---|
| 列出 VM | GET | `/nodes/{node}/qemu` |
| VM 狀態 | GET | `/nodes/{node}/qemu/{vmid}/status/current` |
| VM 設定 | GET | `/nodes/{node}/qemu/{vmid}/config` |
| 啟動 VM | POST | `/nodes/{node}/qemu/{vmid}/status/start` |
| 關閉 VM | POST | `/nodes/{node}/qemu/{vmid}/status/stop` |
| 重啟 VM | POST | `/nodes/{node}/qemu/{vmid}/status/reboot` |

### LXC 容器

| 用途 | 方法 | 端點 |
|---|---|---|
| 列出容器 | GET | `/nodes/{node}/lxc` |
| 容器狀態 | GET | `/nodes/{node}/lxc/{vmid}/status/current` |
| 啟動容器 | POST | `/nodes/{node}/lxc/{vmid}/status/start` |
| 停止容器 | POST | `/nodes/{node}/lxc/{vmid}/status/stop` |

### 儲存

| 用途 | 方法 | 端點 |
|---|---|---|
| 列出儲存 | GET | `/nodes/{node}/storage` |
| 儲存內容 | GET | `/nodes/{node}/storage/{storage}/content` |

### 使用者與權限

| 用途 | 方法 | 端點 |
|---|---|---|
| 列出使用者 | GET | `/access/users` |
| 列出角色 | GET | `/access/roles` |
| 列出 ACL | GET | `/access/acl` |

### 任務

| 用途 | 方法 | 端點 |
|---|---|---|
| 最近任務 | GET | `/nodes/{node}/tasks` |
| 任務狀態 | GET | `/nodes/{node}/tasks/{upid}/status` |

## Token 管理

```bash
# 建立新 token（SSH 到 PVE 主機執行，secret 只顯示一次）
pvesh create /access/users/root@pam/token/<名稱> --privsep 0 --expire 0

# 列出 token
pvesh get /access/users/root@pam/token --output-format json

# 刪除 token
pvesh delete /access/users/root@pam/token/<名稱>
```