文档

入门

将本地Web服务器公开到互联网

ngrok允许您将本地计算机上运行的Web服务器公开到互联网。只是告诉ngrok你的web服务器正在监听什么端口。

如果你不知道你的web服务器正在监听什么端口,它可能是端口80,HTTP的默认值。

示例:将本地计算机的端口80上的Web服务器公开到互联网
ngrok http 80

当您启动ngrok时,它将在您的终端中显示一个UI,其中包含您的隧道的公共URL以及有关通过您的隧道进行的连接的其他状态和指标信息。

ngrok控制台UI
ngrok by @inconshreveable
 
Tunnel Status                 online
Version                       2.0/2.0
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://92832de0.ngrok.io -> localhost:80
Forwarding                    https://92832de0.ngrok.io -> localhost:80
 
Connnections                  ttl     opn     rt1     rt5     p50     p90
                              0       0       0.00    0.00    0.00    0.00
        

检查您的流量

ngrok提供了一个实时的Web UI,您可以在其中内省您的隧道上运行的所有HTTP流量。在启动ngrok之后,只需在Web浏览器中打开http://localhost:4040即可检查请求详细信息。

尝试向您的公开网址发出请求。 之后,回头检查UI。 您将看到请求和响应的所有详细信息,包括时间,持续时间,标题,查询参数和请求有效负载以及线上的原始字节。

详细内省HTTP请求和响应

重播请求

为外部API发出的webhooks开发通常会减慢你的开发周期,因为要求你做一些工作,比如拨打电话,触发挂钩请求。 ngrok允许您通过一次点击重新播放任何请求,大幅加快您的迭代周期。 单击Web检查UI上任何请求右上角的Replay按钮以重播。

通过一次点击,对您的隧道式Web服务器重复任何请求

请求正文验证

ngrok特别支持在网络上使用的最常见的数据交换格式。请求或响应正文中的任何XML或JSON数据会自动为您打印并检查语法错误.

JSON语法错误的位置突出显示

安装您的Authtoken

ngrok.com服务的许多高级功能在后面的章节中描述要求您注册一个帐户。 注册后,您需要使用显示在信息中心上的authtoken配置ngrok。 这将授予您访问仅限帐户功能的权限。 ngrok有一个简单的“authtoken”命令,使这很容易。 在引擎盖下,所有的authtoken命令是添加(或修改)authtoken属性在您的ngrok配置文件

安装您的authtoken
ngrok authtoken <YOUR_AUTHTOKEN>

HTTP隧道

自定义子域名称

ngrok为它为您打开的HTTP隧道分配随机十六进制名称。 这对于一次性个人用途是可以的。 但是,如果您在黑客马拉松上显示URL或与第三方Webhook集成,则如果隧道名称更改或难以阅读,可能会令人沮丧。 您可以使用-subdomain开关为隧道URL指定自定义子域。

示例:打开具有子域“inconshreveable”的隧道
ngrok http -subdomain=inconshreveable 80
ngrok by @inconshreveable
 
...
Forwarding                    http://inconshreveable.ngrok.io -> 127.0.0.1:80
Forwarding                    https://inconshreveable.ngrok.io -> 127.0.0.1:80

密码保护您的隧道

任何可以猜测您的隧道URL的人都可以访问您的本地Web服务器,除非您使用密码保护它。 您可以使用-auth开关使您的隧道安全。 这将对所有请求强制使用您指定为参数的用户名和密码的HTTP基本验证。

示例:密码保护您的隧道
ngrok http -auth="username:password" 8080

自定义域上的隧道(白标签网址)

而不是您的隧道显示为ngrok.io的子域,您可以在您的域上运行ngrok隧道。要通过dev.example.com运行隧道,请按照下列步骤操作:

  1. ngrok.com信息中心的“保留”选项卡上输入dev.example.com作为保留域。这保证没有其他人可以用自己的隧道劫持您的域名。
  2. 在信息中心上,点击“CNAME”图标复制您的CNAME目标。
  3. dev.example.com为您的CNAME目标创建DNS CNAME记录。在本例中,我们将CNAME记录指向2w9c34maz.cname.ngrok.io
  4. 使用-hostname开关调用ngrok,并将自定义域的名称指定为参数
    示例:在自定义domai上运行隧道
    ngrok http -hostname=dev.example.com 8000
通过HTTPS访问自定义域隧道将仍然有效,但证书将不匹配。如果您有TLS证书/密钥对,请尝试使用TLS隧道。

禁用检查

ngrok记录每个HTTP请求和响应通过您的隧道进行检查和重放。 虽然这对开发非常有用,但当您在生产服务上运行ngrok时,您可能希望禁用它以确保安全性和性能。 使用-inspect开关禁用对隧道的检查。

示例:没有检查的http隧道
ngrok http -inspect=false 80

重写主机头

当转发到本地端口时,ngrok不会修改隧道HTTP请求,它们会在接收时以字节为单位复制到您的服务器。 某些应用程序服务器(如WAMP,MAMP和pow)使用Host标头来确定要显示哪个开发站点。 因此,ngrok可以使用修改的主机头重写您的请求。 使用-host-header标头交换机重写传入的HTTP请求。

如果指定了rewrite,则将重写Host头以匹配转发地址的主机名部分。任何其他值将导致主机头被重写为该值。

将主机标题重写为“site.dev”
ngrok http -host-header=rewrite site.dev:80
将主机标题重写为“example.com”
ngrok http -host-header=example.com 80

仅隧道HTTP或HTTPS

默认情况下,当ngrok运行HTTP隧道时,它会打开HTTP和HTTPS流量的端点。如果您只希望转发HTTP或HTTPS流量,但不要同时转发,您可以使用-bind-tls开关切换此行为。

示例:仅侦听HTTP隧道端点
ngrok http -bind-tls=false site.dev:80
示例:仅侦听HTTPS隧道端点
ngrok http -bind-tls=true site.dev:80

TLS隧道

HTTPS隧道使用ngrok.com证书终止ngrok.com服务器上的所有TLS(SSL)流量。 对于生产级服务,您需要使用自己的TLS密钥和证书对您的隧道流量进行加密。 ngrok使这个特别容易与TLS隧道。

将TLS流量转发到端口443上的本地HTTPS服务器
ngrok tls -subdomain=encrypted 443

一旦你的隧道运行,尝试访问它与curl。

curl --insecure https://encrypted.ngrok.io

TLS隧道没有证书警告

注意 --insecure选项在前面的curl命令示例中? 您需要指定,因为您的本地HTTPS服务器没有必要的TLS密钥和证书来终止任何ngrok.io子域的流量。 如果您尝试在网络浏览器中加载该网页,您会注意到它告诉您该网页可能不安全,因为证书不匹配。

如果你希望你的证书匹配和保护免受中间人攻击,你需要两件事。 首先,您需要为您拥有的域名购买SSL(TLS)证书,并配置本地Web服务器以使用该证书及其私钥来终止TLS连接。 如何执行此操作是特定于您的Web服务器和SSL证书提供程序,并超出本文档的范围。 为了举例,我们假设您为域secure.example.com发出了SSL证书。 .

一旦你有你的密钥和证书,并正确安装,现在是时候运行一个TLS隧道在自己的自定义域名。 设置此的说明与HTTP隧道部分:自定义域中的隧道中描述的相同。 您注册的自定义域应与SSL证书(secure.example.com)中的自定义域相同。 设置自定义域后,请使用-hostname 参数在您自己的域上启动TLS隧道。

通过您自己的自定义域转发TLS流量n
ngrok tls -hostname=secure.example.com 443

终止TLS连接

您尝试公开的服务可能无法终止TLS连接。 ngrok客户端可以为您执行此操作,以便您可以加密端到端的流量,但不必担心本地服务是否具有TLS支持。 同时指定 -crt and -key命令行选项来指定TLS证书和密钥的文件系统路径,ngrok客户端将为您处理终止TLS连接。

卸载TLS终止到ngrok客户端
ngrok tls -hostname secure.example.com -key /path/to/tls.key -crt /path/to/tls.crt 80

通过TLS隧道运行非HTTP服务

ngrok TLS隧道对所传输的底层协议没有假设。 本文档中的所有示例都使用HTTPS,因为它是最常见的用例,但您可以通过TLS隧道运行任何TLS封装协议(例如imaps,smtps,sips等),而不进行任何更改。

兼容的客户端

TLS隧道通过检查传入TLS连接上的服务器名称信息(SNI)扩展中存在的数据来工作。 并非所有启动TLS连接的客户端都支持设置SNI扩展数据。 这些客户端将无法与ngrok的TLS隧道正常工作。 幸运的是,几乎所有的现代浏览器都使用SNI。 一些现代软件库没有。 以下客户端列表不支持SNI,不能使用TLS隧道:

更完整的列表可以在维基百科的服务器名称指示页面找到

TCP隧道

并非您希望公开的所有服务都是基于HTTP或TLS的。 ngrok TCP隧道允许您公开通过TCP运行的任何联网服务。这通常用于公开SSH,游戏服务器,数据库等。启动TCP隧道很容易。

公开在端口1234上运行的基于TCP的服务
ngrok tcp 1234

例子

公开侦听默认端口的SSH服务器
ngrok tcp 22
暴露一个Postgres服务器侦听默认端口
ngrok tcp 5432
暴露在默认端口上侦听的Minecraft服务器
ngrok tcp 25565

在保留的远程地址上侦听

通常,每次启动TCP隧道时,都会随机分配远程地址和端口。 对于生产服务(和便利),您通常需要一个稳定的,有保证的远程地址。 为此,首先,登录到ngrok.com仪表板,然后单击“保留的TCP地址”部分中的“保留地址”。 然后,在调用ngrok以绑定您保留的TCP地址上的隧道时,使用-remote-addr选项。

在保留的远程地址上绑定TCP隧道
ngrok tcp --remote-addr 1.tcp.ngrok.io:20301 22

更多隧道选项

通配符域

ngrok允许您将HTTP和TLS隧道绑定到通配符域。 所有通配符域(包括ngrok.io的子域)必须首先在您的信息中心为您的帐户保留。 使用-hostname or -subdomain时,指定前导星号以绑定通配符域。

绑定隧道以接收 example.com的所有子域上的流量
ngrok http --hostname *.example.com 80

通配符域规则

使用通配符域在ngrok.com服务的某些方面产生歧义。以下规则用于解决这些情况,并且了解如果您使用通配符域很重要。

为了示例的目的,假设您为您的帐户保留了地址*.example.com

  • 与嵌套子域(例如foo.bar.baz.example.com)的连接将路由到您的通配符隧道。
  • 您可以在 example.com 的任何有效子域上绑定隧道,而无需创建其他保留的域条目。
  • 没有其他帐户可以保留 foo.example.com或与其他帐户保留的通配符域相匹配的任何其他子域。
  • 连接将路由到最具体的匹配隧道在线。如果您同时运行 foo.example.com*.example.com的隧道,对 foo.example.com的请求将始终路由到foo.example.com

转发到不同机器上的服务器(非本地服务)

ngrok可以转发到本地计算机上未运行的服务。而不是指定端口号,而只是指定一个网络地址和端口。

示例:转发到不同计算机上的Web服务器
ngrok http 192.168.1.1:8080

全球基础设施

ngrok运行全球分布式隧道服务器,为您的应用程序提供快速,低延迟的流量。

地点

ngrok运行世界各地数据中心的隧道服务器。数据中心在给定区域内的位置可能改变而不通知(例如,欧洲服务器可能从法兰克福移动到伦敦)。

  • us - United States (Dallas)
  • eu - Europe (Frankfurt)
  • ap - Asia/Pacific (Singapore)
  • au - Australia (Sydney)

用法

如果您没有明确选择一个区域,您的隧道将托管在默认区域,美国。 选择最接近您的区域与指定设置-region命令行标志或设置配置文件中的region属性一样容易。 例如,在欧洲地区启动隧道:

ngrok http -region eu 8080

保留域和保留地址分配给特定区域(默认为美国区域)。 当您保留域或地址时,必须选择目标区域。 您不能绑定在分配给其他区域以外的其他区域中保留的域或地址。 尝试这样做会产生错误,并阻止您的隧道会话初始化。

限制

ngrok客户端只能连接一个区域。这可能会在将来更改,但目前单个ngrok客户端无法同时在多个区域托管隧道。如果需要,运行多个ngrok客户端。

域不能同时为多个区域保留。 不可能在多个区域中将DNS地理平衡到同一个隧道名称。 如果您需要这样做(eu.tunnel.example.com, us.tunnel.example.com等),请使用特定地区的子网域或TLD。

IP白名单隧道访问

您可以将帐户的隧道端点的访问权限列入白名单。 白名单由ngrok.com服务器强制执行。 它全局应用于所有的隧道端点。 检查到任何隧道端点的任何入站连接,以确保连接的源IP地址与白名单中的至少一个条目匹配。 如果连接与白名单不匹配,它会立即终止,而不会转发到ngrok客户端。

作为特殊情况,如果您的白名单为空,则允许所有连接。.

管理白名单

您可以在ngrok控制面板的auth选项卡上管理IP白名单。在“IP白名单”部分下输入新的IP地址,然后单击添加白名单条目Add Whitelist Entry。对IP白名单的更改最多可能需要30秒才能生效。

IP范围

有时,您可能希望将整个IP范围列入白名单。 而不是只输入一个IP地址,您可以改为使用CIDR notation表示法指定一个IP地址块。 例如,要允许从10.1.2.0到10.1.2.255的所有IP地址,您需要向白名单中添加10.1.2.0/24。

ngrok配置文件

有时,您的ngrok配置太复杂,无法在命令行选项中显示。 ngrok支持一个可选的,非常简单的YAML配置文件,它提供了同时运行多个隧道的能力,以及调整一些ngrok的更多奥术设置。

配置文件位置

您可以使用-config选项将路径传递到显式配置文件。这是建议所有生产部署。

显式指定配置文件位置
ngrok http -config=/opt/ngrok/conf/ngrok.yml 8000

您可以多次传递-config选项。 如果这样做,则将解析第一个配置,并将每个连续的配置合并到其上。 这允许您具有每个项目的ngrok配置文件与隧道定义,但主配置文件在您的主目录与您的authtoken和其他全局设置。

指定具有项目特定覆盖的附加配置文件
ngrok start -config ~/ngrok.yml -config ~/projects/example/ngrok.yml demo admin

默认配置文件位置

如果不为配置文件指定位置,ngrok会尝试从默认位置$HOME/.ngrok2/ngrok.yml读取一个位置。配置文件是可选的;如果该路径不存在,则不会发出错误。

在默认路径中,$ HOME是操作系统定义的当前用户的主目录。 它不是环境变量$ HOME,尽管它们通常是相同的。 对于主要操作系统,如果您的用户名是 example,则可能会在以下路径找到默认配置:

OS X /Users/example/.ngrok2/ngrok.yml
Linux /home/example/.ngrok2/ngrok.yml
Windows C:\Users\example\.ngrok2\ngrok.yml

隧道定义

配置文件的最常见用法是定义隧道配置。 定义隧道配置很有用,因为您可以从命令行按名称启动预配置的隧道,而不必每次记住所有正确的参数。

隧道定义为配置文件中的tunnels属性下的名称->配置的映射。

定义两个名为“httpbin”和“demo”的隧道
tunnels:
  httpbin:
    proto: http
    addr: 8000
    subdomain: alan-httpbin
  demo:
    proto: http
    addr: 9090
    hostname: demo.inconshreveable.com
    inspect: false
    auth: "demo:secret"
启动隧道名为“httpbin”
ngrok start httpbin

您定义的每个隧道都是配置选项名称到值的映射。 配置选项的名称通常与其相应的命令行开关相同。 每个隧道必须定义proto and addr。 其他属性是可用的,许多是协议特定的。

隧道配置属性
proto
required
all
隧道协议名称, one of http, tcp, tls
addr
required
all
将流量转发到此本地端口号或网络地址
inspect
all
启用http请求检查
auth
http
HTTP基本认证凭证,用于对隧道请求强制执行
host_header
http
将HTTP主机头重写为此值,或保留preserve以使其保持不变
bind_tls
http
绑定HTTPS或HTTP端点或同时绑定true, false, or both
subdomain
http
tls
子域名请求。如果未指定,请使用隧道名称
hostname
http
tls
请求的主机名(需要保留名称和DNS CNAME)
crt
tls
PEM TLS证书,在本地转发之前终止TLS流量
key
tls
PEM TLS私钥在此路径上在本地转发之前终止TLS流量
client_cas
tls
此路径上的PEM TLS证书颁发机构将验证传入的TLS客户端连接证书。
remote_addr
tcp
绑定给定地址上的远程TCP端口

运行多个并发隧道

你可以传递多个隧道名称到ngrok start和ngrok将同时运行它们。

从配置文件启动三个命名的隧道
ngrok start admin ssh metrics
ngrok by @inconshreveable

Tunnel Status                 online
Version                       2.0/2.0
Web Interface                 http://127.0.0.1:4040
Forwarding                    http://admin.ngrok.io -> 10.0.0.1:9001
Forwarding                    http://device-metrics.ngrok.io -> localhost:2015
Forwarding                    https://admin.ngrok.io -> 10.0.0.1:9001
Forwarding                    https://device-metrics.ngrok.io -> localhost:2015
Forwarding                    tcp://0.tcp.ngrok.io:48590 -> localhost:22
...

您还可以要求ngrok使用--all开关启动配置文件中定义的所有隧道。

启动配置文件中定义的所有隧道
ngrok start --all

相反,您可以要求ngrok运行,而不使用--none开关启动任何隧道。如果您计划通过API完全管理ngrok的隧道,这将非常有用。

运行ngrok而不启动任何隧道
ngrok start --none

示例配置文件

示例配置文件如下所示。后续部分包含这些示例中显示的所有配置参数的完整文档。.

为多个虚拟托管开发站点运行隧道
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
tunnels:
  app-foo:
    addr: 80
    proto: http
    host_header: app-foo.dev
  app-bar:
    addr: 80
    proto: http
    host_header: app-bar.dev
使用您自己的证书通过http和https隧道定制域
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
tunnels:
  myapp-http:
    addr: 80
    proto: http
    hostname: example.com
    bind_tls: false
  mypp-https:
    addr: 443
    proto: tls
    hostname: example.com
通过隧道暴露ngrok的Web检查接口和API
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
tunnels:
  myapp-http:
    addr: 4040
    proto: http
    subdomain: myapp-inspect
    auth: "user:secretpassword"
    inspect: false
具有所有选项的示例配置文件
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p
region: us
console_ui: true
compress_conn: false
http_proxy: false
inspect_db_size: 50000000
log_level: info
log_format: json
log: /var/log/ngrok.log
metadata: '{"serial": "00012xa-33rUtz9", "comment": "For customer alan@example.com"}'
root_cas: trusted
socks5_proxy: "socks5://localhost:9150"
update: true
update_channel: stable
web_addr: localhost:4040
tunnels:
 website:
   addr: 8888
   auth: bob:bobpassword
   bind_tls: true
   host_header: "myapp.dev"
   inspect: false
   proto: http
   subdomain: myapp
 
 e2etls:
   addr: 9000
   proto: tls
   hostname: myapp.example.com
   crt: example.crt
   key: example.key
 
 ssh-access:
   addr: 22
   proto: tcp
   remote_addr: 1.tcp.ngrok.io:12345

配置选项

authtoken

此选项指定用于在客户端连接到ngrok.com服务时对其进行身份验证的身份验证令牌。创建ngrok.com帐户后,信息中心将显示分配给您帐户的authtoken。

ngrok.yml指定authtoken
authtoken: 4nq9771bPxe8ctg7LKr_2ClH7Y15Zqe4bWLWF9p

console_ui

true 启用控制台UI
false 禁用控制台UI
iftty
default
仅在标准输出为TTY(不是文件或管道)时启用UI

console_ui_color

transparent 在显示控制台UI时不要设置背景颜色
black
default
将控制台UI的背景设置为黑色

http_proxy

用于建立隧道连接的HTTP代理的URL。 许多HTTP代理有连接大小和持续时间限制,将导致ngrok失败。 像许多其他网络工具,ngrok也将尊重环境变量http_proxy如果设置。

通过经过身份验证的HTTP代理的ngrok示例
http_proxy: "http://user:password@proxy.company:3128"

inspect_db_size

positive integers 大小(以字节为单位),分配给通过HTTP隧道保存请求的内存上限以供检查和重放。
0
default
使用默认分配限制,50MB
-1 禁用检查数据库;这具有禁用所有隧道的检查的有效行为

log_level

记录详细信息级别。以递增的顺序,可能的值是:crit,warn,error,info,debug


log_format

写日志记录的格式。.

logfmt 人和机器友好的键/值对
json 换行符分隔的JSON对象
term
default
自定义彩色人格式如果标准输出是TTY,否则与logfmt相同

log

将日志写入此目标位置

stdout 写到标准输出
stderr 写入标准错误
false
default
禁用日志记录
other values 将日志记录写入磁盘上的文件路径
log: /var/log/ngrok.log

metadata

不透明的用户提供的字符串,将作为ngrok.com API响应的一部分返回到此客户端启动的所有隧道的列表在线隧道资源。 这是一个有用的机制,通过您自己的设备或客户标识符来识别隧道。 最多4096个字符。 .

metadata: bad8c1c0-8fce-11e4-b4a9-0800200c9a66

region

选择ngrok客户端将连接以托管其隧道的区域。

us
default
United States
eu Europe
ap Asia/Pacific
au Australia

root_cas

用于验证与ngrok服务器的TLS连接的根证书颁发机构。

trusted
default
请仅使用ngrok.com隧道服务的受信任证书根
host 请使用主机操作系统信任的根证书。您可能希望使用此选项连接到第三方ngrok服务器。
other values 到具有要信任的证书颁发机构的磁盘上的证书PEM文件的路径

socks5_proxy

用于建立与ngrok服务器的连接的SOCKS5代理的URL。

socks5_proxy: "socks5://localhost:9150"

tunnels

名称到隧道定义的映射。有关更多详细信息请参阅隧道定义.


update

true
default
自动更新ngrok到最新版本,如果可用
false 从不更新ngrok,除非用户手动启动

update_channel

更新通道确定要更新的已发布构建的稳定性。对所有生产部署使用“稳定”。

stable
default
渠道
beta 更新为新的测试版本(如果有)

web_addr

绑定的网络地址,用于服务本地Web界面和api。

network address 绑定到此网络地址
127.0.0.1:4040
default
默认网络地址
false 禁用Web UI

ngrok客户端API

ngrok客户端公开了一个REST API,它授予对以下各项的编程访问权限:

  • 收集状态和指标信息
  • 收集和重放捕获的请求
  • 动态启动和停止隧道

基本URL和身份验证

Base URL http://127.0.0.1:4040/api
Authentication None

ngrok客户端API作为ngrok的本地Web检查接口的一部分公开。因为它在本地接口上提供,所以API没有身份验证。如果您覆盖配置文件中的web_addr,基本URL将会更改。

访问正在运行的ngrok客户端的根API资源
curl http://localhost:4040/api/

支持的内容类型

请求参数可以使用 application/x-www-form-urlencoded or application/json编码到API。确保您的客户机适当地设置请求的Content-Type头。 API返回的所有响应都是 application/json

版本控制和API稳定性

ngrok客户端API保证,除非调用者明确选择使用较新的版本,否则绝不会对API进行更改。 呼叫者选择加入API的新版本的机制将在以后当有必要时被确定。 不会选择加入的API的不间断更改示例包括以下内容。

  • 增加新的资源
  • 向现有资源添加新方法
  • 在现有资源表示上添加新字段
  • 修正错误,修改API以符合记录的行为

列出隧道

返回包含状态和指标信息的正在运行的隧道的列表。

Request
GET/api/tunnels
Response
Parameters
tunnels 所有正在运行的隧道的列表。有关每个隧道对象的参数的文档,请参阅隧道详细资源
示例响应
{
    "tunnels": [
        {
            "name": "command_line",
            "uri": "/api/tunnels/command_line",
            "public_url": "https://d95211d2.ngrok.io",
            "proto": "https",
            "config": {
                "addr": "localhost:80",
                "inspect": true,
            },
            "metrics": {
                "conns": {
                    "count": 0,
                    "gauge": 0,
                    "rate1": 0,
                    "rate5": 0,
                    "rate15": 0,
                    "p50": 0,
                    "p90": 0,
                    "p95": 0,
                    "p99": 0
                },
                "http": {
                    "count": 0,
                    "rate1": 0,
                    "rate5": 0,
                    "rate15": 0,
                    "p50": 0,
                    "p90": 0,
                    "p95": 0,
                    "p99": 0
                }
            }
        },
        ...
    ],
    "uri": "/api/tunnels"
}

启动隧道

动态地在ngrok客户端上启动一个新的隧道。请求主体参数与在配置文件中用于定义隧道的参数相同。

Request
POST/api/tunnels
Parameters

参数名称和行为与配置文件中定义的参数名称和行为相同。使用 隧道定义部分作为配置参数及其行为的参考。

请求正文示例
{
    "addr": "22",
    "proto": "tcp",
    "name": "ssh"
}
Response

2201状态码与响应主体描述启动的隧道。请参阅关于响应对象的参数的文档的 Tunnel 详细信息资源

示例响应
{
    "name": "",
    "uri": "/api/tunnels/",
    "public_url": "tcp://0.tcp.ngrok.io:53476",
    "proto": "tcp",
    "config": {
        "addr": "localhost:22",
        "inspect": false,
    },
    "metrics": {
        "conns": {
            "count": 0,
            "gauge": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        },
        "http": {
            "count": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        }
    }
}

隧道细节

获取命名运行隧道的状态和指标

Request
GET/api/tunnels/:name
Response
示例响应
{
    "name": "command_line",
    "uri": "/api/tunnels/command_line",
    "public_url": "https://ac294125.ngrok.io",
    "proto": "https",
    "config": {
        "addr": "localhost:80",
        "inspect": true,
    },
    "metrics": {
        "conns": {
            "count": 0,
            "gauge": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        },
        "http": {
            "count": 0,
            "rate1": 0,
            "rate5": 0,
            "rate15": 0,
            "p50": 0,
            "p90": 0,
            "p95": 0,
            "p99": 0
        }
    }
}

停止隧道

停止正在运行的隧道

Request
DELETE/api/tunnels/:name
Response

204状态代码与空主体

列出捕获的请求

返回捕获用于检查的所有HTTP请求的列表。这将只返回仍在内存中的请求(ngrok在内存使用超过inspect_db_size时清除捕获的请求))

Request
GET/api/requests/http
Query Parameters
limit 要返回的最大请求数
tunnel_name 过滤器仅请求给定的隧道名称
Example Request
curl http://localhost:4040/api/requests/http?limit=50
Response
requests 捕获的请求列表。请参阅请求对象上文档的捕获的请求详细资源资源
示例响应
{
    "uri": "/api/requests/http",
    "requests": [
        {
            "uri": "/api/requests/http/548fb5c700000002",
            "id": "548fb5c700000002",
            "tunnel_name": "command_line (http)",
            "remote_addr": "192.168.100.25",
            "start": "2014-12-15T20:32:07-08:00",
            "duration": 3893202,
            "request": {
                "method": "GET",
                "proto": "HTTP/1.1",
                "headers": {
                    "Accept": [
                        "*/*"
                    ],
                    "Accept-Encoding": [
                        "gzip, deflate, sdch"
                    ],
                    "Accept-Language": [
                        "en-US,en;q=0.8"
                    ],
                    "Connection": [
                        "keep-alive"
                    ],
                    "User-Agent": [
                        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36"
                    ],
                    "X-Original-Host": [
                        "c159663f.ngrok.io"
                    ]
                },
                "uri": "/favicon.ico",
                "raw": ""
            },
            "response": {
                "status": "502 Bad Gateway",
                "status_code": 502,
                "proto": "HTTP/1.1",
                "headers": {
                    "Content-Length": [
                        "1716"
                    ]
                },
                "raw": "",
            }
        },
        ...
    ]
}

重播捕获的请求

针对隧道的本地端点重复请求

Request
POST/api/requests/http
Parameters
id 重放请求的ID
tunnel_name 要播放请求的隧道的名称。如果未指定,请求将针对其记录的相同隧道播放
请求示例
curl -d "id=548fb5c700000002" http://localhost:4040/api/requests/http
Response

204状态代码与空主体

删除捕获的请求

删除所有捕获的请求

Request
DELETE/api/requests/http
Response

204 status code with no response body

捕获的请求详细信息

返回捕获的请求的元数据和原始字节。原始数据在JSON响应中是base64编码的。如果本地服务器尚未响应请求,响应response值可以为null

Request
GET/api/requests/http/:request_id
Response
示例响应
{
    "uri": "/api/requests/http/548fb5c700000002",
    "id": "548fb5c700000002",
    "tunnel_name": "command_line (http)",
    "remote_addr": "192.168.100.25",
    "start": "2014-12-15T20:32:07-08:00",
    "duration": 3893202,
    "request": {
        "method": "GET",
        "proto": "HTTP/1.1",
        "headers": {
            "Accept": [
                "*/*"
            ],
            "Accept-Encoding": [
                "gzip, deflate, sdch"
            ],
            "Accept-Language": [
                "en-US,en;q=0.8"
            ],
            "Connection": [
                "keep-alive"
            ],
            "User-Agent": [
                "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.71 Safari/537.36"
            ],
            "X-Original-Host": [
                "c159663f.ngrok.io"
            ]
        },
        "uri": "/favicon.ico",
        "raw": ""
    },
    "response": {
        "status": "502 Bad Gateway",
        "status_code": 502,
        "proto": "HTTP/1.1",
        "headers": {
            "Content-Length": [
                "1716"
            ]
        },
        "raw": "",
    }
}

向后兼容性

ngrok承诺有关其接口的兼容性和稳定性,以便您可以自信地构建集成顶部,知道在升级到较新版本时期望的更改。

兼容性承诺

  • Point Release (2.0.0 -> 2.0.1) - ngrok承诺在点发布之间没有突破性的变化
  • Minor Version Change (2.0 -> 2.1) - ngrok可能会进行小的更改,打破兼容性的次要版本更改。 ngrok承诺,任何破坏性更改将由一个版本前面,该版本警告将要更改或弃用的行为。
  • Major Version Change (2.0 -> 3.0) - nngrok不承诺任何接口在主要版本更改中是稳定的。

什么接口是受约束的?

  • ngrok命令行界面:命令及其选项
  • ngrok配置文件
  • ngrok客户端API

任何其他界面,如日志格式或Web UI不受任何兼容性承诺,并可能会更改,而不会在版本之间的警告。

2.1中的更改

对配置文件中定义的http and tls隧道的行为更改,或通过没有subdomain or hostname属性的API启动。

tunnels:
  webapp:
    proto: http
    addr: 80

给定此示例隧道配置,行为将以以下方式改变。

老行为

使用隧道的名称作为子域启动隧道,生成URL http://webapp.ngrok.io

新行为

启动具有随机子域的隧道,例如像http://d95211d2.ngrok.io这样的URL

如何保持旧的行为

添加与隧道名称相同的子域subdomain属性:

tunnels:
  webapp:
    proto: http
    addr: 80
    subdomain: webapp

此行为已更改,以便可以启动随机域的隧道。这阻止了使用配置文件和客户端API释放层用户。.

从ngrok 1.0升级

从用户的角度来看,ngrok 2.0的工作方式几乎与ngrok 1.0完全相同。 话虽如此,对于使ngrok一致,更简单和更灵活的目的已经进行了一些重要的改变。 以下部分详细介绍了在升级时需要注意的最重要的区别。

命令行语法

ngrok 2.0不再假定您希望默认创建一个http隧道。相反,您必须显式地命名要创建的隧道的协议。最常见的是,这是一个http隧道。

OLD
ngrok -subdomain=myapp 80
NEW
ngrok http -subdomain=myapp 80
OLD
ngrok -proto=tcp 22
NEW
ngrok tcp 22

此更改使语法一致:ngrok [protocol] [target port]。 它允许每个隧道协议具有特定于它的选项以及其自己的帮助文本。 例如,如果您尝试使用TCP隧道,指定http基本身份验证现在感觉更自然和错误:

OLD
ngrok -httpauth "user:pw" 8080
NEW
ngrok http -auth "user:pw" 8080
OLD, -httpauth ignored
ngrok -proto=tcp -httpauth "user:pw" 22
NEW, error: no 'auth' option defined for TCP tunnels
ngrok tcp -auth "user:pw" 22

配置文件

ngrok配置文件看到了最大的变化。这里只突出最重要的区别。

ngrok配置文件的默认位置已更改。这是为了帮助您并行运行ngrok 1.0和ngrok 2.0。

OLD location
~/.ngrok
NEW location
~/.ngrok2/ngrok.yml

配置文件中authtoken键的拼写已更改为与命令行选项一致:

OLD config
auth_token: abc123
NEW config
authtoken: abc123

配置文件中的隧道定义已更改,使配置结构更简单,嵌套更少。 密钥proto现在采用协议名称而不是映射,并且引入新密钥 addr以指定隧道的本地目标端口/地址。

OLD config
tunnels:
  webapp:
    proto:
      http: 8080
    auth: "user:pw"
  ssh:
    proto:
      tcp: 22
NEW config
tunnels:
  webapp:
    proto: http
    addr: 8080
    subdomain: webapp
    auth: "user:pw"
  ssh:
    proto: tcp
    addr: 22

Authtoken

在配置文件中指定的authtoken与用于ngrok 1.0的authtoken不同。您的2.0 ngrok authtoken可在您的ngrok 2.0仪表板上

Base Domain

出于安全原因,所有ngrok 2.0隧道现在都托管在ngrok.io 域。您不能使用1.0中保留的 ngrok.com域作为2.0隧道。您需要在ngrok 2.0的仪表板上保留等效的域名

自定义域的CNAME记录

当切换到ngrok 2.0时,您需要更改您的DNS CNAME记录以指向不同的目标。 自定义域中的隧道的CNAME记录不再都指向ngrok.com。 而是为每个自定义域分配其CNAME记录的目标地址。 当您希望开始在ngrok 2.0上使用自定义域时,您需要更新DNS记录。 有关详细信息,请参阅自定义域的文档.

同时使用

在升级过程中同时使用ngrok 1.0和ngrok 2.0非常容易。有三个常见的陷阱需要注意:

  • 当同时运行两个客户端时,有时可能遇到一个无法启动的问题,因为它不能绑定端口4040.两个版本的ngrok使用此端口的Web界面。 尝试将ngrok 2.0配置文件中的web_addr设置为不同的值(例如127.0.0.1:4041),以避免冲突。
  • 由于自定义域必须具有指向不同目标的CNAME记录,因此您一次只能在单个版本的ngrok上使用自定义域。
  • 当你调用ngrok没有一个明确的路径,你的操作系统将选择无论哪个版本恰好在你的PATH中找到。这可能不是您打算使用的版本。