TIL

Homelable：homelab 拓扑可视化 + 只读 PVE 接入

内网地址用 <PVE-IP> / <VM-IP> / <LAN>/24 占位，实际部署时换成自己的；token 与密钥只进 .env，不进 git。

它解决什么

Homelable 是自托管的 homelab 可视化：把机器、设备、服务画成一张可交互的拓扑图，节点上挂实时状态。和"写份文档画张图"的区别在于它是活的——网络扫描把发现的设备塞进待确认队列，状态检查每 60 秒把在线/离线画回图上。

三个能力，按实际使用频率排：

  1. 网络扫描：nmap -sV --open 扫配置的 CIDR 段，结果进 Pending 队列，人工 approve / hide / ignore 后才上画布
  2. 节点健康检查：每个节点可挑 ping / http / https / tcp / ssh / prometheus / health 七种方式之一
  3. MCP server（可选）：把拓扑的读写暴露给 AI 客户端。另有 Zigbee2MQTT / Z-Wave JS 的 MQTT 导入，没有对应设备就用不上

部署

官方给的是预构建镜像（backend / frontend / mcp，都在 GHCR），不需要本地 build，docker compose pull 直接拉。几处必须按自己环境改：

  • 前端默认占用 3000。这台机器上若已有服务在用，必须换端口，否则 up 时端口冲突
  • CORS_ORIGINS 要改成真实访问地址。上游的预构建 compose 把它硬编码成 http://localhost:3000，不改的话界面能打开、所有 API 调用失败
  • 端口只绑内网地址（<VM-IP>:端口:端口），不要 0.0.0.0
  • backend 保留 cap_add: NET_RAW：ping 检查和 nmap 的 SYN 扫描都要它。漏掉的表现是"扫描跑完什么都没发现"
  • 数据是 SQLite，绑定挂载一个目录即可（平面图上传也在里面）

自检顺序：容器是否 healthy → 首页返回 200 → 经反代/前端的 /api/v1/health 是否回 {"status":"ok"} → 用 docker exec <backend> nmap -sV --open <宿主IP> 确认扫描真的能跑。

扫描结果长什么样

/24 全段扫一次大概几分钟，捞出来的就是网关、PVE 宿主、docker 宿主机、手机、智能插座、音箱，以及它自己。每台带发现的开放端口。MAC 厂商信息在 bridge 网络里拿不全，要更准得 network_mode: host。

Proxmox 只读接入（坑最深的一步）

Homelable 能从 PVE 的 REST API 直接拉宿主 / VM / LXC，省掉手敲清单。凭证用一个只读 token：

pveum user add homelable@pve --comment "Homelable read-only import"
pveum user token add homelable@pve homelable --privsep 1 --output-format json   # secret 只显示一次
pveum acl modify / --tokens 'homelable@pve!homelable' --roles PVEAuditor
pveum acl modify / --users  homelable@pve            --roles PVEAuditor   # ← 少这行不生效

--privsep 1 的 token 只给自己授 ACL 是不够的（PVE 9.2.18 实测）：token 能通过认证，但权限为零——/access/permissions 返回空对象、/cluster/resources 只列出宿主节点、看不到任何 VM/LXC，界面上的连接测试会回一句 "this API token has no permissions"。给所属用户也授上同一角色后立刻正常。

验证别靠界面，直接打 API：

curl -sk -H "Authorization: PVEAPIToken=<tokenid>=<secret>" \
  https://<PVE-IP>:8006/api2/json/nodes/pve/qemu    # 应列出 VM

.env 里对应五项：PROXMOX_HOST、PROXMOX_PORT、PROXMOX_TOKEN_ID、PROXMOX_TOKEN_SECRET、PROXMOX_VERIFY_TLS=false（PVE 默认自签证书）。改完重启 backend，GET /api/v1/proxmox/config 应回 token_configured: true。

导入后还有两个细节：PVE 宿主条目落进队列时 ip 是空的（API 不返回节点 IP，得手填）；MCP 的 list_proxmox_children 要的是待确认队列里的条目 id，传画布节点 id 会 404。

权限面只有 PVEAuditor（*Audit 类），宿主用户没设密码、无法交互登录。真实风险是 token 泄露，所以只留在内网，别过隧道。

MCP 接口

MCP 是单独一个容器，端点在 http://<VM-IP>:8001/mcp。两个坑：

  • 路径尾斜杠：POST /mcp 回 307 跳到 /mcp/，客户端不跟随重定向的话，看起来就像"服务坏了"
  • 鉴权只有 X-API-Key 一个头，而工具集里有创建/删除/改画布的写操作——所以 MCP 端口不能经 Cloudflare Tunnel 之类暴露出去

接进 agent 客户端后能读全部节点/边/待确认设备，也能加节点、连边、触发扫描、批量 approve。

值不值得

真省事的是扫描 + 自动上画布这一段，以及 Proxmox 导入。健康检查那部分与已有的巡检脚本重叠，锦上添花。长期价值在 MCP：拓扑变成 agent 能读能改的数据，而不是一张死图。

代价是一个要维护的容器组和一个只读 token。若只想要那张图，它确实比手画好看；但要它长期活着，得接受它成为又一个待升级的服务。

相关：PVE: First setup、PVE 双 NVMe 存储、Docker

参考

↑ Top