故障排查指南 (隧道启动失败)

本文档配合 用户指南「隧道状态与失败原因」章节使用。当隧道卡片显示红色「失败」状态时, 先点卡片上的「复制错误信息」拿到失败摘要, 再按下述路径排查。

常见失败类别

启动失败会被映射为以下几类 (卡片上直接显示可读文案, 非原始日志):

§1 认证失败

表现: 失败摘要含「认证失败 / token 无效 / 未授权」等字样, 或服务端返回 401。

排查路径:

1. 重新登录一次 (退出账号后重新登录, 刷新本地 token), 再启动隧道。
2. 确认账号仍有该隧道的使用权限 (节点是否停用、账号是否欠费/封禁)。
3. 若频繁出现, 检查系统时间是否正确 (偏差过大会导致 token 签名校验失败)。
4. 仍失败: 复制错误信息并附上账号节点信息提交反馈。

§2 端口占用

表现: 失败摘要含「端口被占用 / address already in use」等字样。

排查路径:

1. 确认远程端口没有被其他隧道占用 (同一节点的同一远程端口只能分配给一条隧道)。
2. 确认本地端口没有被本机其他程序占用 (如 80 端口被 IIS/nginx 等占用)。
   • Windows: netstat -ano | findstr :端口号 查看占用进程。
   • Linux/macOS: lsof -i :端口号 或 ss -ltnp | grep 端口号。
3. 占用确认后: 停掉占用程序, 或在创建/编辑隧道时更换端口。

§3 节点不可达

表现: 失败摘要含「无法连接 / 连接被拒绝 / 节点不可达」, 或启动后 30 秒无在线确认 (超时)。

排查路径:

1. 使用隧道管理页的「刷新测速」确认该节点是否可达 (延迟/超时/失败)。
   • 超时: 节点过载或网络波动, 稍后重试, 或换一个节点。
   • 失败 (连接被拒): 节点可能下线或未开放该端口。
2. 检查本机网络: 能否正常访问其他网站/服务; 代理/VPN 是否干扰了到节点的连接。
3. 检查本机防火墙/安全软件是否拦截了 mefrpc 出站连接。

§4 进程崩溃

表现: 失败摘要含「进程异常退出 (退出码 N)」等字样。

排查路径:

1. 确认 mefrpc 版本是否与当前节点服务端兼容 (更新页可查看最新版本; 必要时重新下载客户端)。
2. 查看崩溃前终端输出: 在终端页手动执行同样的启动命令, 观察报错点。
3. 配置文件损坏时也会导致崩溃: 删除 Config/frp 下对应的临时配置后重试。
4. 仍崩溃: 复制错误信息 (含退出码), 提交反馈。

§5 未知错误

表现: 失败摘要为原始 API 错误信息。

排查路径:

1. 摘要通常已包含服务端返回的原始信息, 可据此关键词搜索或直接反馈。
2. 将「复制错误信息」的内容 (应用版本 + mefrpc 版本 + 摘要) 完整粘贴到反馈中。

通用建议

• 反馈问题前, 一律使用卡片上的「复制错误信息」, 内容包含应用版本与 mefrpc 版本, 能大幅加快定位。
• 修改网络环境 (代理、DNS、防火墙) 后, 重新「刷新测速」验证节点连通性, 再尝试启动。

更新失败

获取更新信息失败

表现: 「更新」页状态区显示「获取更新失败」, 无最新版本信息。

排查路径:

1. 检查网络连接 (能否访问其他网站); 代理/VPN 是否拦截了到更新 API 的请求。
2. 点击「检查更新」重试; 若更新通道为「预览」, 可切回「稳定」通道再试 (预览通道偶发无发布)。

下载失败 / 校验失败

表现: 状态区显示「更新下载失败…」或「下载文件校验失败…」, 出现「重试下载」按钮。

排查路径:

1. 点击「重试下载」重试一次 (网络波动常见)。
2. 仍失败: 在「设置」页切换下载源 (TPCA ↔ 官方) 后重试。
3. 校验失败且重试仍出现: 下载源文件可能损坏, 等待一段时间后重试, 或切换下载源。
4. 若为 Windows 且下载的是安装包, 确认磁盘空间充足 (安装包数百 MB, 需预留 Cache 目录空间)。

首次启动隧道时 mefrpc 下载失败

表现: 启动隧道时提示下载 mefrpc 客户端失败, 隧道无法启动。

排查路径:

1. 确认 bin/mefrpc.exe (Windows) 或 bin/mefrpc.tar (Linux/macOS) 是否存在; 缺失时启动隧道会自动下载。
2. 下载失败: 在「设置」页切换下载源 (TPCA ↔ 官方) 后重新启动隧道。
3. 校验失败 (文件损坏): 删除 bin 下残留的 mefrpc*.tmp 与损坏文件后重试。