Skip to content

README_zh.md

Latest commit

 

History

History
266 lines (205 loc) · 9.16 KB

README_zh.md

File metadata and controls

266 lines (205 loc) · 9.16 KB
Raw

Reach Logo

Reach

从任何 AI 控制任何服务器。
轻量级远程服务器管理 Agent —— 无需 SSH。

CI Release License Go Reference

English | 中文

为什么选择 Reach？

  • 一个二进制，一个 Token —— 30 秒安装到服务器，零配置文件
  • AI 原生 —— 内置 MCP 服务器，支持 Claude Code、Cursor、Windsurf 或任何兼容 MCP 的 AI
  • 默认安全 —— TLS + Token 认证 + TOFU 指纹锁定 + 命令黑名单 + fail2ban 集成，无需管理 SSH 密钥

竞品定位

Reach 定位：AI 原生、轻量、自托管 —— 无直接竞品的蓝海

现有工具要么面向人类（SSH、Tailscale、Teleport），要么只是给 AI 包了一层 SSH（失去简洁性）。Reach 专为 AI Agent 而生：一个二进制、一个 Token、原生 MCP —— 中间没有 SSH 层。

SSH vs Reach

SSH vs Reach 对比：连接模型、输出格式、安全预检、认证、转义、文件写入、错误处理

SSH 做不到，Reach 能做的

能力 做什么 SSH 为什么不行
命令预检 reach_dryrun("rm -rf /opt/old") → 风险评分 85/100，影响 847 个文件 SSH 没有拦截层 —— 发出去就执行了
结构化监控 reach_stats → CPU%、内存%、进程排行，全是 JSON SSH 返回 top / free -m 文本，AI 要正则解析
原子文件写入 reach_write → 临时文件 → fsync → 重命名 echo > file 失败时文件半写
命令黑名单 服务端阻止 rm -rf /、mkfs、fork bomb SSH 只要有权限就能执行任何命令
一键部署 reach bootstrap myserver --host IP --user root SSH 部署 = 生成密钥、复制密钥、配置 sshd、测试
AI Skill 内置 MCP server 带 instructions —— AI 自动知道用哪个工具 SSH 没有"教 AI 怎么用"的概念

安装

给你的 AI 加上 skill —— 一行搞定：

# Claude Code
claude mcp add-json reach '{"command":"reach","args":["mcp","serve"]}'

# 或任何 AI：把这个 skill 文档发给它 ↓
# https://raw.githubusercontent.com/agent-0x/reach/master/skill.md

把 skill.md 链接发给你的 AI。它会学会什么时候用哪个工具 —— 破坏性命令前先 dryrun、用结构化 stats 而非 shell 解析、原子写入文件。

安装二进制：

curl -fsSL https://raw.githubusercontent.com/agent-0x/reach/master/install.sh | bash

也可以从 Releases 下载，或从源码构建：

git clone https://github.com/agent-0x/reach.git
cd reach && make build
# 二进制文件在 ./bin/reach

快速开始

1. 部署 Agent（在远程服务器上）

reach agent init --dir /etc/reach-agent
reach agent serve --config /etc/reach-agent/config.yaml
# 复制 init 时显示的 Token

提示： 参见 Systemd 部署 以后台服务方式运行。

2. 添加服务器（在本地机器上）

reach add myserver --host 203.0.113.10 --token <token>
# 首次连接时自动锁定证书指纹（TOFU）

3. 开始使用

reach exec myserver "uname -a"
reach read myserver /etc/hostname
reach upload myserver ./deploy.sh /opt/deploy.sh

AI 集成（MCP）

Reach 内置 MCP 服务器，任何兼容 MCP 的 AI 都可以直接管理你的服务器。

Claude Code

reach mcp install          # 当前项目
reach mcp install --global # 所有项目
# 重启 Claude Code —— 工具即可使用

然后直接对话：

你：「检查 myserver 上的 nginx 状态」
AI：[调用 reach_bash("myserver", "systemctl status nginx")]

MCP 工具

工具 说明
reach_bash 执行 Shell 命令
reach_read 读取远程文件
reach_write 写入文件（原子操作：临时文件 → fsync → 重命名）
reach_upload 上传本地文件到服务器
reach_info 获取系统信息（CPU、内存、磁盘、运行时间）
reach_list 列出所有已配置的服务器
reach_stats 获取详细系统状态（CPU%、内存、磁盘、网络、进程排行）
reach_dryrun 执行前检查命令危险性（风险评分 0-100）

CLI 参考

命令 说明
reach agent init [--dir] 生成 TLS 证书 + Token，写入配置
reach agent serve [--config] 启动 HTTPS Agent 服务
reach add <name> --host --token [--port] 添加服务器（TOFU 指纹锁定）
reach remove <name> 移除服务器
reach list 列出所有已配置的服务器
reach exec <server> <cmd> [-t timeout] 远程执行命令
reach read <server> <path> 读取远程文件
reach write <server> <path> 将 stdin 写入远程文件
reach upload <server> <local> <remote> 上传文件
reach download <server> <remote> <local> 下载文件
reach info <server> 查看系统信息
reach health <server> 健康检查
reach mcp install [--global] 注册为 Claude Code MCP 服务器
reach mcp serve 启动 MCP stdio 服务器（内部使用）
reach stats <server> 查看详细系统状态
reach dryrun <server> <cmd> 执行前检查命令风险

架构

┌─────────────────────────────────┐
│  本地机器                        │
│                                 │
│  Claude Code / Cursor / Gemini  │
│         │ MCP (stdio)           │
│         ▼                       │
│  ┌─────────────┐               │
│  │ reach mcp   │               │
│  │   serve     │               │
│  └──────┬──────┘               │
│         │ HTTPS + Bearer Token  │
└─────────┼───────────────────────┘
          │
          ▼
┌─────────────────────────────────┐
│  远程服务器                      │
│                                 │
│  ┌─────────────┐               │
│  │ reach agent │               │
│  │   serve     │               │
│  └─────────────┘               │
│   :7100 (TLS)                  │
└─────────────────────────────────┘

安全模型

  • 自签名 TLS + TOFU —— 首次 reach add 时锁定证书指纹，后续连接验证
  • 128 位 Bearer Token —— agent init 时生成，仅通过 TLS 传输
  • 进程隔离 —— 每个命令在独立进程组中运行，超时强制终止
  • 原子文件写入 —— 临时文件 → fsync → 重命名，不会产生半写文件
  • 命令黑名单 —— 阻止危险命令（rm -rf /、mkfs、dd、fork bomb 等）
  • fail2ban 就绪 —— 认证失败时记录 AUTH_FAIL from <IP> 到 systemd 日志

配置

所有安全功能默认启用。在 Agent 的 config.yaml 中自定义：

security:
  command_blacklist: true
  custom_blacklist:
    - "\\bshutdown\\b"
    - "\\breboot\\b"
  auth_fail_log: true

fail2ban 集成

# /etc/fail2ban/filter.d/reach-agent.conf
[Definition]
failregex = AUTH_FAIL from <HOST>:
journalmatch = _SYSTEMD_UNIT=reach-agent.service
# /etc/fail2ban/jail.d/reach-agent.conf
[reach-agent]
enabled  = true
backend  = systemd
filter   = reach-agent
maxretry = 3
findtime = 600
bantime  = 3600
banaction = ufw
port     = 7100

作为服务运行

注意： 如果 reach 安装在其他位置（如 ~/.local/bin/reach），请调整 ExecStart 路径。

# /etc/systemd/system/reach-agent.service
[Unit]
Description=Reach Agent
After=network.target

[Service]
ExecStart=/usr/local/bin/reach agent serve --config /etc/reach-agent/config.yaml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now reach-agent

贡献

参见 CONTRIBUTING.md。

许可证

MIT