timmy/88_247
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 初始化 PVECluster (192.168.88.0/24) 文件庫

Browse Source 
仿照 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>
This commit is contained in:
Timmy
2026-04-15 16:02:48 +08:00
commit 40945cf625
7 changed files with 1122 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

229
API.md Normal file
View File

@@ -0,0 +1,229 @@
# 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`