Timmy
1990d5a011
- README.md: project landing page with cluster overview and doc index - API.md: comprehensive Proxmox VE API endpoint reference - QUICKSTART.md: 5-minute guide with copy-paste examples - SUMMARY.md: cluster health, resource usage, and service inventory - CLAUDE.md: Claude Code project context Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
230 lines
7.3 KiB
Markdown
230 lines
7.3 KiB
Markdown
# Proxmox VE API 參考手冊
|
||
|
||
> 適用版本：PVE 8.4.14 | 基底 URL：`https://192.168.42.38:8006/api2/json/`
|
||
|
||
## 認證
|
||
|
||
### API Token（推薦）
|
||
|
||
```bash
|
||
# 在 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 小時過期）
|
||
|
||
```bash
|
||
# 步驟 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 管理
|
||
|
||
```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.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，結構統一：
|
||
|
||
```json
|
||
{
|
||
"data": <回傳資料（物件或陣列）>
|
||
}
|
||
```
|
||
|
||
錯誤時：
|
||
|
||
```json
|
||
{
|
||
"errors": { "<欄位>": "<錯誤訊息>" },
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
HTTP 狀態碼：
|
||
- `200` 成功
|
||
- `400` 參數錯誤
|
||
- `401` 未認證
|
||
- `403` 無權限
|
||
- `500` 伺服器錯誤
|
||
|
||
## 非同步任務
|
||
|
||
修改類操作（啟動、關閉、備份、複製等）會回傳 UPID（任務 ID），可用來追蹤進度：
|
||
|
||
```bash
|
||
# 回傳範例
|
||
{"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 節點上執行，無需認證：
|
||
|
||
```bash
|
||
# 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`
|