homebutler

HomeButler

只汇报值得一提的变化。
一个 Go 单文件二进制程序，会记住你的服务器上次的样子， 并告诉你——或 Agent——发生了哪些变化。

网站 · 文档 · 版本发布

这就是全部理念。大多数 homelab 工具只向你展示此刻的图表，把“这重要吗？”留给你自己。HomeButler 会记住你的服务器上次的样子，判断哪些变化值得一提，然后告诉你——即使前后各有六个容器，也不能算作“没有变化”，因为其中一个容器已经换了。

阅读报告

homebutler report
homebutler report --keep 7      # retain only the latest 7 snapshots
homebutler report --no-save     # preview without writing a snapshot

report 会为你的 homelab 提供简明的管家式摘要：当前健康状况、警告、与上一个快照相比值得注意的变化，以及建议运行的后续命令。首次运行时，HomeButler 会在 ~/.homebutler/reports/snapshots/ 下创建基线；之后的运行会与最新快照进行比较。旧快照会自动清理（默认 --keep 30），避免报告无限增长。

终端中会用颜色区分各个区块的规则、标签和严重程度。输出通过管道传输、重定向或从 cron 运行时，会自动关闭颜色。

阅读变更

每条变更行（例如顶部卡片中的那些）都分为三列：变更类型、发生变更的对象和 具体发生了什么。类型是八个词之一，在 --json 中也使用同一个词，因此 Agent 无需阅读说明文字，就能据此分支处理：

replaced 正是其他功能存在的原因。以相同名称重新创建容器后，所有数量都会保持不变。因此，在 0.26.0 之前，比较数量的报告会显示“没有显著变化”，但你运行的对象实际上已被替换。

其次是 skipped：homebutler 会说明无法进行比较，而不是报告没有变化。无法确定的“全部正常”比没有答案更糟。

标题会标明用于对比的快照，因此“发生了什么变化”所涵盖的时间范围始终明确。

📖 哪些变化会显示为一行，哪些会被有意隐藏 →

查看运行效果

半分钟看完整个过程 · 观看大尺寸版本

为什么选择 homebutler？

HomeButler 帮助你解答每个家庭实验室最终都会遇到的那些枯燥却棘手的问题：

• 我的服务器现在运行着什么？
• 哪个容器占用了这个端口？
• 这项服务为什么凌晨 3 点重启了？
• 我的备份真的可以恢复吗？
• 我能否安装这个自托管应用，而不用再手写一个 compose 文件？
• 我能否让 AI 助手检查我的服务器，而不向它开放完整的 SSH shell？

无需守护进程，也无需数据库。你可以通过终端、cron、按需启动的 Web 仪表板或 AI Agent 来运行它。

设计目标很简单：为人和 Agent 提供一个范围明确、结构化的服务器交互界面。HomeButler 会返回易读摘要和 JSON，而不是让你信任一个黑盒 shell 会话。

自托管之所以困难，并不是因为运行一次 docker compose up 有多难，而是因为维护工作永无止境：端口冲突、容器悄然重启、备份看起来一切正常却经不起恢复检验，而且每台服务器最终都会变得略有不同。

HomeButler 是一套小型运维工具包，专为应对这些棘手问题而设计。

与你现有的工具搭配使用

继续用 Uptime Kuma 查看是否在线，用 Beszel 或 Netdata 查看图表，用 Dozzle 查看日志。 HomeButler 回答它们都不会问的问题：与上次相比有什么变化？这重要吗？

• 它不会在监控的机器上运行 Agent。 通过 homebutler deploy 将二进制文件部署到机器上一次即可；它只会在需要时通过 SSH 运行——没有守护进程，不开放端口，两次运行之间也不会监听任何内容。

• 判断依据是书面规则，而不是模型。 哪些内容会出现在报告中，见 docs/report.md；相同输入会生成相同报告——无需 AI，无需账户，也没有付费版。

• 它会检查备份能否恢复。 从未恢复过的备份只是一个文件夹。backup drill 会将归档启动为应用的第二个副本，并为其分配独立的网络和端口；在确认归档可用前，必须通过 HTTP 健康检查——之后会删除它创建的所有内容。演练失败时会以非零状态码退出，因此 backup drill --all 应与 backup 放在同一个 cron 条目中。docs/backup.md 说明了它会做什么，以及无法证明什么。

  🔐 Integrity: ✅ tar valid (8 files)
  🚀 Boot: ✅ container started in 0s
  🌐 Health: ✅ HTTP 200 on port 60405
  
  ✅ DRILL PASSED
  

快速开始

# One-line install (auto-detects OS/arch)
curl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | sh

# Or via Homebrew
brew install Higangssh/homebutler/homebutler

# Or as a container — the hub that reaches your machines over SSH
docker run -d -p 8080:8080 -v ~/.config/homebutler:/config -v ~/.ssh:/root/.ssh:ro \
  ghcr.io/higangssh/homebutler serve --host 0.0.0.0 --token "$(openssl rand -hex 16)"

# Interactive setup — add your servers in seconds
homebutler init

也可以通过容器使用，并通过 SSH 连接到你的机器——docs/docker.md： docker run -v ~/.config/homebutler:/config -v ~/.ssh:/root/.ssh:ro ghcr.io/higangssh/homebutler

立即开始使用：

homebutler status                    # CPU, memory, disk, uptime
homebutler docker list               # running containers
homebutler inventory scan            # containers + ports + topology
homebutler report                    # butler-style health report + change summary
homebutler install uptime-kuma       # deploy a self-hosted app
homebutler backup drill uptime-kuma  # verify a backup actually restores
homebutler watch tui                 # terminal dashboard
homebutler serve                     # web dashboard at http://localhost:8080

所有功能均支持机器可读输出：

homebutler status --json
homebutler inventory scan --json
homebutler report --json

其他功能

• 安装应用 — 用一条命令部署 Uptime Kuma、Jellyfin、Pi-hole、Gitea、Portainer 等
• 绘制服务器地图 — 查看容器、暴露的端口、系统端口和服务拓扑
• 运行诊断检查 — 诊断资源压力、已停止的容器、公共端口、备份卫生状况、通知、报告基线就绪情况，以及配置的 Proxmox 端点可达性
• 捕获崩溃 — 保存 Docker、systemd 或 PM2 重启前后的日志，并检测反复崩溃的循环
• 验证备份 — 在隔离容器中启动备份，再决定是否信任它们
• 查看 Proxmox 集群 — 查看节点、QEMU 和 LXC 来宾、存储、任务状态以及如实呈现的新鲜度的仪表板；电源操作会明确标出目标
• 随处使用 — 可通过 CLI、JSON、Web 仪表板或 MCP 供 AI Agent 使用，无需向它们提供 SSH 访问权限

🩺 Doctor Check

homebutler doctor
homebutler doctor --strict          # non-zero exit if warnings/failures are found
homebutler doctor --json            # automation / MCP friendly

doctor 是一项只读预检，用于发现 homelab 用户通常为时已晚才注意到的问题：磁盘或内存使用率过高、容器已停止、绑定到公共接口的端口、过期或缺失的备份、未配置通知、report 是否有用于检测变化的基线，以及每个已配置的 Proxmox 端点是否能使用其令牌访问。每条检查结果都会指出下一步要运行的命令，因此 --strict 可用于 cron 或 CI——包括无法访问或正在重启的 Proxmox 主机。

每条检查结果都带有一个 category，而 --json 也会包含同一个词，因此调用方无需读取标题即可按类别筛选：

incomplete 是最值得处理的类别。它表示你正在查看的结果缺少一个部分，这与该部分一切正常不同。

🗂 配置验证

homebutler config validate
homebutler config validate --strict   # exit non-zero on warnings too
homebutler config validate --json

config validate 会读取你的配置，但不会启动任何程序；它会告知使用了哪个文件、四条解析规则中的哪一条选中了该文件，以及 homebutler 如何解析每个部分。之所以提供此功能，是因为配置出错有两种情况，而它们都不会发出提示：homebutler 不认识的键会被静默丢弃，而不存在的 --config 路径会回退到内置默认值，而不是报错。

Sections
   ✓ servers     2 servers (homelab, nas)
   · notify      not set
   ✓ alerts      cpu 95% · memory 85% · disk 90%

Findings
   ⚠️ Line 5: field notifiy not found in the homebutler config
      → Did you mean "notify"? Unrecognised keys are ignored silently.

监控与告警

🔄 进程重启监控

你的容器在凌晨 3 点崩溃了——但为什么？ homebutler watch 会在问题发生时立即捕获，保存崩溃前的日志，分析原因，并告诉你问题是否反复发生。

支持的后端： Docker（实时事件流）· systemd（轮询）· PM2（轮询）

步骤 1：添加要监控的目标

homebutler watch add nginx              # Interactive: choose Docker / systemd / PM2
homebutler watch add --kind docker nginx          # or specify directly
homebutler watch add --kind systemd nginx.service
homebutler watch add --kind pm2 my-api
homebutler watch list                   # See what you're watching

步骤 2：开始监控

homebutler watch start                  # Foreground, Ctrl+C to stop
homebutler watch start --interval 10s   # Custom poll interval (default 30s)

homebutler watch install     # register it with systemd or launchd
homebutler watch installed   # is it registered?
homebutler watch uninstall

watch install 会将监控循环交给负责监督主机的组件——Linux 上的 systemd 用户级单元，macOS 上的 launchd Agent——因此即使注销或重启，监控也会继续运行。二者都在用户级运行，且不是可选项：在 Linux 上，监控列表保存在你的主目录中，因此 root 单元会发现列表为空；在 macOS 上，Docker Desktop 只会在已登录的会话中运行，因此 LaunchDaemon 会轮询一个并不存在的守护进程。在 Linux 上，用户单元会在注销时停止，除非启用了 lingering；watch install 会检查此项，如果未启用，就会提示你运行 loginctl enable-linger $USER（只有系统拒绝时才需要使用 sudo）。

watch start 是监控进程。它会监视监控列表中的容器和服务是否重启，根据你设置的阈值检查 CPU、内存和磁盘，并运行你配置的任何修复规则——由一个进程负责，使用同一组通知提供程序。alerts --watch 仍然可用，并可独立执行阈值监控。

配置中 proxmox: 下的每个端点也会被轮询：无法访问或受 ACL 过滤的端点，以及该端点 guests: 下列出的任何虚拟机，在问题出现时会报告一次事件，问题解决后再报告一次恢复事件。未在此处列出的虚拟机仅作观察——无论是否被刻意停止，watch start 都不会就其发出警报。有关 guests: 字段，请参阅 Proxmox 设置 →。

检测到崩溃时，你会看到：

[03:14:22] INCIDENT: nginx (incident nginx-20260410-031422.581-7a2124)
  Crash: OOM — process killed by SIGKILL (oom, confidence: high)
  ⚠ FLAPPING: acute (3 restarts in short window)

步骤 3：调查

homebutler watch history                # List all incidents
homebutler watch show <incident-id>     # Full details

watch show 的输出包括：

• 死亡前日志 — 进程终止前刚刚输出的内容
• 重启后日志 — 重启后发生的情况
• 崩溃分析 — 类别（oom / panic / segfault / timeout / dependency / error）、原因、置信度、匹配的日志模式
• 反复崩溃状态 — 进程是否陷入崩溃循环

崩溃分析

系统会根据退出代码和日志模式自动分析每个事件：

系统会自动匹配 panic:、Out of memory、Connection refused、FATAL 和 timeout 等日志模式，帮助找出根本原因。

反复崩溃检测

检测进程是否陷入重启循环（例如：崩溃 → 重启 → 再次崩溃）：

• 急性 — 10 分钟内重启 3 次或以上（当前出现故障）
• 慢性 — 24 小时内重启 5 次或以上（缓慢反复出现的问题）

反复崩溃事件会在历史记录中标记为 [FLAPPING]，并在 watch show 中突出显示。

通知（可选，默认关闭）

通知默认关闭，这对于所有内容均在本地运行的隔离网络或封闭网络很有用。

~/.config/homebutler/config.yaml 中的最简示例如下：

notify:
  telegram:
    bot_token: "your-bot-token"
    chat_id: "your-chat-id"

watch:
  enabled: true
  notify_on: flapping
  cooldown: 5m
  flapping:
    short_window: 10m
    short_threshold: 3
    long_window: 24h
    long_threshold: 5
  retention:
    max_incidents: 200

alerts:
  cpu: 90
  memory: 85
  disk: 90
  rules:
    - name: cpu-spike
      metric: cpu
      threshold: 90
      action: notify

    - name: elsa-monitor-down
      metric: container
      kind: systemd          # docker (default) | systemd | pm2
      watch: [lh-elsa-monitor.service]
      action: restart

重启非容器对象

除非规则另有说明，action: restart 会重启 Docker 容器。 kind: systemd 或 kind: pm2 则会将其指向某个服务或 PM2 应用。

kind 写在规则上，而不是从监控列表中查找，因此，重启主机服务是你在配置中明确要求的操作。这也意味着，在 kind 出现之前编写的所有规则，其含义都完全不变。

使用前有两点需要注意：

systemctl restart 需要 root 权限或 polkit 规则。 如果以非特权用户身份运行 homebutler，systemd 重启操作会被拒绝并报告为失败；当 alerts --watch 启动时也会发出警告，而不是等到规则首次触发时才发出。

不会重启处于反复重启状态的目标。 重启已陷入重启循环的对象只会让循环继续，而大多数 systemd 单元都带有 Restart=always，因此 homebutler 重启它们会与 systemd 自身的退避机制冲突。阈值使用上文的 watch.flapping 设置；跳过操作会被报告，但不计为成功或失败。此规则同样适用于 Docker 目标。

旧版 ~/.homebutler/watch/config.json 仍会作为监控专用设置的备用来源读取，旧版 alerts.yaml 通知／webhook 提供程序设置也仍受支持，以兼容较早的配置。

• watch.enabled: true — 允许发送监控通知

• watch.notify_on: flapping — 仅在检测到反复重启循环时发送通知

• watch.notify_on: incident — 每次事件都发送通知

• watch.notify_on: all — 事件和反复重启状态都会发送通知

• watch.notify_on: off — 禁用监控通知，但保留提供程序配置

• watch.cooldown: 5m — 在冷却时间内，抑制具有相同事件指纹的重复通知

• watch.flapping — 用于检测重启循环的可选高级调优设置

• watch.retention.max_incidents: 200 — 磁盘上保留的事件数量，按时间从新到旧排列。服务陷入重启循环时，目录增长最快。设为 -1 可保留所有事件。

  每个事件最多保留两侧各 100 行日志，且日志总量不超过 64 KB。仅限制行数无法限制文件大小：一行中可能包含任意长的堆栈跟踪或 JSON 文档，而被 OOM 终止的容器恰恰最可能写入这类内容。日志超出限制时会保留末尾内容——进程最后说的话最能解释它为何停止——并说明丢弃了多少内容。

这些设置也可以写在 watch.notify: 块下，这是规范写法：

watch:
  notify:
    enabled: true
    notify_on: flapping
    cooldown: 5m
  flapping:
    short_window: 10m

两种写法都会被读取，因此两种布局都可以使用。如果文件中两种写法都有，notify: 块优先，homebutler config validate 会对此作出提示。

管理目标

homebutler watch remove nginx           # Stop watching
homebutler watch check                  # One-shot check (no continuous monitoring)

告警阈值（高级）

alerts 仍可用于检查 CPU、内存和磁盘阈值，但这是高级工作流，不建议新用户从此入手。

homebutler alerts --watch                  # default: 30s interval
homebutler alerts --watch --interval 10s   # check every 10 seconds
homebutler alerts history                  # view alert history
homebutler notify test                     # test your notification channels

默认阈值：CPU 90％、内存 85％、磁盘 90％。请先从 watch 开始，只有在明确需要基于阈值进行检查时，再添加 alerts。

备份与恢复

一条命令即可备份 Docker——包括卷、Compose 文件和环境变量。

homebutler backup                          # backup everything
homebutler backup --service jellyfin       # specific service
homebutler backup --to /mnt/nas/backups/   # custom destination
homebutler backup list                     # list backups
homebutler restore ./backup.tar.gz         # restore

⚠️ 为确保数据一致性，备份前应暂停数据库服务。

📖 完整备份文档 → — 了解其工作原理、归档结构和安全说明。

🔍 备份演练

“有备份”和“能够恢复”是两回事。

备份演练会在隔离的 Docker 环境中启动备份，并验证应用是否确实能够响应——就像为数据举行一次消防演习。演练失败时会以非零状态退出。

homebutler backup drill uptime-kuma        # verify one app
homebutler backup drill --all              # verify all apps
homebutler backup drill --json             # machine-readable output
homebutler backup drill --archive ./file   # use a specific backup

完整操作指南，包括演练通过并不能证明什么：docs/backup.md。

执行步骤：

1. 查找最新的备份归档
2. 验证归档完整性（tar 校验）
3. 创建隔离的 Docker 网络和随机端口
4. 使用备份数据启动应用
5. 执行 HTTP 健康检查
6. 报告通过或失败，并清理所有内容

🔍 Backup Drill — uptime-kuma

  📦 Backup: ~/.homebutler/backups/backup_2026-04-04_1711.tar.gz
  📏 Size: 18.6 MB
  🔐 Integrity: ✅ tar valid (8 files)

  🚀 Boot: ✅ container started in 0s
  🌐 Health: ✅ HTTP 200 on port 58574
  ⏱️  Total: 2s

  ✅ DRILL PASSED

零风险——在完全隔离的环境中运行，不会触碰正在运行的服务。

支持以下应用的健康检查：nginx-proxy-manager、vaultwarden、uptime-kuma、pi-hole、gitea、jellyfin、plex、portainer、homepage、adguard-home。

应用安装

$ homebutler install list
📦 Available apps (15):

  uptime-kuma          A self-hosted monitoring tool
  vaultwarden          Lightweight Bitwarden-compatible password manager
  jellyfin             Free software media system for streaming movies, TV, and music
  pi-hole              Network-wide ad blocking via DNS filtering
  …

homebutler install uptime-kuma — 几秒钟即可部署可自托管的应用。预先检查 Docker、端口和重复项。自动生成 docker-compose.yml。查看所有可用应用 →

只需一条命令即可部署可自托管的应用。每个应用都通过 docker compose 运行，并提供自动预检查、健康验证和整洁的生命周期管理。

# List available apps
homebutler install list

# Install (default port)
homebutler install uptime-kuma

# Install with custom port
homebutler install uptime-kuma --port 8080

# Install jellyfin with media directory
homebutler install jellyfin --media /mnt/movies

# Check status
homebutler install status uptime-kuma

# Stop (data preserved)
homebutler install uninstall uptime-kuma

# Stop + delete everything
homebutler install purge uptime-kuma

工作原理

~/.homebutler/apps/
  └── uptime-kuma/
       ├── docker-compose.yml   ← auto-generated, editable
       └── data/                ← persistent data (bind mount)

• 预检查 — 验证 Docker 是否已安装并运行、端口是否可用，以及是否存在重复容器
• 基于 Compose — 每个应用都有自己的 docker-compose.yml，可供检查和自定义
• 数据安全 — uninstall 会停止容器，但保留数据；purge 会删除所有内容，包括应用使用的 Docker 卷，并列出这些卷。目前有一个例外：卸载并重新安装后，filebrowser 的账户和设置不会保留（见表格）
• 跨平台 — 自动检测 Docker 套接字（默认、colima、podman）

可用应用

应用专属选项

# Jellyfin: mount your media library
homebutler install jellyfin --media /mnt/movies

# Pi-hole / AdGuard: DNS ad blocking (port 53 required)
homebutler install pi-hole
# ⚠️ If port 53 is in use (Linux): sudo systemctl disable --now systemd-resolved

# Portainer: Docker GUI (mounts docker socket)
homebutler install portainer
# Access via HTTPS: https://localhost:9443

# Nginx Proxy Manager: reverse proxy
homebutler install nginx-proxy-manager
# Default login: [email protected] / changeme (change immediately!)

# Any app: custom port
homebutler install <app> --port 9999

安全检查

• 端口冲突检测 — 安装前检查端口是否已被占用
• DNS 互斥检查 — 如果同时安装了 pi-hole 和 adguard-home，会发出警告
• Docker 套接字警告 — 当应用需要访问 Docker 套接字时发出提醒（portainer）
• 操作系统专属指引 — Linux 提供 systemd-resolved 修复方法，macOS 提供 lsof 命令
• 安装后提示 — DNS 设置、HTTPS 访问和默认凭据警告

想要更多应用？提交 issue 或查看贡献指南。

仪表盘

🌐 Web 仪表板

homebutler serve — 通过 go:embed 嵌入单个二进制文件的 Web 仪表板。可在任意浏览器中查看服务、Docker 容器、开放端口、警报，并使用 Wake-on-LAN。使用 --token 时，还可以编辑配置：阈值、通知渠道、服务、Proxmox 端点和唤醒设备。

Report 标签页：真正查看报告的地方

有人收到通知后会打开的页面。首先显示需要关注的事项，然后显示发生的变化及每项变化附带的友好描述，最后显示用于比较的快照及其时间。无法进行比较时会明确说明，而不会让人误以为一切正常。

加载页面不会保存快照——如果每次打开页面都会创建快照，就会清理掉你想要用来比较的基准快照。保存快照可以通过按钮完成。

homebutler serve              # Start on port 8080
homebutler serve --port 3000  # Custom port
homebutler serve --demo       # Demo mode with realistic sample data
homebutler serve install      # Let the host keep it running

🖥️ TUI 仪表板

homebutler watch tui — 由 Bubble Tea 驱动的终端仪表板。实时监控所有已配置的服务器，显示带颜色的资源条和 Docker 容器状态。无需浏览器。

🗺️ 清单与拓扑

homebutler inventory scan
homebutler inventory show --filter exposed
homebutler inventory export --format mermaid
homebutler --json inventory scan

inventory scan 可快速绘制服务器上运行内容的地图：系统健康状况、Docker 容器、应用端口和系统端口。Docker 发布的端口会关联到拥有它们的容器，因此 Colima／Lima 等本地转发详情也一目了然。

🏠 Home Network
   Server  homelab (192.168.1.10)
   Summary ✅ 1 running · ⚪ 1 stopped · 🌍 2 public ports · 🔒 4 local ports

📦 Containers (2)
   ├─ ⚪ vaultwarden · not started
   │  └─ image vaultwarden/server:latest
   └─ ✅ api-server · running
      ├─ image my-api:latest
      └─ exposes :8080 → 8080/tcp

🌐 App Ports (1)
   └─ 🌍 :8080/tcp · api-server

如果想了解“哪些内容可从我的机器／网络外部访问？”，而不必通读整个树状结构，可以只筛选暴露的端口：

homebutler inventory scan --filter exposed

🏠 Home Network
   Server  homelab

🌐 Exposed Ports
   ├─ :8080/tcp · api-server
   └─ :8443/tcp · dashboard

只显示监听所有接口（0.0.0.0、::、*）的端口。绑定到特定地址的内容都会隐藏，包括环回地址和 LAN 地址。不支持的筛选值会返回错误；同时使用 --filter 和 --json 也会返回错误；默认的 inventory scan 输出保持不变。

需要为 GitHub、Obsidian、文档或 AI 助手生成图表时，请使用 Mermaid 导出：

graph TD
  home["🏠 Home Network"] --> homelab["🖥 homelab<br/>192.168.1.10"]
  homelab --> c1["📦 api-server<br/>running"]
  homelab --> p1["🌍 :8080/tcp<br/>api-server"]
  c1 -. exposes .-> p1

🧊 Proxmox VE

homebutler proxmox status
homebutler proxmox guests --status running
homebutler proxmox guest shutdown --node pve1 --type lxc --vmid 105 --confirm
homebutler proxmox task UPID:pve1:... --node pve1

Proxmox 端点是独立的一类目标，在 proxmox: 下配置，使用 API token 而非 SSH，因此不会加入 --server 或 --all 的扇出操作。 TLS 验证始终开启：信任验证先使用固定的 SHA-256 指纹，其次是 CA 文件，最后才是显式启用的 insecure 回退选项。

读取操作很简单，但电源操作不同：每项操作都必须明确指定端点、节点、来宾类型和 VMID，并且必须带上 --confirm 才会执行；此项检查会在读取任何凭据之前进行。这些操作还需要在端点上配置专用的 action_token_id（以及 action_token 或 action_token_file）——仅有读取 token 无法启动、重启或关闭来宾；如何创建第二个 token，请参阅Proxmox 设置 →。 shutdown 会请求来宾正常关机；它不同于 Proxmox 的强制 stop，后者会切断电源，可能导致文件系统受损。操作成功后会报告已提交的任务，而不是来宾已完成操作；可使用 proxmox task 单独查询任务状态。

proxmox script 会打印固定到某个提交的 Community Script 安装命令，并附上警告：该脚本未经 homebutler 审核，且会以 root 身份运行。它绝不会获取或运行该脚本——关于为何如此，请参阅 #62。

📖 Proxmox 设置、token 与 TLS →

安装

Homebrew（推荐）

brew install Higangssh/homebutler/homebutler

自动安装到 PATH。支持 macOS 和 Linux。

单行安装

curl -fsSL https://raw.githubusercontent.com/Higangssh/homebutler/main/install.sh | sh

自动检测操作系统和架构，下载最新版本并安装到 PATH。

npm（MCP 服务）

npm install -g homebutler

自动下载 Go 二进制文件。此软件包会发布一个命令 homebutler-mcp，用于启动 MCP 服务——npx -y homebutler@latest 启动的是该服务，而不是 CLI。若要使用命令行，请使用上文的其他安装方式。

Go 安装

go install github.com/Higangssh/homebutler@latest

从源代码构建

git clone https://github.com/Higangssh/homebutler.git
cd homebutler
make build-all

make build-all 会将 Web 仪表板编译到二进制文件中，并且需要安装 Node。make build 会跳过这一步——无论使用哪种方式，CLI 都是完整的；此时运行 homebutler serve 会提示缺少仪表板，并说明两种获取方式。

卸载

rm $(which homebutler)           # Remove binary
rm -rf ~/.config/homebutler      # Remove config (optional)

使用方法

homebutler <command> [flags]

Commands:
  status              System status (CPU, memory, disk, uptime)
  doctor              Diagnose health, exposure, backups, and readiness
  config validate     Check the config file and report what is ignored
  docker list         List running containers
  install <app>       Install a self-hosted app (docker compose)
  alerts              Show current alert status
  watch tui           TUI dashboard (monitors all configured servers)
  watch add/list/remove  Manage watched containers
  watch check/start   One-shot or continuous restart detection
  watch history/show  Browse restart history
  proxmox status      Proxmox VE cluster, nodes, guests, and storage
  serve               Web dashboard (browser-based, go:embed)

Flags:
  --json              JSON output (default: human-readable)
  --verbose, -v       Show detailed error information
  --server <name>     Run on a specific remote server
  --all               Run on all configured servers in parallel
  --port <number>     Port for serve command (default: 8080)
  --config <path>     Config file (auto-detected, see Configuration)

运行 homebutler --help 查看所有命令。

Commands:
  init                Interactive setup wizard
  config validate     Check the config file and report what is ignored
  status              System status (CPU, memory, disk, uptime)
  doctor              Diagnose health, exposure, backups, and readiness
  watch tui           TUI dashboard (monitors all configured servers)
  watch add <name>    Add container to restart watch list
  watch list          Show watched containers
  watch remove <name> Remove container from watch list
  watch check         One-shot restart check
  watch start         Continuous monitoring: restarts, thresholds, rules
  watch install       Register watch with systemd or launchd
  watch installed     Report whether it is registered
  watch uninstall     Remove the service unit
  watch history       List restart history (alias: incidents)
  watch show <id>     Show restart details with logs
  serve               Web dashboard (browser-based, go:embed)
  docker list         List running containers
  docker restart <n>  Restart a container
  docker stop <n>     Stop a container
  docker logs <n>     Show container logs
  docker top <n>      Show processes running inside a container
  docker inspect <n>  Show image, state, ports, mounts, networks, health
  report              What changed since the last snapshot
  inventory scan      Map containers, ports, and topology
  inventory show      Same as scan (--filter exposed narrows it)
  inventory export    Export the map (--format mermaid)
  proxmox status      Proxmox VE cluster, nodes, guests, storage
  proxmox guests      List QEMU and LXC guests
  proxmox node <n>    Node detail
  proxmox guest ...   start / shutdown / reboot (needs --confirm)
  proxmox task <upid> Task status for an action already submitted
  proxmox tasks       Recent tasks on a node
  proxmox script      Community Script install commands (prints, never runs)
  notify test         Send a test notification through configured providers
  wake <name>         Send Wake-on-LAN packet
  ports               List open ports with process info
  ps                  Show top processes (alias: processes)
  ps --sort mem       Sort by memory instead of CPU
  ps --limit 20       Show top 20 (default: 10, 0 = all)
  network scan        Discover devices on LAN
  alerts              Show current alert status
  alerts --watch      Thresholds only (watch start covers these too)
  trust <server>      Register SSH host key (TOFU)
  backup              Backup Docker volumes, compose files, and env
  backup list         List existing backups
  backup drill <app>  Verify backup restores correctly (isolated)
  backup drill --all  Verify all apps in backup
  restore <archive>   Restore from a backup archive
  upgrade             Upgrade local + all remote servers to latest
  deploy              Install homebutler on remote servers
  install <app>       Install a self-hosted app (docker compose)
  install list        List available apps
  install status <a>  Check installed app status
  install uninstall   Stop app (keep data)
  install purge       Stop app + delete all data
  mcp                 Start MCP server (JSON-RPC over stdio)
  version             Print version

Flags:
  --json              JSON output (default: human-readable)
  --verbose, -v       Show detailed error information
  --server <name>     Run on a specific remote server
  --all               Run on all configured servers in parallel
  --port <number>     Port for serve command (default: 8080)
  --demo              Run serve with realistic demo data
  --watch             Continuous monitoring mode (alerts command)
  --interval <dur>    Watch interval, e.g. 30s, 1m (default: 30s)
  --config <path>     Config file (auto-detected, see Configuration)
  --local             Upgrade only the local binary (skip remote servers)
  --local <path>      Use local binary for deploy (air-gapped)
  --service <name>    Target a specific Docker service (backup/restore)
  --allow-bind <path> Host path a restore may write a bind mount to (repeatable)
  --endpoint <name>   Proxmox endpoint from config (optional if only one)
  --confirm           Required for a Proxmox guest power action
  --to <path>         Custom backup destination directory
  --archive <path>    Specific backup archive for drill
  --all               Verify all supported apps (backup drill)

homebutler serve                # http://localhost:8080
homebutler serve --port 3000    # custom port
homebutler serve --demo         # demo mode with sample data
homebutler serve install        # hand it to launchd or systemd, so it survives logout
homebutler serve uninstall      # and take it back

配置

homebutler init    # interactive setup wizard

📖 report 的比较内容 → — 了解哪些内容会生成一行、哪些内容会被刻意隐藏，以及原因。

📖 配置详情 → — 配置文件位置、监视/通知选项和高级警报阈值。

多服务器

通过 SSH 在一台机器上管理多台服务器。

homebutler status --server rpi     # query specific server
homebutler status --all            # query all in parallel
homebutler deploy --server rpi     # install on remote server
homebutler upgrade                 # upgrade all servers

📖 多服务器设置 → — SSH 身份验证、配置示例、部署和升级。

MCP 服务

内置的 MCP 服务 — Agent 获得与输入 JSON 相同的报告，包含 kind、target 和 detail，而不是需要解析的句子；每个工具都被归类为读取、写入或破坏性操作。

想要自动化时，请使用自然语言。 MCP 客户端可以调用 homebutler 工具来检查服务器状态、列出 Docker 容器、检查端口，或运行运维工作流。

{
  "mcpServers": {
    "homebutler": {
      "command": "npx",
      "args": ["-y", "homebutler@latest"]
    }
  }
}

适用于 Claude Desktop、ChatGPT、Cursor、Windsurf 以及任何 MCP 客户端。

若要让 Agent 查看信息但无法进行任何更改，请在 args 中添加 "--max-risk", "read"。不会提供会进行更改的工具；即使按名称调用，也会被拒绝；report 运行时不会保存快照。只读模式会阻止更改，但不限制读取：日志和容器详情仍然可见。只读模式涵盖的内容 →

📖 MCP 服务设置 → — 支持的客户端、可用工具、Agent 技能。

架构

管家负责观察、判断哪些内容值得告知，然后将其告诉你或 Agent。

某项内容发生变化 → report 为其命名并排序 → 通知、仪表板或 MCP 调用 传递相同的答案。

        ┌─────────┐  ┌─────────┐  ┌─────────┐
        │   CLI   │  │   MCP   │  │   Web   │
        │ stdout  │  │  stdio  │  │  :8080  │
        └────┬────┘  └────┬────┘  └────┬────┘
             └────────────┼────────────┘
                          ▼
                   internal/*
         system · docker · ports · network
         wake · alerts · remote (SSH)

三个接口，一个核心：

三者都调用相同的 internal/ 包 — 不存在代码重复。

Agent 读取的报告与用户相同，并会获取需要据此进行分支判断的内容， 而不是需要自行解读的屏幕：

report = json.loads(subprocess.run(
    ["homebutler", "report", "--json"], capture_output=True, text=True).stdout)

for change in report["notable_changes"]:
    if change["kind"] == "replaced":         # the container came back as something else
        redeploy(change["target"])
    else:
        log(change["text"])                  # "port: :8080/tcp — nginx → caddy"

每一行也都包含 text，因此调用方若只想打印内容，就不必重新拼接句子。未发现任何内容的运行会返回 "notable_changes": []， 因此在安静的一天，上面的循环不会执行任何操作。

以上所有内容都不属于 homebutler 的职责范围：MCP 客户端、聊天机器人、cron 行或终端前的用户，最终都会获得相同的答案。

默认不会开放任何端口。 CLI 和 MCP 仅使用 stdin/stdout。Web 仪表板为可选功能（homebutler serve，绑定到 127.0.0.1）。

贡献

欢迎贡献！请先创建 issue，讨论你想要进行的更改。CONTRIBUTING.md 介绍了 homebutler 接受的贡献，以及新目标需要满足的要求。

安全

发现漏洞？请通过安全选项卡私下报告，而不是创建公开 issue。SECURITY.md 介绍了受理范围以及你可以期待的处理方式。

许可证

MIT