42_38/PVE_API.md

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

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

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

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

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