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>
129 lines
3.4 KiB
Markdown
129 lines
3.4 KiB
Markdown
# Proxmox VE API 筆記
|
||
|
||
## 環境資訊
|
||
|
||
| 項目 | 值 |
|
||
|---|---|
|
||
| **PVE 版本** | 8.4.16 |
|
||
| **主機 IP（API 入口）** | 192.168.88.247（pve-002） |
|
||
| **叢集名稱** | PVECluster |
|
||
| **節點** | pve-000 (.73)、pve-001 (.249)、pve-002 (.247) |
|
||
| **VM/容器數量** | 25（13 VM + 12 LXC） |
|
||
|
||
> 三節點任一個 IP 都可以當 API 入口（同一管理介面）。
|
||
|
||
## API Token
|
||
|
||
| 項目 | 值 |
|
||
|---|---|
|
||
| **Token ID** | `root@pam!claude` |
|
||
| **Secret** | `17e96169-a32f-4e2d-951e-859c77770306` |
|
||
| **權限** | privsep=0（繼承 root 完整權限） |
|
||
| **到期** | 永不過期 |
|
||
|
||
另有舊 token `root@pam!monitor`（privsep=0），secret 已遺失。
|
||
|
||
## API 基本格式
|
||
|
||
```
|
||
https://192.168.88.247:8006/api2/json/<路徑>
|
||
```
|
||
|
||
## 認證方式
|
||
|
||
### API Token（推薦）
|
||
|
||
```bash
|
||
curl -sk https://192.168.88.247:8006/api2/json/<端點> \
|
||
-H "Authorization: PVEAPIToken=root@pam!claude=17e96169-a32f-4e2d-951e-859c77770306"
|
||
```
|
||
|
||
### Ticket（帳密登入，2 小時過期）
|
||
|
||
```bash
|
||
# 1. 取得 ticket
|
||
curl -sk https://192.168.88.247:8006/api2/json/access/ticket \
|
||
-d "username=root@pam&password=25915525"
|
||
|
||
# 回傳 ticket 和 CSRFPreventionToken
|
||
|
||
# 2. GET 請求
|
||
curl -sk https://192.168.88.247:8006/api2/json/<端點> \
|
||
-b "PVEAuthCookie=<ticket>"
|
||
|
||
# 3. POST/PUT/DELETE 請求需額外帶 CSRF header
|
||
curl -sk -X POST https://192.168.88.247: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` |
|
||
|
||
## 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/<名稱>
|
||
```
|