HomeLab Monitor

HomeLab Monitor

一个页面掌握整个家庭实验室和 AI 设备组——真实 GPU 状态（支持任意厂商）、每秒令牌数、每小时电费、运行时间、训练任务、容器、磁盘。无需 Agent、独立指标栈或云服务。

你的家庭实验室逐渐添了几台机器、一台 Pi，还有一张神秘地总在忙碌的 GPU——最近它还开始运行模型了。HomeLab Monitor 为你提供一个可自托管的页面，回答你真正关心的问题：GPU 实际在做什么、哪个模型占用了它、运行成本是多少、哪个容器在吃 RAM、什么正在占满磁盘，以及有没有设备离线——通过 SSH 监控所有设备：Linux、Pi，甚至 Windows。连接 VPN 后，用手机也能轻松查看。

开始使用

# Grab the compose file and go. No GPU required — the GPU panels just light up when one's present.
curl -fsSLO https://raw.githubusercontent.com/SikamikanikoBG/homelab-monitor/main/docker-compose.yml
docker compose up -d

打开 http://<your-host>:9800 即可。完整选项（从源代码安装、GPU 工具包、Windows/WSL2）→ 安装文档。

🆕 最新动态 — 每次发布都会详细介绍，并说明背后的考量：最新版本 · 更新日志。仪表板也会在自我更新后，在应用内显示一次更新说明。

你将获得

一个页面，查看所有设备，解答你真正关心的问题。经典功能一应俱全，其上还构建了完整的 AI 驾驶舱。

实验室首页，也是墙面屏幕。 概览页打开后会显示启动台：你常用的应用以带有真实徽标的磁贴呈现，可直接从容器行固定，自动填入地址，并可分组、拖动排序。固定项保存在中枢，而非某个浏览器中——在笔记本上固定后，手机和墙面屏幕上也能看到。整个面板会适配屏幕：每次绘制后都会测量溢出，并按顺序让出空间——缩短列表、收窄设备群栏、将固定项折叠到 +N 更多后面，而不是把卡片截成两半或让内容超出屏幕。已验证支持从 4K 到 1366×768 的分辨率。点击 ⛶ 显示（或访问 /?display=1，专用自助服务终端只需此设置），即可隐藏所有多余界面元素并铺满显示器：你可以选择墙面屏幕显示哪些面板；在基于 Chromium 的浏览器中，还能在指定屏幕上全屏打开。 让 GPU 一目了然——每台机器上的标签页也保持一致。 标注为“100% 利用率”的显卡，仍可能在降频、受内存带宽限制，或时钟频率悄然下滑。GPU 标签页会解读 nvidia-smi 的限频原因，并显示内存带宽利用率、核心／显存时钟频率、功耗与功耗上限的对比、P-state——以及风扇转速——覆盖整个设备群中的每台机器，而不只是运行容器的那台。多 GPU 机器会为每张卡分别显示一个面板，并让每项指标共用同一刻度，因此温度曲线更高，确实代表显卡更热；热降频时段会直接标注在迷你趋势图上。你可以看到服务正在使用哪张卡（一台 3×3090 的机器会显示某个模型的 63 GB 显存用量分别为 22.5／22.1／18.8 GB，而不是合并成一个数字），查看各服务的能耗，并在显卡降频、过热或风扇故障时收到告警——按显卡持续监测，并针对每台主机设置阈值，因为功耗上限被刻意调低的机器，本来就应该运行在上限。现在也不再只有 NVIDIA：Linux 上的 AMD GPU 会直接通过内核的 amdgpu 接口读取（无需 ROCm）；Windows 主机上的 AMD 和 Intel GPU 也能读取——无需厂商工具，便可显示显卡名称、利用率和 VRAM。驱动无法报告的数据会明确说明，而不是自信地显示为零。

成本明细，精确到进程。 将功耗换算成费用：先按机器统计，再按组件统计（GPU 数据来自 nvidia-smi，CPU／DRAM 数据来自 RAPL），然后细化到每个进程、容器或模型——点击任意一行，即可查看其在任意时间范围内的功耗和费用。支持分时电价（Economy 7、Heures Creuses，……），也可以直接选择所在国家，以获得合理的估算值。每瓦功耗要么是实测值，要么来自你设置的基准值；绝不会臆测墙插功耗。高峰时段热力图还能把数月的样本汇总成一张图，显示实验室在什么时段最费钱——按星期几 × 小时排列的 7×24 网格，让你一眼看出一周中哪个时段最贵。

为你的训练运行计算费用。 使用单文件客户端从 Jupyter、Colab 或 Kaggle 推送运行记录（或从 MLflow 同步），即可同时获取损失曲线和实际消耗的 GPU 能量，并显示在同一时间轴上。你可以自行创建、命名、设置过期时间并撤销 API 密钥。

“能装得下吗？”——测出来，不靠猜。 Benchmark Lab 会加载每个本地 ollama 模型，并在你的实际显卡上逐级测试不同的上下文长度，记录生成和提示词的每秒 token 数、加载时间、从 VRAM 溢出到系统 RAM 的数据量，以及仍可完整装入 VRAM 的最大上下文长度——这就是值得设置的上限。选择要测试的 GPU（通过临时创建并固定到指定 GPU 的 ollama 容器——不会触碰你正在使用的主容器），叠加已保存的运行结果以比较显卡；每次运行还会返回其能耗和费用。结果会保存：只需进行一次基准测试，只有发生变化时才需要重新运行。

实验室的其他功能，依旧如往常：

• 如实呈现容器状态 — 显示健康状况，并将 RAM 和 VRAM 分列显示（是真正的驻留 RAM，不是页面缓存）；点击容器，即可在侧边抽屉中查看实时日志。舰队中的每个容器都拥有相同的控制项 — 日志、启动／停止／重启、重启策略、固定；所有操作都通过探测器已在使用的同一 SSH 连接完成，整个标签页也适用于手机。
• systemd 服务 — 本地或远程服务，突出显示你自己的单元，并优先显示故障项。
• WizTree 风格的磁盘树状图 — 适用于舰队中的任意主机。 点击查看占用中心节点 或 你添加的任意 Linux 主机磁盘空间的文件夹；远程主机通过其他所有功能共用的同一 SSH 连接进行扫描，因此仍然无需在远程主机上安装任何东西。此外还提供 网络 I/O 和各容器的流量发起者排行，以及用于查看 CPU 和 RAM 占用情况的 迷你 htop。
• 仪表板实时更新。 利用率、RAM、温度和功耗每隔几秒就会通过推送流更新一次，而不是固定轮询；与此同时，它发送的请求 比以前更少，因为开销较大的历史查询只会在对应图表区间可能变化时才获取，而你没有查看的标签页则完全不会产生开销。采样和存储频率保持不变，因此历史数据的密度和开销的准确性都与之前完全一致。
• 通过 SSH 管理多台机器 — 为每台主机粘贴一个密钥；支持 Linux、Pi，甚至 Windows。无需 Agent，也无需安装。GPU 标签页也支持按主机查看：远程多 GPU 机器会显示 每张显卡的 VRAM、利用率、功耗和温度，以及占用显存的进程。
• 内置运行时间监控 — 直接通过容器监控任意 HTTP 端点或 TCP 端口（你的服务、NAS、远程站点）：心跳条、24 小时／7 天运行时间百分比、延迟，以及 智能的逐项检查告警 — 防抖确认、恢复通知和停机时长，以及可选的响应缓慢警告。无需自行托管额外的运行时间监控服务 — 它已内置于容器中。
• 推送告警 — 支持 Discord、ntfy.sh 和 Telegram；仅在状态变化时触发，避免刷屏。

按标签页查看完整功能 → 功能。

用两句话了解多机管理

打开 主机 标签页，将自动生成的 SSH 密钥粘贴到每台远程主机上，中心节点便会开始轮询这些主机 — 无需 Agent，只需 SSH + Python 3（Windows 上使用 PowerShell）。中心节点通过 SSH 传输一个小型独立探测程序；远程主机上不会留下任何文件。同一连接还让你能从中心节点打开远程主机的 GPU 控制台 并 扫描其磁盘 — 远程主机仍然无需安装任何东西。

入门指南、Windows 设置和安全模型 → 多机管理文档。

配置

在 docker-compose.yml 的 environment: 下设置这些变量（均为可选）：

变量	默认值	含义
SAMPLE_INTERVAL	10	存储样本的间隔秒数。这是存储频率——每项能耗和费用数据都会按此间隔累计，因此修改它会影响历史数据的计价方式
FAST_INTERVAL	2	屏幕上实时值的刷新间隔秒数。仅读取开销低的计数器，不存储任何数据，因此不会占用历史记录，也不会影响准确性。设为 0 可关闭推送流，仪表板将改用轮询
RETENTION_DAYS	180	历史数据的保留时长
PRESSURE_FREE_MB	2048	可用 VRAM 低于此值时视为“压力”状态
PORT	9800	仪表板端口
MCP_PORT	9810	内置只读 MCP 服务的端口
ENABLE_MCP	1	设为 0 可在不运行 MCP 服务的情况下运行仪表板
ENABLE_CONTROLS	1	设为 0 可从 Containers 和 Services 选项卡中移除启动／停止／重启按钮
ALLOW_SELF_UPDATE	1	设为 0 可禁用应用内更新
WATCH_CONTAINERS	—	要扫描 OOM 的额外容器（以逗号分隔）
WATCH_SERVICES	—	始终显示的 systemd 单元，即使是供应商提供的单元也会显示（以逗号分隔）
CHECK_UPDATES	true	设为 false 可禁用每日 GitHub releases 检查（不会发出外部请求）
CHECK_OS_UPDATES	true	设为 false 可停止报告待安装的 OS 软件包更新
PUBLIC_STATUS	—	设置后启用公开状态页（也可在 Settings 中切换，无需重启）
DB_PATH	/data/gpu.db	容器内的历史数据存储位置
HOST_ROOT	/rootfs	只读主机根目录的挂载点
DOCKER_SOCK	/var/run/docker.sock	用于读取容器的 Docker 套接字

历史数据保存在 ./data/gpu.db（绑定挂载）中，因此重启和升级后仍会保留。有关警报、systemd D-Bus 挂载和各服务器调优的信息，请参阅 → 配置文档。

底层实现

该中心将 nvidia-smi（以及通过内核中的 amdgpu sysfs 接口支持的 AMD GPU，还有通过内置 GPU 性能计数器支持的 Windows 主机上的 AMD/Intel GPU）、Docker API、模型服务器 API（Ollama、vLLM、llama.cpp、A1111 等）、systemd D-Bus 以及 /proc 和 /sys 的数据整合为一个采样视图，持久化到 SQLite，并在读取时进行降采样，因此加载六个月范围的数据与加载最近一小时的数据一样快。单页应用，内置 Chart.js，无需构建步骤。

• 可识别 30 多种模型服务器 → 模型服务器
• 标准 /metrics 端点，可采集到你现有的任意仪表板中 → 指标导出
• 完整的数据管道和调用方归因 → 工作原理

连接 AI Agent（MCP）

你的家庭实验室现在对 AI Agent 一目了然了——只需让客户端连接一个 URL，就能查看每台主机、容器、GPU 和磁盘。只读，无需额外设置。

HomeLab Monitor 不再只是给你看的仪表板；它也能为你的 AI Agent 提供上下文。同一个容器中内置了只读 MCP 服务（在 :9810 上提供服务），因此 Claude、Claude Code 或任何 MCP 客户端只需一行配置即可连接，并通过 19 个命名工具探索你的整个家庭实验室，覆盖范围与仪表板相同：主机、容器、systemd 服务、GPU 及其使用者、每个进程的 RAM、AI 模型服务、已安装的模型、成本、实验运行、模型基准测试、磁盘树图、历史记录和警报。

_{连接任何 MCP 客户端——Claude、ChatGPT，或运行你自己的本地 Ollama 模型的 Agent——即可读取家庭实验室的实时状态。只读：双方只进行问答。}

# the dashboard is on :9800; the MCP server rides along on :9810
claude mcp add --transport http homelab http://YOUR-HUB:9810/mcp

连接后，无需再到处翻找标签页，直接提问即可——Agent 会选用合适的工具：

• “我的 GPU 已经满载一小时了——当前加载的是哪个模型服务，实际是谁在调用它？”
• “是什么占满了 /backup？列出最大的文件夹，并标出任何看起来像是失控日志的内容。”
• “现在哪台主机的 RAM 最少？占用最多的进程是什么？”
• “我打算这个周末重启并升级操作系统——哪台机器最需要升级？考虑到每台机器上正在运行的服务，怎样安排顺序才安全？”

只读是刻意设计的——没有写入工具，因此 Agent 可以查看，但绝不会改动你的设备。随时设置 ENABLE_MCP=0 即可关闭。完整工具列表和设置方法 → MCP 文档。

安全

这是一个主机监控工具：它拥有主机访问权限，还可以读写 Docker 套接字和 D-Bus 套接字（默认启用自我更新，以及 Containers/Services 标签页中的启动/停止/重启控件——设置 ALLOW_SELF_UPDATE=0/ENABLE_CONTROLS=0，或使用 docker-compose.readonly.yml，即可将其限制为纯监控），并以只读方式挂载根目录——这些宽泛的权限是有意设计的。仪表板本身没有登录/身份验证——它适用于可信任的局域网。**请将它置于局域网/VPN/防火墙之后，不要将其暴露到公共互联网。**详情 → 文档。

⭐ 支持这个项目

如果 HomeLab Monitor 帮你少开了一两个浏览器标签页，在 GitHub 上点个 ⭐ 确实能帮助其他家庭实验室爱好者发现它。谢谢！

💬 社区

一起打造它会更有趣。加入 HomeLab Monitor Discord——打个招呼、展示你的设备、交流想法、寻求帮助，或者只是一起聊聊。路线图讨论、“我们要不要做 X？”之类的问题，以及快速互助都会在这里发生——新贡献者也会在这里受到热情欢迎。

邀请朋友、发布想法、提交 issue——让我们一起发展一个友好、健康的家庭实验室社区。💛

贡献

非常欢迎提交 issue 和 PR——尤其是新的模型服务探测器、新的监控项和 GPU 后端。这是一个旨在帮助其他家庭实验室爱好者的业余工具，请友善交流。请参阅 CONTRIBUTING.md。

贡献者

感谢所有提交问题、发起 PR 或帮助制定路线图的人。AMD GPU 后端的全部功能——在 v0.28.0 中通过 DRM fdinfo 获取每个进程的 VRAM 用量，并实现完整的面板功能对等；在 v0.26.0 中为统一内存 APU 提供真实的 VRAM 数据——均由 @andreahaku 贡献。v0.27.0 的机群感知模型注册表和 v0.23.0 的维护时段由 @1HazyOne707 贡献。v0.27.0 的 RAPL CPU/DRAM 功耗功能和 v0.24.0 的 backend/ 模块树重构由 @pehota 贡献。完整且持续更新的致谢记录，请参阅更新日志。

许可证

MIT — 请参阅 LICENSE。