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

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

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

HTTP请求和响应的详细内容

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

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

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

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

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

安装你的认证token

cpolar authtoken <YOUR_AUTHTOKEN>

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

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

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

cpolar http -httpauth="username:password" 8080

增加http重定向功能，使http地址跳转至https同域名地址，客户端命令行增加参数-redirect-https=true，如果需要在配置文件中配置加参数redirect_https: true
例如：

cpolar http -redirect-https=true -region=cn 8080

cpolar假定要转发到的服务器正在侦听未加密的HTTP流量，但是如果您的服务器正在侦听加密的HTTPS流量怎么办？ 您可以使用https://协议指定URL，以请求cpolar对本地服务器使用HTTPS。

通过指定https://协议转发到https服务器

cpolar http https://localhost:8443

您可以在自己的域名上运行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隧道。

当使用自己的自定义域名时，您可能无法访问公开的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

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

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

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

cpolar tcp 1234

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

cpolar tcp 22

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

cpolar tcp 5432

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

cpolar tcp 25565

由于FTP协议是个多端口协议，它需要侦听本地TCP 21端口和一个数据传输端口段（1024-65535），所以通常难以穿透。以下为cpolar给出的解决方案：

cpolar ftp 21

如图：系统共返回4个隧道，一个ftp信令隧道和三个数据隧道.
ftp信令隧道：ftp://开头地址
ftp数据隧道：data://开头地址

ftp信令隧道，用于连接FTP服务器的信令端口TCP 21.
ftp数据隧道，用于链接FTP服务器的数据端口段。（全例为:25057-25059)

2）配置你的FTP服务器，将FTP服务器配置成被动模式

2.1 数据端口段：配置成与cpolar提供的一致(25057-25059)，
2.2 User the following IP: 填写1.tcp.cpolar.io的公网IP地址.
本例的IP地址为34.92.101.174
2.3 去掉最下面勾选项。（本地客户端访问仍使用公网IP，因为cpolar客户端是从本地访问）

注:如果使用中国区，会获取1.tcp.cpolar.cn的公网地址，当前的公网IP为：132.232.121.150

3）使用FTP客户端，连接FTP服务器。

4） 链接成功。

HTTPS隧道使用cpolar.com证书限制cpolar.com服务器上的所有TLS（SSL）通信。 对于生产级服务，您需要使用自己的TLS密钥和证书对隧道通信进行加密。 cpolar使用TLS隧道使此操作异常简单。

将TLS流量转发到端口443上的本地HTTPS服务器

cpolar tls -subdomain=encrypted 443

隧道运行后，尝试使用curl进行访问。

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

您尝试公开的服务可能无法限制TLS连接。 cpolar客户端可以为您执行此操作，以便您可以端对端加密通信，而不必担心本地服务是否支持TLS。 同时指定-crt和-key命令行选项，以指定TLS证书和密钥的文件系统路径，然后cpolar客户端将为您限制TLS连接。

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

cpolar TLS隧道不对正在传输的基础协议进行任何假设。 本文档中的所有示例都使用HTTPS，因为它是最常见的用例，但是您可以在TLS隧道上运行任何TLS封装的协议（例如imaps，smtps，sip等），而无需进行任何更改。

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

如果要使证书匹配并免受中间人攻击，则需要两件事。首先，您需要为拥有的域名购买SSL（TLS）证书，并将本地Web服务器配置为使用该证书及其私钥来终止TLS连接。如何执行此操作仅针对您的Web服务器和SSL证书提供者，不在本文档的讨论范围之内。为了举例说明，我们假设为您颁发了域secure.example.com的SSL证书。

获得密钥和证书并正确安装它们之后，现在该在您自己的自定义域名上运行TLS隧道了。设置的说明与HTTP隧道部分中描述的相同：“自定义域上的隧道”。您注册的自定义域应与SSL证书（secure.example.com）中的域相同。设置自定义域后，使用-hostname参数在您自己的域上启动TLS隧道。

通过您自己的自定义域转发TLS流量

cpolar tls -region=us -hostname=secure.example.com 443

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

Microsoft Internet Explorer 6.0
Microsoft Internet Explorer 7 & 8 on Windows XP or earlier
Native browser on Android 2.X
Java <=1.6
Python 2.X, 3.0, 3.1 if required modules are not installed
可以在Wikipedia上的Server Name Indiciation页面上找到更完整的列表。

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

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

cpolar http -hostname=*.example.com 80

使用通配符域会在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

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

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

cpolar http 192.168.1.1:8080

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

• us – 美国（俄亥俄州）
• cn – 中国（北京）
• cn_vip – 中国 VIP China
• cn_top – 中国 Top China 支持微信公众号、微信小程序（基础套餐及以上支持)
• hk – 中国（香港）
• eu – 欧洲（法兰克福） (即将开放)
• ap – 亚太地区（新加坡） （即将开放）
• au – 澳大利亚（悉尼） （即将开放）

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

cpolar http -region=cn 8080

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

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

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

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

有时，您可能希望将整个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”

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

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

明确指定配置文件位置

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

如果没有为配置文件指定位置，则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

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

socks5_proxy

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

经过身份验证的socks5代理的cpolar示例

socks5_proxy: socks5://user:password@proxy.company:1080

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

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

隧道定义为配置文件中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	http tls	此路径上的PEM TLS证书可在本地转发之前终止TLS流量
key	http tls	PEM TLS此路径上的私钥，用于在本地转发之前加密认证TLS数据流
client_cas	http tls	此路径上的PEM TLS证书颁发机构将验证传入的TLS客户端连接证书。
remote_addr	tcp tls ftp	保留的公网TCP地址及端口号
redirect_https	http	为true 将Web站点http请求重定向至https协议同域名站点

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

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

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

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

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

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

• https://github.com/optimizamx/odt-relative-urls
• http://wordpress.org/plugins/relative-url/
• http://wordpress.org/plugins/root-relative-urls/

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

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

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

cpolar http -host-header=myapp.dev 80

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

• Set the configuration variable http_proxy
• Set the configuration varible socks5_proxy

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

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

拼读：si-polar

• see：看见， polar：极点
• 望穿-极点