家庭实验室利器：HomeLab-Monitor 多主机监控仪表盘部署教程

简介

什么是 HomeLab-Monitor ？

HomeLab-Monitor 是一个开源的家庭实验室监控仪表盘，可以在单个容器中监控 GPU、Docker 容器、systemd 服务、磁盘使用情况等。它特别适合运行 AI 模型的家庭实验室，可以实时显示哪个容器正在使用 GPU、消耗了多少显存。如果你也在用 云栈社区 里大伙儿常讨论的那些“ homelab 神器”，那这个项目可能会让你眼前一亮。

主要特点

• GPU 监控：实时显示 VRAM 使用率、功耗、温度，并自动识别哪个容器正在占用 GPU
• 容器健康监控：显示容器状态、内存使用（真实驻留内存，非页面缓存）和显存占用
• systemd 服务监控：支持本地和远程服务，可高亮显示自定义单元，失败服务优先展示
• 磁盘空间分析：类似 WizTree 的磁盘树状图，可深入分析文件夹，找出占用空间的大文件
• 多主机支持：通过 SSH 连接多台机器（Linux、树莓派、Windows），无需安装代理
• 推送告警：支持 Discord 和 ntfy.sh 通知，边缘触发避免重复告警
• MCP 服务器：内置只读 MCP 服务器，可让 AI 代理（如 Claude）探索你的家庭实验室
• 开源免费：基于 MIT 协议开源，可免费使用和修改

应用场景

• AI 模型服务器监控：实时查看 Ollama、vLLM、llama.cpp 等模型服务器的 GPU 占用情况
• 家庭服务器运维：监控多台服务器的 CPU、内存、磁盘使用情况
• 容器化应用管理：查看所有 Docker 容器的运行状态和资源占用
• 系统服务管理：监控 systemd 服务的运行状态，及时发现故障
• 远程设备管理：通过 SSH 连接树莓派、Windows 等远程设备进行统一监控

HomeLab-Monitor 是一个即插即用的家庭实验室监控解决方案，让你在一个页面上掌握整个实验室的运行状态。

安装

在群晖上以 Docker 方式安装。

如果你熟悉在 运维/DevOps/SRE 领域常用的容器化部署流程，那接下来的步骤会非常轻松。在注册表中搜索 sikamikaniko123，选择第一个 sikamikaniko123/homelab-monitor，版本选择 latest。

本文写作时，latest 版本对应为 0.14.4；

docker cli 安装

如果你熟悉命令行，可能用 docker cli 更快捷

# 新建文件夹 homelab-monitor 和 子目录
mkdir -p /volume1/docker/homelab-monitor/data

# 进入 homelab-monitor 目录
cd /volume1/docker/homelab-monitor

# 一键启动
docker run -d \
  --name=homelab-monitor \
  --restart=unless-stopped \
  --network=host \
  --pid=host \
  --cap-add=SYS_PTRACE \
  --security-opt=apparmor=unconfined \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v /:/rootfs:ro \
  -v $(pwd)/data:/data \
  -v /run/dbus/system_bus_socket:/run/dbus/system_bus_socket:ro \
  -e PORT=9800 \
  -e SAMPLE_INTERVAL=10 \
  -e RETENTION_DAYS=180 \
  sikamikaniko123/homelab-monitor:latest

注意：HomeLab-Monitor 使用 host 网络模式和 pid: host，这是为了能够访问 Docker API 和监控系统进程。同时需要添加 SYS_PTRACE 权限和禁用 AppArmor。

环境变量

以下均为可选的环境变量

变量	默认值	含义
PORT	9800	仪表盘监听在 0.0.0.0:$PORT。使用 host 网络时，这也是局域网端口。
MCP_PORT	9810	内置只读 MCP 服务监听在 0.0.0.0:$MCP_PORT/mcp。
ENABLE_MCP	0	是否启用仪表盘内置的 MCP 服务；取消注释并设置后可关闭或开启。
MCP_ALLOWED_HOSTS	(empty)	限制 MCP HTTP 传输可接受的 Host 头；可用 host:* 通配符。未设置时，默认可从 homelab 内部访问。
SAMPLE_INTERVAL	10	采集器循环之间的秒数间隔。
RETENTION_DAYS	180	SQLite 历史数据保留时长。读取时会做降采样，所以更长时间范围查询也很轻量。
PRESSURE_FREE_MB	2048	当可用显存低于此值时，会被视为“压力”状态，用于洞察和告警。
HOST_ROOT	/rootfs	宿主机的 / 挂载到容器中的位置，用于磁盘统计。
DBUS_SYSTEM_BUS_ADDRESS	unix:path=/run/dbus/system_bus_socket	指向宿主机 systemd D-Bus socket 的地址，用于读取系统服务健康状态。
NVIDIA_VISIBLE_DEVICES	all	允许 NVIDIA 容器运行时在可用时注入 GPU 设备。
NVIDIA_DRIVER_CAPABILITIES	utility	允许注入 nvidia-smi 等 NVIDIA 工具。
WATCH_CONTAINERS	(empty)	以英文逗号分隔的容器名称列表，即使没有被归因到 GPU，也总是扫描这些容器的 OOM 事件。
WATCH_SERVICES	(empty)	以英文逗号分隔的 systemd 单元列表，始终在 Services 选项卡中显示。

docker-compose 安装

也可以用 docker-compose 安装，将下面的内容保存为 docker-compose.yml 文件

services:
  homelab-monitor:
    image: sikamikaniko123/homelab-monitor:latest
    container_name: homelab-monitor
    restart: unless-stopped
    network_mode: host
    pid: host
    cap_add:
      - SYS_PTRACE
    security_opt:
      - apparmor=unconfined
    environment:
      NVIDIA_VISIBLE_DEVICES: all
      NVIDIA_DRIVER_CAPABILITIES: utility
      PORT: "9800"
      MCP_PORT: "9810"
      SAMPLE_INTERVAL: "10"
      RETENTION_DAYS: "180"
      PRESSURE_FREE_MB: "2048"
      HOST_ROOT: "/rootfs"
      DBUS_SYSTEM_BUS_ADDRESS: "unix:path=/run/dbus/system_bus_socket"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /:/rootfs:ro
      - ./data:/data
      - /run/dbus/system_bus_socket:/run/dbus/system_bus_socket:ro

然后通过 SSH 登录到您的群晖，执行下面的命令：

# 新建文件夹 homelab-monitor 和 子目录
mkdir -p /volume1/docker/homelab-monitor/data

# 进入 homelab-monitor 目录
cd /volume1/docker/homelab-monitor

# 将 docker-compose.yml 放入当前目录

# 一键启动
docker-compose up -d

运行

在浏览器中访问 http://<群晖IP>:9800 即可进入 Web 界面。

就像你在 开源实战 中遇到的许多优秀项目一样，它对硬件的要求非常灵活。如果需要 GPU 监控，需要安装 NVIDIA Container Toolkit，但老苏没有条件试。

可以监控容器

群晖上并不支持 systemd

如果需要 systemd 服务监控，需确保 D-Bus socket 已正确挂载

可以监视主机的详情，包括 CPU、内存等等

磁盘的详情

网络信息

多主机监控

HomeLab-Monitor 支持通过 SSH 连接多台远程设备：

1. 打开 Dashboard 的 Hosts 标签页
2. 复制自动生成的 SSH 公钥到远程设备
3. 远程设备只需支持 SSH + Python 3（Windows 需要 PowerShell）

MCP

HomeLab-Monitor 支持 MCP 服务，如果你用 claude 可以用命令行直接安装

claude mcp add --transport http homelab http://<群晖IP>:9810/mcp

再以 Cherry Studio 做个示例

• 名称：例如就叫 homelab
• 类型：选择 可流式传输的 HTTP（streaableHttp）
• URL：地址为 http://<群晖IP>:9810/mcp

保存之后可以看到工具

随便问个问题，例如：主机上安装了多少个容器？

或者看看 占用内存最大的容器是哪个？

注意事项

1. 网络安全：HomeLab-Monitor 运行时具有主机访问权限，包括 Docker socket、根文件系统和 D-Bus socket。请将其保持在局域网/VPN/防火墙内，不要暴露到公网
2. GPU 支持：GPU 监控是可选功能，没有 GPU 的主机仍然可以正常使用容器、服务和磁盘监控
3. 数据持久化：历史数据存储在 ./data/gpu.db，请确保该目录有适当的读写权限
4. systemd 监控：如果不需要监控 systemd 服务，可以移除 D-Bus socket 的挂载，Services 面板会显示"unavailable"
5. 资源占用：HomeLab-Monitor 非常轻量，内存占用通常在 50MB 以内

参考文档

HomeLab-Monitor: One page for your whole home lab & AI rig — GPU, containers, services, disks
地址： https://github.com/SikamikanikoBG/homelab-monitor

HomeLab-Monitor Documentation
地址： https://sikamikanikobg.github.io/homelab-monitor/

HomeLab-Monitor Docker Hub
地址： https://hub.docker.com/r/sikamikaniko123/homelab-monitor