TunnelAdmin

English | 简体中文

基于 Web 的 SSH 连接管理器 + MCP Server。浏览器里管理主机、开终端、传文件、建隧道；AI Agent 通过 MCP 协议（Streamable HTTP）直接操作你的服务器——agent 首次连接每台主机都需要你在网页上确认（human-in-the-loop 审批），批准后可选择「始终信任」免审批直连。

纯 Vibe Coding 项目：本项目全部代码由 AI 驱动开发（Oh My Pi + DeepSeek V4 Flash 模型）， 人工仅提供需求描述与验收反馈。Logo 由豆包 AI 生成（assets/logo.png）。

功能

Related MCP server: R-Shell

技术栈

• 后端：Node.js 22+ / TypeScript / Fastify 5 / ssh2 / better-sqlite3 / @modelcontextprotocol/sdk

• 前端：React 19 / Vite / xterm.js (@xterm/xterm 6) / Tailwind 4 / zustand

• 桌面：Electron 33 / electron-builder（Windows / Linux）

• 安全：密码登录（httpOnly cookie，可免登录模式）、MCP Bearer token、AES-256-GCM 凭据加密、主密钥 0600 文件

快速开始

npm install

# 开发模式（server :8080 + web :5173 热更新）
npm run dev

# 生产构建并启动（server 托管 web/dist）
npm run build
npm start

首次启动会在 data/ 下生成：

• master.key — AES 主密钥（0600）

• password.hash — Web 登录密码哈希；初始密码打印在启动日志中（可在设置页修改）

环境变量

桌面客户端（Windows）

# Windows 侧一键打包（建议管理员运行；自动下载便携 Node/代理探测）
scripts\build-win.ps1
# 或双击 scripts\build-win.bat

产物：release\TunnelAdmin-<version>-x64.exe（安装器）+ .zip（便携版）。 桌面版自动免登录（TUNNELADMIN_AUTH=none），数据存于 %APPDATA%\tunneladmin。

MCP 接入 AI Agent

1. Web 界面 → 设置 → MCP → 新建 Token（或「📋 复制提示词」一键生成接入说明）

2. Agent 配置示例（Claude Code / Cursor 的 .mcp.json）：

{
  "mcpServers": {
    "tunneladmin": {
      "type": "http",
      "url": "https://你的服务器:8080/mcp",
      "headers": { "Authorization": "Bearer ta_xxxxx" }
    }
  }
}

3. Agent 调用 ssh_connect 时，你的浏览器会弹出确认框；批准后返回 sessionId，后续 ssh_exec / 文件操作复用该会话并保持工作目录。

安全说明

• 公网部署务必置于 HTTPS 反向代理后（如 Caddy：caddy reverse-proxy --from your.domain --to :8080）

• MCP endpoint 强制 Bearer token 认证

• 凭据全量加密落盘；主密钥文件权限 0600，建议备份

• 单用户设计；多用户/RBAC 不在当前范围

目录结构

server/src/
  index.ts          入口：Fastify + WS + MCP + 静态托管
  config.ts         配置加载 / 密码与 cookie 签名
  crypto.ts         AES-256-GCM
  db.ts             SQLite schema
  approval.ts       agent 连接审批服务
  events.ts         WebSocket 事件总线
  ws.ts             终端桥（xterm ↔ ssh2 流，断连检测 + tmux 持久）
  ssh/manager.ts    连接池（跳板机链、keepalive）
  routes/           auth / hosts / tokens / misc / sftp / forward
  mcp/              MCP server（Streamable HTTP 无状态模式）+ 工具集
web/src/
  pages/            Terminals（外层 tab：主机/编辑器/设置/传输/审计）/ tabs / Login
  components/       TerminalView (xterm) / SideBar / ReplayOverlay / ApprovalModal
  store.ts          zustand（布局树 / 工作区持久化 / 传输记录）
desktop/            Electron 主进程 + server 启动器
scripts/            Windows 打包脚本（build-win.ps1 / bat）

设计要点

• Web 与 MCP 共享连接核心：连接配置、凭据解密、跳板机逻辑只有一份

• MCP 无状态模式：每个请求新建 Server + transport（SDK Protocol 单实例只支持单 transport），会话状态存进程级共享 Map

• 审批链路：MCP 请求挂起 → WS 推送弹窗 → 用户批准 → 连接建立，超时自动拒绝

• 共享会话：同一 SSH 连接可开多 channel——MCP 的 exec 与用户在 Web 附加的交互 shell 并行（ssh2 多 channel），agent 活动经 exec:activity 事件实时镜像；终端协议按 streamId 区分多视图

• 终端保活：外层/内层 tab 切换不卸载终端（CSS 隐藏保持挂载）；SSH 断连自动重连（5s→30s 退避）且 tmux 现场不丢

• 远程转发为主：部署在服务器上时「本地转发」的端口开在服务器上浏览器够不着，故主推远程转发；本地转发仅服务端进程可用

开发统计（Vibe Coding 用量）

本表由 node scripts/update-usage.cjs 自动生成（提交前运行）：统计 ~/.omp/agent/sessions/-sources-tunneladmin/*.jsonl，每个会话文件 = 一次会话；新会话自动累加进「累计」。