freewaretools/proxview

# ProxView        **为你运行的每一个 Proxmox VE cluster 和 Proxmox Backup Server 提供的只读全面视图。** ProxView 是一款专为运行**多个** Proxmox 站点的家庭实验室玩家设计的免费、自托管**只读监控仪表板**——它是一个轻量级、无许可证的 Proxmox Datacenter Manager 替代方案，只需一条命令即可部署。它**仅进行读取操作**：使用最小权限的 *audit* API token 获取指标，使用只读 SSH key 获取温度数据。ProxView 永远不会在你的节点上启动、停止、迁移或更改任何内容——它是仪表板，而不是控制器。  - 🖥️ **所有站点上每个节点的 CPU、内存、磁盘和温度**，实时显示 - 📦 每个节点上运行的 **VMs 和 CTs**，包含状态和资源使用情况 - 📈 **历史图表**（CPU / 内存 / 温度），支持 1小时 · 24小时 · 7天 时间范围 - 💾 **PBS 备份健康度** —— datastore 满载度、备份新鲜度、GC 和 verify 状态 - 🌡️ **通过 SSH 获取温度** (`lm-sensors`) —— 这是 Proxmox API 唯一无法提供的数据 - 🔔 **一目了然的警报** —— 节点离线、datastore 快满、备份过期、CPU 过热 - 🔒 **默认安全** —— 首次运行管理员设置、加密的凭证、仅限 localhost 的核心服务 - 🌐 **可选的远程访问** —— 应用内引导式的 Cloudflare Tunnel 和 Tailscale 向导（无需编辑 `.env`） ## 它的预期运行方式 ProxView 通过 API（只读的 *audit* token）连接到每个 Proxmox VE / PBS 站点，并通过 SSH 获取温度。当 ProxView 和你的站点能够**私下**相互通信时，效果最佳： - **都在同一个网络中？** 直接将 ProxView 指向每个站点的局域网 IP。 - **跨站点分布？** 将 ProxView 和你的节点放在 **Tailscale tailnet** 或 **WireGuard tunnel** 上，并通过其私有 IP 添加每个站点。两者都可以在一个地方设置 —— **Settings → Connectivity**。 **使其远离公共互联网。** ProxView 是为私有局域网或 tailnet 构建的，而不是为了万维网（WWW）——它保存着你运行的每个 cluster 的凭证，因此不应该直接暴露给外网访问。 要在你外出时访问它，首选 **Tailscale**（仅对你自己的设备可见）。对于无论如何都想要一个简单公共 URL 的家庭实验室用户，应用内包含了一个引导式的 **Cloudflare Tunnel** 向导——如果你使用它，请使用 **Cloudflare Access** 对 hostname 进行限制，这样仪表板就不会直接暴露给全世界。 ## 快速开始 ``` git clone https://github.com/freewaretools/proxview.git && cd proxview cp .env.example .env # optionally set PROXVIEW_SECRET_KEY (openssl rand -hex 32) docker compose up -d --build ``` 首次启动时，ProxView 会在日志中打印一个一次性的**设置链接** —— 打开它来创建你的管理员账户： ``` docker compose logs -f app # look for: Setup ProxView: http://localhost:8080/setup?token=... ``` 然后打开 `http://localhost:8080`，登录并在 **Settings** 下添加你的站点。 **首先尝试使用合成数据**（无需真实的 cluster）： ``` DEMO=1 docker compose up -d --build ``` ## 作为 Proxmox LXC 部署（一条命令） 在 **Proxmox VE host** 上以 root 身份运行——它会创建 container、安装 Docker、运行 ProxView、配置管理员，并打印一个**即用型 URL + 登录信息**（无需繁琐的 token 操作）： ``` bash -c "$(curl -fsSL https://raw.githubusercontent.com/freewaretools/proxview/main/proxmox/proxview-lxc.sh)" ``` 默认使用非特权 CT —— 在 `vmbr0` (DHCP) 上分配 2 vCPU / 1 GB RAM / 6 GB 磁盘。你可以使用环境变量覆盖任何设置： ``` CTID=131 STORAGE=local-zfs RAM_MB=2048 \ NET=192.168.1.50/24 GATEWAY=192.168.1.1 \ bash -c "$(curl -fsSL https://raw.githubusercontent.com/freewaretools/proxview/main/proxmox/proxview-lxc.sh)" ``` 默认情况下，它会**自动生成**一个强效的管理员密码并将其打印出来。如果要自定义密码，请将其添加到命令前（无需编辑文件——这不是 compose 路径）： ``` PROXVIEW_ADMIN_PASSWORD='choose-your-own' \ bash -c "$(curl -fsSL https://raw.githubusercontent.com/freewaretools/proxview/main/proxmox/proxview-lxc.sh)" ``` 该 container **仅限局域网访问** —— 使用应用内的 Cloudflare/Tailscale 向导跨网络访问它。（可调参数：`CTID`、`CT_HOSTNAME`、`CORES`、`RAM_MB`、`DISK_GB`、`BRIDGE`、`NET`、`GATEWAY`、`STORAGE`、`PROXVIEW_PORT`、`PROXVIEW_IMAGE`、`PROXVIEW_ADMIN_USER`、`PROXVIEW_ADMIN_PASSWORD`。） ## 添加 Proxmox VE 站点 1. 在 Proxmox 中：**Datacenter → Permissions → API Tokens**，为在 `/`（只读）拥有 **`PVEAuditor`** 角色的用户创建一个 token。复制 token ID（`user@realm!name`）和 secret。 2. 在 ProxView 的 **Settings → Add a site** 中：输入名称、`https://:8006`、token ID 和 secret。对于默认的自签名 cert，请保持 *Verify TLS* 关闭。 3. （可选）**温度**：展开 *Temperatures via SSH*，添加节点的 host、SSH 用户和只读 private key。要求在该节点上执行 `apt install lm-sensors`。 Proxmox Backup Server 的工作方式相同（`https://:8007`，一个 `Audit` token —— 注意 PBS 在 secret 之前使用了一个**冒号**，ProxView 会为你处理它）。 点击任意节点以深入查看每个指标的历史记录（CPU · 内存 · 温度 · 功率）：  ## 本地开发 ``` npm install npm run dev # backend (Fastify) on :8080, frontend (Vite) on :5173 with /api proxy ``` ## 远程访问（可选，需主动开启） 核心服务仅绑定到 `127.0.0.1`。请从 **Settings → Connectivity** 中根据需要故意暴露它——每个向导都会链接到提供商以获取 token，然后 ProxView 会在应用内应用它。无需编辑 `.env`，无需使用 compose 命令。  - **Cloudflare Tunnel** —— 公共 HTTPS，无需开放端口。在 Cloudflare Zero Trust 中创建一个 tunnel（将公共 hostname 指向 `http://localhost:8080`，并使用 **Cloudflare Access** 对其进行保护），粘贴 tunnel token，然后连接。ProxView 会为你运行 `cloudflared`。 - **Tailscale** —— 通过 Tailscale Serve 实现的仅限 tailnet 访问的 HTTPS。粘贴可重用的 auth key 并连接；ProxView 会加入你的 tailnet，并可通过 `https://proxview..ts.net` 访问。勾选 **Funnel** 可同时将其公开暴露。 一旦 ProxView 加入 tailnet，你就可以通过它们的 `100.x` IP 添加站点。 `cloudflared` 和 `tailscaled` 都内置在镜像中，并在用户空间运行——无需额外的 container 权限。Token 会与你的站点凭证一起进行 AES-256-GCM 加密存储。 ### 在友好的局域网 URL 上提供服务，无需端口 (Caddy) 比起 `http://192.168.1.50:8080`，更喜欢 `http://proxview.home`？一个可选的 Caddy reverse proxy 可以在 `:80` / `:443` 上提供 ProxView 服务，并带有自动 HTTPS（使用 Caddy 的内部 CA，因此不需要公共域名）： ``` PROXVIEW_HOSTNAME=proxview.home \ docker compose -f docker-compose.yml -f docker-compose.caddy.yml up -d ``` Caddy 处理**端口和证书**；你仍然需要**名称解析**（应用无法凭空发明 DNS）： - **`.local` 名称** 在 macOS/Windows 上通过 mDNS 自动解析 —— 无需设置。 - **其他名称**（`.home`、`.lan` 等）需要在你的路由器 / Pi-hole / AdGuard 中设置 **A record**，或者添加一条 `hosts` 条目，指向 ProxView host。 默认仅限局域网。在公共 VPS 上，请首选 Cloudflare/Tailscale 向导，或者将 `CADDY_BIND` 设置为私有/隧道 IP。 ### 跨网络访问节点 WireGuard 需要内核级网络，因此它作为 compose 插件运行，而不是在应用内运行。在 **Settings → Connectivity** 中，生成一对密钥，填写 `wireguard/wg0.conf`（参见 `wireguard/wg0.conf.example`），在你的 WG 服务器上将公钥添加为 peer，然后执行： `docker compose -f docker-compose.yml -f docker-compose.wireguard.yml up -d`

高级：作为 compose sidecar 运行隧道

如果你不想在应用 container 内运行隧道，经典的 sidecar 文件仍然在这里：在 `.env` 中设置 `CF_TUNNEL_TOKEN` / `TS_AUTHKEY` 并使用 `docker compose --profile cloudflare up -d` 或 `docker compose -f docker-compose.yml -f docker-compose.tailscale.yml up -d`。

## 架构 - **backend/** —— Fastify + TypeScript。保存凭证（AES-256-GCM 加密），轮询每个站点（`/cluster/resources`、`/status/datastore-usage`、SSH `sensors -j`），保留实时快照，将时间序列写入 SQLite，通过 SSE 流式传输更新，并提供构建好的前端。 - **frontend/** —— React + Vite + Zustand。深色、高密度的监控 UI（uPlot 图表）。 - 打包为 **一个 Docker 镜像 / 一个核心服务**。数据（SQLite + secret key）存放在 `./data` 卷中。 ## 配置 | 环境变量 | 默认值 | 用途 | |-----|---------|---------| | `PORT` | `8080` | 仪表板发布到的主机端口 | | `BIND_ADDR` | `127.0.0.1` | 发布到的主机接口。在 VPS 上，设置为你的 WireGuard/Tailscale IP（例如 `10.0.0.7`）——切勿在公共服务器上设置为 `0.0.0.0` | | `DEMO` | `0` | `1` 提供合成数据 | | `PROXVIEW_SECRET_KEY` | 自动 | 用于凭证加密的 32 字节十六进制 key | | `PROXVIEW_ADMIN_USER` / `PROXVIEW_ADMIN_PASSWORD` | — | 在首次启动时自动配置管理员（跳过设置 token）。方便脚本化部署 | | `POLL_INTERVAL_MS` | `10000` | PVE/PBS 轮询频率 | | `TEMP_INTERVAL_MS` | `45000` | SSH 温度轮询频率 | | `RETENTION_DAYS` | `30` | 时间序列保留天数 | | `COOKIE_SECURE` | `0` | 当始终位于 HTTPS 之后时设置为 `1` | ## 路线图 | # | 里程碑 | 状态 | |---|-----------|--------| | M1 | 基础搭建 + Docker | ✅ | | M2 | 首次运行认证 + DB | ✅ | | M3 | PVE provider + 实时概览 | ✅ | | M4 | 时间序列 + 历史图表 | ✅ | | M5 | 通过 SSH 获取温度 | ✅ | | M6 | PBS provider + 备份健康 | ✅ | | M7 | 远程访问插件 + 细节优化 | ✅ | ## 安全说明 - **设计上只读。** ProxView 永远不会修改你的 cluster —— 仅向其提供 audit token：PVE 使用 `PVEAuditor`，PBS 使用 `Audit`。切勿使用 `root@pam`。 - 备份 `data/secret.key`（或设置 `PROXVIEW_SECRET_KEY`）：它用于解密你存储的站点凭证。 - 将其保留在私有网络或 tailnet 上。相比公开暴露，首选 Tailscale；如果你使用 Cloudflare Tunnel 向导，请在前面加上 **Cloudflare Access**。 ## 贡献 欢迎提交 Issues 和 PR —— 有关开发设置和（简短的）基本规则，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。最重要的一点是：ProxView 保持**只读**。 ## 许可证 [](LICENSE) © 2026 freewaretools

标签：Docker, Fastify, Proxmox, React, Syscalls, TypeScript, 仪表盘, 安全插件, 安全防御评估, 自动化攻击, 请求拦截, 运维监控