Lynricsy/OneSSH · 上手攻略

仓库：Lynricsy/OneSSH
链接：https://github.com/Lynricsy/OneSSH
分类：devops-tool
作者：Jay
更新：2026-08-13

是什么

OneSSH 是一个面向 AI Agent 的集中式 SSH 网关，用 Go 写的单个二进制（默认端口 8866），提供 MCP（Model Context Protocol）接口让 AI Agent 以工具调用方式操作远程主机。核心思路是：私钥/密码从不离开网关，Agent 只拿临时令牌 + MCP 工具，权限在网关侧集中管理，所有操作留下结构化审计日志。

解决什么问题

让 Agent 直连 SSH 私钥有两大风险：（1）密钥管理分散，每台主机独立维护 authorized_keys，撤销时要登录每台机器；（2）操作粒度只到会话，无法控制 Agent 具体读写哪个文件。OneSSH 把 SSH 授权收敛到网关一层：令牌即权限、撤销删记录即可、每次调用都有审计。

快速安装

# 1. 生成主密钥（32 字节随机 hex，生产环境必须持久化，不要每次重启重生成）
export ONESSH_MASTER_KEY="$(openssl rand -hex 32)"
export ONESSH_ADMIN_PASSWORD='replace-with-a-strong-password'

# 2. 一键启动（自动拉取 ghcr.io/lynricsy/onessh:latest）
docker compose up -d

# 3. 确认服务健康
curl --fail http://localhost:8866/healthz

然后打开 http://localhost:8866 ，用 ONESSH_ADMIN_PASSWORD 登录控制台，完成后续配置。

⚠️ 主密钥丢失 = 所有 SSH 凭据无法恢复，生产环境必须持久化 ONESSH_MASTER_KEY 到可靠存储。

核心配置流程

第一步：导入 SSH 密钥或主机密码

在控制台「密钥」页： - 生成新的 ed25519 密钥对，或 - 导入已有的 OpenSSH 私钥，或 - 直接用目标主机的用户密码

第二步：添加目标主机

在「主机」页添加目标服务器（IP/域名 + 用户 + 认证方式），点击「测试连接」。首次连接会记录 TOFU（Trust on First Use）指纹；主机指纹变更会被直接拒绝，需要在 WebUI 手动重置。

无法直连的目标可配置跳板机（最多 5 级串联，禁止成环）。

第三步：创建 Agent 令牌

在「令牌」页创建 MCP 令牌，绑定允许执行的主机范围和权限（执行权限 vs 主机配置管理权限，默认关闭后者）。

手工令牌的明文只显示一次，立刻复制进 Agent 的安全配置。

MCP 客户端接入

OneSSH MCP 端点：http://localhost:8866/mcp

{
  "mcpServers": {
    "onessh": {
      "type": "streamable-http",
      "url": "http://localhost:8866/mcp",
      "headers": {
        "Authorization": "Bearer osh_REPLACE_ME"
      }
    }
  }
}

字段名（Authorization vs headers）取决于 MCP 客户端，部分客户端需要通过 HTTP transport 注入。

推荐方式：MCP OAuth 2.1（PKCE）

MCP 客户端支持 OAuth 时走授权码流程：访问 /.well-known/oauth-authorization-server 自动发现端点，用 S256 PKCE 授权，访问令牌 1 小时有效，刷新令牌 30 天且每次使用自动轮换。管理员在授权页选择主机范围，客户端拿到的令牌自动受限。

MCP 工具清单

类别	工具
连接/执行	`hosts_list` · `exec` · `session_env` · `exec_many` · `output_read`
主机管理	`hosts_manage_list` · `host_create` · `host_update` · `host_test` · `host_reset_fingerprint` · `host_delete`
后台任务	`job_start` · `job_list` · `job_status` · `job_logs` · `job_kill`
文件	`file_read` · `file_write` · `file_edit` · `file_list` · `file_transfer`
搜索	`grep` · `find`
记忆	`memory_remember` · `memory_recall` · `memory_list` · `memory_update` · `memory_forget` · `memory_stats` · `memory_sleep`
资源	`image_view` · `host_status`

编码对应：file_read → read、file_write → write、file_edit → edit、exec → bash、grep → grep、find → find、file_list → ls，基本对齐主流 Agent 工具命名。

搜索的降级路径

grep / find 优先在目标主机调用原生 rg（ripgrep）和 fd；目标无安装时 OneSSH 经 SFTP 上传临时静态 helper（Linux amd64/arm64），执行完自删除；/tmp 不可写/不可执行/平台不支持时，自动降级到纯 SFTP + Go 实现。

# 禁用临时 helper
export ONESSH_SEARCH_HELPER=off

engine 字段标注实际引擎：rg/fd（原生）、helper（临时二进制）、sftp（降级），降级时返回 warning 说明性能影响。

记忆系统

按主机 bank：每台主机的记忆独立存储，主机改名不丢失，删除主机时记忆一并清理。
全局 bank：不带 host 参数时读写全局记忆。
召回算法：trigram FTS5 + 重要度 + 72h 时近度衰减。配置 OpenAI 兼容 embedding 后自动加入余弦相似度；embedding 失败退化到纯 FTS，不中断 Agent 调用。
memory_sleep：不调用 LLM，纯确定性去重 + 长期未用衰减 + 低分旧记忆清理。

典型适用场景

多主机运维 Agent：Claude / GPT 等 Agent 通过 MCP 管理 10+ 台服务器，无需给 Agent 配私钥。
权限精细化管控：限定 Agent 只能读某些目录、只能在特定主机执行，降低误操作风险。
审计合规：所有 SSH 操作有结构化日志，包括拒绝记录，文件正文只记长度摘要不落盘敏感数据。
跳板机串联：通过跳板机访问 NAT 后的内部机器，Agent 感知不到跳板存在。
跨主机文件传输：通过 file_transfer 在 H1→H2 之间直接传文件，不走本地中转。

坑与注意

ONESSH_MASTER_KEY 必须持久化：每次重启容器重新生成会导致所有已加密的 SSH 密钥和密码永久丢失。用环境变量挂载或 volume 持久化，不要用 docker run --rm 临时跑。
生产环境必须 HTTPS：OAuth 端点（/.well-known/oauth-*）和 MCP 端点必须公网 HTTPS，localhost/HTTP 只在本地开发时可用。配置 ONESSH_PUBLIC_URL 设为实际访问地址。
跳板机关联限制：被其他主机依赖的跳板机不能直接删除，需先把依赖者改回直连或切换到其他跳板。
令牌撤销立即生效：删除令牌记录即失效，不需要动任何机器上的 authorized_keys，但已有 SSH 连接不受影响（会话级控制）。
file_edit 乐观锁：expected_sha256 冲突时需要重新 file_read 后再提交，没有自动 merge。
macOS 阴影实现：Web UI 终端用 Ghostty Web（WASM + Canvas），截图和自动化依赖 accessibility snapshots，macOS 上需 granted 输入监控权限。
memory_remember 的审计记录：正文参数在审计日志中只记录长度，不记录内容——但如果正文是密码等高敏感数据，建议先做摘要再存入。

与同类对比

工具	定位	MCP 支持	凭证管理	审计	跳板
OneSSH	Agent SSH 网关	✅ 原生 MCP OAuth	网关侧加密	✅ 结构化	✅ 多级
Teleport	基础设施访问管理	❌ 专用协议	CA 证书	✅	✅
sshd_config + authorized_keys	原生 SSH	❌	分散每机	有限	❌
Mosh	移动 SSH	❌	原始	❌	❌
JumpServer	堡垒机	❌	✅	✅	✅
AWS SSM Session Manager	云 SSH	❌	IAM	✅	❌

OneSSH 的差异化在于原生 MCP 工具接口（不是 SSH 协议封装，而是 Agent 友好的工具抽象）+ AES-256-GCM 凭据加密 + MCP OAuth 2.1 授权码流程，是目前专门为 AI Agent 设计的 SSH 网关里工程完成度较高的一个。

一句话推荐结论

如果你在给 AI Agent 配 SSH 能力，OneSSH 是目前最干净的方案——私钥不离网关、MCP 工具开箱即用、OAuth 令牌级撤销；但它是一个新生项目（2025+），生产环境大规模使用前建议评估社区成熟度和安全审计状态。

原始 commit：https://github.com/Lynricsy/OneSSH（README，fetch 日期 2026-08-13）