跳至主要內容

ngrok、Cloudflare Tunnel 与 frp 本地暴露工具手册

高谷深陵大约 11 分钟约 3402 字
ngrok Cloudflare Tunnel frp 本地暴露治理知识海报
本地隧道暴露治理参考图把本地端口、隧道 agent、公网域名、访问控制、日志、token 和关闭回收放进同一条风险链。高清原图

Webhook 一直超时，本地日志却毫无动静

支付沙箱向回调地址重试，开发机上的 localhost:8080 没收到一个请求。把端口映射到公网之前，先证明上游真的可用，并且只含测试数据：

python -m http.server 8080 --bind 127.0.0.1
curl -i http://127.0.0.1:8080/

如果这里已经连接失败，隧道只会把本地故障变成公网 502 或 504。若这里返回 200，再决定入口是否值得开放。数据库、Redis、MQ、Docker socket、管理后台、Actuator、Swagger 和带真实用户数据的接口都不应成为临时公网目标；“原本只在本机”不是鉴权策略。

一条隧道的请求路径是：公网 DNS/边缘入口接收连接，平台或自建服务完成 TLS 与路由，agent 维持出站控制连接，再把请求转给本地 upstream。公网侧不必向开发机开放入站端口，但 agent 一旦连通，就建立了绕过原有内网可见性的入口。故障证据也要沿这条链逐段收集：本地 curl、agent 会话、边缘状态码、上游访问日志和第三方回调结果。

用 ngrok 完成第一次正反实验

从官方安装入口安装 agent 后，先检查二进制与配置路径。authtoken 标识账号并授权 agent 建立端点，应由密码管理器或本机 secret store 在启动进程时注入。ngrok config add-authtoken 会把 token 写入配置文件，而且把真实值放在命令参数中还会扩大 shell history 与进程观察面，因此共享开发机不走这条路径：

ngrok version
ngrok config check
: "${NGROK_AUTHTOKEN:?inject NGROK_AUTHTOKEN from a secret store}"
ngrok http 8080

终端会显示公网 HTTPS URL。不要只在同一台电脑浏览，换移动网络执行：

curl -i https://<assigned-host>/

预期状态和本地请求一致，agent 与本地服务日志各出现一次请求。随后停止本地 HTTP 服务但保留 ngrok，再请求相同 URL；预期变成边缘可达但 upstream 失败的错误。这个反例把 DNS、TLS 和 agent 控制连接保留下来，只破坏本地端口，所以 502 此时是定位证据，不是“平台坏了”。最后重启本地服务，响应应恢复。

需要固定配置时使用 Agent Config v3：

version: 3
agent:
  log: stdout
  log_format: json
  web_addr: 127.0.0.1:4040
endpoints:
  - name: webhook-dev
    description: "sandbox webhook"
    traffic_policy:
      on_http_request:
        - actions:
            - type: basic-auth
              config:
                credentials:
                  - "webhook-dev:${secrets.get('dev-tunnel', 'basic-password')}"
    upstream:
      url: http://127.0.0.1:8080
      protocol: http1

version 决定配置模型；v3 将全局项放入 agent，端点放入 endpoints，旧 tunnels 结构处于弃用路径。name 是启动和审计身份，省略 endpoint url 会分配随机地址，upstream.url 决定本地目标，protocol 决定 agent 到上游使用 HTTP/1 还是 HTTP/2。web_addr 应保持回环地址，因为本地检查接口本身也会暴露请求元数据。agent 会读取 NGROK_AUTHTOKEN 并让它覆盖配置中的同名属性，因此共享示例无需保存 token。字段变化与启动方法可查 Agent Config v3 和 Agent CLI。

ngrok start webhook-dev

公网 URL 不是秘密，也不是权限边界。上面的 traffic_policy 已经绑定到 webhook-dev endpoint；只把 on_http_request 另存成文件却不通过 endpoint 的 traffic_policy_file 或 CLI 的 --traffic-policy-file 引用，鉴权不会生效。ngrok 的 HTTP 鉴权应使用 Traffic Policy，而不是依赖已弃用的快捷参数。

secrets.get() 在运行时从 ngrok vault 取值，策略文件不保存密码；若团队未采用平台 vault，就由本机 secret store 渲染一份不入库的策略文件。开启完整流量捕获时，插入某些动作字段的 secret 仍可能在 Traffic Inspector 中以明文出现，因此排障结束要关闭捕获并清理受限会话，不能把“vault 中加密”误解成“流量证据永不含 secret”。应用自己的 webhook 签名校验仍要保留，因为边缘 Basic Auth 只限制谁能到达入口，不能证明业务消息来自支付平台。正向请求应携带两层所需凭证；反向请求去掉 Basic Auth，预期在边缘被拒绝，且本地访问日志没有该请求。这一“拒绝发生在上游之前”的证据比看到一个错误页面更有价值。

Cloudflare Quick Tunnel 到受管入口

安装 cloudflared 后，可用 Quick Tunnel 排除账号与 DNS 配置的干扰：

cloudflared --version
cloudflared tunnel --url http://127.0.0.1:8080

命令输出随机 trycloudflare.com 地址，外部 curl 成功即可证明本地 upstream 与 cloudflared 转发链路工作。Quick Tunnel 有并发和功能限制，并且不提供稳定的团队治理对象；它适合短时开发验证，不适合成为 CI、演示环境或第三方长期回调的固定依赖。限制发生变化时以 Quick Tunnels 为准。

当 URL 被第三方保存、多人共享或需要身份策略时，应建立受管 tunnel、DNS 与 Access 策略。先为目标 hostname/path 创建 self-hosted Access application 和默认拒绝策略，再发布 tunnel route；如果先发布路由而没有 Access application，该 hostname 会直接向公网开放。对 webhook 这类机器调用使用 Service Auth 或应用签名，不要套交互式网页登录。locally-managed 配置的核心形态是：

tunnel: <tunnel-uuid>
credentials-file: /run/secrets/cloudflared/<tunnel-uuid>.json

ingress:
  - hostname: webhook.example.test
    path: /sandbox/webhook
    service: http://127.0.0.1:8080
  - service: http_status:404

tunnel 选择受管对象，credentials-file 允许 connector 运行该 tunnel，不等于管理整个账号；hostname 和 path 缩小路由面，service 指向上游。ingress 规则按顺序匹配，末尾必须有 catch-all，否则未预期主机或路径可能没有明确拒绝语义。可先验证规则，再运行：

cloudflared tunnel ingress validate
cloudflared tunnel ingress rule https://webhook.example.test/sandbox/webhook
cloudflared tunnel run <tunnel-name>

Cloudflare 的配置文件说明给出了 ingress 顺序与兜底规则，Tunnel 权限说明区分账号证书和 tunnel credential。运行 connector 的主机只应得到所需 tunnel 凭证，域名与 Access 管理权留给更小的管理员集合。公网入口还应启用 Access token 校验：可让 cloudflared 通过 Protect with Access 校验，也可由上游验证 Access JWT；否则一条绕过 Access 的错误路由仍可能直达应用。

反向实验应分别请求允许路径和随机路径。允许路径在通过 Access 后到达本地，随机路径应由 cloudflared 的 http_status:404 兜底规则结束，上游应用日志不得出现。再用无 Access 身份或错误 service token 请求允许路径，预期在 Cloudflare 侧被拒绝，cloudflared 与上游应用均不出现该业务请求。若随机路径也到达上游，说明 ingress 顺序或通配规则过宽；若合法请求也被拒绝，先查 Access 策略身份，再查 connector 和 upstream，不要通过临时删除所有策略来“确认网络”。

frp 把平台责任搬回自己

frp 需要公网主机运行 frps，开发机运行 frpc。先从同一发行版本取得两端二进制并检查：

frps --version
frpc --version
frps verify -c frps.toml
frpc verify -c frpc.toml

新配置优先使用 TOML、YAML 或 JSON；INI 已弃用，新能力不会继续进入 INI。服务端不能只写一个监听端口和共享 token，还要限制代理能占用的资源：

bindAddr = "0.0.0.0"
bindPort = 7000
vhostHTTPPort = 8080
proxyBindAddr = "0.0.0.0"

auth.method = "token"
auth.tokenSource.type = "file"
auth.tokenSource.file.path = "/run/secrets/frp-token"
auth.additionalScopes = ["HeartBeats", "NewWorkConns"]

allowPorts = [{ start = 20000, end = 20100 }]
maxPortsPerClient = 4
transport.maxPoolCount = 5
transport.heartbeatTimeout = 90
transport.tls.force = true

log.to = "console"
log.level = "info"

bindPort 是 frpc 控制连接入口，不是业务 HTTP 端口；vhostHTTPPort 承载 HTTP 代理；proxyBindAddr 决定业务代理监听在哪个网卡。allowPorts 约束 TCP/UDP 远端端口，maxPortsPerClient 限制单客户端代理数量，maxPoolCount 抑制预建连接池，心跳超时决定失联状态何时清理。additionalScopes 让心跳和新工作连接也携带认证信息，tls.force 拒绝未启用 TLS 的客户端控制连接。

客户端只拿到连接该服务所需的 token 文件：

serverAddr = "frp.example.test"
serverPort = 7000
user = "team-a"

auth.method = "token"
auth.tokenSource.type = "file"
auth.tokenSource.file.path = "/run/secrets/frp-token"
auth.additionalScopes = ["HeartBeats", "NewWorkConns"]

[[proxies]]
name = "webhook-dev"
type = "http"
localIP = "127.0.0.1"
localPort = 8080
customDomains = ["webhook.example.test"]
transport.bandwidthLimit = "1MB"
transport.bandwidthLimitMode = "server"

serverAddr/serverPort 指向 frps 控制入口，localIP/localPort 是开发机上游，customDomains 依赖域名解析到 frps，并由 Host 选择代理；user 为代理名增加租户前缀，但不是完整授权模型。bandwidthLimitMode = "server" 让限速在 frps 侧执行，避免只依赖客户端自律；它仍不能替代连接数、请求体大小、应用鉴权、应用限流和云主机出站预算。共享 token 只能证明 frpc 获准连接 frps，不能限制公网访客访问 webhook.example.test，所以公网入口仍须由应用签名、前置身份代理或受控 Basic Auth 保护。字段语义可对照 frp 客户端配置、服务端配置与认证说明。

启动两端后先看 frpc 是否注册代理，再从外网带正确 Host 请求。把客户端 token 文件改成错误值并重启，预期登录被拒绝；恢复 token 后代理重新上线。然后停止 frpc，等待服务端按心跳超时清理，公网入口应失败且服务端不再列出该在线代理。若停止后仍可访问，优先查重复 frpc 进程、systemd 服务、容器副本和另一个同名代理。

把隧道接进项目而不接进密钥

仓库可以保存无密钥示例和启动脚本，实际 token 由环境、文件型 secret 或平台身份注入：

config/tunnel/ngrok.example.yml
config/tunnel/cloudflared.example.yml
config/tunnel/frpc.example.toml
scripts/tunnel/start-webhook
scripts/tunnel/stop-webhook
.ngrok/
.cloudflared/
config/tunnel/*.local.*
config/tunnel/*credential*.json
config/tunnel/*token*

启动脚本应先探测 127.0.0.1 健康端点，再启动指定路由，并把 owner、用途、端点标识和进程 ID 写入本机状态文件。停止脚本按“第三方回调改回占位地址或删除、停止 agent、撤销平台端点/DNS、删除本机状态与临时日志、从外网确认失败”的顺序执行。仅杀本地进程可能留下 DNS、Access application、云端 endpoint 或 systemd 自动重启。

Webhook 的业务验收还要保留原始请求体完成签名验证，拒绝重放标识和超出时间窗的消息，并使用幂等键防止平台重试造成重复写入。隧道不改变这些契约。测试证据应包含一次合法回调、一次错误签名、一次重复事件和一次关闭后的失败请求；不要把真实 Authorization、Cookie、签名值或请求体贴进工单。

容量、成本与失效方式

隧道多了一段边缘、控制连接和 agent 到 upstream 的排队。长连接、文件上传、流式响应和突发 webhook 会占用并发连接、带宽、内存与平台配额。观察端到端延迟分位数、活跃连接、边缘状态码、upstream 状态码、重连次数、传输字节和拒绝次数；阈值从真实压测与 SLO 得出，不能拿 Quick Tunnel 的体验数字推生产容量。

ngrok 与 Cloudflare 把边缘、证书和部分访问策略作为托管成本，自建 frp 则把云主机、带宽、DDoS 风险、补丁、日志、证书、备份和 on-call 全部变成团队成本。frp 看似没有按端点付费，但公网出站、滥用流量和无人维护的服务器往往更贵。需要稳定域名、组织身份、审计和低运维负担时优先受管方案；需要完全掌控网络路径、可接受自建责任且已有成熟运维能力时才考虑 frp。

让临时入口真正有终点

长期治理的对象不是某条命令，而是“谁在何种理由下把哪个上游暴露给谁”。允许清单应按数据级别和服务类型定义，数据库与管理面直接禁止，普通测试 HTTP 仍需 owner、身份策略、最长生命周期和关闭证据。平台账号使用 SSO 与最小角色，tunnel credential、agent authtoken、frp token、DNS 权限和 webhook secret 分开授权、分开轮换。

日志默认视为敏感数据：query、header、回调 body 和错误响应都可能包含凭证或个人信息。生产化入口应做字段级脱敏、短保留、访问审计和删除验证；开发排障优先记录 request ID、路径模板、状态码和字节数，而不是完整报文。

当一个随机 URL 开始被 CI、客户演示或多个第三方依赖，它已经不再“临时”。此时应迁移到受管域名、明确身份策略、容量预算、监控告警、变更审批和可演练回滚的入口；如果组织无法为 frps 指定 owner、升级窗口和滥用处置人，就不应把自建 frp 作为共享基础设施。

跳到正文