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.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.IP白名单隧道访问

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

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

5.1.管理白名单

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

5.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”

6.cpolar配置文件

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

6.1.指定配置文件路径

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

明确指定配置文件位置

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

6.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

6.3.隧道定义

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

隧道定义为配置文件中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
将流量转发到该本地端口号或网络地址
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地址

6.4.示例配置文件

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

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

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

6.5.同时运行多个隧道

您可以将多个隧道名称传递给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

6.6.配置选项

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
美国
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.使用 cpolar …

7.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']);

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

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

cpolar http -host-header=myapp.dev 80

7.3.出站代理

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

8.故障排除

8.1.CORS与HTTP基本身份验证

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

9.常见问题

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

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

9.2.我怎么发音cpolar?

拼读:si-polar

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