故障排除

无法连接 SSH

1. 确认主机、端口和用户名正确。
2. 检查当前网络是否能访问目标地址。
3. 密码、MFA 或私钥认证是否与服务器配置一致。
4. 如果通过跳板机，分别验证跳板机与目标主机。
5. 查看设置中的日志，区分网络错误、认证失败和主机密钥拒绝。

主机密钥发生变化

NetShuttle 默认拒绝密钥变化。先通过带外渠道确认服务器确实完成合法轮换，再在服务器详情页按 host/port 清除旧记录并重新确认指纹。不要直接绕过验证。

本地端口无法监听

• 检查端口是否已被其他进程占用。
• 确认绑定地址和规则端口一致。
• 检查防火墙或安全软件是否阻止监听。
• 尝试改用高位端口验证配置。
• 确认 SSH 连接仍处于已连接状态。

远程转发不可达

• 确认远端 SSH 服务器允许 tcpip-forward。
• 检查远端监听地址是否允许目标客户端访问。
• 检查远端防火墙和 SSH 服务配置。
• 确认本地目标服务正在监听。

SOCKS5 代理不可用

确认客户端使用 SOCKS5 而不是 HTTP 代理，并检查代理地址、端口和规则启用状态。当前实现为无认证 SOCKS5，只处理 CONNECT 命令。

外部终端没有启动

1. 确认目标终端 App 已安装，或在设置中选择自定义 .app。
2. 检查系统是否弹出 Apple Events 或文件访问授权。
3. 等待最多 6 秒；NetShuttle 会按 Profile 策略自动回退。
4. 打开日志确认哪个策略立即失败、哪个策略超时。
5. 尝试 Terminal.app，排除单一终端兼容问题。

iCloud 同步不可用

• 确认设备已登录 iCloud。
• 确认 iCloud Drive 与 Keychain 均启用。
• 检查 NetShuttle 的 iCloud Documents 能力。
• 等待首次密钥同步后重试。
• 如果迁移未完成，应用会继续使用源 Provider；不要手工复制密文文件。

自动重连没有发生

检查 SSH 是否为手动断开、网络是否可用、是否已达到最大重连次数。用户主动断开和主动停用的隧道不会自动恢复。