HomeButler 是一个针对 Homelab 多服务器环境设计的运维状态报告工具，以单一 Go 二进制文件形式分发。它的核心思路不是展示当前的实时图表，而是记住服务器上一次的状态，并判断哪些变化值得告知用户或 AI 代理。
主要能力
变更检测与报告：HomeButler 会保存快照并在后续运行时与最近一次快照比较。每一行变化包含三个信息：变化类型、变化对象和具体变化内容。类型使用固定词汇，并且在 --json 输出中保持一致，便于机器解析。其中 replaced 表示同名容器被重新创建但各项计数不变的情况，这是计数比较方式无法发现的重要变化；skipped 表示无法比较，而不是报告没有变化。报告头部会注明所比较的快照，避免时间窗口歧义。
系统与容器监控：通过 SSH 远程检查服务器，展示系统健康、Docker 容器、应用端口和系统端口。Docker 发布的端口会关联回所属容器。inventory scan 提供快速清单，可使用 --filter 过滤仅显示对所有接口开放的端口。
进程重启监控与崩溃分析：watch 功能支持 Docker、systemd 和 PM2 后端。Docker 使用实时事件流，systemd 和 PM2 使用轮询。检测到崩溃时保存死亡前日志和重启后日志，并根据退出码和日志模式分析原因分类，如 oom、panic、segfault、timeout、dependency、error，同时识别 flapping 重启循环（急性：10 分钟内 3 次以上；慢性：24 小时内 5 次以上）。
备份验证：backup drill 将备份档案在隔离容器中以独立网络和端口启动，要求通过 HTTP 健康检查才判定为通过，失败时返回非零退出码，可放入 cron 定期执行。
doctor 预检：只读检查常见问题，包括磁盘或内存使用过高、停止的容器、公开绑定端口、过期或缺失的备份、通知缺失、报告基线是否就绪、配置的 Proxmox 端点是否可达等。每个发现都会给出下一步建议命令。
配置验证：config validate 在不启动任何服务的情况下读取配置，告知使用了哪个文件、四条解析规则中的哪一条选中了它，以及每个配置段的解析结果，避免未知键被静默丢弃或路径不存在时静默回退默认值。
一键应用安装：homebutler install 可部署 Uptime Kuma、Jellyfin、Pi-hole、Gitea、Portainer 等自托管应用，自动预检查 Docker、端口和重复项，并生成 docker-compose.yml。
Web 仪表盘：homebutler serve 启动内嵌在二进制中的 Web 界面，可查看服务器、Docker 容器、开放端口、告警和 Wake-on-LAN，支持 --token 编辑配置。前端在构建时编译进 Go 二进制，无需 Node.js。
Proxmox 支持：可查看节点、QEMU 和 LXC 客户机、存储、任务状态，并对客户机执行电源操作。
MCP 集成：内置 MCP 服务器，允许 AI 助手以结构化接口检查服务器，而无需提供完整 SSH shell。
使用方式
可通过 CLI、cron、Web 仪表盘或 AI 代理运行。支持以容器方式运行并通过 SSH 访问目标机器：
docker run -v ~/.config/homebutler:/config -v ~/.ssh:/root/.ssh:ro ghcr.io/higangssh/homebutler
机器可读的 JSON 输出在各处均可使用。watch install 可将监控循环安装为 Linux systemd 用户单元或 macOS launchd 代理，使其在注销和重启后继续运行。
适用场景
适用于需要维护多台自托管服务器的 Homelab 用户，尤其是希望快速了解服务器变化、排查凌晨服务重启原因、验证备份可恢复性、以结构化方式让 AI 助手检查服务器而不暴露 SSH 的场景。也可与 Uptime Kuma、Beszel、Netdata、Dozzle 等工具并存使用。
限制与说明
判断规则是书面规则而非模型，相同输入产生相同报告，不需要 AI、账户或付费层级，但资料未说明是否存在付费版本。被监控机器上不运行代理或守护进程，二进制通过 homebutler deploy 部署一次，仅在通过 SSH 请求时运行。通知默认禁用，适合隔离或封闭网络。systemd 重启需要 root 或 polkit 规则，非特权运行会被拒绝。处于 flapping 状态的目标不会被重启。具体安装和配置细节可参考官方文档与发布页面。
