# 快速上手指南

5 分鐘內開始操作 PVECluster。

## 前置條件

- 可連線至 `192.168.42.0/24` 網段
- 已安裝 `curl` 和 `python3`（用於解析 JSON）

## 1. 確認連線

```bash
# SSH（三台任一皆可）
ssh 192.168.42.38 "pveversion"
# 預期輸出：pve-manager/8.4.14/...

# API
curl -sk https://192.168.42.38:8006/api2/json/version \
  -H "Authorization: PVEAPIToken=root@pam!claude=fefcffca-df6e-48de-8adf-7907cd2ea879"
# 預期輸出：{"data":{"version":"8.4.14",...}}
```

## 2. 設定環境變數（方便後續操作）

```bash
export PVE_HOST="https://192.168.42.38:8006/api2/json"
export PVE_AUTH="Authorization: PVEAPIToken=root@pam!claude=fefcffca-df6e-48de-8adf-7907cd2ea879"

# 定義快捷函式
pve-get()  { curl -sk "$PVE_HOST$1" -H "$PVE_AUTH"; }
pve-post() { curl -sk -X POST "$PVE_HOST$1" -H "$PVE_AUTH" "${@:2}"; }
```

## 3. 查看叢集狀態

```bash
# 節點概覽
pve-get /nodes | python3 -m json.tool

# 所有 VM/容器
pve-get /cluster/resources?type=vm | python3 -c "
import sys, json
data = json.load(sys.stdin)['data']
data.sort(key=lambda x: x['vmid'])
print(f\"{'VMID':<6} {'Type':<5} {'Status':<9} {'Node':<8} {'Name':<12} {'CPU':>4} {'Mem':>8}\")
print('-' * 60)
for d in data:
    mem = f\"{d['mem'] // 1048576}M\" if d['mem'] else '-'
    print(f\"{d['vmid']:<6} {d['type']:<5} {d['status']:<9} {d['node']:<8} {d['name']:<12} {d.get('maxcpu','?'):>4} {mem:>8}\")
"
```

## 4. 常用操作範例

### 啟動 / 停止容器

```bash
# 啟動 CT103（N8N）
pve-post /nodes/pve/lxc/103/status/start

# 優雅關閉 CT103
pve-post /nodes/pve/lxc/103/status/shutdown

# 強制停止
pve-post /nodes/pve/lxc/103/status/stop
```

### 啟動 / 停止 VM

```bash
# 啟動 VM 120（K3s Worker）
pve-post /nodes/pve-02/qemu/120/status/start

# 關閉 VM
pve-post /nodes/pve-02/qemu/120/status/shutdown
```

### 查看單一 VM/容器狀態

```bash
# CT 狀態
pve-get /nodes/pve/lxc/102/status/current | python3 -m json.tool

# VM 狀態
pve-get /nodes/pve/qemu/110/status/current | python3 -m json.tool
```

### 查看 / 修改設定

```bash
# 查看 CT102 設定
pve-get /nodes/pve/lxc/102/config | python3 -m json.tool

# 透過 SSH 修改記憶體（改為 1GB）
ssh 192.168.42.38 "pvesh set /nodes/pve/lxc/102/config --memory 1024"
```

### 儲存使用狀況

```bash
pve-get /cluster/resources?type=storage | python3 -c "
import sys, json
data = json.load(sys.stdin)['data']
seen = set()
print(f\"{'Storage':<20} {'Type':<8} {'Shared':<7} {'Used':>10} {'Total':>10} {'Usage':>6}\")
print('-' * 65)
for d in sorted(data, key=lambda x: x['storage']):
    key = d['storage']
    if key in seen: continue
    seen.add(key)
    total = d.get('maxdisk', 0)
    used = d.get('disk', 0)
    pct = f\"{used/total*100:.0f}%\" if total else '-'
    print(f\"{key:<20} {d['plugintype']:<8} {'yes' if d.get('shared') else 'no':<7} {used//1073741824:>8} GB {total//1073741824:>8} GB {pct:>6}\")
"
```

### 立即備份

```bash
# 備份 CT115 到 PBS
pve-post /nodes/pve-02/vzdump \
  -d "vmid=115" \
  -d "storage=pbs" \
  -d "mode=snapshot" \
  -d "notes-template={{guestname}}"
```

### 建立快照

```bash
# CT 快照
pve-post /nodes/pve/lxc/102/snapshot \
  -d "snapname=before-upgrade" \
  -d "description=升級前快照"

# 列出快照
pve-get /nodes/pve/lxc/102/snapshot | python3 -m json.tool
```

## 5. 節點與 VMID 對照速查

操作 API 需要知道目標在哪個節點上：

| VMID | 節點 | 類型 | 用途 |
|---|---|---|---|
| 100-101, 107, 109, 115, 117 | pve-02 | lxc | SSH Jump, Headscale, MailPit, PDF, Lydia |
| 102-105, 116, 119, 125, 126 | pve | lxc | Tailscale, N8N, Caddy, MyIP, Bark, Gotify, Ubuntu |
| 108, 112, 114, 118, 124 | pve-03 | lxc | Python, OpenClaw, Podman, PG, NPM+Keycloak |
| 110, 121 | pve | qemu | OpenWRT, K3s |
| 111, 120 | pve-02 | qemu | PBS, K3s |
| 122 | pve-03 | qemu | K3s |

> 不確定在哪個節點？用 `/cluster/resources?type=vm` 查詢即可。

## 6. Web UI

瀏覽器開啟 `https://192.168.42.38:8006`，使用 `root` / PAM 認證登入。
三個節點任一 IP 皆可進入同一管理介面。