Homebutler

使用 homebutler CLI 管理家庭实验室（homelab）服务器。单二进制文件，无需守护进程或数据库，输出 JSON 格式，兼容 MCP。

前提条件

homebutler 必须已安装并位于系统 PATH 中。

# 检查是否已安装
which homebutler

# 方式 1：通过 Homebrew 安装（macOS/Linux）
brew install Higangssh/homebutler/homebutler

# 方式 2：通过 Go 安装
go install github.com/Higangssh/homebutler@latest

# 方式 3：从源码构建
git clone https://github.com/Higangssh/homebutler.git
cd homebutler && make build && sudo mv homebutler /usr/local/bin/

命令列表

初始化向导

homebutler init                      # 交互式配置初始化

在 ~/.config/homebutler/config.yaml 创建配置文件，并通过引导式提示完成配置。

系统状态

homebutler status                    # 本地服务器
homebutler status --server rpi       # 指定远程服务器
homebutler status --all              # 并行查询所有服务器

返回信息包括：主机名、操作系统、架构、运行时间、CPU（使用率% / 核心数）、内存（总量 / 已用 / 使用率%）、磁盘（挂载点 / 总量 / 已用 / 使用率%）

Butler 报告

homebutler report                    # 健康状态、警告、变更项及建议操作
homebutler report --no-save          # 预览报告（不保存快照）
homebutler report --keep 7           # 保留最近 7 个快照
homebutler report --json             # 结构化输出，适用于自动化脚本或 MCP 集成

当用户询问“我的 homelab / 服务器当前状态如何？”并希望获得简洁的运行概览时，请优先使用该命令。它会捕获当前系统/容器/端口状态，并与上一次执行结果进行比对。

资产清单与拓扑结构

homebutler inventory scan                     # 以树状视图展示系统、容器、端口信息
homebutler inventory scan --json              # 结构化资产清单输出
homebutler inventory export --format mermaid  # 导出 Mermaid 格式拓扑图

当用户询问“当前运行了哪些服务？”、“哪个容器占用了该端口？”或需要为文档编写、AI 分析提供上下文和网络拓扑时，请使用该命令。

Docker 管理

homebutler docker list               # 列出全部容器
homebutler docker list --server rpi  # 列出指定远程服务器上的容器
homebutler docker list --all         # 列出所有服务器上的容器
homebutler docker restart      # 重启某容器
homebutler docker stop         # 停止某容器
homebutler docker logs         # 输出最后 50 行日志
homebutler docker logs  200    # 输出最后 200 行日志

Wake-on-LAN（网络唤醒）

homebutler wake            # 按 MAC 地址唤醒
homebutler wake                    # 按配置中定义的名称唤醒
homebutler wake  192.168.1.255     # 自定义广播地址

配置中的名称需在 wake 目标节下定义。

开放端口

homebutler ports                     # 查询本地服务器
homebutler ports --server rpi        # 查询远程服务器
homebutler ports --all               # 查询所有服务器

返回信息包括：协议、地址、端口、PID、进程名

网络扫描

homebutler network scan

通过 ping 扫描 + ARP 表探测本地局域网设备。返回信息包括：IP 地址、MAC 地址、主机名、状态。
注意：扫描可能耗时最长达 30 秒；部分设备若未响应 ping 请求，则不会出现在结果中。

TUI 仪表盘

homebutler watch                     # 所有服务器的实时终端仪表盘

实时监控所有已配置服务器，自动刷新。终端 UI 中显示 CPU、内存、磁盘使用率及 Docker 容器状态。

Web 仪表盘

homebutler serve                     # 启动 Web 仪表盘（默认端口 8080）
homebutler serve --port 3000         # 自定义端口
homebutler serve --demo              # 演示模式（使用模拟数据，不调用真实系统接口）

浏览器访问地址：http://localhost:8080。只读视图，展示所有服务器、Docker 容器及告警信息。

SSH 主机密钥信任管理

homebutler trust             # 信任远程服务器的 SSH 主机密钥
homebutler trust  --reset    # 删除旧密钥并重新建立信任

采用 TOFU（首次使用即信任）模型。首次通过 SSH 连接新服务器前必须执行此操作。

升级

homebutler upgrade                   # 升级本地及所有远程服务器上的 homebutler
homebutler upgrade --local           # 仅升级本地二进制文件

从 GitHub 下载最新发布版本并完成安装。对远程服务器，通过 SSH 执行升级操作。

资源告警

homebutler alerts                    # 查询本地服务器
homebutler alerts --server rpi       # 查询远程服务器
homebutler alerts --all              # 查询所有服务器

依据配置文件中设定的阈值检查 CPU、内存、磁盘使用情况，按资源分别返回状态（ok / warning / critical）。

部署（远程安装）

homebutler deploy --server rpi                          # 从 GitHub Releases 下载安装
homebutler deploy --server rpi --local ./homebutler     # 离线环境：复制本地二进制文件
homebutler deploy --all                                 # 部署至全部远程服务器

通过 SSH 在远程服务器上安装 homebutler，自动识别目标系统的 OS 和架构。
安装路径优先级： /usr/local/bin → sudo /usr/local/bin → ~/.local/bin（同时自动将该路径加入 .profile/.bashrc/.zshrc 的 PATH）。

应用安装

homebutler install list              # 列出可用应用
homebutler install              # 安装指定应用（基于 docker compose）
homebutler install  --port 9090 # 自定义端口
homebutler install status       # 查看应用运行状态
homebutler install uninstall    # 停止应用但保留数据
homebutler install purge        # 停止应用并彻底删除所有数据

通过 docker compose 部署自托管应用。每个应用均独立部署于 ~/.homebutler/apps// 目录下，含自动生成的 docker-compose.yml 文件及持久化数据目录。安装前自动检测 Docker 是否可用、端口是否冲突、是否存在重复安装。当前支持的应用包括：uptime-kuma、plex、vaultwarden、filebrowser、it-tools、gitea、jellyfin、homepage、stirling-pdf、speedtest-tracker、mealie、pi-hole、adguard-home、portainer、nginx-proxy-manager。

备份、恢复与备份验证

homebutler backup                          # 备份 Docker compose 卷及文件
homebutler backup --service uptime-kuma    # 仅备份指定服务
homebutler backup list                     # 列出备份归档文件
homebutler backup drill uptime-kuma        # 在隔离环境中启动备份并验证 HTTP 健康状态
homebutler backup drill --all              # 对备份中所有支持的应用执行验证
homebutler backup drill --archive ./file   # 验证指定归档文件
homebutler restore ./backup.tar.gz         # 从归档文件恢复卷数据

当用户询问“我的备份是否可信？”时，请优先使用 backup drill：它会校验归档完整性，在隔离的 Docker 环境中启动应用、执行健康检查，并自动清理临时资源。

MCP 服务器

homebutler mcp                       # 启动 MCP 服务器（基于 stdio 的 JSON-RPC）

启动内置的 MCP（Model Context Protocol）服务器，供 Claude Desktop、ChatGPT、Cursor 及其他 MCP 客户端使用。不监听任何网络端口，仅通过 stdio 通信。

当前支持的 MCP 工具：

• system_status
• report
• inventory_scan、inventory_export
• docker_list、docker_restart、docker_stop、docker_logs、docker_stats
• wake、open_ports、network_scan、alerts
• backup_create、backup_list、backup_drill、backup_restore
• install_list、install_app、install_status、install_uninstall、install_purge

版本信息

homebutler version

输出格式

所有命令默认输出人类可读文本。如需机器可解析的 JSON 输出（推荐用于 AI 或脚本集成），请添加 --json 参数。

配置文件

配置文件按以下顺序自动查找：

1. --config — 显式指定路径
2. $HOMEBUTLER_CONFIG — 环境变量指定路径
3. ~/.config/homebutler/config.yaml — XDG 标准路径（推荐）
4. ./homebutler.yaml — 当前工作目录

若未找到配置文件，则使用合理默认值。

配置项说明

• servers — 服务器列表，含 SSH 连接参数
• wake — 命名的 WOL 目标（含 MAC 地址与广播地址）
• alerts.cpu/memory/disk — CPU / 内存 / 磁盘告警阈值（百分比）
• output — 默认输出格式

多服务器配置示例

servers:
  - name: main-server
    host: 192.168.1.10
    local: true

  - name: rpi
    host: 192.168.1.20
    user: pi
    auth: key                # "key"（默认，推荐）或 "password"
    key: ~/.ssh/id_ed25519   # 可选，支持自动发现

  - name: vps
    host: example.com
    user: deploy
    port: 2222
    auth: key
    key: ~/.ssh/id_ed25519

使用指南

1. 始终执行命令，切勿猜测 — 使用 homebutler status 获取真实数据
2. 为用户提供结果解读 — 不要直接输出原始 JSON，应以自然语言总结关键信息
3. 及时预警异常 — 若任一资源状态为 “warning” 或 “critical”，需明确高亮提示
4. 使用 --all 获取全局视图 — 当用户询问 “所有服务器” 或 “全部” 时，优先使用 --all
5. 使用 --server 聚焦特定目标 — 当用户提及具体服务器名称时，使用 --server
6. Docker 错误处理 — 若目标服务器未安装 Docker 或 Docker daemon 未运行，需清晰说明原因
7. 网络扫描提示 — 提醒用户该操作可能耗时约 30 秒
8. 安全注意事项 — 切勿在群聊等公开场景中暴露含主机名/IP 的原始 JSON，应做脱敏摘要
9. 离线部署建议 — 对无外网环境，推荐使用 --local 参数

安全说明

• SSH 认证：始终优先使用密钥认证而非密码；切勿在配置文件中明文存储密码。
• 网络扫描：仅限在您拥有的本地网络中运行；执行前应明确提醒用户。
• 部署操作：仅允许部署至您拥有控制权的服务器；远程安装前必须获得用户确认。
• 配置文件权限：确保配置文件仅对属主可读写（chmod 600）。
• 无遥测机制：homebutler 不向外发送任何数据；所有操作均在本地执行，或仅连接用户明确配置的目标主机。

错误处理

• SSH 连接失败 → 检查配置中的 host/port/user 字段，确认远程服务器已注册对应 SSH 公钥
• 远程服务器未找到 homebutler → 首先运行 homebutler deploy --server
• Docker 未安装 → 明确告知用户该服务器上未安装 Docker
• Docker daemon 未运行 → 建议执行 sudo systemctl start docker
• 网络扫描超时 → 在大型子网中属正常现象，建议重试
• 权限被拒绝 → 某些系统上执行端口或 Docker 相关命令可能需要 sudo 权限

典型交互示例

用户：“服务器当前状态如何？”
→ 优先执行 homebutler report，汇总健康状态、告警、显著变更及建议操作；仅在需要原始瞬时状态时使用 homebutler status。

用户：“有什么变化？这个端口是谁在用？帮我梳理一下 homelab 拓扑。”
→ 执行 homebutler inventory scan 或 homebutler inventory export --format mermaid。

用户：“检查所有服务器。”
→ 执行 homebutler status --all，逐台简述各服务器状态。

用户：“树莓派怎么样？”
→ 执行 homebutler status --server rpi，并作简要总结。

用户：“当前运行了哪些 Docker 容器？”
→ 执行 homebutler docker list，列出容器名及其运行状态。

用户：“把 NAS 唤醒。”
→ 执行 homebutler wake nas（若已配置）；否则请用户提供 MAC 地址。

用户：“所有服务器上有无告警？”
→ 执行 homebutler alerts --all，汇报所有 warning/critical 级别告警。

用户：“在新服务器上部署 homebutler。”
→ 执行 homebutler deploy --server ，并反馈执行结果。

用户：“安装 uptime-kuma。”
→ 执行 homebutler install uptime-kuma，反馈访问 URL 及部署状态。

用户：“有哪些应用可选？”
→ 执行 homebutler install list，展示全部可用应用列表。

用户：“彻底卸载 vaultwarden。”
→ 执行 homebutler install purge vaultwarden，并确认数据删除操作。

用户：“我的备份是否可靠？”
→ 执行 homebutler backup drill 或 homebutler backup drill --all，反馈通过/失败结果及健康状态。