Timmy
40945cf625
仿照 timmy/42_38 結構建立 7 份文件，涵蓋 3 節點 PVE 8.4.16 叢集 （pve-000/.73、pve-001/.249、pve-002/.247）的架構、API、儲存、 備份與服務分類。 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
230 lines
7.4 KiB
Markdown
230 lines
7.4 KiB
Markdown
# Proxmox VE API 參考手冊
|
||
|
||
> 適用版本：PVE 8.4.16 | 基底 URL：`https://192.168.88.247:8006/api2/json/`
|
||
|
||
## 認證
|
||
|
||
### API Token（推薦）
|
||
|
||
```bash
|
||
# 在 Header 中帶入 Token
|
||
curl -sk https://192.168.88.247:8006/api2/json/<端點> \
|
||
-H "Authorization: PVEAPIToken=root@pam!claude=17e96169-a32f-4e2d-951e-859c77770306"
|
||
```
|
||
|
||
Token 格式：`PVEAPIToken=<使用者>!<token名稱>=<secret-uuid>`
|
||
|
||
### 現有 Token
|
||
|
||
| Token ID | privsep | 權限 | 狀態 |
|
||
|---|---|---|---|
|
||
| `root@pam!claude` | 0（繼承 root） | 完整權限 | 可用（本文件預設） |
|
||
| `root@pam!monitor` | 0（繼承 root） | 完整權限 | secret 已遺失 |
|
||
|
||
### Ticket 認證（帳密登入，2 小時過期）
|
||
|
||
```bash
|
||
# 步驟 1：取得 ticket + CSRF token
|
||
RESPONSE=$(curl -sk https://192.168.88.247:8006/api2/json/access/ticket \
|
||
-d "username=root@pam&password=25915525")
|
||
|
||
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.88.247:8006/api2/json/<端點> \
|
||
-b "PVEAuthCookie=$TICKET"
|
||
|
||
# 步驟 3：POST/PUT/DELETE 請求（需額外帶 CSRF）
|
||
curl -sk -X POST https://192.168.88.247:8006/api2/json/<端點> \
|
||
-b "PVEAuthCookie=$TICKET" \
|
||
-H "CSRFPreventionToken: $CSRF" \
|
||
-d "參數=值"
|
||
```
|
||
|
||
## Token 管理
|
||
|
||
```bash
|
||
# 建立 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.88.247:8006/api2/json/access/users/root@pam/token/<名稱> \
|
||
-H "Authorization: PVEAPIToken=root@pam!claude=17e96169-a32f-4e2d-951e-859c77770306" \
|
||
-d "privsep=0&expire=0"
|
||
```
|
||
|
||
## 端點參考
|
||
|
||
以下所有端點前綴為 `https://192.168.88.247: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-000`、`pve-001`、`pve-002`
|
||
|
||
### 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-iscsi`、`pve-iscsi-3t`、`backup1`
|
||
|
||
### 備份
|
||
|
||
| 方法 | 端點 | 說明 |
|
||
|---|---|---|
|
||
| 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，結構統一：
|
||
|
||
```json
|
||
{
|
||
"data": <回傳資料（物件或陣列）>
|
||
}
|
||
```
|
||
|
||
錯誤時：
|
||
|
||
```json
|
||
{
|
||
"errors": { "<欄位>": "<錯誤訊息>" },
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
HTTP 狀態碼：
|
||
- `200` 成功
|
||
- `400` 參數錯誤
|
||
- `401` 未認證
|
||
- `403` 無權限
|
||
- `500` 伺服器錯誤
|
||
|
||
## 非同步任務
|
||
|
||
修改類操作（啟動、關閉、備份、複製等）會回傳 UPID（任務 ID），可用來追蹤進度：
|
||
|
||
```bash
|
||
# 回傳範例
|
||
{"data": "UPID:pve-002:000F4D1C:01234567:12345678:qmstart:115:root@pam!claude:"}
|
||
|
||
# 查詢任務狀態
|
||
curl -sk https://192.168.88.247:8006/api2/json/nodes/pve-002/tasks/<UPID>/status \
|
||
-H "Authorization: PVEAPIToken=root@pam!claude=17e96169-a32f-4e2d-951e-859c77770306"
|
||
|
||
# 查詢任務日誌
|
||
curl -sk https://192.168.88.247:8006/api2/json/nodes/pve-002/tasks/<UPID>/log \
|
||
-H "Authorization: PVEAPIToken=root@pam!claude=17e96169-a32f-4e2d-951e-859c77770306"
|
||
```
|
||
|
||
## pvesh CLI 對照
|
||
|
||
API 端點可直接用 `pvesh` 在 PVE 節點上執行，無需認證：
|
||
|
||
```bash
|
||
# GET /cluster/resources
|
||
ssh root@192.168.88.247 "pvesh get /cluster/resources --output-format json"
|
||
|
||
# POST /nodes/pve-000/lxc/104/status/start
|
||
ssh root@192.168.88.247 "pvesh create /nodes/pve-000/lxc/104/status/start"
|
||
|
||
# PUT /nodes/pve-000/lxc/104/config
|
||
ssh root@192.168.88.247 "pvesh set /nodes/pve-000/lxc/104/config --memory 2048"
|
||
|
||
# DELETE /nodes/pve-000/lxc/999
|
||
ssh root@192.168.88.247 "pvesh delete /nodes/pve-000/lxc/999"
|
||
```
|
||
|
||
pvesh 方法對照：`GET → get`、`POST → create`、`PUT → set`、`DELETE → delete`
|