# Proxmox VE API 筆記

## 環境資訊

| 項目 | 值 |
|---|---|
| **PVE 版本** | 8.4.14 |
| **主機 IP** | 192.168.42.38 |
| **叢集名稱** | PVECluster |
| **節點** | pve (42.38)、pve-02 (42.39)、pve-03 (42.40) |
| **VM/容器數量** | 27 |

## API Token

| 項目 | 值 |
|---|---|
| **Token ID** | `root@pam!claude` |
| **Secret** | `fefcffca-df6e-48de-8adf-7907cd2ea879` |
| **權限** | privsep=0（繼承 root 完整權限） |
| **到期** | 永不過期 |

另有舊 token `root@pam!automation`（privsep=1，PVEAdmin 角色），secret 已遺失。

## API 基本格式

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

## 認證方式

### API Token（推薦）

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

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

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

# 回傳 ticket 和 CSRFPreventionToken

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

# 3. POST/PUT/DELETE 請求需額外帶 CSRF header
curl -sk -X POST https://192.168.42.38: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` |

## Proxmox Backup Server (PBS)

> PBS 是獨立系統（VM 111，`192.168.42.30:8007`，主機名 `pbs`），**PVE API token 不適用**。PBS 本身的管理走免密 SSH + `proxmox-backup-manager` CLI；但「PVE 如何使用 PBS」（備份排程、查 PBS 儲存用量）仍透過 PVE API。

### 環境

| 項目 | 值 |
|---|---|
| **PBS 主機** | `192.168.42.30`（hostname `pbs`，= VM 111） |
| **Web/API** | `https://192.168.42.30:8007`（fingerprint 見 PVE storage 設定） |
| **存取** | 開發機免密 SSH `root@192.168.42.30` |
| **Datastore** | `data-store` → `/mnt/datastore`（ext4 on `/dev/sdb1`，200 GB on syno-lvm） |

### PBS 端 CLI（SSH 進 pbs 執行）

```bash
# Datastore 狀態 / GC
proxmox-backup-manager datastore list
proxmox-backup-manager garbage-collection status data-store
proxmox-backup-manager garbage-collection start data-store

# 驗證工作（verify job）
proxmox-backup-manager verify-job list
proxmox-backup-manager verify-job create v-weekly \
  --store data-store --schedule "sat 05:00" \
  --ignore-verified true --outdated-after 30
proxmox-backup-manager verify data-store          # 立即全驗一次

# 任務 log
proxmox-backup-manager task list
```

### PVE 端：PBS 相關 API（用一般 PVE API token）

| 用途 | 方法 | 端點 |
|---|---|---|
| PBS 儲存用量 | GET | `/nodes/{node}/storage/pbs/status` |
| PBS 備份內容（snapshot 清單） | GET | `/nodes/{node}/storage/pbs/content` |
| 列出備份排程 | GET | `/cluster/backup` |
| 單一排程設定 | GET | `/cluster/backup/{id}` |
| 排程實際納入的 guest | GET | `/cluster/backup/{id}/included_volumes` |
| 新增排程 | POST | `/cluster/backup` |
| 修改排程（啟用/保留等） | PUT | `/cluster/backup/{id}` |
| 刪除排程 | DELETE | `/cluster/backup/{id}` |
| 手動觸發備份 | POST | `/nodes/{node}/vzdump` |

備份排程的目前配置與沿革見 `PVECluster_Architecture.md` §六。

### Datastore 線上擴容（80G → 200G 範例）

```bash
# 1) PVE 端擴 VM 磁碟（API 或 pvesh）
curl -sk -X PUT -H "Authorization: PVEAPIToken=..." \
  --data-urlencode "disk=scsi2" --data-urlencode "size=+120G" \
  https://192.168.42.38:8006/api2/json/nodes/pve-02/qemu/111/resize

# 2) PBS 端線上擴分割區 + 檔案系統（不停機）
echo 1 > /sys/class/block/sdb/device/rescan
sgdisk -e /dev/sdb                       # 移動備份 GPT 標頭到磁碟末端
parted /dev/sdb ---pretend-input-tty resizepart 1 100%   # 對 Yes 確認
partx -u /dev/sdb                        # 更新 kernel 對掛載中分割區的視圖
resize2fs /dev/sdb1                      # ext4 線上擴展
```

## Token 管理

```bash
# 建立新 token（SSH 到 PVE 主機執行）
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/<名稱>
```