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

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 執行）

# 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 範例）

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

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