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

docs: add PVECluster architecture and API reference

Browse Source 
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>
This commit is contained in:
Timmy
2026-04-10 11:08:10 +08:00
commit d30bf61a76
2 changed files with 378 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

252
PVECluster_Architecture.md Normal file
View File

@@ -0,0 +1,252 @@
# PVECluster 叢集架構文件
> 最後更新：2026-04-10
## 一、叢集概覽
| 項目 | 值 |
|---|---|
| **叢集名稱** | PVECluster |
| **PVE 版本** | 8.4.14（Kernel 6.8.12-16-pve） |
| **節點數** | 3 |
| **Quorum** | 正常（corosync_votequorum） |
| **VM/容器總數** | 27（含 1 個 template） |
| **HA** | 未啟用 |
## 二、節點硬體規格
三台節點規格完全相同：
| 項目 | 規格 |
|---|---|
| **CPU** | Intel Core i3-6100 @ 3.70GHz（2C/4T） |
| **記憶體** | 16 GB DDR4 |
| **系統碟** | ~68 GB（LVM，含 local + local-lvm） |
| **網卡** | Realtek RTL8111 GbE |
| **顯示** | Intel HD Graphics 530（內顯） |
| **SATA** | Intel Q170 Chipset AHCI |
### 節點清單
| 節點 | IP | 用途 | 上線時間 |
|---|---|---|---|
| **pve** | 192.168.42.38 | 主節點 | ~9.2 天 |
| **pve-02** | 192.168.42.39 | 工作節點 | ~9.2 天 |
| **pve-03** | 192.168.42.40 | 工作節點 | ~9.2 天 |
### 節點資源使用（即時快照）
| 節點 | CPU 使用率 | 記憶體使用 | 系統碟使用 |
|---|---|---|---|
| pve | ~7% | 6.7 GB / 16 GB (43%) | 12.2 GB / 68 GB |
| pve-02 | ~12% | 10.9 GB / 16 GB (70%) | 12.1 GB / 68 GB |
| pve-03 | ~15% | 10.1 GB / 16 GB (64%) | 11.0 GB / 68 GB |
## 三、網路架構
```
網際網路
│
▼
[192.168.42.10] Gateway（OpenWRT VM 110 的 GW）
│
├── vmbr0 (Linux Bridge)
│ ├── pve (enp1s0) — 192.168.42.38/24
│ ├── pve-02 (enp1s0) — 192.168.42.39/24
│ └── pve-03 (enp1s0) — 192.168.42.40/24
│
├── VM 110 OpenWRT — 進階路由/防火牆
│
└── 所有 VM/CT 皆掛在 vmbr0
IP 範圍：192.168.42.100 ~ 192.168.42.126
```
- **Bridge**: `vmbr0`（每節點各一，bridge port 為 `enp1s0`）
- **Gateway**: `192.168.42.10`
- **SDN Zone**: `localnetwork`（三節點皆啟用，狀態正常）
- **所有 VM/CT 靜態 IP**，格式為 `192.168.42.<VMID>`
## 四、儲存架構
### 儲存池一覽
| 儲存名稱 | 類型 | 共享 | 容量 | 已用 | 用途 |
|---|---|---|---|---|---|
| **local** | dir | 否 | 68 GB/節點 | ~12 GB | ISO、備份、模板 |
| **local-lvm** | lvmthin | 否 | ~160 GB/節點 | 變動 | VM 磁碟、CT rootfs |
| **syno-lvm** | LVM (iSCSI) | 是 | 1 TB | ~902 GB | VM 磁碟、CT rootfs（主要儲存） |
| **syno-iscsi** | iSCSI | 是 | — | — | syno-lvm 的底層 target |
| **synology-backup** | CIFS | 是 | 2.75 TB | ~2.37 TB | 備份、ISO、模板、snippets |
| **pbs** | PBS | 是 | 294 GB | ~16 GB | Proxmox Backup Server 備份 |
### 儲存拓撲
```
Synology NAS (192.168.42.20)
├── iSCSI Target ──► syno-iscsi ──► syno-lvm (LVM, 1TB, 共享)
│ └── 大部分 VM/CT 磁碟存放於此
└── CIFS Share (Backup) ──► synology-backup (2.75TB, 共享)
└── 備份、ISO、模板
Proxmox Backup Server (192.168.42.30, VM 111)
└── PBS datastore "data-store" ──► pbs (294GB, 共享)
└── VM/CT 快照備份
各節點本地
├── /var/lib/vz ──► local (68GB)
│ └── ISO、vztmpl、備份
└── LVM thin pool ──► local-lvm (~160GB)
└── 部分 VM/CT 磁碟（CT112, CT113, CT123）
```
## 五、VM / 容器清單
### QEMU 虛擬機
| VMID | 名稱 | 節點 | 狀態 | CPU | 記憶體 | 磁碟 | Tags | 用途 |
|---|---|---|---|---|---|---|---|---|
| **110** | OpenWRT | pve | running | 2C | 1.5 GB | 8 GB (syno-lvm) | openwrt | 進階路由/防火牆 |
| **111** | PBS | pve-02 | running | 2C | 2 GB | 32G + 300G (syno-lvm) | proxmoxbackupserver | Proxmox Backup Server (192.168.42.30) |
| **120** | K3s Worker | pve-02 | running | 2C | 8 GB | 83 GB (syno-lvm) | k3s | Kubernetes 工作節點 |
| **121** | K3s Worker | pve | running | 2C | 8 GB | 82 GB (syno-lvm) | k3s | Kubernetes 工作節點 |
| **122** | K3s Worker | pve-03 | running | 2C | 8 GB | 82 GB (syno-lvm) | k3s | Kubernetes 工作節點 |
| **9000** | ubuntu-2404-cloud-template | pve | stopped | 2C | 2 GB | 3.5 GB (syno-lvm) | — | Cloud-init 模板 |
### LXC 容器
| VMID | 名稱 | 節點 | 狀態 | CPU | 記憶體 | 磁碟 | IP | Tags / 用途 |
|---|---|---|---|---|---|---|---|---|
| **100** | CT100 | pve-02 | running | 1C | 256 MB | 8G (syno-lvm) | .42.100 | SSH Jump + Bore Tunnel |
| **101** | CT101 | pve-02 | running | 1C | 128 MB | 8G (syno-lvm) | .42.101 | Headscale + RustDesk + Watchtower |
| **102** | CT102 | pve | running | 1C | 512 MB | 8G (syno-lvm) | .42.102 | Tailscale + Watchtower |
| **103** | CT103 | pve | **stopped** | 1C | 768 MB | 16G (syno-lvm) | .42.103 | N8N 自動化 + Watchtower |
| **104** | CT104 | pve | running | 1C | 96 MB | 8G (syno-lvm) | .42.104 | Caddy 反向代理（80/443） |
| **105** | CT105 | pve | running | 1C | 128 MB | 8G (syno-lvm) | .42.105 | MyIP Server + Watchtower |
| **106** | CT106 | pve | **stopped** | 2C | 512 MB | 8G (syno-lvm) | .42.106 | Podman（閒置） |
| **107** | CT107 | pve-02 | running | 1C | 64 MB | 8G (syno-lvm) | .42.107 | MailPit Server |
| **108** | CT108 | pve-03 | running | 4C | 4 GB | 16G (syno-lvm) | .42.108 | Python 開發環境 |
| **109** | CT109 | pve-02 | **stopped** | 2C | 1 GB | 8G (syno-lvm) | .42.109 | Stirling PDF |
| **112** | CT112 | pve-03 | running | 2C | 2 GB | 32G (local-lvm) | .42.112 | OpenClaw |
| **113** | CT113 | pve | **stopped** | 1C | 512 MB | 8G (local-lvm) | DHCP | （閒置） |
| **114** | CT114 | pve-03 | running | 1C | 512 MB | 8G (syno-lvm) | .42.114 | Podman |
| **115** | CT115 | pve-02 | running | 4C | 2 GB | 40G (syno-lvm) | .42.115 | Lydia（Production） |
| **116** | CT116 | pve | running | 1C | 128 MB | 8G (syno-lvm) | .42.116 | Bark 推播伺服器 |
| **117** | CT117 | pve-02 | running | 4C | 2 GB | 60G (syno-lvm) | .42.117 | Lydia（Test） |
| **118** | CT118 | pve-03 | running | 2C | 2 GB | 8G (syno-lvm) | DHCP | Podman + PostgreSQL |
| **119** | CT119 | pve | **stopped** | 1C | 64 MB | 8G (syno-lvm) | .42.119 | Gotify 推播伺服器 |
| **123** | CT123 | pve | **stopped** | 1C | 1 GB | 16G (local-lvm) | .42.123 | （閒置） |
| **124** | CT124 | pve-03 | running | 2C | 8 GB | 80G (syno-lvm) | .42.124 | NPM + Keycloak + Karakeep + Watchtower |
| **126** | CT126 | pve | running | 1C | 256 MB | 8G (syno-lvm) | .42.126 | Headscale |
### 狀態統計
| 狀態 | 數量 |
|---|---|
| Running | 20 |
| Stopped | 6（CT103, CT106, CT109, CT113, CT119, CT123） |
| Template | 1（VM 9000） |
### 各節點負載分佈
| 節點 | VM | LXC (running) | LXC (stopped) | 分配 CPU | 分配記憶體 |
|---|---|---|---|---|---|
| **pve** | 2 (110, 121) | 7 (102,104,105,116,126) | 4 (103,106,113,119,123) | 16C | ~22 GB |
| **pve-02** | 2 (111, 120) | 5 (100,101,107,115,117) | 1 (109) | 16C | ~17 GB |
| **pve-03** | 1 (122) | 5 (108,112,114,118,124) | 0 | 15C | ~27 GB |
## 六、備份策略
### Proxmox Backup Server
- **位置**: VM 111（pve-02），IP `192.168.42.30:8007`
- **Datastore**: `data-store`（294 GB，已用 ~16 GB）
- **保留策略**: `keep-all=1`
### 備份排程（目前皆已停用 enabled=0）
| 排程 | 目標 | 儲存 | 保留 | 壓縮 |
|---|---|---|---|---|
| 每日 03:00 | CT115, CT117（Lydia prod/test） | pbs | keep-daily=7 | — |
| 02:30, 22:30 | CT103, CT106, CT108, CT124 | pbs | keep-daily=7 | zstd |
| 每日 02:00 | VM 110（OpenWRT） | pbs | keep-daily=3 | — |
### Synology NAS 備份
- **位置**: `192.168.42.20`，CIFS share `Backup`
- **容量**: 2.75 TB（已用 ~2.37 TB）
- CT124 有掛載 `/mnt/ds1515-backup` 指向此 share
## 七、關鍵服務架構圖
```
┌─────────────────────────────────────────────────────────────────┐
│ PVECluster │
│ 192.168.42.38/39/40 │
├──────────────┬──────────────────┬────────────────────────────────┤
│ pve (.38) │ pve-02 (.39) │ pve-03 (.40) │
├──────────────┴──────────────────┴────────────────────────────────┤
│ │
│ 【網路層】 │
│ VM110 OpenWRT ─── 路由/防火牆 ─── GW: 192.168.42.10 │
│ CT104 Caddy ───── 反向代理（80/443） │
│ CT124 NPM ─────── Nginx Proxy Manager │
│ │
│ 【認證/安全】 │
│ CT124 Keycloak ── SSO 認證 │
│ CT100 ─────────── SSH Jump Box + Bore Tunnel │
│ CT101 ─────────── Headscale + RustDesk（遠端存取） │
│ CT102 ─────────── Tailscale │
│ CT126 ─────────── Headscale │
│ │
│ 【應用服務】 │
│ CT115 Lydia ───── Production（4C/2GB/40G） │
│ CT117 Lydia ───── Test（4C/2GB/60G） │
│ CT108 ─────────── Python 開發環境（4C/4GB） │
│ CT112 ─────────── OpenClaw（2C/2GB/32G） │
│ CT124 Karakeep ── 書籤/知識管理 │
│ │
│ 【Kubernetes】 │
│ VM120 K3s ─────── Worker (pve-02, 8GB) │
│ VM121 K3s ─────── Worker (pve, 8GB) │
│ VM122 K3s ─────── Worker (pve-03, 8GB) │
│ │
│ 【工具/通知】 │
│ CT107 ─────────── MailPit（郵件測試） │
│ CT116 ─────────── Bark（推播通知） │
│ CT119 ─────────── Gotify（推播通知，已停） │
│ CT105 ─────────── MyIP Server │
│ CT103 ─────────── N8N 自動化（已停） │
│ CT109 ─────────── Stirling PDF（已停） │
│ │
│ 【資料庫】 │
│ CT118 ─────────── PostgreSQL + Podman │
│ │
│ 【備份】 │
│ VM111 PBS ─────── Proxmox Backup Server (192.168.42.30) │
│ Synology NAS ──── iSCSI (syno-lvm) + CIFS (backup) │
│ 192.168.42.20 │
│ │
│ 【模板】 │
│ VM9000 ────────── Ubuntu 24.04 Cloud-init Template │
└──────────────────────────────────────────────────────────────────┘
```
## 八、Corosync 叢集通訊
```
totem:
cluster_name: PVECluster
version: 2
secauth: on
link_mode: passive
ip_version: ipv4-6
nodelist:
pve (nodeid=1, ring0=192.168.42.38, votes=1)
pve-02 (nodeid=2, ring0=192.168.42.39, votes=1)
pve-03 (nodeid=3, ring0=192.168.42.40, votes=1)
quorum:
provider: corosync_votequorum
需要 2/3 節點在線才能維持 quorum
```

126
PVE_API.md Normal file
View File

@@ -0,0 +1,126 @@
# 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/<名稱>
```