Timmy
d30bf61a76
Include cluster architecture overview (nodes, VMs, storage, networking, backup strategy) and Proxmox VE API usage guide with token credentials. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
127 lines
3.3 KiB
Markdown
127 lines
3.3 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` |
|
||
|
||
## 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/<名稱>
|
||
```
|