timmy/42_38
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add README, API reference, quickstart guide, and cluster summary

Browse Source 
- 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>
This commit is contained in:
Timmy
2026-04-10 11:12:15 +08:00
parent d30bf61a76
commit 1990d5a011
5 changed files with 603 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.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`