SSH 隧道管理器
文档目录展开收起
维护02

常见问题

端口被占、反复要密码、18 秒超时、macOS 灰图标——这些情况到底怎么回事。


点了「关闭」,为什么记录还在?

设计如此。关闭只终止 ssh 进程、把 PID 清零,配置留在 tunnels.json 里,随时可以「启动」复用。要真正去掉一条记录,用「删除」。

提示本地端口被占用,怎么办?

报错里会写占用进程的名字和 PID:

本地端口 127.0.0.1:4096 已被占用 — 占用进程:node(PID 41288)

三种常见情况:

  • 开发服务器:5173 被 pnpm dev 占着。换个本地端口,或先停掉前端服务。
  • 上一次的 ssh 残留:进程名以 ssh 开头时会额外提示,结束它或换端口。
  • 另一条运行中的记录:同一个 bind:port 只能有一条,先关掉那条。

为什么有时候要等 18 秒才报失败?

18 秒是兜底,不是常规路径。大多数失败会立刻返回:

  • 端口被占:启动前就报。
  • 认证失败:进程退出后立刻归因。
  • 连不上:ssh 自己的 ConnectTimeout=15 先退出。

真正会等到 18 秒的,是「连接建立了、但服务器迟迟不完成认证或转发」这种半死不活的状态。超时后进程会被杀掉并回收,不会留在后台。

密码会保存吗?

不会。密码只存在于内存和 ssh 子进程的环境变量里(SSH_ASKPASS + STM_ASKPASS_PWD),不写 tunnels.json、不进日志。应用重启后需要重新输入。

每次都弹密码框,能免密吗?

配密钥或 ssh-agent 就行,应用优先走密钥。密码流程只是没有密钥时的兜底。

远程端口填错了会怎样?

可能仍然显示「运行中」。本地监听成功只说明 ssh 把本地端口绑上了,远程端口能不能用要等你真正连接时才知道。这是 ssh -L 本身的语义,不是应用的判定漏洞。

关闭窗口后隧道还在跑?

是的。关闭窗口只是隐藏到托盘,这是桌面工具的惯例。要退出并保留隧道,用托盘菜单的「退出应用(保留隧道)」;要退出并关掉全部隧道,选「退出应用(关闭隧道)」。

支持 Linux 吗?

代码里有 Linux 分支(libc::kill、lsof / ss),但没有发布 Linux 安装包,也没有在 Linux 上做过完整验证。

macOS 上图标是灰底方块?

macOS 26 会把不符合 Apple 图标栅格的图标缩小并套进灰色底框。当前 .icns 已按 824-on-1024 栅格渲染。真正的 Liquid Glass 外观需要 .icon bundle 编译出的 Assets.car,只能在 macOS + Xcode 26 上用 actool 生成。

能转发 UDP 吗?

不能。ssh -L 只转发 TCP。

数据能直接搬走吗?

可以。tunnels.json 是纯 JSON,复制到另一台机器的同名目录即可(路径见数据与日志)。pid 字段在新机器上没有意义,通常会显示「已停止」;万一那个 PID 恰好被 ssh 占用,会显示为运行中,点一次「关闭」即可归零。