隧道排错手册

端口转发失败可能发生在四个位置：客户端、监听端口、SSH 连接和目标服务。先定位失败发生在哪一层，不要反复重建所有配置。

第一步：确认失败模式

现象	大概率先检查
隧道无法启动	本地或远端端口占用、规则冲突
隧道启动但连接被拒绝	目标地址、目标端口、目标服务
本机监听正常但远端不可见	绑定地址、GatewayPorts、防火墙
SOCKS5 部分域名失败	DNS 解析位置、IPv6、目标防火墙
连接后立即断开	SSH 认证、服务器策略、网络变化
之前可用，突然失效	主机密钥、网络切换、远端服务迁移

本地端口占用

macOS：

lsof -nP -iTCP:15432 -sTCP:LISTEN

Linux：

ss -lntp | grep 15432

处理方式：

• 停止占用端口的进程。
• 为 NetShuttle 规则换一个本地端口。
• 检查两条规则是否使用相同监听地址和端口。

远端目标不可达

从 SSH 服务器一侧测试：

nc -vz db.internal 5432
curl -v http://127.0.0.1:8080

如果远端服务器也访问不了，问题在目标服务、远端路由或防火墙，不在 NetShuttle。

需要分别确认：

• 域名是否能在正确一侧解析。
• 目标服务是否监听预期地址。
• 目标端口是否允许来源 IP。
• IPv4 与 IPv6 是否混用。
• 云安全组或主机防火墙是否放行。

远程转发没有监听

在远端服务器检查：

ss -lntp | grep 8080

检查 SSH 配置：

AllowTcpForwarding no
GatewayPorts no

含义：

配置	影响
AllowTcpForwarding no	禁止端口转发
AllowTcpForwarding local	只允许本地转发
AllowTcpForwarding remote	只允许远程转发
GatewayPorts no	远端只能绑定 localhost
GatewayPorts clientspecified	客户端可指定绑定地址
GatewayPorts yes	可绑定所有接口

服务器策略只能由管理员修改，客户端无法绕过。

SOCKS5 问题

浏览器提示代理失败

确认：

• 协议选 SOCKS5。
• 地址是 127.0.0.1。
• 端口与 NetShuttle 规则一致。
• 浏览器没有同时启用冲突的扩展 VPN 或系统代理。

域名可以解析但连接被拒绝

可能是本机 DNS 返回了错误地址。测试远端解析：

curl --socks5-hostname 127.0.0.1:1080 http://service.internal:8080

如果远端解析成功、本机解析失败，说明应使用 socks5h 语义。

IPv6 失败

检查客户端是否返回 IPv6 地址，而远端网络只能访问 IPv4。尝试指定 IPv4 或让代理端解析域名。

HTTPS 证书错误

SOCKS5 只负责建立 TCP 连接，不会替换 TLS。证书错误应检查域名、证书链和访问入口。

连接成功但应用仍报错

有些应用不支持 SOCKS5 或代理环境变量。确认：

• 应用是否支持 SOCKS5。
• 是否需要 socks5h 或允许远端 DNS。
• 是否只支持 HTTP 代理。
• 是否绕过 localhost 或内部域名。

网络切换后的恢复

NetShuttle 会区分用户主动断开和意外断开：

• 用户主动断开：不自动恢复。
• 用户主动停用隧道：不会被自动重连打开。
• SSH 意外断开：按指数退避重连。
• 因 SSH 断开而停用的隧道：连接恢复后自动恢复。

如果网络不可用，重连会进入等待集合。网络恢复后重新开始连接。

主机密钥变化

如果日志显示主机密钥验证失败：

1. 通过可信渠道确认服务器完成合法轮换。
2. 在服务器详情页删除对应 host/port 的旧记录。
3. 重新连接并确认新指纹。

不要跳过验证来解决连接问题。

建议的排错顺序

SSH 是否连接
→ 隧道是否启动
→ 监听端是否出现
→ 监听地址是否正确
→ 目标是否从正确一侧可达
→ DNS 和 IP 协议是否正确
→ 防火墙与安全组是否放行
→ 客户端代理配置是否正确

收集日志时不要泄露秘密

提交日志前删除：

• 用户名和完整主机名。
• 私钥路径和口令。
• OTP、Token 和密码。
• 内网业务域名。
• 终端输出中的业务数据。