rootpilot-ssh-diagnose

rootpilot-ssh-diagnose

这是 RootPilot 开源且支持自选大模型的版本。完整产品还提供经过校准的诊断（针对 29 种标准故障场景的准确率为 89.7%，对健康主机零误报）、告警触发的自动诊断、历史记录和多主机管理 → rootpilotx.com · 部署仓库：rootpilot-release

一个 MCP 服务，让任何 MCP 客户端——Claude Desktop、Claude Code 或你自己的客户端——都能通过 SSH 安全地从你的服务器收集只读诊断信息。它会从固定的只读命令白名单中收集证据；由你的模型进行推理。此服务绝不会运行白名单之外的任何命令，也绝不会更改你的主机。

为什么要使用

服务器出现异常时，你通常得 SSH 登录并运行同样的二十条命令——df -h、docker ps、dmesg | grep -i oom、free -m——然后盯着输出逐一查看。此服务将这一过程变成对话：你的大模型会请求它所需的确切证据，获得经过结构化处理且已脱敏的输出，再据此推断根本原因。你始终掌握控制权；除 SSH 连接到你自己的主机外，没有任何信息会离开你的机器。

安全模型（请先阅读）

• 只读白名单。 内置命令恰好有 38 条（get_whitelist 会列出全部命令）。没有任何工具可以运行任意命令——即使需要确认也不行。每条命令都只检查状态。
• 唯一可注入的值是容器名称，在放入命令之前会先根据 ^[a-zA-Z0-9_.-]+$ 进行验证。web; rm -rf / 会被拒绝，而不是转义。
• 输出中的机密信息会在到达模型之前脱敏：KEY=value 格式的机密信息、Bearer/Basic 令牌、sk-/ghp_/AKIA… 形式的密钥、PEM 私钥块，以及嵌入 URL 中的凭据。docker inspect 的环境变量值也会经过清理。
• 每条命令都有超时限制（15s），并设有输出截断保护，避免命令挂起或输出过多。
• 凭据保留在本地。 主机定义保存在由你控制的文件中；密码绝不会被记录。

30 秒完成设置

将此服务添加到你的 MCP 客户端。对于 Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "rootpilot-ssh-diagnose": {
      "command": "npx",
      "args": ["-y", "@rootpilot/mcp-ssh-diagnose"],
      "env": {
        "RP_HOSTS": "/Users/me/.rootpilot-mcp/hosts.json"
      }
    }
  }
}

然后创建 hosts.json（参见 hosts.example.json）：

[
  { "name": "prod-1", "host": "1.2.3.4", "port": 22, "user": "rootpilot",
    "auth": { "type": "key", "keyPath": "~/.ssh/rootpilot_key" } },
  { "name": "prod-2", "host": "10.0.0.5", "user": "ops",
    "auth": { "type": "password", "password": "..." } }
]

重启客户端。向它询问：“诊断 prod-1”（或运行 diagnose-host 提示词）。

请使用权限最小化的账户。 请为诊断创建专用的只读 SSH 用户，而不要重复使用 root。虽然这些命令只会读取状态，但账户权限也应体现这一点。

工具

工具	参数	功能
list_hosts	probe?	列出已配置的主机；使用 probe 时还会测试 SSH 连通性
get_whitelist	—	返回全部 38 条命令（键、用途、模板），让你和模型能准确审查哪些命令可以运行
collect	host、keys[]（≤8）、container?	运行指定的白名单命令，并返回经过脱敏和截断的输出
collect_base	host	快捷方式：获取基础概览（docker_ps、df、df_inode、free、uptime、dmesg_oom、docker_daemon）
container_deep_dive	host、container	快捷方式：针对一个容器运行 docker_logs、docker_inspect（已脱敏）、container_state、docker_stats

内置提供两个提示词：diagnose-host（以证据为先的根本原因排查流程）和 health-check（快速巡检）。

配置

环境变量	默认值	用途
RP_HOSTS	—	hosts.json 的路径（必填）
RP_PROBE_URL	https://cloudflare.com	用于出站连接／DNS 探测的目标
RP_NO_PROMO	—	设为 1 可关闭指向完整产品的一行提示

工作原理

  your MCP client (the LLM)
        │  "collect df, docker_ps, dmesg_oom from prod-1"
        ▼
  rootpilot-ssh-diagnose  ──ssh──▶  your server
        │  renders a whitelisted template, runs it read-only,
        │  redacts secrets, truncates, returns structured output
        ▼
  the LLM reasons about root cause from the evidence

该服务刻意不执行任何自行分析——没有内置的大模型调用，也没有多轮编排。这样的边界正是关键所在：它是一个简洁、可审计的证据收集工具。经校准的诊断（针对不同症状，在后续轮次中决定要收集哪些证据，并依据故障场景库进行评分）是完整的 RootPilot 产品所提供的功能。

常见问题

它会更改我的服务器吗？ 不会。所有命令都只读，也没有可执行任意命令的工具。完整的白名单可通过 get_whitelist 查看。

我的数据会传到哪里？ 除了在此服务（运行于你的机器上）与主机之间通过 SSH 传输外，不会传到任何地方。命令输出会发送给你的 MCP 客户端所使用的大模型。不会收集遥测数据。

它使用哪个大模型？ 它自身不使用任何大模型——你需要自备大模型。你的 MCP 客户端运行的模型会负责推理。

它能管理 Windows 服务器或跳板机吗？ v1 暂不支持。它面向通过直接 SSH 连接的 Linux 主机。

它与 RootPilot 有何不同？ 它负责收集证据；由你（或你的模型）临时解读。RootPilot 还提供经校准的诊断、由告警触发的自动诊断、每台主机的历史记录（“病历”）以及多主机管理。参见 rootpilotx.com。

开发

npm install
npm run build      # compile to dist/
npm test           # whitelist / injection / redaction / timeout tests
npm run typecheck

许可证

MIT——参见 LICENSE。