Contents

SSH Tunnel:用图形界面管理多条 SSH 隧道

一、前言

SSH 端口转发的命令不算难,难的是日常维护。隧道一多,命令记不住、终端不敢关、断了要手动重连、哪个还活着全靠记忆。这个工具就是来收拾这些事的。

写一条转发命令是几秒钟的事:

1
ssh -N -L 3306:db.internal:3306 -i ~/.ssh/id_rsa user@jump.example.com

但用起来就不是几秒钟的事了。手上同时开着五六条隧道的时候,问题会一个接一个冒出来——参数记不住要翻笔记,每条隧道都得占一个终端窗口,终端一关隧道就没了,网络抖一下断线还得手动敲一遍重连,至于哪条还活着、哪条已经挂了,基本靠猜。

我把自己这套流程做成了一个桌面工具:SSH Tunnel,基于 Wails v2 + Vue 3,用图形界面管理多条 SSH 隧道。

二、解决什么问题

针对上面那几个痛点,工具的做法是这样的。

命令不用记了。 隧道保存成配置,点一下启停。已经写好的 ssh -L ... 命令可以直接粘贴进来,工具会解析成配置项,不用重新填一遍表单。

终端可以关了。 隧道跑在应用自己的进程里,配合系统托盘常驻,关掉主窗口隧道照样跑。macOS 上还能把 Dock 图标藏起来,完全当菜单栏应用用。

断线不用手动重连。 内置自动重连,最小退避、最大退避、心跳间隔都能配。

隧道状态看得见。 每条隧道的状态实时同步,托盘图标会随整体状态变色:有隧道在跑是蓝色,全部停止自动变灰。

连接状态也看得见。 这一条是 v0.0.2 补上的。隧道通了不等于业务通了——连到哪、跑了多少流量、是哪个本机进程发起的,以前只能靠 lsof 或者抓包。现在有独立的连接监控页,这些信息直接列在表格里。

三、主要功能

1. 多隧道管理

每条隧道独立启停,状态实时同步,支持一键全部启用 / 全部关闭。

2. 三种转发模式

-L 本地转发、-R 远程转发、-D 动态转发都支持。

动态转发这里做了一点额外的事:同一个监听端口上同时兼容 SOCKS5 和 HTTP 代理,按首字节自动识别协议。HTTP 模式下支持 CONNECT 隧道(可以走 HTTPS 或任意 TCP),也支持普通请求转发,并复用 keep-alive 连接。

3. 连接监控

v0.0.2 新增。把「现在有哪些连接、连到哪、跑了多少流量」直接摆到界面上,不用再开 lsof 或抓包。

表格里每条连接显示:进程名与 PID、来源地址、目标地址、所属隧道、协议(TCP / SOCKS5 / HTTP / HTTPS)。顶部汇总活跃连接数、累计上下行流量和当前速率。

排序做得比较细。进程 / 来源、目标 / 隧道、流量、速率、时长这五列都能点表头排序:点一次升序,再点一次降序,第三次取消回到默认顺序。数值列第一次点先给降序,文本列先给升序。每秒刷新数据之后,排序按当前列动态重排,不会跳回默认。

进程反查是这块的重点。它按本地端口倒推是哪个进程发起的连接,三个平台各用各的办法:

平台 实现
macOS libproc 遍历进程 fd
Linux /proc/net/tcp + /proc/<pid>/fd 反查 socket inode
Windows GetExtendedTcpTable 一次系统调用拿到全部连接及所属 PID

-R 远程转发的发起方在 SSH 服务器那一侧,本机没有对应进程,所以这类连接只显示来源 IP。

断开操作支持单条和全部。隧道停止时会一并清理该隧道的连接,不留僵尸记录。已经结束的连接会保留 5 秒(最多 200 条),能看到断开原因:

原因 含义
手动断开 在监控页点了断开
隧道停止 所属隧道被停掉
目标不可达 连不上目标地址

开销这块做了控制。只有打开连接监控页面时才以 1Hz 采样并推送,离开页面就停,不看就不花 CPU。连接登记表上限 4096 条,达到上限只是新连接不再显示,转发本身不受影响。

4. 代理中转

到 SSH 服务器的这一段连接,可以再经由 HTTP / HTTPS / SOCKS5 代理建立,支持代理认证。适用于跳板机本身也要走代理才能访问的场景,连接测试同样走这条链路。

5. 自动重连

断线后自动重试,退避策略可配置。默认最小退避 1000 ms、最大退避 30000 ms,心跳间隔 30 秒(填 0 关闭)。

6. 系统托盘

托盘菜单里可以直接启停隧道、全部启用、全部关闭、显示窗口、退出程序。每条隧道用符号标识状态:

符号 含义
● 运行中
◐ 连接中
⚠ 错误
○ 已停止

7. 导入与导出

三种方式,覆盖迁移和备份的场景:

  • 从 SSH 命令导入 —— 粘贴 ssh -L 8080:localhost:80 -i ~/.ssh/id_rsa user@host,自动解析成隧道配置
  • 导出为 SSH 命令 —— 任意隧道一键导出成等效的 ssh 命令行,方便直接粘到终端里用
  • JSON 导入导出 —— 支持合并和覆盖两种模式,换机器或者备份配置都用得上

四、界面预览

1. 隧道列表

主界面列出所有隧道配置,包含运行状态、转发规则和错误信息。

/images/post/2026101002/tunnel-list.png

2. 连接监控

实时展示所有进行中的连接:进程、来源、目标、流量与速率。图中按流量降序排列。左侧绿色圆点表示活动连接,灰色是刚结束还在保留期内的,红色表示连接目标失败。

/images/post/2026101002/conn-monitor.png

3. 新建与编辑隧道

配置 SSH 连接信息、认证方式(密钥或密码)、端口转发规则和高级选项。保存前可以先用「测试连接」验证 SSH 连通性,这一步只测连接,不会真的启动转发。

/images/post/2026101002/tunnel-edit.png

4. 导入与导出

三个页签对应三种方式:从 SSH 命令导入、JSON 导入导出、导出 SSH 命令。

/images/post/2026101002/import-export.png

5. 设置

开机自启、窗口行为、Dock 显示这些全局配置都在这里。配置文件路径也会显示出来,可以直接打开所在目录。

/images/post/2026101002/settings.png

6. 系统托盘

托盘菜单里直接操作隧道,图标颜色反映整体运行状态。

/images/post/2026101002/tray-menu.png

五、下载与安装

1. 直接下载

到 Releases 页面按平台取对应文件:

平台 架构 文件
macOS Apple Silicon ssh-tunnel-v0.0.2-darwin-arm64.zip
macOS Intel ssh-tunnel-v0.0.2-darwin-amd64.zip
macOS 通用(Intel + ARM) ssh-tunnel-v0.0.2-darwin-universal.zip
Windows x64 ssh-tunnel-v0.0.2-windows-amd64.exe(免安装)、ssh-tunnel-v0.0.2-windows-amd64-installer.exe(NSIS 安装包)
Windows x86 ssh-tunnel-v0.0.2-windows-386.exe(免安装)
Linux x64 ssh-tunnel-v0.0.2-linux-amd64

Linux 只提供 x64,因为 Wails v2 不支持 Linux 386。

顺带说一句 v0.0.1 的遗留问题:那一版的 Windows 安装包因为构建机缺少 makensis 被静默跳过,实际只发布了免安装 exe。v0.0.2 补装了 NSIS,安装包这次是齐的。

2. 从源码构建

需要 Go 1.21+、Node.js 16+ 和 Wails CLI v2:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
# 安装 Wails CLI
go install github.com/wailsapp/wails/v2/cmd/wails@latest

# 克隆并安装前端依赖
git clone https://github.com/midaug/ssh-tunnel.git
cd ssh-tunnel
cd frontend && npm install && cd ..

# 开发模式(热重载,可在 http://localhost:34115 调试)
wails dev

# 构建当前平台
wails build -clean

# 交叉编译
wails build -platform darwin/universal -clean
wails build -platform windows/amd64 -clean

构建产物输出到 build/bin/。

六、技术实现

层 技术
框架 Wails v2(Go + WebView)
后端 Go,golang.org/x/crypto/ssh,golang.org/x/net/proxy
前端 Vue 3 + TypeScript + Pinia + Vue Router
系统托盘 fyne.io/systray
进程反查 macOS libproc / Linux procfs / Windows iphlpapi
macOS Dock 控制 cgo 调用 NSApp.setActivationPolicy
开机自启 macOS LaunchAgent / Windows 注册表 / Linux .desktop

选 Wails 而不是 Electron,主要是看中产物体积和内存占用——它用系统自带的 WebView 渲染前端,不用打包一整个 Chromium。v0.0.2 的 macOS ARM 版本压缩后 3.8 MB。

隧道运行时分成三块:manager.go 管多隧道的启停和状态汇总,tunnel.go 管单条隧道的生命周期和自动重连,三种转发模式各自实现在 forward_local.go / forward_remote.go / forward_dynamic.go 里。proxy.go 负责经 HTTP/HTTPS/SOCKS5 代理拨号到 SSH 服务器,隧道拨号和连接测试共用这条路径。

连接监控是新增的两个包:internal/conn 是连接登记表,负责快照、速率采样和主动断开;internal/proc 按本地端口反查进程,三个平台各一份实现。

七、平台支持与系统要求

功能 macOS Windows
系统托盘 ✅ ✅
连接监控(含进程反查) ✅ ✅
开机自启 ✅ LaunchAgent ✅ 注册表
隐藏 Dock 图标 ✅ 菜单栏应用模式 —
启动时不显示窗口 ✅ ✅
关闭窗口最小化到托盘 ✅ ✅

Linux 同样能构建,连接监控和进程反查(走 /proc)也都支持,只是没有 Dock 和托盘的系统级集成。

系统版本要求:

平台 最低版本 备注
macOS 10.13 High Sierra —
Windows 10 / Server 2016 需要 WebView2 Runtime(Win10/11 通常已内置)

Windows 7 和 8 不支持——Wails v2 依赖 WebView2(Edge 内核),而且 Go 1.21+ 本身已经移除了 Win7 支持。

配置文件按平台放在用户配置目录下:

平台 路径
macOS ~/Library/Application Support/ssh-tunnel/config.json
Windows %AppData%\ssh-tunnel\config.json
Linux ~/.config/ssh-tunnel/config.json

配置写盘在 v0.0.2 改成了原子替换,写到一半崩溃不会把原文件写坏;文件真的损坏了也能自动恢复。

八、更新日志

1. v0.0.2(2026-10-21)

新增

  • 连接监控:实时连接列表、流量与速率、五列排序、单条 / 全部断开
  • 进程反查:macOS libproc / Linux procfs / Windows iphlpapi
  • 三平台 CI:每次提交自动在 macOS / Linux / Windows 上跑测试

修复

  • 转发正确性:半关闭未传播导致响应被截断;-R 目标缺端口时拼出非法地址
  • 连接稳定性:SSH 握手无法中断、keepalive 超时不生效、stopCh 数据竞争
  • 配置安全:写盘改为原子替换并可从损坏中恢复;修正 IPv6 导出括号与含空格密钥路径
  • 界面:macOS 上 confirm() / alert() 被 WebView 静默吞掉(表现为「删除点了没反应」)、编辑页覆盖旧隧道、-D 行删除按钮错位;删除隧道补上二次确认
  • 连接监控:表头与数值列错位;速率改为按实际采样间隔换算(原先把每次采样的增量直接当每秒速率,采样延迟时会虚高)
  • 托盘与退出:托盘菜单重建时的 goroutine 泄漏、Dock 切换的线程问题、主动退出被「最小化到托盘」拦截
  • 发布:Windows 产物补上 NSIS 安装包

2. v0.0.1(2026-07-28)

首个可用版本:多隧道管理、三种转发模式、系统托盘、导入导出。

九、小结

这个工具解决的是我自己的实际问题:隧道多了之后,命令行和终端窗口的方式确实不太够用。v0.0.2 把连接层面的可见性补上之后,排查「隧道是通的但服务连不上」这类问题省事了不少。

项目还在早期,有问题或者想要的功能,欢迎到 GitHub 上提 issue。

顺带一提,SSH 端口转发本身的用法,之前写过一篇 SSH Tunnel 端口转发详解,三种转发模式的参数和场景在那里讲得比较细,可以对照着看。