# ssh-tool

**Repository Path**: rymaker/ssh-tool

## Basic Information

- **Project Name**: ssh-tool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-28
- **Last Updated**: 2026-08-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SSH 端口映射工具

Windows 桌面工具：用 SSH 隧道把远程服务器上的服务映射到本机，或反过来把本机服务
暴露给服务器，也可以直接开一个走服务器出口的 SOCKS5 代理。

**Electron + Vue 3 + TypeScript**，转发内核基于 [ssh2](https://github.com/mscdex/ssh2)，
纯 Node 实现，不依赖本机的 ssh 客户端。

## 功能

**多隧道 + 分组**

- 一个界面管理任意多条隧道，每条独立启停，状态、流量分别统计
- 隧道按分组归类，可整组一键开启 / 停止；服务器凭据独立维护、被多条隧道复用
- 支持复制隧道、复制等效的 `ssh` 命令、按名称 / 端口 / 地址搜索

**三种转发方式**

| 方式 | 等效命令 | 用途 |
|------|----------|------|
| 本地转发 | `ssh -L 本地端口:目标:端口` | 把服务器能访问的服务（数据库、内网站点）映射到本机 |
| 远程转发 | `ssh -R 服务器端口:本机:端口` | 把本机服务暴露到服务器（对外需 sshd 开启 `GatewayPorts`） |
| SOCKS 代理 | `ssh -D 本地端口` | 本机开一个 SOCKS5 代理，流量从服务器出去 |

**认证与安全**

- 密码、私钥文件（含密码短语）、SSH Agent 三种认证方式
- 密码与密码短语用 Electron safeStorage（Windows 下即 DPAPI）加密后落盘，不存明文；可选择不记住
- 首次连接记住服务器主机指纹（TOFU），指纹变化时拒绝连接并提示，防止中间人

**账号与端到端加密同步**

- 邮箱注册、登录、退出、设备重命名与撤销；不登录时仍可完整离线使用
- 服务器、隧道和分组可手动或自动同步；主题、自启、托盘行为等设备设置始终保留在本机
- “同步密码/密码短语”和“同步私钥内容”是两个独立开关，默认都关闭
- 同步密码经 Argon2id 派生密钥，文档使用 AES-256-GCM 在 Electron 主进程加密
- 服务端只保存密文；token、Vault key 和原始私钥不会暴露给 Renderer
- 支持一次性恢复密钥、revision 乐观锁、三方合并、离线退避与幂等重试
- 关闭敏感同步时会轮换 Vault key、生成新恢复密钥并原子清除旧历史
- 云端私钥解密后直接由主进程交给 `ssh2`，不会自动写入 `~/.ssh`

**运行时**

- 断线自动重连，退避间隔 1→2→5→10→20→30 秒（上限可配），重连过程与倒计时可见
- 每条隧道实时显示上下行速率、活跃 / 累计连接数、累计流量、运行时长与迷你速率曲线
- 实时日志面板：按级别过滤、关键字搜索、自动滚动、一键导出为文本
- 保活心跳，避免空闲连接被服务器或防火墙掐断
- 最小化 / 关闭到系统托盘，托盘菜单可直接开关单条隧道；开机自启与静默启动
- 单实例运行，重复启动会唤醒已有窗口；退出时清理所有隧道

## 开发

```bash
npm install
npm run dev        # 开发模式（热更新）
npm test           # 客户端单元与集成测试（隧道场景使用本机模拟 SSH 服务器）
npm run typecheck  # 主进程 + 渲染进程类型检查
npm run build      # 产出 out/
npm run icons      # 重新生成 resources/ 下的图标
```

客户端构建变量放在仓库根目录 `.env`：

```dotenv
SSH_TOOL_SYNC_API_URL=http://192.168.1.100:3000
SSH_TOOL_LOG_LEVEL=info
SSH_TOOL_LOG_TO_FILE=true
SSH_TOOL_LOG_MAX_BYTES=5242880
SSH_TOOL_LOG_MAX_FILES=3
```

`npm run build` 和 `npm run dist` 会把这些非敏感客户端配置写入 Electron 主进程 bundle；客户端
自动追加 `/api/v1`。`.env.development` 默认使用 `http://127.0.0.1:3000` 供
`npm run dev` 联调。HTTP、HTTPS、IP 地址和域名都可以使用。

HTTP 不提供传输层加密，经过公网时登录密码、token 和 key envelope 可能被窃听或篡改；
端到端加密只能保护同步文档内容。可信局域网或本机可以直接使用 HTTP，公网仍建议 HTTPS。

运行进程时仍可用同名环境变量临时覆盖内置值。只有 `SSH_TOOL_SYNC_API_URL` 和
`SSH_TOOL_LOG_*` 会通过白名单进入客户端；数据库密码、JWT、MFA 等服务端变量绝不能打进 exe。

应用运行日志同时输出到主进程控制台和 Electron `userData/logs/main.log`。默认每个文件
5 MiB，保留当前文件及 2 个历史文件；界面日志面板启动后也会显示实际日志路径。日志只记录
启动、同步状态和隧道状态，不记录密码、token、私钥、请求体或同步密文。

## 打包

```bash
npm run dist
```

在 `release/` 下产出 NSIS 安装包与免安装的 portable exe。
未配置 Windows 代码签名证书时产物可以运行，但 Authenticode 状态会是 `NotSigned`；
正式发布前应在安全的构建环境中配置证书后重新打包。

## 目录

| 路径 | 说明 |
|------|------|
| `src/main/index.ts` | 应用入口：窗口、托盘、生命周期、开机自启 |
| `src/main/logger.ts` | 脱敏 JSON 日志、级别过滤和文件轮转 |
| `src/main/ipc.ts` | IPC 路由 |
| `src/main/store.ts` | portable 配置与 v1→v2 迁移 |
| `src/main/persistence/device-secret-store.ts` | 本机密码、密码短语和私钥路径的 safeStorage sidecar |
| `src/main/security/` | token、Vault 缓存、Argon2id/AES-GCM 与运行时凭据 |
| `src/main/sync/` | API、序列化、三方合并、离线队列与同步状态机 |
| `src/main/tunnel/tunnel.ts` | 单条隧道：连接、转发、统计、重连 |
| `src/main/tunnel/manager.ts` | 多隧道管理、批量启停、日志缓冲 |
| `src/main/tunnel/socks5.ts` | SOCKS5 握手（动态转发用） |
| `src/preload/index.ts` | 暴露给渲染进程的 API（contextBridge） |
| `src/renderer/` | Vue 3 界面 |
| `src/shared/types.ts` | 三端共用的类型定义 |
| `test/` | Vitest 单元/集成测试；隧道场景包含模拟 SSH 服务器 |

配置位于 Electron 的 `userData` 目录。`config.json` 只包含结构字段；
`device-secrets.json`、`sync-auth.json` 和 `sync-vault-cache.json` 中的敏感内容均由
系统安全存储保护。首次升级会保留 `config.v1.pre-v2.backup.json`，迁移不会自动上传凭据。

恢复密钥只显示一次。丢失同步密码和恢复密钥后，服务端无法解密或恢复同步配置；
当前设备的本地配置仍可继续使用。

## 说明

- 早期的 Python + tkinter 版本已被本版本取代；仓库里如果还留着 `venv/`，可以直接删掉。
- 私钥支持 OpenSSH / PEM 格式；PuTTY 的 `.ppk` 需要先用 PuTTYgen 导出为 OpenSSH 格式。