191 lines
5.9 KiB
Markdown
191 lines
5.9 KiB
Markdown
# 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` |
|
||
|
||
## 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 執行）
|
||
|
||
```bash
|
||
# 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 範例）
|
||
|
||
```bash
|
||
# 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 管理
|
||
|
||
```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/<名稱>
|
||
```
|