ngrok-engine

ngrok 引擎：端点与流量策略

几乎所有 ngrok 任务都涉及两个决策：

1. 选择哪种端点？ Agent、云端还是内部端点——以及使用哪种协议。
2. 流量应该如何处理？ 即在边缘运行的流量策略。

本技能会在任务所需的层面回答这两个问题，并将详细内容放在 references/ 中。至于将结果应用到何处，则是另一个问题——请参阅 ngrok-surfaces。

请根据用户的意图做出这些决策。不要让用户选择端点类型；他们不需要了解这套分类。

1. 端点类型

• Agent 端点——由正在运行的 Agent 或 SDK 进程创建，仅在该进程运行期间存在。适用于临时场景、本地使用、演示和测试。
• 云端端点——通过 API、仪表板或 IaC 创建，不依赖任何 Agent。始终在线，URL 稳定。用于生产环境入口，以及第三方按自己的时间安排连接的任何场景。
• 内部端点——没有公共 URL。只能通过 forward-internal 操作访问。接收方借此避免暴露在公共互联网中。

大多数任务最终会采用以下组合结构：

云端端点（公共端点，运行策略）-> forward-internal -> 内部端点 -> 本地服务

协议与类型是两个独立维度。HTTP 是默认协议；TCP（SSH、RDP、数据库）会带来若干变化——公共 TCP 端点需要预留地址，内部 TCP URL 需要显式指定端口，策略阶段会变为 on_tcp_connect，而 Kubernetes 操作器完全不支持 TCP。

完整的决策逻辑、绑定方式和 TCP 规则：references/endpoints.md。

2. 流量策略

按阶段分组的规则。每条规则都可选包含 CEL expressions，并包含一个 actions 列表。

on_http_request:
  - expressions:
      - "req.url.path.startsWith('/admin')"
    actions:
      - type: deny

• 阶段： on_http_request、on_http_response、on_tcp_connect、on_event_stream_message。
• 规则按顺序运行，终止操作会结束执行链。每个云端端点策略都必须以终止操作结束；Agent 端点则不必如此。
• 在所有界面上，策略正文都相同。 只有附加方式不同。

语法、CEL 变量、Secrets 和 Vaults、最常用的七种操作，以及操作如何串联：references/traffic-policy.md。

操作词汇表

全部 26 种操作，让你无需获取其他内容也能了解有哪些操作：

• 连接修改：deny、forward-internal、http-request、log、restrict-ips、set-vars、terminate-tls
• 请求修改：add-headers、circuit-breaker、log、owasp-crs-request、rate-limit、redirect、remove-headers、request-body-find-replace、set-vars、url-rewrite
• 响应修改：add-headers、compress-response、custom-response、log、owasp-crs-response、remove-headers、response-body-find-replace、set-vars、sse-find-replace
• 安全：basic-auth、jwt-validation、oauth、openid-connect、owasp-crs-request、owasp-crs-response、restrict-ips、terminate-tls、verify-webhook
• 流量控制：circuit-breaker、close-connection、deny、forward-internal、http-request、owasp-crs-request、owasp-crs-response、rate-limit

绝不要猜测操作的配置。 请分两步查阅：

1. references/action-catalog.md——索引。每种操作占一行，列出阶段、是否会结束执行链，以及操作用途。
2. references/actions/<action>.md——该操作的配置字段、结果变量和示例。

只阅读所需操作对应的文件；整个目录约有 12k 个 token，而单个操作的文档只有几百个 token。

面向 Agent 的注意事项

• references/traffic-policy.md 中列出的七个操作只是现有任务技能恰好会用到的操作。它们并非最重要的部分——任务需要其他操作时，请查阅目录。
• 许多操作会自行执行策略（rate-limit 会返回自身的 429，verify-webhook 则会默认拒绝）。添加重复的 deny 前，请先查看该操作的条目。
• 将策略单独保存在 policy.yaml 中，这样用户日后添加第二个入口时，策略也能保留。
• 如果已连接 ngrok MCP 服务，请在展示或应用你编写或编辑的每项策略前，使用 gw_validate_traffic_policy 进行验证。它会执行与保存时相同的检查，包括计划权益检查，并报告每个问题所在的行和列。如果策略针对云端、TCP 或内部端点，请传入 endpoint_type、scheme 和 binding。