docs: add PVECluster architecture and API reference

Include cluster architecture overview (nodes, VMs, storage, networking,
backup strategy) and Proxmox VE API usage guide with token credentials.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

PVE_API.md

@@ -0,0 +1,126 @@
+# 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` |
+
+## 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/<名稱>
+```