mcpField
T
troubleshoot-ngrok

troubleshoot-ngrok

github.com/ngrok云与 DevOps18143 次安装4 天前更新
代码仓库

关于 troubleshoot-ngrok

troubleshoot-ngrok 是诊断 ngrok 端点或 Agent 故障的技能,按错误代码查阅对应文档,再检查实时状态以定位原因。适用于使用 ngrok MCP 服务、Shell 或本地检查器排查问题的场景。

主要功能

  1. 01从错误页面或输出获取错误代码
  2. 02查阅错误代码对应的文档
  3. 03检查端点、Agent 和流量状态
  4. 04验证 Traffic Policy
  5. 05依据症状排查无错误代码的问题
  6. 06重发失败请求确认修复

适用场景

  1. 01诊断端点离线或上游连接失败
  2. 02检查 Agent 连接状态与版本
  3. 03定位某次请求失败的原因
  4. 04排查策略未生效或 TLS 错误

MCP 相关

通过 ngrok MCP 服务调用错误文档、端点、Agent、流量检查器、连接、账户限制和策略验证工具。未连接时,可改用 Agent 输出、本地检查器和控制面板。

安装

复制下面的命令,在终端中运行。

$npx skills add https://github.com/ngrok/skills --skill troubleshoot-ngrok

安装后在 Claude Code 中输入/troubleshoot-ngrok确认已加载。

详细介绍

排查 ngrok 问题

通过三个步骤诊断无法正常工作的 ngrok 端点或 Agent:获取错误,阅读对应的文档页面,然后检查实时状态以确定适用的原因。

1. 获取错误

ngrok 错误包含 ERR_NGROK_<code> 代码。它会显示在浏览器的错误页面、Agent 输出、API 响应和流量检查器中。有些代码是数字(ERR_NGROK_8012),有些是名称(ERR_NGROK_AGENT_NOT_FOUND)。

获取代码。如果用户只有错误消息,请保留其原文和具体值。如果完全没有错误,请转到按症状排查。

2. 阅读错误对应的文档页面

每个代码都有一个页面,介绍其原因和解决方法。不要凭记忆解释代码:错误代码各不相同,近似猜测可能会误导用户。

  • 使用 ngrok MCP 服务的 docs_get_error: 使用 code 调用;如果没有代码,则使用 message 调用。如果它针对一条消息返回多个代码,请向用户询问代码。不要自行选择。
  • 其他情况: 如果只有错误消息,请从错误页面或 Agent 输出中获取代码,或者向用户询问;不要根据消息猜测代码。获取代码后,访问 https://ngrok.com/docs/errors/err_ngrok_<code>.md,将代码转换为小写,并去掉 ERR_NGROK_ 前缀。例如,ERR_NGROK_8012 对应 err_ngrok_8012.md。如果返回 404,说明代码有误;请与用户核实。

docs_search 无法找到错误页面。不要用它查询错误代码。

3. 确定适用的原因

错误页面会列出所有可能的原因。检查账户以确定适用的原因,而不是让用户逐一排查。

使用 ngrok MCP 服务时:

问题工具
有没有服务正在提供此 URL?使用 URL 调用 get_resource。gw_list_endpoints 会显示账户提供的服务;URL 相差一点点是常见原因。
Agent 是否已连接?其版本是否为最新?gw_list_agents:可查看已连接的 Agent、版本及任何弃用期限。
这一个请求发生了什么?使用 ngrok 错误页面中的请求 ID 调用 gw_get_traffic_inspector_request。
哪些请求失败了?gw_query_traffic_inspector:每一行都包含 ngrok 错误代码。可按主机、状态或路径筛选。
TCP 或 TLS 端点故障gw_query_connections(可按错误代码筛选),然后调用 gw_get_connection。
账户是否达到限制?platform_get_enforced_limits。platform_get_usage 报告的是用量,而不是上限。
流量策略是否有效?gw_validate_traffic_policy 会报告每个问题所在的行和列。

不使用该服务时,请查看 Agent 自身的输出(ngrok http <port> --log stdout)、本地检查器 http://localhost:4040 和控制面板。

然后按照页面上的说明修复问题,并重新发送失败的请求以确认。

最常见错误代码的说明

完整的修复方法请参阅文档页面。以下说明补充了页面未提及的信息。

  • ERR_NGROK_3200(端点离线)。 没有服务正在提供所访问的 URL。请检查两件事:Agent 是否已连接?它提供的是否与该 URL 完全一致?子域名不同或输入错误都会导致同样的错误。访问者报告 3200 错误时,所有者的 Agent 通常已停止运行。访问者可能无能为力。
  • ERR_NGROK_8012(上游连接失败)。 ngrok 正常工作,但本地服务没有响应。请确认服务运行在 Agent 转发到的端口和协议上(http 与 https、localhost 与 127.0.0.1 或容器地址)。
  • 身份验证错误(例如 ERR_NGROK_4018)。凭证缺失或无效。请先确认使用的是哪种凭证:Agent 使用 authtoken,API 和 IaC 使用 API 密钥。请转交给 ngrok-setup。
  • 会话限制(例如 ERR_NGROK_108)。同一账户下已有另一个 Agent 连接。gw_list_agents 会显示它的运行位置。

按症状分类(无错误)

  • 在 localhost 上运行正常,通过 ngrok URL 访问时返回 400 或被拒绝。 应用或开发服务器拒绝了 ngrok Host 标头。请参阅 expose-localhost/references/TROUBLESHOOTING.md。对于内部端点,使用 --host-header=rewrite(参见 run-mcp-gateway)。
  • Agent 启动后立即退出。 可能是凭据问题(参见 ngrok-setup),也可能是配置文件无法解析。运行 ngrok config check。
  • 流量策略没有生效。 该策略未关联到当前访问的端点,或者较早的规则终止了规则链。请在用户使用的界面上确认关联情况(参见 ngrok-surfaces)。规则顺序请参阅 ngrok-engine。
  • ngrok 域名出现 TLS 或证书错误。 首先查看 status.ngrok.com 是否有服务事件。如果没有,可能是用户的网络中有设备或软件正在拦截 TLS:ISP 过滤器、VPN,或受管理设备上的终端安全软件。请用户尝试切换网络,并使用 openssl s_client -connect <host>:443 -servername <host> 对比证书颁发者。

给 Agent 的说明

  • 如果你可以使用 MCP 服务或 shell,请自行运行检查。告知用户原因和解决方法,而不是列出需要检查的事项。
  • 依据代码进行判断。如果代码明确指出了原因,就不要猜测。
  • 如果原因与凭据或策略有关,请转交给 ngrok-setup 或 ngrok-engine。不要在此处重复其内容。

评论

支持 Markdown