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

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

常见失败类别

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

§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、防火墙) 后, 重新「刷新测速」验证节点连通性, 再尝试启动。

证书申请失败 (26.4)

「证书助手」基于 lego 的 DNS-01 流程, 有两种验证方式 (见用户指南「证书助手 → 验证方式」): DNS 账户 (一键自动) 由应用调用 DNS 服务商 API 自动读写 TXT 记录; 手动 DNS 由您自行添加 TXT 记录。

lego 下载失败 (无法准备证书组件)

• 表现: 点「开始申请」后长时间停留在「正在准备 lego…」, 或直接提示「无法准备证书组件 lego (下载或校验失败)」。
• 原因: 网络无法访问 GitHub (主源) 与备用镜像, 或下载内容校验不通过。
• 处理: 确认网络与代理后重试; 应用会依次尝试主源与备用源, 校验失败通常意味着下载不完整, 重试即可。若始终不可用, 可改用「手动 DNS」模式 (仍需 lego, 仅验证方式不同)。

手动 DNS: 一直停留在「请添加 TXT 记录后继续」

• 这是正常等待状态 (仅手动模式有这一步): 应用在等您到 DNS 服务商添加 TXT 记录, 不会自动超时。
• 处理: 复制窗口中的「记录主机」与「记录值」到 DNS 控制台 (类型选 TXT), 保存后点窗口上的「我已添加」。
• 若误关闭窗口, 本次申请会被取消 (lego 进程被终止), 重新申请即可。

DNS 账户 (一键自动) 模式失败

自动模式下应用已拿到服务商返回的明确错误, 界面文案通常直接给出原因:

申请过程中窗口会实时显示「运行日志」(已脱敏的 lego 输出), 失败时可直接展开定位原因。

手动 DNS 模式常见失败

证书填了却启动失败

• Staging 证书不可用于生产: Staging 证书不被浏览器信任, 仅用于流程验证; 正式使用需改用 Production 重新申请。
• 证书与私钥不匹配: 请使用同一次申请产出的 fullchain.pem 与 privkey.pem; 用「从证书助手选择」会成对填入, 避免手工配错。
• 证书临期提醒: 选择 Staging 证书时会提示「Staging (测试)」; 其他证书距到期不足 30 天会提示「即将到期 (N d)」。

更新内容窗口 (26.4)

窗口显示「暂时无法获取更新说明」

• 表现: 升级后首次启动弹出「本次更新内容」, 但内容区显示「暂时无法获取更新说明, 可稍后在更新页查看。」。
• 原因: 更新接口不可达 (网络/代理) 或服务端暂无当前版本条目。
• 处理: 检查网络后到「更新」页查看完整版本变更; 该窗口失败不会影响启动, 也不会因此重试弹窗。
• 「博客更新」页签拉取失败: 同上, 会提示获取失败; 可切换回「更新日志 (API)」页签或到更新页查看。

不希望再次弹出

• 窗口只要展示过即记为已读 (记录在 Cache/whats-new.json), 同一版本不会二次打扰; 版本号未变化时也不会弹出。

更新失败

获取更新信息失败

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

排查路径:

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 与损坏文件后重试。

链接启动隧道 (pml2://)

应用支持 pml2:// 通用链接, 用于从浏览器/网页一键启动指定隧道:

pml2://StartProxy/<隧道ID>?Name=<隧道名>

(mefrp:// 前缀同样识别; Name 可省略, 省略时终端标签显示 #隧道ID。)

首次使用的平台差异

注册在主实例启动时进行一次; 应用目录被移动或重装后, 下次启动会自动改写为新路径。

点击链接的行为

• 应用未运行 (冷启动): 链接参数写入 Cache/startup.json, 主窗口在 2 分钟内读到即拉起对应隧道 (读取后立即删除该临时文件, 不会重复启动)。
• 应用已在运行: 第二次启动会把链接透传给已运行实例 (命名管道 tech.rycb.pml2), 由它显示主窗口并启动隧道。

链接点了没反应?