88_247/PVE_API.md

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（推薦）

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

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

# 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 管理

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