TunnelDeck 桌面版使用指南：把 ssh -L 变成可保存的隧道

SSH 本地端口转发很好用，但当命令越来越多，记住端口、目标地址和密钥位置就会变得麻烦。TunnelDeck 是我做的一款轻量、跨平台的 SSH 隧道桌面工具：它把 ssh -L 变成可以保存、编辑、快速启停的连接，同时保留主机指纹校验、系统凭据存储和本地监听等安全边界。

例如，下面这条命令：

ssh -L 9108:127.0.0.1:9108 -p 33899 root@ssh.example.com

可以直接导入 TunnelDeck。连接建立后，本机访问 127.0.0.1:9108，流量会经过 SSH 服务器转发到它所能访问的 127.0.0.1:9108。

本文以桌面版 v0.3.1 为主，完整介绍安装、创建连接、密码与私钥认证、首次指纹确认、网页快捷入口和常见故障排查。

TunnelDeck 适合什么场景

TunnelDeck 当前专注于 SSH 本地端口转发（-L），适合：

临时访问只监听在服务器本机的管理面板；
通过跳板机访问数据库、开发服务或内网 Web 应用；
保存多条常用隧道，按需启动或停止；
不想每次重新输入一整条 ssh -L 命令；
希望网页隧道连接后，可以再手动用默认浏览器打开。

它不是 VPN，也不提供远程转发 -R、SOCKS 动态代理 -D 或远程 Shell。导入器还会拒绝 ProxyCommand 等可能执行外部命令的选项。

先看懂四个关键参数

以开头的命令为例：

配置项	示例值	含义
SSH 服务器	`ssh.example.com:33899`	TunnelDeck 实际登录的 SSH 主机和端口
SSH 用户	`root`	SSH 登录用户
本地入口	`127.0.0.1:9108`	你的电脑上供应用访问的地址
远程目标	`127.0.0.1:9108`	从 SSH 服务器视角访问的目标

最容易混淆的是最后一项：远程目标里的 127.0.0.1 指 SSH 服务器自身，不是正在运行 TunnelDeck 的电脑。如果服务位于 SSH 服务器能访问的另一台内网机器，就应填写那台机器的地址，例如 10.0.0.20:8080。

本机应用
  └─ 127.0.0.1:9108
       └─ 加密 SSH 连接 → ssh.example.com:33899
            └─ SSH 服务器发起连接 → 127.0.0.1:9108

1. 安装桌面版

目前项目还没有 Apple 或 Windows 代码签名身份，因此 v0.3.1 不提供未签名的预编译桌面安装包。安装脚本会先检查环境，再下载固定版本源码并在本机完成构建。这种方式不会要求你绕过 macOS Gatekeeper 或 Windows SmartScreen 去运行来源不明的二进制文件。

macOS 与 Linux

建议先只检查依赖：

curl -fsSL https://raw.githubusercontent.com/Nciae-Zyh/TunnelDeck/v0.3.1/install.sh \
  | sh -s -- --check

确认输出后再安装：

curl -fsSL https://raw.githubusercontent.com/Nciae-Zyh/TunnelDeck/v0.3.1/install.sh | sh

没有 curl 时也可以使用：

wget -qO- https://raw.githubusercontent.com/Nciae-Zyh/TunnelDeck/v0.3.1/install.sh | sh

Windows PowerShell

irm https://raw.githubusercontent.com/Nciae-Zyh/TunnelDeck/v0.3.1/install.ps1 | iex

安装器会检查 Go 1.25+、Node.js 20+ 和对应平台的构建依赖。缺少 Go 或 Node.js 时，它们会被下载到 TunnelDeck 的私有用户目录，并校验官方 SHA-256，不会修改全局 PATH。

macOS 还需要 Xcode Command Line Tools，应用安装到 ~/Applications/TunnelDeck.app；
Linux 需要 GTK3 与 WebKitGTK 4.1，程序安装到 ~/.local/bin/TunnelDeck；
Windows 需要 WebView2，程序安装到 %LOCALAPPDATA%\Programs\TunnelDeck\，同时创建开始菜单入口。

将远程脚本交给 Shell 前，建议先打开 v0.3.1 安装脚本阅读内容。完整依赖和手动构建方式也记录在源码安装指南中。

2. 导入已有的 ssh -L 命令

如果手上已有可以工作的命令，最快的方法是：

打开 TunnelDeck，点击“导入命令”；
粘贴完整的 ssh -L 命令；
检查解析出的 SSH 主机、端口、用户、本地入口和远程目标；
为连接填写一个便于识别的名称；
选择认证方式，保存后启动。

TunnelDeck 解析参数后由 Go SSH 库直接建立连接，不会把输入拼接成 Shell 命令执行。为了把导入边界保持在可审计范围内，目前只接受一条本地转发，不接受远程命令、-R、-D 或 ProxyCommand。

3. 手动创建一条隧道

点击“新建”，依次填写：

名称：例如“开发环境面板”；
SSH 服务器与端口：例如 ssh.example.com 和 33899；
SSH 用户名：使用服务器实际允许登录的用户；
本地监听地址与端口：通常保持 127.0.0.1，再选一个未占用端口；
远程目标地址与端口：填写 SSH 服务器可以访问的服务；
认证方式：选择密码或 SSH 私钥；
点击“保存并启动”。

默认绑定 127.0.0.1，意味着只有本机程序能访问这条隧道。除非明确需要让局域网其他设备接入，并且已经配置系统防火墙，否则不要改成 0.0.0.0 或 ::。TunnelDeck 在这种情况下也会显示暴露风险提示。

4. 选择密码或私钥认证

密码认证

输入 SSH 登录密码即可。默认不要勾选“记住凭据”，密码只在当前运行期间保留，停止隧道后会从隧道对象中清除。

私钥认证

选择私钥文件；如果私钥已加密，再输入私钥口令。公钥需要提前写入服务器对应用户的 authorized_keys。

如果主动启用“记住凭据”，TunnelDeck 会调用操作系统提供的安全存储：

macOS Keychain；
Windows Credential Manager；
Linux Secret Service。

普通的 profiles.json 不保存密码、私钥内容或私钥口令。即使如此，服务器端仍应使用最小权限账号，限制可登录来源，并定期轮换密钥。

5. 首次连接要核对主机指纹

第一次连接某台 SSH 服务器时，TunnelDeck 会显示其 SHA-256 主机指纹。不要只因为弹窗出现就直接信任：应通过服务器控制台、运维文档或其他可信渠道核对指纹，再点击“信任并连接”。

确认后的记录写入 TunnelDeck 独立的 known_hosts。如果服务器主机密钥后来发生变化，连接会被阻止，而不是静默接受新密钥。正常重装服务器也可能导致变化，但在确认原因之前，不要绕过这个警告——它也可能意味着主机写错或连接被劫持。

6. 连接后访问服务

隧道显示“运行中”后，使用本地入口访问服务：

网页：在浏览器打开 http://127.0.0.1:9108；
数据库：让数据库客户端连接 127.0.0.1 和本地端口；
其他 TCP 服务：同样把客户端目标改为本地入口。

如果目标是网页，可以在配置中启用“这是网页服务”，并选择 HTTP 或 HTTPS。连接成功后会出现“打开网页”按钮，由用户点击后调用系统默认浏览器。

TunnelDeck 不会在启动应用、启动隧道或自动重连时擅自打开网页。因为很多端口并不是 HTTP 服务，把“连接”和“打开网页”分开能避免错误跳转，也不会在后台重连时不断弹出浏览器窗口。

7. 日常管理与自动重连

列表会显示每条配置的运行状态和活动连接数。你可以按需启动、停止、编辑或删除配置。编辑运行中的隧道时，应先停止旧连接，再让新参数生效，避免误以为界面已改但旧监听仍在运行。

对于临时网络中断，TunnelDeck 会发送 SSH keepalive，并使用 2–30 秒的指数退避尝试重连。重连只恢复隧道，不会自动打开网页。

常见问题排查

本地端口无法监听

通常是端口已被其他程序占用。换一个本地端口，或先确认占用者：

lsof -nP -iTCP:9108 -sTCP:LISTEN

SSH 服务器连不上

先检查域名、SSH 端口、用户名、防火墙和当前网络是否允许访问。可以在终端使用相同参数做一次基础连接测试，但不要把密码写进命令或截图。

隧道已运行，但目标服务打不开

从 SSH 服务器的视角检查目标地址。尤其注意：远程目标写 127.0.0.1 时，服务必须运行在 SSH 服务器本机。还要确认目标服务确实监听对应端口，并允许 SSH 用户所在主机访问。

私钥无法使用

检查是否选错公钥文件、私钥格式是否受支持，以及加密私钥的口令是否正确。私钥应只对当前系统用户开放读取权限。

出现主机密钥变更警告

先暂停连接并核对服务器是否重装、域名是否解析到了新主机。只有通过可信渠道确认新指纹后，才更新信任记录；不要为了“先连上”而关闭校验。

为什么桌面版比较轻

TunnelDeck 使用 Go、Wails 和 Vue 3 构建，界面复用操作系统 WebView，不会随应用打包一整套 Chromium。SSH 隧道由 golang.org/x/crypto/ssh 直接建立。当前 macOS ARM64 应用包约 8.7 MB。

项目采用 MIT License，源码、安装脚本和发布记录都在 TunnelDeck GitHub 仓库。当前稳定版本可在 v0.3.1 Release查看。

Chrome 应用商店版本已经上线

TunnelDeck Chrome 侧边栏扩展 v0.3.1现已在 Chrome Web Store 公开上线，可以直接从商店安装。完整源码、桌面端安装脚本和问题反馈仍统一维护在 TunnelDeck GitHub 仓库。

推荐按下面的顺序完成安装：

先按本文第 1 节或 GitHub README 安装 TunnelDeck 桌面端；
从 Chrome Web Store 安装扩展；
启动桌面端，在底部“Chrome 浏览器集成”中确认正式扩展 ID jnfkjehpbkmfnidfcilehhkpbjjinmod；
如果状态显示尚未注册，点击“注册 Chrome 服务”，然后重新加载扩展；
点击 Chrome 工具栏中的 TunnelDeck 图标，即可在侧边栏管理连接。

浏览器扩展通过 Native Messaging 控制本机 TunnelDeck，可以创建、编辑、导入和启停连接，也能在用户点击后打开已标记的网页服务；它不会在浏览器进程中自行建立 SSH。因此，商店扩展负责快捷操作，桌面版仍然是实际运行 SSH 隧道的核心。

留言