From d30bf61a76bdb6b5b010fc3a26d924e226a4b6c7 Mon Sep 17 00:00:00 2001 From: Timmy Date: Fri, 10 Apr 2026 11:08:10 +0800 Subject: [PATCH] docs: add PVECluster architecture and API reference 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) --- PVECluster_Architecture.md | 252 +++++++++++++++++++++++++++++++++++++ PVE_API.md | 126 +++++++++++++++++++ 2 files changed, 378 insertions(+) create mode 100644 PVECluster_Architecture.md create mode 100644 PVE_API.md diff --git a/PVECluster_Architecture.md b/PVECluster_Architecture.md new file mode 100644 index 0000000..777b5d2 --- /dev/null +++ b/PVECluster_Architecture.md @@ -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.` + +## 四、儲存架構 + +### 儲存池一覽 + +| 儲存名稱 | 類型 | 共享 | 容量 | 已用 | 用途 | +|---|---|---|---|---|---| +| **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 +``` diff --git a/PVE_API.md b/PVE_API.md new file mode 100644 index 0000000..aaaf48c --- /dev/null +++ b/PVE_API.md @@ -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=" + +# 3. POST/PUT/DELETE 請求需額外帶 CSRF header +curl -sk -X POST https://192.168.42.38:8006/api2/json/<端點> \ + -b "PVEAuthCookie=" \ + -H "CSRFPreventionToken: " \ + -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/<名稱> +```