ssh-tunnel-debug

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SSH Tunnel Debugger

SSH 隧道调试工具

You are diagnosing issues with SSH tunnels managed by the

ssh-tunnels

CLI. Follow this systematic approach to identify and fix the problem.

你正在诊断由

ssh-tunnels

CLI管理的SSH隧道问题，请遵循以下系统化方法来识别并修复问题。

Step 1: Get the current state

步骤1：获取当前状态

bash

ssh-tunnels status --json

Look for tunnels where

enabled: true

but

alive: false

portOpen: false

. These are the broken ones.

bash

ssh-tunnels status --json

查找

enabled: true

但

alive: false

或

portOpen: false

的隧道，这些就是出现故障的隧道。

Step 2: Check the logs

步骤2：查看日志

For each broken tunnel:

bash

ssh-tunnels logs <tunnel-id>

针对每个故障隧道：

bash

ssh-tunnels logs <tunnel-id>

Step 3: Diagnose by error message

步骤3：根据错误消息诊断

"Permission denied (publickey)"

Cause: Wrong SSH username or SSH key not authorized on the remote host. Fix:

bash

ssh-tunnels remove <id>
ssh-tunnels add --name "Same Name" --host <host> --user root --localPort <port> --remoteHost <rhost> --remotePort <rport> --enabled

Try

root

first. If that doesn't work, ask the user what username they use to SSH into that server manually (

ssh <user>@<host>

原因：SSH用户名错误，或者SSH密钥未在远程主机上授权。 修复方案：

bash

ssh-tunnels remove <id>
ssh-tunnels add --name "Same Name" --host <host> --user root --localPort <port> --remoteHost <rhost> --remotePort <rport> --enabled

先尝试使用

root

用户。如果无效，请询问用户手动SSH连接该服务器时使用的用户名（命令：

ssh <user>@<host>

）。

"Connection refused"

Cause: SSH server is not running on the target host, or it's on a non-standard port. Checks:

bash

undefined

原因：目标主机上的SSH服务器未运行，或者使用了非标准端口。 检查操作：

bash

undefined

Test SSH connectivity directly

直接测试SSH连通性

ssh -o ConnectTimeout=5 -o BatchMode=yes <user>@<host> echo "OK" 2>&1

If the SSH server is on a non-standard port, recreate the tunnel with `--sshPort`.

ssh -o ConnectTimeout=5 -o BatchMode=yes <user>@<host> echo "OK" 2>&1

如果SSH服务器使用非标准端口，请重新创建隧道并指定`--sshPort`参数。

"Connection timed out" or "No route to host"

"Connection timed out"或"No route to host"

Cause: Host is unreachable — wrong hostname, firewall, or network issue. Checks:

bash

undefined

原因：主机无法访问——主机名错误、防火墙限制或网络问题。 检查操作：

bash

undefined

Test basic connectivity

测试基础连通性

ping -c 3 -W 5 <host> 2>&1

Test SSH port specifically

专门测试SSH端口

nc -z -w 5 <host> <ssh-port> 2>&1 && echo "Port open" || echo "Port closed/filtered"

undefined

nc -z -w 5 <host> <ssh-port> 2>&1 && echo "Port open" || echo "Port closed/filtered"

undefined

"Host key verification failed"

Cause: The server's host key changed or this is the first connection. Fix:

bash

undefined

原因：服务器的主机密钥已更改，或者这是首次连接该主机。 修复方案：

bash

undefined

Remove the old host key

删除旧的主机密钥

ssh-keygen -R <host>

The tunnel manager uses StrictHostKeyChecking=accept-new, so re-enabling should work

隧道管理器使用StrictHostKeyChecking=accept-new参数，因此重新启用隧道即可恢复

ssh-tunnels disable <id> && ssh-tunnels enable <id>

undefined

ssh-tunnels disable <id> && ssh-tunnels enable <id>

undefined

"bind: Address already in use"

Cause: Another process is already using the local port. Fix:

bash

undefined

原因：另一个进程已在使用本地端口。 修复方案：

bash

undefined

Find what's using the port

查找占用端口的进程

lsof -i :<local-port> -P -n

Either stop that process or change the tunnel's local port

停止该进程，或者修改隧道的本地端口

To change the local port, remove and re-add the tunnel with a different `--localPort`.

要修改本地端口，需删除现有隧道并使用不同的`--localPort`参数重新添加。

"channel 0: open failed: connect failed: Connection refused"

Cause: The SSH tunnel is connected, but the remote service is not listening on the specified remoteHost:remotePort. Checks:

bash

undefined

原因：SSH隧道已连接，但远程服务未在指定的

remoteHost:remotePort

上监听。 检查操作：

bash

undefined

SSH in and check if the service is running

登录远程主机并检查服务是否运行

ssh <user>@<host> "netstat -tlnp 2>/dev/null | grep <remote-port> || ss -tlnp | grep <remote-port>"

The remote service may be down, or `--remoteHost` / `--remotePort` may be wrong.

ssh <user>@<host> "netstat -tlnp 2>/dev/null | grep <remote-port> || ss -tlnp | grep <remote-port>"

可能是远程服务已停止，或者`--remoteHost`/`--remotePort`参数配置错误。

Empty log file or no log file

日志文件为空或无日志文件

Cause: The SSH process crashed immediately or was never spawned. Checks:

bash

undefined

原因：SSH进程立即崩溃，或者从未启动。 检查操作：

bash

undefined

Check the PID file

检查PID文件

cat ~/.ssh-tunnels/pids/<id>.pid 2>/dev/null

Try a manual SSH connection to see what happens

尝试手动建立SSH连接以查看问题

ssh -v -N -L <localPort>:<remoteHost>:<remotePort> <user>@<host>

undefined

ssh -v -N -L <localPort>:<remoteHost>:<remotePort> <user>@<host>

undefined

Step 4: Verify the fix

步骤4：验证修复效果

After making changes:

bash

ssh-tunnels status --json

Confirm that

alive: true

and

portOpen: true

for the fixed tunnel.

Then test the actual connection through the tunnel:

bash

undefined

修改配置后：

bash

ssh-tunnels status --json

确认故障隧道的

alive: true

和

portOpen: true

。

然后测试通过隧道的实际连接：

bash

undefined

For PostgreSQL (port 5432)

针对PostgreSQL（端口5432）

pg_isready -h 127.0.0.1 -p <local-port> 2>&1 || echo "Not ready"

For HTTP services

针对HTTP服务

curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:<local-port>/ 2>&1

For any TCP service (generic check)

针对任何TCP服务（通用检测）

nc -z -w 3 127.0.0.1 <local-port> && echo "Port responding" || echo "Port not responding"

undefined

nc -z -w 3 127.0.0.1 <local-port> && echo "Port responding" || echo "Port not responding"

undefined

Step 5: Check for systemic issues

步骤5：检查系统性问题

If multiple tunnels are failing:

bash

undefined

如果多个隧道出现故障：

bash

undefined

Check if SSH agent is running and has keys loaded

检查SSH代理是否运行且已加载密钥

ssh-add -l 2>&1

Check if there's a network-level issue

检查是否存在网络层面的问题

(all tunnels to the same host failing = host or network problem)

（所有连接同一主机的隧道都故障 = 主机或网络问题）

ssh-tunnels status --json | grep -E '"host"|"alive"'

Force a full re-sync

强制完全同步

ssh-tunnels sync

undefined

ssh-tunnels sync

undefined

Step 6: Nuclear option — full reset

步骤6：终极方案——完全重置

If nothing else works, reset a specific tunnel:

bash

ssh-tunnels disable <id>

如果其他方法都无效，重置指定隧道：

bash

ssh-tunnels disable <id>

Clean up any stale state

清理任何残留状态

rm -f ~/.ssh-tunnels/pids/<id>.pid ssh-tunnels enable <id> ssh-tunnels logs <id>

undefined

rm -f ~/.ssh-tunnels/pids/<id>.pid ssh-tunnels enable <id> ssh-tunnels logs <id>

undefined

Menu bar app issues

菜单栏应用问题

If the menu bar app is not showing or not updating:

bash

undefined

如果菜单栏应用未显示或未更新：

bash

undefined

Check if it's running

检查是否在运行

pgrep -f "electron.*app.mjs" && echo "Running" || echo "Not running"

Restart it

重启应用

pkill -f "electron.*app.mjs"

The LaunchAgent should restart it automatically, or:

LaunchAgent应自动重启它，或者手动执行：

launchctl unload ~/Library/LaunchAgents/com.statechange.ssh-tunnel-manager.plist 2>/dev/null launchctl load ~/Library/LaunchAgents/com.statechange.ssh-tunnel-manager.plist

Check launch agent status

检查LaunchAgent状态

launchctl list | grep statechange

undefined

launchctl list | grep statechange

undefined

Quick reference

快速参考

Symptom	Most likely cause	First thing to try
"Permission denied"	Wrong SSH user	Recreate with `--user root`
Tunnel stops immediately	Auth failure or port conflict	`ssh-tunnels logs <id>`
Tunnel starts but port not open	Remote service down	SSH in and check the service
All tunnels failing	Network issue or SSH agent	`ssh-add -l` , check connectivity
Tunnel works then dies	Server-side timeout	Check ServerAliveInterval
"Address already in use"	Port conflict	`lsof -i :<port>`

症状	最可能的原因	首先尝试的操作
"Permission denied"	SSH用户名错误	使用 `--user root` 重新创建隧道
隧道立即停止	认证失败或端口冲突	执行 `ssh-tunnels logs <id>` 查看日志
隧道启动但端口未开放	远程服务已停止	登录远程主机检查服务状态
所有隧道故障	网络问题或SSH代理异常	执行 `ssh-add -l` ，检查连通性
隧道可正常工作后中断	服务器端超时	检查ServerAliveInterval配置
"Address already in use"	端口冲突	执行 `lsof -i :<port>` 查找占用进程