1.入门指南 #

1.1.将本地Web服务器公开到Internet #

cpolar允许您将本地计算机上运行的Web服务器公开到Internet。告诉cpolar您的Web服务器正在侦听哪个端口。

如果您不知道Web服务器正在侦听哪个端口,则可能是80端口,即HTTP的默认端口。

示例:将本地计算机的端口80上的Web服务器公开到Internet

cpolar http 80

启动cpolar时,它将在终端中显示一个UI,其中包含隧道的公共URL以及有关通过隧道建立的连接的其他状态和度量信息。

cpolar控制台用户界面


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

1.2.监听您的消息包流量 #

cpolar客户端提供实时Web UI管理界面,您可以在其中查看隧道上运行的所有HTTP流量。启动cpolar客户端后,只需在Web浏览器中打开http://localhost:4040 即可检查请求详细信息。

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

HTTP请求和响应的详细内容
cpolar-inspector

1.3.重放请求 #

开发外部API发布的Web API通常会要求您做一些工作(如微信公网众号用户发送消息)来触发回调请求,从而减慢开发周期。 cpolar允许您通过单击重放任何Http请求,这样大大加快了开发调试周期。点击网络检查用户界面上任意请求右上角的重放(Replay)按钮进行重放。

只需点击一下即可重放任何针对隧道网络服务器的请求
cplar replay

1.4.请求消息体检查 #

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

突出显示JSON语法错误的位置
cpolar 支持HTTP消息体语法检查

1.5.配置token认证令牌 #

cpolar服务的许多高级功能,需要与您注册的帐户关联才能使用。一旦您注册成功,您需要在后台仪表板上显示的authtoken参数配置cpolar客户端。它将授予您访问自己帐户的功能权限。 cpolar客户端有一个简单的’authtoken’命令,它使用起来很简单。

安装你的认证token
cpolar authtoken <YOUR_AUTHTOKEN>

2.HTTP 隧道 #

2.1.自定义子域名 #

cpolar将分配一个随机子域名给您的HTTP隧道,这对于一次性个人用途是可以的。
然而,如果你在黑客马拉松上显示网址或者与第三方Web API集成时,如果隧道名称是随机的,可能会令人沮丧或难以阅读。这时,您可以使用自定义域名功能,为隧道URL指定一个有容易记忆的子域名。它可以在命令行下使用-subdomain参数开关启动。

示例:打开包含子域名为’myapp’的隧道.

cpolar http -subdomain=myapp 80

 
 

显示结果

cpolar by @bestExpresser

...
Forwarding                    http://myapp.cpolar.io -> 127.0.0.1:80
Forwarding                    https://myapp.cpolar.io -> 127.0.0.1:80

2.2.用密码保护你的隧道 #

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

示例:用密码保护您的隧道

cpolar http -httpauth="username:password" 8080

2.3.自定义域名上的隧道(白色标签URL) #

您可以在自己的域名上运行cpolar隧道,而不是将您的隧道显示为cpolar.io的子域名。 例如:要在dev.example.com域名上建立隧道,请按照下列步骤操作:

1.在cpolar.com用户管理后台仪表板的“保留”选项卡上输入dev.example.com作为保留域名。 这保证了没有其他人可以使用自己的隧道劫持您的域名。
2.在仪表板上,单击“CNAME”图标以复制CNAME目标。
3.从dev.example.com到您的CNAME目标创建DNS CNAME记录。 在此示例中,我们将CNAME记录指向2w9c34maz.cname.cpolar.io
4.使用-hostname开关调用cpolar,并将自定义域的名称指定为参数。

示例:在自定义域名上运行隧道

cpolar http -hostname=dev.example.com 8000

通过HTTPS访问自定义域隧道仍然有效,但证书不匹配。 如果您有TLS证书/密钥对,请尝试使用TLS隧道。

2.4.自定义域名使用自有HTTPS证书 #

当使用自己的自定义域名时,您可能无法访问公开的https服务,因为HTTPS证书不同。 cpolar客户端可以轻松为您完成此操作,使您可以端到端加密通迅,而不必担心本地服务是否具有HTTPS支持。 您只需要在命令行中指定-crt-key两个参数,以指定TLS证书和密钥的文件系统路径,cpolar客户端将负责为您握手TLS连接。

使用cpolar客户端启动自定义域名的HTTPS连接。

cpolar http -hostname=secure.example.com -key=/path/to/tls.key -crt=/path/to/tls.crt 80

2.5.Websockets #

Websocket端点通过cpolar的http隧道工作,无需任何更改。 但是,目前还没有支持监听初始化连接时,返回临时状态码101时的交换消息。

3.TCP 隧道 #

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

例如:公开一个在端口1234上运行的基于TCP的服务

cpolar tcp 1234

3.1.举例 #

公开在默认端口上侦听的SSH服务器

cpolar tcp 22

公开Postgres服务器监听默认端口

cpolar tcp 5432

暴露Minecraft服务器侦听默认端口

cpolar tcp 25565

4.高级的隧道选项 #

4.1.泛域名 #

cpolar允许您将HTTP和TLS隧道绑定到通配符域名(泛域名)。 所有通配符域(泛域名),甚至是cpolar.io子域的通配符必须首先保留在仪表板上的帐户中。 使用-hostname-subdomain时,请指定前导*星号以绑定通配符域。

绑定隧道以接收** example.com`的所有子域的流量**

cpolar http -hostname=*.example.com 80

4.2.泛域名规则 #

使用通配符域会在cpolar.com服务的某些方面产生歧义。 以下规则用于解决这些情况,对于了解您是否使用通配符域非常重要。

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

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

4.3.转发到不同计算机上的服务器(非本地服务) #

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

示例:转发到其他计算机上的Web服务器

cpolar http 192.168.1.1:8080

5.全球基础设施 #

5.1.地理位置 #

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

  • us – 美国(俄亥俄州)
  • cn – 中国(北京)
  • hk – 中国(香港) (即将开放)
  • eu – 欧洲(法兰克福) (即将开放)
  • ap – 亚太地区(新加坡) (即将开放)
  • au – 澳大利亚(悉尼) (即将开放)

5.2.使用方法 #

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

cpolar http -region=cn 8080

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

6.IP白名单隧道访问 #

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

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

6.1.管理白名单 #

您可以在cpolar仪表板的验证选项卡上管理IP白名单。 在“IP白名单”部分下输入新的IP地址,然后单击添加白名单条目。 对IP白名单的更改最多可能需要30秒才能生效。

6.2.IP范围 #

有时,您可能希望将整个IP范围列入白名单。 您可以使用[[1] CIDR_notation] [CIDR_notation]指定IP地址块,而不是仅输入单个IP地址。 例如,要允许从10.1.2.0到10.1.2.255的所有IP地址,您需要将10.1.2.0/24添加到白名单。
[CIDR_notation]:https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing#CIDR_notation“CIDR_notation”

7.cpolar配置文件 #

有时您的cpolar配置太复杂,无法在命令行选项中表达。 cpolar支持一个可选的,非常简单的YAML配置文件,它为您提供同时运行多个隧道的功能,以及调整一些cpolar更神秘的设置。

7.1.指定配置文件路径 #

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

明确指定配置文件位置

cpolar http -config=/opt/cpolar/conf/cpolar.yml 8000

7.2.默认配置文件路径 #

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

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

操作系统 默认配置文件路径
OS X /Users/john/.cpolar/cpolar.yml
Linux /home/john/.cpolar/cpolar.yml
Windows C:\Users\john\.cpolar\cpolar.yml

7.3.配置选项 #

authtoken

此选项指定用于在连接到cpolar服务时对此客户端进行身份验证的身份验证令牌。 创建cpolar帐户后,您的后台管理界面将显示分配给您帐户的authtoken。

cpolar.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代理具有连接大小和持续时间限制,这将导致cpolar失败。 像许多其他网络工具一样,如果设置了cpolar,它也会尊重环境变量http_proxy

经过身份验证的HTTP代理上的cpolar示例
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
禁用日志输出
其它值 将日志记录写入磁盘上的文件路径
log: /var/log/cpolar.log

metadata

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

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

region

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

us
default
美国
cn 中国
hk 香港
eu 欧洲
ap 亚太
au 澳大利亚

root_cas

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

trusted
default
仅使用cpolar.com隧道服务的可信证书根目录
host 使用主机操作系统信任的根证书。 您可能希望使用此选项连接到第三方cpolar服务器。
其它值 指定路径的颁发机构要信任的磁盘上的证书PEM文件

socks5_proxy

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

socks5_proxy: "socks5://localhost:9150"

tunnels

隧道定义的名称映射。有关详细信息,请参阅隧道定义

update

true 如果可用,自动将cpolar更新为最新版本
false
default
除非用户手动启动,否则永远不要更新cpolar

update_channel

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

stable
默认
在可用时更新到稳定版本
beta 在可用时更新到新的beta版本

web_addr

要绑定的网络地址,用于提供本地Web界面和api。

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

7.4.隧道定义 #

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

隧道定义为配置文件中tunnels属性下的name – > configuration映射。

定义两个名为httpdevdemo的隧道

tunnels:
  httpdev:
    proto: http
    addr: 8000
    subdomain: alan
  demo:
    proto: http
    addr: 9090
    hostname: demo.bestexpresser.com
    inspect: false
    auth: "demo:secret"

启动名为httpdev的隧道

cpolar start httpdev

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

等。

proto
required
all
隧道协议名称, http, tcp可选。
addr
required
all
将流量转发到该本地端口号或网络地址
region
all
全球地理区域,默认 us 美国区域,可选 cn 中国区域
inspect
all
启用监听HTTP请求
auth
http
HTTP基本身份验证凭据以强制执行隧道请求
host_header
http
将HTTP Host标头重写为此值,或保留以保持不变
bind_tls
http
bind an HTTPS or HTTP endpoint or both true, false, or both
subdomain
http
tls
要请求的子域名。 如果未指定,则使用隧道名称
hostname
http
tls
要求的主机名(需要保留名称和DNS CNAME)
remote_port
tcp
tls
远程需要保留的TCP端口号
crt
tls
此路径上的PEM TLS证书可在本地转发之前终止TLS流量
key
tls
PEM TLS此路径上的私钥,用于在本地转发之前终止TLS流量
client_cas
tls
此路径上的PEM TLS证书颁发机构将验证传入的TLS客户端连接证书。
remote_addr
tcp
绑定给定地址上的远程TCP地址

7.5.示例配置文件 #

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

为多个虚拟托管开发站点运行隧道

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: tcp
    hostname: example.com

通过隧道暴露cpolar的Web监查界面

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
http_proxy: false
inspect_db_size: 50000000
log_level: info
log_format: json
log: /var/log/cpolar.log
metadata: '{"serial": "00012xa-33rUtz9", "comment": "For customer alan@example.com"}'
root_cas: trusted
socks5_proxy: "socks5://localhost:9150"
update: false
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: tcp
    hostname: myapp.example.com
    crt: example.crt
    key: example.key

  ssh-access:
    addr: 22
    proto: tcp
    remote_port: 12345

7.6.同时运行多个隧道 #

您可以将多个隧道名称传递给cpolar start,而cpolar将同时运行它们。

从配置文件中启动三个命名隧道

cpolar start admin ssh metrics

cpolar by @bestexpresser

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

您还可以要求cpolar使用start-all子命令启动配置文件中定义的所有隧道。

启动配置文件中定义的所有隧道

cpolar start-all

8.使用 cpolar … #

8.1.Wordpress #

要使用Wordpress安装正常工作,通常需要做两件事:

1.您必须确保Wordpress发布相对URL。 您可以通过安装以下插件之一来完成此操作

2.您必须确保Wordpress了解它是为了通过隧道主机名提供服务。 您可以通过修改wp-config来配置Wordpress以包含以下行:

define('WP_SITEURL', 'http://' . $_SERVER['HTTP_HOST']);
define('WP_HOME', 'http://' . $_SERVER['HTTP_HOST']);

8.2.虚拟主机 (pow, MAMP, WAMP, and others) #

流行的Web服务器(如MAMP和WAMP)依赖于一种通常被称为“虚拟主机”的技术,这意味着它们会查询HTTP请求的“主机”标头,以确定它们应该为多个站点服务。 要公开这样的网站,可以要求cpolar重写所有隧道请求的主机头,以匹配您的Web服务器所期望的。 您可以使用-host-header选项(请参阅:重写主机标头)来选择要定位的虚拟主机。 例如,要路由到本地站点myapp.dev,您将运行:

cpolar http -host-header=myapp.dev 80

8.3.出站代理 #

cpolar通过HTTP或SOCKS5代理正常工作。 cpolar尊重标准的unix环境变量http_proxy。 您还可以在cpolar配置文件中显式设置代理配置:

9.故障排除 #

9.1.CORS与HTTP基本身份验证 #

是的,但你不能使用cpolar的-httpauth选项。 cpolar的http隧道允许您指定基本身份验证凭据以保护您的隧道。 但是,cpolar对所有请求强制执行此策略,包括CORS规范要求的预检“OPTIONS”请求。 在这种情况下,您的应用程序必须实现自己的基本身份验证 有关更多详细信息,请参阅this github issue

10.常见问题 #

10.1.我的隧道存储了哪些信息? #

cpolar不会记录或存储通过隧道连接传输的任何数据。 cpolar会记录有关用于调试目的的连接的一些信息,以及隧道名称和连接持续时间等指标。 要获得完整的端到端安全性,请使用TLS隧道

10.2.我怎么发音cpolar? #

拼读:si-polar

  • see:看见, polar:极点
  • 望穿-极点
关闭菜单