# Proxmox VE API 參考手冊

> 適用版本：PVE 8.4.14 | 基底 URL：`https://192.168.42.38:8006/api2/json/`

## 認證

### API Token（推薦）

```bash
# 在 Header 中帶入 Token
curl -sk https://192.168.42.38:8006/api2/json/<端點> \
  -H "Authorization: PVEAPIToken=root@pam!claude=fefcffca-df6e-48de-8adf-7907cd2ea879"
```

Token 格式：`PVEAPIToken=<使用者>!<token名稱>=<secret-uuid>`

### 現有 Token

| Token ID | privsep | 權限 | 狀態 |
|---|---|---|---|
| `root@pam!claude` | 0（繼承 root） | 完整權限 | 可用 |
| `root@pam!automation` | 1（獨立權限） | PVEAdmin 角色 | secret 已遺失 |

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

```bash
# 步驟 1：取得 ticket + CSRF token
RESPONSE=$(curl -sk https://192.168.42.38:8006/api2/json/access/ticket \
  -d "username=root@pam&password=<密碼>")

TICKET=$(echo $RESPONSE | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['ticket'])")
CSRF=$(echo $RESPONSE | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['CSRFPreventionToken'])")

# 步驟 2：GET 請求
curl -sk https://192.168.42.38:8006/api2/json/<端點> \
  -b "PVEAuthCookie=$TICKET"

# 步驟 3：POST/PUT/DELETE 請求（需額外帶 CSRF）
curl -sk -X POST https://192.168.42.38:8006/api2/json/<端點> \
  -b "PVEAuthCookie=$TICKET" \
  -H "CSRFPreventionToken: $CSRF" \
  -d "參數=值"
```

## 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/<名稱>

# 透過 API 建立
curl -sk -X POST https://192.168.42.38:8006/api2/json/access/users/root@pam/token/<名稱> \
  -H "Authorization: PVEAPIToken=root@pam!claude=fefcffca-df6e-48de-8adf-7907cd2ea879" \
  -d "privsep=0&expire=0"
```

## 端點參考

以下所有端點前綴為 `https://192.168.42.38:8006/api2/json`。

### 叢集

| 方法 | 端點 | 說明 |
|---|---|---|
| GET | `/version` | API 版本 |
| GET | `/cluster/status` | 叢集狀態與 quorum |
| GET | `/cluster/resources` | 所有資源總覽 |
| GET | `/cluster/resources?type=vm` | 僅 VM/容器 |
| GET | `/cluster/resources?type=storage` | 僅儲存 |
| GET | `/cluster/resources?type=node` | 僅節點 |

### 節點

| 方法 | 端點 | 說明 |
|---|---|---|
| GET | `/nodes` | 節點清單 |
| GET | `/nodes/{node}/status` | 節點詳細狀態 |
| GET | `/nodes/{node}/network` | 網路介面設定 |
| GET | `/nodes/{node}/storage` | 儲存清單 |
| GET | `/nodes/{node}/tasks` | 最近任務 |
| GET | `/nodes/{node}/tasks/{upid}/status` | 任務狀態 |

> `{node}` 可用值：`pve`、`pve-02`、`pve-03`

### QEMU 虛擬機

| 方法 | 端點 | 說明 |
|---|---|---|
| GET | `/nodes/{node}/qemu` | 列出該節點所有 VM |
| GET | `/nodes/{node}/qemu/{vmid}/status/current` | VM 當前狀態 |
| GET | `/nodes/{node}/qemu/{vmid}/config` | VM 設定 |
| PUT | `/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/shutdown` | 優雅關機 |
| POST | `/nodes/{node}/qemu/{vmid}/status/reboot` | 重啟 VM |
| POST | `/nodes/{node}/qemu/{vmid}/status/reset` | 硬重置 VM |
| POST | `/nodes/{node}/qemu/{vmid}/clone` | 複製 VM |
| POST | `/nodes/{node}/qemu/{vmid}/snapshot` | 建立快照 |
| GET | `/nodes/{node}/qemu/{vmid}/snapshot` | 列出快照 |
| DELETE | `/nodes/{node}/qemu/{vmid}` | 刪除 VM |

### LXC 容器

| 方法 | 端點 | 說明 |
|---|---|---|
| GET | `/nodes/{node}/lxc` | 列出該節點所有容器 |
| GET | `/nodes/{node}/lxc/{vmid}/status/current` | 容器當前狀態 |
| GET | `/nodes/{node}/lxc/{vmid}/config` | 容器設定 |
| PUT | `/nodes/{node}/lxc/{vmid}/config` | 修改容器設定 |
| POST | `/nodes/{node}/lxc/{vmid}/status/start` | 啟動容器 |
| POST | `/nodes/{node}/lxc/{vmid}/status/stop` | 停止容器 |
| POST | `/nodes/{node}/lxc/{vmid}/status/shutdown` | 優雅關閉 |
| POST | `/nodes/{node}/lxc/{vmid}/status/reboot` | 重啟容器 |
| POST | `/nodes/{node}/lxc/{vmid}/clone` | 複製容器 |
| POST | `/nodes/{node}/lxc/{vmid}/snapshot` | 建立快照 |
| GET | `/nodes/{node}/lxc/{vmid}/snapshot` | 列出快照 |
| DELETE | `/nodes/{node}/lxc/{vmid}` | 刪除容器 |

### 儲存

| 方法 | 端點 | 說明 |
|---|---|---|
| GET | `/nodes/{node}/storage` | 列出儲存 |
| GET | `/nodes/{node}/storage/{storage}/status` | 儲存狀態 |
| GET | `/nodes/{node}/storage/{storage}/content` | 儲存內容（ISO/備份/磁碟） |
| POST | `/nodes/{node}/storage/{storage}/upload` | 上傳 ISO/模板 |
| DELETE | `/nodes/{node}/storage/{storage}/content/{volume}` | 刪除內容 |

> `{storage}` 可用值：`local`、`local-lvm`、`syno-lvm`、`synology-backup`、`pbs`

### 備份

| 方法 | 端點 | 說明 |
|---|---|---|
| GET | `/cluster/backup` | 列出備份排程 |
| POST | `/cluster/backup` | 建立備份排程 |
| GET | `/cluster/backup/{id}` | 取得排程詳情 |
| PUT | `/cluster/backup/{id}` | 修改排程 |
| DELETE | `/cluster/backup/{id}` | 刪除排程 |
| POST | `/nodes/{node}/vzdump` | 立即執行備份 |

### 使用者與權限

| 方法 | 端點 | 說明 |
|---|---|---|
| GET | `/access/users` | 列出使用者 |
| POST | `/access/users` | 建立使用者 |
| GET | `/access/roles` | 列出角色 |
| GET | `/access/acl` | 列出 ACL |
| PUT | `/access/acl` | 修改 ACL |

### 防火牆

| 方法 | 端點 | 說明 |
|---|---|---|
| GET | `/nodes/{node}/firewall/rules` | 節點防火牆規則 |
| GET | `/nodes/{node}/qemu/{vmid}/firewall/rules` | VM 防火牆規則 |
| GET | `/nodes/{node}/lxc/{vmid}/firewall/rules` | CT 防火牆規則 |
| GET | `/cluster/firewall/groups` | 防火牆安全群組 |

## 回傳格式

所有回傳皆為 JSON，結構統一：

```json
{
  "data": <回傳資料（物件或陣列）>
}
```

錯誤時：

```json
{
  "errors": { "<欄位>": "<錯誤訊息>" },
  "data": null
}
```

HTTP 狀態碼：
- `200` 成功
- `400` 參數錯誤
- `401` 未認證
- `403` 無權限
- `500` 伺服器錯誤

## 非同步任務

修改類操作（啟動、關閉、備份、複製等）會回傳 UPID（任務 ID），可用來追蹤進度：

```bash
# 回傳範例
{"data": "UPID:pve:000F4D1C:01234567:12345678:qmstart:110:root@pam!claude:"}

# 查詢任務狀態
curl -sk https://192.168.42.38:8006/api2/json/nodes/pve/tasks/<UPID>/status \
  -H "Authorization: PVEAPIToken=root@pam!claude=fefcffca-df6e-48de-8adf-7907cd2ea879"

# 查詢任務日誌
curl -sk https://192.168.42.38:8006/api2/json/nodes/pve/tasks/<UPID>/log \
  -H "Authorization: PVEAPIToken=root@pam!claude=fefcffca-df6e-48de-8adf-7907cd2ea879"
```

## pvesh CLI 對照

API 端點可直接用 `pvesh` 在 PVE 節點上執行，無需認證：

```bash
# GET /cluster/resources
ssh 192.168.42.38 "pvesh get /cluster/resources --output-format json"

# POST /nodes/pve/lxc/102/status/start
ssh 192.168.42.38 "pvesh create /nodes/pve/lxc/102/status/start"

# PUT /nodes/pve/lxc/102/config
ssh 192.168.42.38 "pvesh set /nodes/pve/lxc/102/config --memory 1024"

# DELETE /nodes/pve/lxc/999
ssh 192.168.42.38 "pvesh delete /nodes/pve/lxc/999"
```

pvesh 方法對照：`GET → get`、`POST → create`、`PUT → set`、`DELETE → delete`