拒绝 Excel 记账式运维:开源管理平台 Home Lab Hub 一站式统筹硬件、VM 与存储拓扑

今天我们来深度实测一个专为极客、Homelab（家庭实验室）玩家以及中小企业 IT 运维人员设计的开源自托管基础设施管理平台：Home Lab Hub（GitHub 仓库名：raidowl/homelab-hub）。

对于热爱折腾服务器和私有云的极客来说，随着手里设备数量的增加，一个极具共性的痛点逐渐显现：几台物理服务器（Hardware）、几十个虚拟机（VM）、若干 Docker 容器、不同协议的网络共享存储（NFS、SMB、iSCSI、FTP），以及复杂的虚拟局域网（VLAN）。

传统的记录方式要么是在 Notion/Excel 表格里硬抠，要么是用简单的 Markdown 记备忘录。这不仅效率低下，更无法直观呈现设备与应用之间的网络关联与依赖流向。

Home Lab Hub 的切入点极其精准：它通过全量 CRUD（增删改查）资产管理、层级树状图（Tree View）以及基于 Cytoscape.js 的网络拓扑图谱（Network Graph Map），将杂乱的设备资产整理为直观、可交互的拓扑看板，让折腾 Homelab 的体验从“手工账本”进化到了“可视化指挥中心”。

部署实录

在部署与技术栈核验方面，Home Lab Hub 采用了极其清爽且经典的前后端分离架构：前端基于 Svelte 4、Vite 5 与 Pico CSS，拓扑图渲染由 Cytoscape.js 驱动；后端基于 Python 3.14 与 Flask 3，底层持久化使用 SQLAlchemy 2 并由 Alembic 管理数据库迁移，默认采用 SQLite 进行轻量落盘（数据库文件保存在 ./data/homelab-hub.db）。

项目支持跨平台的 ARM64 与 x86_64 架构，无论是标准的 X86 物理机、还是树莓派（Raspberry Pi 4+）、香橙派等低功耗 ARM 设备均能无缝运行。

对于绝大多数 Homelab 玩家，最推荐通过 Docker Compose 进行秒级拉起：

# 创建并编辑 docker-compose.yml 文件
services:
  homelab-hub:
    image: raidowl/homelab-hub:latest
    container_name: homelab-hub
    ports:
      - "8000:8000"
    volumes:
      - ./data:/data
    restart: unless-stopped

拉起容器非常简单：

# 启动常驻容器（数据库迁移会在容器启动时由 Alembic 自动完成）
docker compose up -d

如果你偏好纯物理机运行或需进行二次开发，手动部署流程也非常规范：

# 1. 克隆仓库
git clone https://github.com/raidowl/homelab-hub.git
cd homelab-hub

# 2. 准备 Python 虚拟环境并安装后端依赖
cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3. 执行数据库迁移升级 head
alembic upgrade head

# 4. 前端构建 (静态产物落盘至 frontend/dist/)
cd ../frontend
npm install
npm run build

# 5. 启动 Flask 开发服务（或生产环境使用 Gunicorn）
cd ../backend
python wsgi.py

容器或服务拉起后，直接在浏览器中访问 http://localhost:8000 即可开启控制面板。由于数据库保存在本地的 ./data/ 卷中，在后续版本升级时，只需在容器重启前执行一次数据卷备份即可防止意外损毁：

# 数据备份最佳实践
cp -r ./data ./data-backup-$(date +%Y%m%d)

核心亮点

亮点一：基于 Cytoscape.js 的全拓扑深度优先图谱（Network Graph Map）

这绝对是整个 Home Lab Hub 最吸睛的功能。

在传统的资产列表里，你很难一眼看清“哪台物理机的哪个虚拟机运行着哪套应用，又挂载了哪台 NAS 的 SMB 共享”。

Home Lab Hub 内置了 Cytoscape.js（一个功能强大的开源图形理论与网络可视化库）。它利用深度优先布局算法（Depth-First Layout），将你录入的硬件、虚拟机、应用服务、存储卷和网络设备之间的关联自动绘制为可缩放、可拖拽、节点可展开的高清拓扑图。点击任意节点，不仅高亮上下文依赖链路，还能直接唤起编辑模态框。

亮点二：覆盖全维度 Homelab 场景的资产管理与共享自动推导

区别于通用 ITAM（IT 资产管理）软件的生硬，Home Lab Hub 极其贴合个人实验室场景：

• • 全类型分类支持：分类涵盖 Hardware、VMs、Apps/Services、Storage、Networks、Shares（网络共享）以及 Misc（杂项）。
• • Shares 智能推导：特别针对存储场景，可直接在 Storage 实体下新建 NFS、SMB、iSCSI、FTP、SFTP、WebDAV 等具体共享协议，并自动推导连接字符串（如 smb://192.168.1.100/media），免去了手动记录繁琐挂载路径的麻烦。
• • 交叉搜索与树状视图：提供跨实体的全局搜索框，以及类似 IDE 侧边栏的折叠树状视图（Tree View），大到整台物理服务器，小到某一个特定的虚拟网卡，都能实现秒级定位。

亮点三：内嵌 Markdown 实时文档与单 JSON 文件全量备份

很多 Homelab 玩家习惯为特定服务写操作手册或排坑笔记。

Home Lab Hub 内部直接集成了一个基于 ByteMD 的层级 Markdown 文档编辑器，支持实时双栏预览和自动保存（Auto-save）。你可以将部署命令、配置文件备忘直接挂载在对应设备或应用的文档节点下。

同时，考虑到数据安全，面板 Header 直接提供了 一键 JSON 导出与恢复（Export/Import） 功能。不仅能从 UI 界面下载 homelab-export.json，还可以通过标准 REST API 或 curl 管道在 Cron 定时脚本中一键备份整个数据金库：

# 通过 API 接口轻松实现无头化自动化备份
curl -X GET http://localhost:8000/api/inventory/export -o homelab-export-$(date +%Y%m%d).json

避坑与总结

在实测与代码依赖分析中，我们也为计划部署 Home Lab Hub 的用户总结以下两点技术事实与使用避坑指南：

• • 完全覆盖导入（Import）的数据清除风险：通过 API 或 UI 执行 POST /api/inventory/import 恢复数据时，后端的处理逻辑是**“先清空当前数据库中的全量旧数据，再从 JSON 重新灌入”**，而非做增量 Merge（合并）。因此，在执行 Import 操作前，务必先点击 Export 下载一份最新的备份 JSON，以防误操作导致已有资产数据不可逆丢失。
• • Gunicorn 生产部署时的反向代理配置：在非 Docker 模式下，直接运行 python wsgi.py 仅适合单人开发测试。若使用 Gunicorn（如 gunicorn -w 4 -b 127.0.0.1:5001 wsgi:app）进行生产常驻，由于内置的 Flask 并不擅长高效分发静态资源，建议在前面套一层 Nginx 作为反向代理，将静态前端 location / 指向 frontend/dist/ 编译产物，而将 /api/ 路由转发至 Gunicorn 监听端口，以获得最佳的并发访问性能。

YourwayAI 主笔点评：

如果你手头有几台服务器、树莓派和 NAS，正苦于找不到一个轻量、美观且能清晰呈现设备依赖网路的基础设施看板，Home Lab Hub 绝对是一个诚意满满的极客项目。

它不仅拥有经典的 Python 3.14/Svelte 4 技术栈，更通过漂亮的拓扑图与 Markdown 内嵌文档，将“资产盘点”这件原本枯燥的事变得极具仪式感。极其推荐在个人 Homelab 环境中用 Docker 一键拉起使用！