文档 - cpolar 安全的内网穿透工具

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请求和响应的详细内容

1.3.重放请求 #

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

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

1.4.请求消息体检查 #

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

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

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映射。

定义两个名为httpdev和demo的隧道

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

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

等。

`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）
`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_addr: 1.tcp.cpolar.io:20031

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：极点
望穿-极点