42_38/API.md

Proxmox VE API 參考手冊

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

認證

API Token（推薦）

# 在 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 小時過期）

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

# 建立 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，結構統一：

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

錯誤時：

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

HTTP 狀態碼：

• 200 成功
• 400 參數錯誤
• 401 未認證
• 403 無權限
• 500 伺服器錯誤

非同步任務

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

# 回傳範例
{"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 節點上執行，無需認證：

# 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