frp/README_zh.md

1031 lines
32 KiB
Markdown
Raw Normal View History

2016-04-06 11:43:50 +08:00
# frp
2017-05-19 02:59:51 +08:00
[![Build Status](https://travis-ci.org/fatedier/frp.svg?branch=master)](https://travis-ci.org/fatedier/frp)
2016-04-06 11:43:50 +08:00
[README](README.md) | [中文文档](README_zh.md)
2019-01-15 11:27:53 +08:00
frp 是一个可用于内网穿透的高性能的反向代理应用,支持 tcp, udp 协议,为 http 和 https 应用协议提供了额外的能力,且尝试性支持了点对点穿透。
2016-07-07 18:07:45 +08:00
## 目录
2016-12-21 01:18:12 +08:00
<!-- vim-markdown-toc GFM -->
2017-12-05 01:34:33 +08:00
2016-07-07 18:07:45 +08:00
* [开发状态](#开发状态)
* [架构](#架构)
* [使用示例](#使用示例)
2016-12-21 01:18:12 +08:00
* [通过 ssh 访问公司内网机器](#通过-ssh-访问公司内网机器)
* [通过自定义域名访问部署于内网的 web 服务](#通过自定义域名访问部署于内网的-web-服务)
* [转发 DNS 查询请求](#转发-dns-查询请求)
2019-07-31 00:41:43 +08:00
* [转发 Unix 域套接字](#转发-unix-域套接字)
2018-01-24 23:27:03 +08:00
* [对外提供简单的文件访问服务](#对外提供简单的文件访问服务)
2019-04-10 13:39:26 +08:00
* [为本地 HTTP 服务启用 HTTPS](#为本地-http-服务启用-https)
2017-07-17 00:57:10 +08:00
* [安全地暴露内网服务](#安全地暴露内网服务)
2017-12-05 01:34:33 +08:00
* [点对点内网穿透](#点对点内网穿透)
2016-07-07 18:07:45 +08:00
* [功能说明](#功能说明)
2017-07-17 00:57:10 +08:00
* [配置文件](#配置文件)
2018-12-11 11:56:00 +08:00
* [配置文件模版渲染](#配置文件模版渲染)
2016-12-21 01:18:12 +08:00
* [Dashboard](#dashboard)
2019-03-11 16:24:54 +08:00
* [Admin UI](#admin-ui)
2020-03-11 14:13:16 +08:00
* [监控](#监控)
* [Prometheus](#prometheus)
* [客户端身份验证](#客户端身份验证)
* [Token](#token)
* [OIDC](#oidc)
2016-12-21 01:18:12 +08:00
* [加密与压缩](#加密与压缩)
2019-03-11 16:24:54 +08:00
* [TLS](#tls)
2017-07-17 00:57:10 +08:00
* [客户端热加载配置文件](#客户端热加载配置文件)
2018-01-18 16:43:03 +08:00
* [客户端查看代理状态](#客户端查看代理状态)
2018-04-24 01:26:05 +08:00
* [端口白名单](#端口白名单)
2018-05-07 16:46:04 +08:00
* [端口复用](#端口复用)
2019-11-26 10:23:37 +08:00
* [限速](#限速)
* [代理限速](#代理限速)
2017-05-18 01:51:32 +08:00
* [TCP 多路复用](#tcp-多路复用)
2017-07-17 00:57:10 +08:00
* [底层通信可选 kcp 协议](#底层通信可选-kcp-协议)
2016-12-21 01:18:12 +08:00
* [连接池](#连接池)
2018-05-25 01:25:36 +08:00
* [负载均衡](#负载均衡)
2019-01-15 11:27:53 +08:00
* [健康检查](#健康检查)
2016-12-21 01:18:12 +08:00
* [修改 Host Header](#修改-host-header)
2018-05-25 01:25:36 +08:00
* [设置 HTTP 请求的 header](#设置-http-请求的-header)
2017-07-17 00:57:10 +08:00
* [获取用户真实 IP](#获取用户真实-ip)
2019-04-10 13:39:26 +08:00
* [HTTP X-Forwarded-For](#http-x-forwarded-for)
* [Proxy Protocol](#proxy-protocol)
2016-12-21 01:18:12 +08:00
* [通过密码保护你的 web 服务](#通过密码保护你的-web-服务)
* [自定义二级域名](#自定义二级域名)
2016-12-28 00:26:50 +08:00
* [URL 路由](#url-路由)
2020-03-11 14:13:16 +08:00
* [TCP 端口复用类型](#tcp-端口复用类型)
2017-05-18 01:51:32 +08:00
* [通过代理连接 frps](#通过代理连接-frps)
2018-01-29 23:05:17 +08:00
* [范围端口映射](#范围端口映射)
2020-01-03 11:35:12 +08:00
* [客户端插件](#客户端插件)
* [服务端管理插件](#服务端管理插件)
2016-07-07 18:07:45 +08:00
* [开发计划](#开发计划)
2016-08-21 00:52:15 +08:00
* [为 frp 做贡献](#为-frp-做贡献)
2016-08-24 13:36:38 +08:00
* [捐助](#捐助)
2019-03-11 16:24:54 +08:00
* [知识星球](#知识星球)
2016-12-21 01:18:12 +08:00
* [支付宝扫码捐赠](#支付宝扫码捐赠)
2017-06-12 01:31:33 +08:00
* [微信支付捐赠](#微信支付捐赠)
2016-12-21 01:18:12 +08:00
* [Paypal 捐赠](#paypal-捐赠)
2016-04-19 18:53:48 +08:00
2016-12-21 01:18:12 +08:00
<!-- vim-markdown-toc -->
2016-04-06 11:43:50 +08:00
## 开发状态
2019-01-15 11:27:53 +08:00
frp 仍然处于开发阶段,未经充分测试与验证,不推荐用于生产环境。
2016-04-06 11:43:50 +08:00
2017-05-18 01:51:32 +08:00
master 分支用于发布稳定版本dev 分支用于开发,您可以尝试下载最新的 release 版本进行测试。
**目前的交互协议可能随时改变,不保证向后兼容,升级新版本时需要注意公告说明同时升级服务端和客户端。**
2016-04-06 11:43:50 +08:00
2016-07-07 18:07:45 +08:00
## 架构
2016-04-06 11:43:50 +08:00
2016-07-07 18:07:45 +08:00
![architecture](/doc/pic/architecture.png)
2016-04-06 11:43:50 +08:00
2016-07-07 18:07:45 +08:00
## 使用示例
2016-04-06 11:43:50 +08:00
2016-07-07 18:07:45 +08:00
根据对应的操作系统及架构,从 [Release](https://github.com/fatedier/frp/releases) 页面下载最新版本的程序。
2016-04-06 11:43:50 +08:00
2017-05-18 01:51:32 +08:00
**frps****frps.ini** 放到具有公网 IP 的机器上。
2016-04-06 11:43:50 +08:00
2016-07-07 18:07:45 +08:00
**frpc****frpc.ini** 放到处于内网环境的机器上。
### 通过 ssh 访问公司内网机器
1. 修改 frps.ini 文件,这里使用了最简化的配置,设置了 frp 服务器端接收客户端流量的端口:
2016-07-07 18:07:45 +08:00
```ini
# frps.ini
[common]
bind_port = 7000
```
2. 启动 frps
`./frps -c ./frps.ini`
3. 修改 frpc.ini 文件,假设 frps 所在服务器的公网 IP 为 x.x.x.x
2016-07-07 18:07:45 +08:00
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[ssh]
2017-05-18 19:08:43 +08:00
type = tcp
2016-12-21 01:18:12 +08:00
local_ip = 127.0.0.1
2016-07-07 18:07:45 +08:00
local_port = 22
2017-05-18 01:51:32 +08:00
remote_port = 6000
2016-07-07 18:07:45 +08:00
```
注意,`local_port`(客户端侦听)和 `remote_port`(服务器端暴露)是用来出入 frp 系统的两端,`server_port` 则是服务器用来与客户端通讯的。
2016-07-07 18:07:45 +08:00
4. 启动 frpc
`./frpc -c ./frpc.ini`
5. 通过 ssh 访问内网机器,假设用户名为 test
`ssh -oPort=6000 test@x.x.x.x`
2016-08-12 13:44:25 +08:00
### 通过自定义域名访问部署于内网的 web 服务
2016-07-07 18:07:45 +08:00
有时想要让其他人通过域名访问或者测试我们在本地搭建的 web 服务,但是由于本地机器没有公网 IP无法将域名解析到本地的机器通过 frp 就可以实现这一功能,以下示例为 http 服务https 服务配置方法相同, vhost_http_port 替换为 vhost_https_port type 设置为 https 即可。
2017-05-18 01:51:32 +08:00
1. 修改 frps.ini 文件,设置 http 访问端口为 8080
2016-07-07 18:07:45 +08:00
```ini
# frps.ini
[common]
bind_port = 7000
vhost_http_port = 8080
```
2019-08-20 17:17:17 +08:00
2. 启动 frps
2016-07-07 18:07:45 +08:00
`./frps -c ./frps.ini`
2017-05-18 01:51:32 +08:00
3. 修改 frpc.ini 文件,假设 frps 所在的服务器的 IP 为 x.x.x.xlocal_port 为本地机器上 web 服务对应的端口, 绑定自定义域名 `www.yourdomain.com`:
2016-07-07 18:07:45 +08:00
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[web]
type = http
local_port = 80
2017-05-18 01:51:32 +08:00
custom_domains = www.yourdomain.com
2016-07-07 18:07:45 +08:00
```
4. 启动 frpc
`./frpc -c ./frpc.ini`
2016-08-12 13:44:25 +08:00
5.`www.yourdomain.com` 的域名 A 记录解析到 IP `x.x.x.x`,如果服务器已经有对应的域名,也可以将 CNAME 记录解析到服务器原先的域名。
2016-07-07 18:07:45 +08:00
6. 通过浏览器访问 `http://www.yourdomain.com:8080` 即可访问到处于内网机器上的 web 服务。
2016-12-21 01:18:12 +08:00
### 转发 DNS 查询请求
DNS 查询请求通常使用 UDP 协议frp 支持对内网 UDP 服务的穿透,配置方式和 TCP 基本一致。
2017-05-18 01:51:32 +08:00
1. 修改 frps.ini 文件:
2016-12-21 01:18:12 +08:00
```ini
# frps.ini
[common]
bind_port = 7000
```
2. 启动 frps
`./frps -c ./frps.ini`
3. 修改 frpc.ini 文件,设置 frps 所在服务器的 IP 为 x.x.x.x转发到 Google 的 DNS 查询服务器 `8.8.8.8` 的 udp 53 端口:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[dns]
type = udp
local_ip = 8.8.8.8
local_port = 53
2017-05-18 01:51:32 +08:00
remote_port = 6000
2016-12-21 01:18:12 +08:00
```
4. 启动 frpc
`./frpc -c ./frpc.ini`
5. 通过 dig 测试 UDP 包转发是否成功,预期会返回 `www.google.com` 域名的解析结果:
2017-09-26 21:06:28 +08:00
`dig @x.x.x.x -p 6000 www.google.com`
2016-12-21 01:18:12 +08:00
2019-07-31 00:41:43 +08:00
### 转发 Unix 域套接字
2017-06-12 01:31:33 +08:00
2018-01-24 23:27:03 +08:00
通过 tcp 端口访问内网的 unix域套接字(例如和 docker daemon 通信)。
2017-06-12 01:31:33 +08:00
2017-07-17 00:57:10 +08:00
frps 的部署步骤同上。
2017-06-12 01:31:33 +08:00
2018-01-24 23:27:03 +08:00
1. 启动 frpc启用 `unix_domain_socket` 插件,配置如下:
2017-06-12 01:31:33 +08:00
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[unix_domain_socket]
type = tcp
remote_port = 6000
plugin = unix_domain_socket
plugin_unix_path = /var/run/docker.sock
```
2017-07-17 00:57:10 +08:00
2. 通过 curl 命令查看 docker 版本信息
2017-06-12 01:31:33 +08:00
2017-07-17 00:57:10 +08:00
`curl http://x.x.x.x:6000/version`
2017-06-12 01:31:33 +08:00
2018-01-24 23:27:03 +08:00
### 对外提供简单的文件访问服务
通过 `static_file` 插件可以对外提供一个简单的基于 HTTP 的文件访问服务。
frps 的部署步骤同上。
1. 启动 frpc启用 `static_file` 插件,配置如下:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[test_static_file]
type = tcp
remote_port = 6000
plugin = static_file
# 要对外暴露的文件目录
plugin_local_path = /tmp/file
# 访问 url 中会被去除的前缀,保留的内容即为要访问的文件路径
plugin_strip_prefix = static
plugin_http_user = abc
plugin_http_passwd = abc
```
2. 通过浏览器访问 `http://x.x.x.x:6000/static/` 来查看位于 `/tmp/file` 目录下的文件,会要求输入已设置好的用户名和密码。
2019-04-10 13:39:26 +08:00
### 为本地 HTTP 服务启用 HTTPS
通过 `https2http` 插件可以让本地 HTTP 服务转换成 HTTPS 服务对外提供。
1. 启用 frpc启用 `https2http` 插件,配置如下:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[test_htts2http]
type = https
custom_domains = test.yourdomain.com
plugin = https2http
plugin_local_addr = 127.0.0.1:80
# HTTPS 证书相关的配置
plugin_crt_path = ./server.crt
plugin_key_path = ./server.key
plugin_host_header_rewrite = 127.0.0.1
2019-08-14 20:44:44 +08:00
plugin_header_X-From-Where = frp
2019-04-10 13:39:26 +08:00
```
2. 通过浏览器访问 `https://test.yourdomain.com` 即可。
2017-07-17 00:57:10 +08:00
### 安全地暴露内网服务
2017-06-12 01:31:33 +08:00
2017-07-17 00:57:10 +08:00
对于某些服务来说如果直接暴露于公网上将会存在安全隐患。
使用 **stcp(secret tcp)** 类型的代理可以避免让任何人都能访问到要穿透的服务,但是访问者也需要运行另外一个 frpc。
以下示例将会创建一个只有自己能访问到的 ssh 服务代理。
frps 的部署步骤同上。
1. 启动 frpc转发内网的 ssh 服务,配置如下,不需要指定远程端口:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[secret_ssh]
type = stcp
# 只有 sk 一致的用户才能访问到此服务
sk = abcdefg
local_ip = 127.0.0.1
local_port = 22
```
2. 在要访问这个服务的机器上启动另外一个 frpc配置如下
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
2017-12-05 01:34:33 +08:00
[secret_ssh_visitor]
2017-07-17 00:57:10 +08:00
type = stcp
# stcp 的访问者
2017-12-05 01:34:33 +08:00
role = visitor
2017-07-17 00:57:10 +08:00
# 要访问的 stcp 代理的名字
server_name = secret_ssh
sk = abcdefg
# 绑定本地端口用于访问 ssh 服务
bind_addr = 127.0.0.1
bind_port = 6000
```
3. 通过 ssh 访问内网机器,假设用户名为 test
`ssh -oPort=6000 test@127.0.0.1`
2017-06-12 01:31:33 +08:00
2017-12-05 01:34:33 +08:00
### 点对点内网穿透
frp 提供了一种新的代理类型 **xtcp** 用于应对在希望传输大量数据且流量不经过服务器的场景。
使用方式同 **stcp** 类似,需要在两边都部署上 frpc 用于建立直接的连接。
目前处于开发的初级阶段,并不能穿透所有类型的 NAT 设备,所以穿透成功率较低。穿透失败时可以尝试 **stcp** 的方式。
1. frps 除正常配置外需要额外配置一个 udp 端口用于支持该类型的客户端:
```ini
bind_udp_port = 7001
```
2. 启动 frpc转发内网的 ssh 服务,配置如下,不需要指定远程端口:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[p2p_ssh]
type = xtcp
# 只有 sk 一致的用户才能访问到此服务
sk = abcdefg
local_ip = 127.0.0.1
local_port = 22
```
3. 在要访问这个服务的机器上启动另外一个 frpc配置如下:
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[p2p_ssh_visitor]
type = xtcp
# xtcp 的访问者
role = visitor
# 要访问的 xtcp 代理的名字
server_name = p2p_ssh
sk = abcdefg
# 绑定本地端口用于访问 ssh 服务
bind_addr = 127.0.0.1
bind_port = 6000
```
4. 通过 ssh 访问内网机器,假设用户名为 test:
`ssh -oPort=6000 test@127.0.0.1`
2017-07-17 00:57:10 +08:00
## 功能说明
2017-06-12 01:31:33 +08:00
2017-07-17 00:57:10 +08:00
### 配置文件
2017-06-12 01:31:33 +08:00
2017-07-17 00:57:10 +08:00
由于 frp 目前支持的功能和配置项较多,未在文档中列出的功能可以从完整的示例配置文件中发现。
[frps 完整配置文件](./conf/frps_full.ini)
[frpc 完整配置文件](./conf/frpc_full.ini)
2016-07-07 18:07:45 +08:00
2018-12-11 11:56:00 +08:00
### 配置文件模版渲染
配置文件支持使用系统环境变量进行模版渲染,模版格式采用 Go 的标准格式。
示例配置如下:
```ini
# frpc.ini
[common]
server_addr = {{ .Envs.FRP_SERVER_ADDR }}
server_port = 7000
[ssh]
type = tcp
local_ip = 127.0.0.1
local_port = 22
remote_port = {{ .Envs.FRP_SSH_REMOTE_PORT }}
```
启动 frpc 程序:
```
export FRP_SERVER_ADDR="x.x.x.x"
export FRP_SSH_REMOTE_PORT="6000"
./frpc -c ./frpc.ini
```
frpc 会自动使用环境变量渲染配置文件模版,所有环境变量需要以 `.Envs` 为前缀。
2016-08-12 12:50:12 +08:00
### Dashboard
通过浏览器查看 frp 的状态以及代理统计信息展示。
2019-01-15 11:27:53 +08:00
**注Dashboard 尚未针对大量的 proxy 数据展示做优化,如果出现 Dashboard 访问较慢的情况,请不要启用此功能。**
2016-08-12 12:50:12 +08:00
需要在 frps.ini 中指定 dashboard 服务使用的端口,即可开启此功能:
```ini
[common]
dashboard_port = 7500
2017-05-18 01:51:32 +08:00
# dashboard 用户名密码,默认都为 admin
2016-12-21 01:18:12 +08:00
dashboard_user = admin
dashboard_pwd = admin
2016-08-12 12:50:12 +08:00
```
2016-08-13 22:32:11 +08:00
打开浏览器通过 `http://[server_addr]:7500` 访问 dashboard 界面,用户名密码默认为 `admin`
2016-08-12 12:50:12 +08:00
![dashboard](/doc/pic/dashboard.png)
2019-03-11 16:24:54 +08:00
### Admin UI
Admin UI 可以帮助用户通过浏览器来查询和管理客户端的 proxy 状态和配置。
需要在 frpc.ini 中指定 admin 服务使用的端口,即可开启此功能:
```ini
[common]
admin_addr = 127.0.0.1
admin_port = 7400
admin_user = admin
admin_pwd = admin
```
打开浏览器通过 `http://127.0.0.1:7400` 访问 Admin UI用户名密码默认为 `admin`
如果想要在外网环境访问 Admin UI将 7400 端口映射出去即可,但需要重视安全风险。
2020-03-11 14:13:16 +08:00
### 监控
2016-07-07 18:07:45 +08:00
2020-03-11 14:13:16 +08:00
frps 当启用 Dashboard 后,会默认开启内部的监控,数据存放在内存中,每次重启进程后会清空,监控数据可以通过 dashboard 的地址发送 HTTP 请求获取。
目前还支持 Prometheus 作为可选的监控系统。
#### Prometheus
`frps.ini` 中启用 Dashboard并且设置 `enable_prometheus = true`,则通过 `http://{dashboard_addr}/metrics` 可以获取到 Prometheus 的监控数据。
### 客户端身份验证
目前 frpc 和 frps 之间支持两种身份验证方式,`token` 和 `oidc`
通过 `frpc.ini``frps.ini``[common]` section 的 `authentication_method` 参数配置需要使用的验证方法。
`authenticate_heartbeats = true` 将会在每一个心跳包中附加上鉴权信息。
`authenticate_new_work_conns = true` 将会在每次建立新的工作连接时附加上鉴权信息。
#### Token
`authentication_method = token`,将会启用基于 token 的验证方式。
需要在 `frpc.ini``frps.ini``[common]` section 中设置相同的 `token`
#### OIDC
`authentication_method = oidc`,将会启用基于 OIDC 的身份验证。
验证流程参考 [Client Credentials Grant](https://tools.ietf.org/html/rfc6749#section-4.4)
启用这一验证方式,配置 `frpc.ini``frps.ini` 如下:
```ini
# frps.ini
[common]
authentication_method = oidc
oidc_issuer = https://example-oidc-issuer.com/
oidc_audience = https://oidc-audience.com/.default
```
```ini
[common]
authentication_method = oidc
oidc_client_id = 98692467-37de-409a-9fac-bb2585826f18 # Replace with OIDC client ID
oidc_client_secret = oidc_secret
oidc_audience = https://oidc-audience.com/.default
oidc_token_endpoint_url = https://example-oidc-endpoint.com/oauth2/v2.0/token
```
2016-07-07 18:07:45 +08:00
### 加密与压缩
2017-05-18 01:51:32 +08:00
这两个功能默认是不开启的,需要在 frpc.ini 中通过配置来为指定的代理启用加密与压缩的功能,压缩算法使用 snappy
2016-07-07 18:07:45 +08:00
```ini
# frpc.ini
[ssh]
type = tcp
2017-05-18 01:51:32 +08:00
local_port = 22
remote_port = 6000
2016-07-07 18:07:45 +08:00
use_encryption = true
2017-05-18 01:51:32 +08:00
use_compression = true
2016-07-07 18:07:45 +08:00
```
如果公司内网防火墙对外网访问进行了流量识别与屏蔽,例如禁止了 ssh 协议等,通过设置 `use_encryption = true`,将 frpc 与 frps 之间的通信内容加密传输,将会有效防止流量被拦截。
2017-05-18 01:51:32 +08:00
如果传输的报文长度较长,通过设置 `use_compression = true` 对传输内容进行压缩,可以有效减小 frpc 与 frps 之间的网络流量,加快流量转发速度,但是会额外消耗一些 cpu 资源。
2016-07-07 18:07:45 +08:00
2019-03-11 16:24:54 +08:00
#### TLS
从 v0.25.0 版本开始 frpc 和 frps 之间支持通过 TLS 协议加密传输。通过在 `frpc.ini``common` 中配置 `tls_enable = true` 来启用此功能,安全性更高。
为了端口复用frp 建立 TLS 连接的第一个字节为 0x17。
2020-03-11 14:13:16 +08:00
通过将 frps.ini 的 `[common]``tls_only` 设置为 true可以强制 frps 只接受 TLS 连接。
2019-03-11 16:24:54 +08:00
**注意: 启用此功能后除 xtcp 外,不需要再设置 use_encryption。**
2017-07-17 00:57:10 +08:00
### 客户端热加载配置文件
2018-01-18 16:43:03 +08:00
当修改了 frpc 中的代理配置,可以通过 `frpc reload` 命令来动态加载配置文件,通常会在 10 秒内完成代理的更新。
2017-07-17 00:57:10 +08:00
启用此功能需要在 frpc 中启用 admin 端口,用于提供 API 服务。配置如下:
2016-07-07 18:07:45 +08:00
2017-07-17 00:57:10 +08:00
```ini
# frpc.ini
[common]
admin_addr = 127.0.0.1
admin_port = 7400
```
之后执行重启命令:
2018-01-18 16:43:03 +08:00
`frpc reload -c ./frpc.ini`
2017-07-17 00:57:10 +08:00
等待一段时间后客户端会根据新的配置文件创建、更新、删除代理。
**需要注意的是,[common] 中的参数除了 start 外目前无法被修改。**
2016-07-07 18:07:45 +08:00
2018-01-18 16:43:03 +08:00
### 客户端查看代理状态
frpc 支持通过 `frpc status -c ./frpc.ini` 命令查看代理的状态信息,此功能需要在 frpc 中配置 admin 端口。
2018-04-24 01:26:05 +08:00
### 端口白名单
2016-07-07 18:07:45 +08:00
2018-04-24 01:26:05 +08:00
为了防止端口被滥用,可以手动指定允许哪些端口被使用,在 frps.ini 中通过 `allow_ports` 来指定:
2016-08-12 12:50:12 +08:00
```ini
# frps.ini
[common]
2018-04-24 01:26:05 +08:00
allow_ports = 2000-3000,3001,3003,4000-50000
2016-08-12 12:50:12 +08:00
```
2018-04-24 01:26:05 +08:00
`allow_ports` 可以配置允许使用的某个指定端口或者是一个范围内的所有端口,以 `,` 分隔,指定的范围以 `-` 分隔。
2016-08-12 12:50:12 +08:00
2018-05-07 16:46:04 +08:00
### 端口复用
目前 frps 中的 `vhost_http_port``vhost_https_port` 支持配置成和 `bind_port` 为同一个端口frps 会对连接的协议进行分析,之后进行不同的处理。
例如在某些限制较严格的网络环境中,可以将 `bind_port``vhost_https_port` 都设置为 443。
后续会尝试允许多个 proxy 绑定同一个远端端口的不同协议。
2019-11-26 10:23:37 +08:00
### 限速
#### 代理限速
目前支持在客户端的代理配置中设置代理级别的限速,限制单个 proxy 可以占用的带宽。
```ini
# frpc.ini
[ssh]
type = tcp
local_port = 22
remote_port = 6000
2020-02-04 21:34:46 +08:00
bandwidth_limit = 1MB
2019-11-26 10:23:37 +08:00
```
2020-02-04 21:34:46 +08:00
在代理配置中增加 `bandwidth_limit` 字段启用此功能,目前仅支持 `MB``KB` 单位。
2019-11-26 10:23:37 +08:00
2017-05-18 01:51:32 +08:00
### TCP 多路复用
从 v0.10.0 版本开始,客户端和服务器端之间的连接支持多路复用,不再需要为每一个用户请求创建一个连接,使连接建立的延迟降低,并且避免了大量文件描述符的占用,使 frp 可以承载更高的并发数。
该功能默认启用,如需关闭,可以在 frps.ini 和 frpc.ini 中配置,该配置项在服务端和客户端必须一致:
```ini
# frps.ini 和 frpc.ini 中
[common]
tcp_mux = false
```
2017-07-17 00:57:10 +08:00
### 底层通信可选 kcp 协议
2017-06-14 01:23:34 +08:00
2019-04-10 13:39:26 +08:00
底层通信协议支持选择 kcp 协议,在弱网环境下传输效率提升明显,但是会有一些额外的流量消耗。
2017-06-14 01:23:34 +08:00
开启 kcp 协议支持:
1. 在 frps.ini 中启用 kcp 协议支持,指定一个 udp 端口用于接收客户端请求:
```ini
# frps.ini
[common]
bind_port = 7000
# kcp 绑定的是 udp 端口,可以和 bind_port 一样
kcp_bind_port = 7000
```
2. 在 frpc.ini 指定需要使用的协议类型,目前只支持 tcp 和 kcp。其他代理配置不需要变更
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
# server_port 指定为 frps 的 kcp_bind_port
server_port = 7000
protocol = kcp
```
3. 像之前一样使用 frp需要注意开放相关机器上的 udp 的端口的访问权限。
2016-08-12 12:50:12 +08:00
### 连接池
默认情况下当用户请求建立连接后frps 才会请求 frpc 主动与后端服务建立一个连接。当为指定的代理启用连接池后frp 会预先和后端服务建立起指定数量的连接,每次接收到用户请求后,会从连接池中取出一个连接和用户连接关联起来,避免了等待与后端服务建立连接以及 frpc 和 frps 之间传递控制信息的时间。
这一功能比较适合有大量短连接请求时开启。
2017-05-18 01:51:32 +08:00
1. 首先可以在 frps.ini 中设置每个代理可以创建的连接池上限,避免大量资源占用,客户端设置超过此配置后会被调整到当前值:
2016-08-12 12:50:12 +08:00
```ini
# frps.ini
[common]
2017-05-18 01:51:32 +08:00
max_pool_count = 5
2016-08-12 12:50:12 +08:00
```
2017-05-18 01:51:32 +08:00
2. 在 frpc.ini 中为客户端启用连接池,指定预创建连接的数量:
2016-08-12 12:50:12 +08:00
```ini
# frpc.ini
2017-05-18 01:51:32 +08:00
[common]
pool_count = 1
2016-08-12 12:50:12 +08:00
```
2018-05-25 01:25:36 +08:00
### 负载均衡
可以将多个相同类型的 proxy 加入到同一个 group 中,从而实现负载均衡的功能。
2019-04-10 13:39:26 +08:00
2019-07-31 00:41:43 +08:00
目前只支持 TCP 和 HTTP 类型的 proxy。
2018-05-25 01:25:36 +08:00
```ini
2018-11-21 14:51:33 +08:00
# frpc.ini
2018-05-25 01:25:36 +08:00
[test1]
type = tcp
local_port = 8080
remote_port = 80
group = web
group_key = 123
[test2]
type = tcp
local_port = 8081
remote_port = 80
group = web
group_key = 123
```
用户连接 frps 服务器的 80 端口frps 会将接收到的用户连接随机分发给其中一个存活的 proxy。这样可以在一台 frpc 机器挂掉后仍然有其他节点能够提供服务。
2019-07-31 00:41:43 +08:00
TCP 类型代理要求 `group_key` 相同,做权限验证,且 `remote_port` 相同。
HTTP 类型代理要求 `group_key, custom_domains 或 subdomain 和 locations` 相同。
2018-05-25 01:25:36 +08:00
2019-01-15 11:27:53 +08:00
### 健康检查
通过给 proxy 加上健康检查的功能,可以在要反向代理的服务出现故障时,将这个服务从 frps 中摘除,搭配负载均衡的功能,可以用来实现高可用的架构,避免服务单点故障。
在每一个 proxy 的配置下加上 `health_check_type = {type}` 来启用健康检查功能。
**type** 目前可选 tcp 和 http。
tcp 只要能够建立连接则认为服务正常http 会发送一个 http 请求,服务需要返回 2xx 的状态码才会被认为正常。
tcp 示例配置如下:
```ini
# frpc.ini
[test1]
type = tcp
local_port = 22
remote_port = 6000
# 启用健康检查,类型为 tcp
health_check_type = tcp
# 建立连接超时时间为 3 秒
health_check_timeout_s = 3
# 连续 3 次检查失败,此 proxy 会被摘除
health_check_max_failed = 3
# 每隔 10 秒进行一次健康检查
health_check_interval_s = 10
```
http 示例配置如下:
```ini
# frpc.ini
[web]
type = http
local_ip = 127.0.0.1
local_port = 80
custom_domains = test.yourdomain.com
# 启用健康检查,类型为 http
health_check_type = http
# 健康检查发送 http 请求的 url后端服务需要返回 2xx 的 http 状态码
health_check_url = /status
health_check_interval_s = 10
health_check_max_failed = 3
health_check_timeout_s = 3
```
2016-08-12 12:50:12 +08:00
### 修改 Host Header
通常情况下 frp 不会修改转发的任何数据。但有一些后端服务会根据 http 请求 header 中的 host 字段来展现不同的网站,例如 nginx 的虚拟主机服务,启用 host-header 的修改功能可以动态修改 http 请求中的 host 字段。该功能仅限于 http 类型的代理。
```ini
# frpc.ini
[web]
type = http
local_port = 80
custom_domains = test.yourdomain.com
host_header_rewrite = dev.yourdomain.com
```
原来 http 请求中的 host 字段 `test.yourdomain.com` 转发到后端服务时会被替换为 `dev.yourdomain.com`
2018-05-25 01:25:36 +08:00
### 设置 HTTP 请求的 header
2018-05-20 23:41:15 +08:00
对于 `type = http` 的代理,可以设置在转发中动态添加的 header 参数。
```ini
# frpc.ini
[web]
type = http
local_port = 80
custom_domains = test.yourdomain.com
host_header_rewrite = dev.yourdomain.com
header_X-From-Where = frp
```
对于参数配置中所有以 `header_` 开头的参数(支持同时配置多个),都会被添加到 http 请求的 header 中,根据如上的配置,会在请求的 header 中加上 `X-From-Where: frp`
2017-07-17 00:57:10 +08:00
### 获取用户真实 IP
2019-04-10 13:39:26 +08:00
#### HTTP X-Forwarded-For
目前只有 **http** 类型的代理支持这一功能,可以通过用户请求的 header 中的 `X-Forwarded-For` 来获取用户真实 IP默认启用。
#### Proxy Protocol
frp 支持通过 **Proxy Protocol** 协议来传递经过 frp 代理的请求的真实 IP此功能支持所有以 TCP 为底层协议的类型,不支持 UDP。
**Proxy Protocol** 功能启用后frpc 在和本地服务建立连接后,会先发送一段 **Proxy Protocol** 的协议内容给本地服务,本地服务通过解析这一内容可以获得访问用户的真实 IP。所以不仅仅是 HTTP 服务,任何的 TCP 服务,只要支持这一协议,都可以获得用户的真实 IP 地址。
需要注意的是,在代理配置中如果要启用此功能,需要本地的服务能够支持 **Proxy Protocol** 这一协议,目前 nginx 和 haproxy 都能够很好的支持。
这里以 https 类型为例:
```ini
# frpc.ini
[web]
type = https
local_port = 443
custom_domains = test.yourdomain.com
# 目前支持 v1 和 v2 两个版本的 proxy protocol 协议。
proxy_protocol_version = v2
```
只需要在代理配置中增加一行 `proxy_protocol_version = v2` 即可开启此功能。
本地的 https 服务可以通过在 nginx 的配置中启用 **Proxy Protocol** 的解析并将结果设置在 `X-Real-IP` 这个 Header 中就可以在自己的 Web 服务中通过 `X-Real-IP` 获取到用户的真实 IP。
2017-07-17 00:57:10 +08:00
2016-12-21 01:18:12 +08:00
### 通过密码保护你的 web 服务
由于所有客户端共用一个 frps 的 http 服务端口,任何知道你的域名和 url 的人都能访问到你部署在内网的 web 服务,但是在某些场景下需要确保只有限定的用户才能访问。
frp 支持通过 HTTP Basic Auth 来保护你的 web 服务,使用户需要通过用户名和密码才能访问到你的服务。
该功能目前仅限于 http 类型的代理,需要在 frpc 的代理配置中添加用户名和密码的设置。
```ini
# frpc.ini
[web]
type = http
local_port = 80
custom_domains = test.yourdomain.com
http_user = abc
2018-04-23 03:04:33 +08:00
http_pwd = abc
2016-12-21 01:18:12 +08:00
```
2017-05-18 01:51:32 +08:00
通过浏览器访问 `http://test.yourdomain.com`,需要输入配置的用户名和密码才能访问。
2016-12-21 01:18:12 +08:00
### 自定义二级域名
在多人同时使用一个 frps 时,通过自定义二级域名的方式来使用会更加方便。
通过在 frps 的配置文件中配置 `subdomain_host`,就可以启用该特性。之后在 frpc 的 http、https 类型的代理中可以不配置 `custom_domains`,而是配置一个 `subdomain` 参数。
2017-05-18 01:51:32 +08:00
只需要将 `*.{subdomain_host}` 解析到 frps 所在服务器。之后用户可以通过 `subdomain` 自行指定自己的 web 服务所需要使用的二级域名,通过 `{subdomain}.{subdomain_host}` 来访问自己的 web 服务。
2016-12-21 01:18:12 +08:00
```ini
# frps.ini
2017-05-18 01:51:32 +08:00
[common]
2016-12-21 01:18:12 +08:00
subdomain_host = frps.com
```
将泛域名 `*.frps.com` 解析到 frps 所在服务器的 IP 地址。
```ini
# frpc.ini
[web]
type = http
local_port = 80
subdomain = test
```
2018-11-21 14:51:33 +08:00
frps 和 frpc 都启动成功后,通过 `test.frps.com` 就可以访问到内网的 web 服务。
2016-12-21 01:18:12 +08:00
2019-01-15 11:27:53 +08:00
**注:如果 frps 配置了 `subdomain_host`,则 `custom_domains` 中不能是属于 `subdomain_host` 的子域名或者泛域名。**
2016-12-21 01:18:12 +08:00
同一个 http 或 https 类型的代理中 `custom_domains``subdomain` 可以同时配置。
2016-12-28 00:26:50 +08:00
### URL 路由
frp 支持根据请求的 URL 路径路由转发到不同的后端服务。
通过配置文件中的 `locations` 字段指定一个或多个 proxy 能够匹配的 URL 前缀(目前仅支持最大前缀匹配,之后会考虑正则匹配)。例如指定 `locations = /news`,则所有 URL 以 `/news` 开头的请求都会被转发到这个服务。
```ini
# frpc.ini
[web01]
type = http
local_port = 80
custom_domains = web.yourdomain.com
locations = /
[web02]
type = http
local_port = 81
custom_domains = web.yourdomain.com
locations = /news,/about
```
按照上述的示例配置后,`web.yourdomain.com` 这个域名下所有以 `/news` 以及 `/about` 作为前缀的 URL 请求都会被转发到 web02其余的请求会被转发到 web01。
2020-03-11 14:13:16 +08:00
### TCP 端口复用类型
frp 支持将单个端口收到的连接路由到不同的代理,类似 `vhost_http_port``vhost_https_port`
目前支持的复用器只有 `httpconnect`
当在 `frps.ini``[common]` 中设置 `tcpmux_httpconnect_port`frps 将会监听在这个端口,接收 HTTP CONNECT 请求。
frps 会根据 HTTP CONNECT 请求中的 host 路由到不同的后端代理。
示例配置如下:
```ini
# frps.ini
[common]
bind_port = 7000
tcpmux_httpconnect_port = 1337
```
```ini
# frpc.ini
[common]
server_addr = x.x.x.x
server_port = 7000
[proxy1]
type = tcpmux
multiplexer = httpconnect
custom_domains = test1
[proxy2]
type = tcpmux
multiplexer = httpconnect
custom_domains = test2
```
通过上面的配置frps 如果接收到 HTTP CONNECT 请求内容:
```
CONNECT test1 HTTP/1.1\r\n\r\n
```
该连接将会被路由到 proxy1 。
2017-05-18 01:51:32 +08:00
### 通过代理连接 frps
2016-12-21 01:18:12 +08:00
在只能通过代理访问外网的环境内frpc 支持通过 HTTP PROXY 和 frps 进行通信。
可以通过设置 `HTTP_PROXY` 系统环境变量或者通过在 frpc 的配置文件中设置 `http_proxy` 参数来使用此功能。
2017-06-17 18:01:08 +08:00
仅在 `protocol = tcp` 时生效。
2016-12-21 01:18:12 +08:00
```ini
# frpc.ini
2017-06-12 01:31:33 +08:00
[common]
2016-12-21 01:18:12 +08:00
server_addr = x.x.x.x
server_port = 7000
http_proxy = http://user:pwd@192.168.1.128:8080
```
2018-01-29 23:05:17 +08:00
### 范围端口映射
在 frpc 的配置文件中可以指定映射多个端口,目前只支持 tcp 和 udp 的类型。
这一功能通过 `range:` 段落标记来实现,客户端会解析这个标记中的配置,将其拆分成多个 proxy每一个 proxy 以数字为后缀命名。
例如要映射本地 6000-6005, 6007 这6个端口主要配置如下
```ini
# frpc.ini
[range:test_tcp]
type = tcp
local_ip = 127.0.0.1
local_port = 6000-6006,6007
remote_port = 6000-6006,6007
```
2018-05-20 23:55:22 +08:00
实际连接成功后会创建 8 个 proxy命名为 `test_tcp_0, test_tcp_1 ... test_tcp_7`
2018-01-29 23:05:17 +08:00
2020-01-03 11:35:12 +08:00
### 客户端插件
2017-06-12 01:31:33 +08:00
默认情况下frpc 只会转发请求到本地 tcp 或 udp 端口。
2020-01-03 11:35:12 +08:00
客户端插件模式是为了在客户端提供更加丰富的功能,目前内置的插件有 `unix_domain_socket`、`http_proxy`、`socks5`、`static_file`。具体使用方式请查看[使用示例](#使用示例)。
2017-06-12 01:31:33 +08:00
2017-06-24 12:17:09 +08:00
通过 `plugin` 指定需要使用的插件,插件的配置参数都以 `plugin_` 开头。使用插件后 `local_ip``local_port` 不再需要配置。
2017-06-12 01:31:33 +08:00
使用 **http_proxy** 插件的示例:
```ini
# frpc.ini
[http_proxy]
type = tcp
remote_port = 6000
plugin = http_proxy
plugin_http_user = abc
plugin_http_passwd = abc
```
`plugin_http_user``plugin_http_passwd` 即为 `http_proxy` 插件可选的配置参数。
2020-01-03 11:35:12 +08:00
### 服务端管理插件
[使用说明](/doc/server_plugin_zh.md)
2020-03-20 20:54:22 +08:00
从 [gofrp/plugin](https://github.com/gofrp/plugin) 中寻找更多插件。
2016-07-07 18:07:45 +08:00
## 开发计划
计划在后续版本中加入的功能与优化,排名不分先后,如果有其他功能建议欢迎在 [issues](https://github.com/fatedier/frp/issues) 中反馈。
2016-12-21 01:18:12 +08:00
* frps 记录 http 请求日志。
2016-04-06 11:43:50 +08:00
2016-08-21 00:52:15 +08:00
## 为 frp 做贡献
2016-04-06 11:43:50 +08:00
2016-08-21 00:52:15 +08:00
frp 是一个免费且开源的项目,我们欢迎任何人为其开发和进步贡献力量。
2016-04-06 11:43:50 +08:00
2016-08-21 00:52:15 +08:00
* 在使用过程中出现任何问题,可以通过 [issues](https://github.com/fatedier/frp/issues) 来反馈。
* Bug 的修复可以直接提交 Pull Request 到 dev 分支。
* 如果是增加新的功能特性,请先创建一个 issue 并做简单描述以及大致的实现方法,提议被采纳后,就可以创建一个实现新特性的 Pull Request。
* 欢迎对说明文档做出改善,帮助更多的人使用 frp特别是英文文档。
2016-08-16 14:09:29 +08:00
* 贡献代码请提交 PR 至 dev 分支master 分支仅用于发布稳定可用版本。
2016-08-21 00:52:15 +08:00
* 如果你有任何其他方面的问题,欢迎反馈至 fatedier@gmail.com 共同交流。
2016-04-06 11:43:50 +08:00
2016-06-03 18:15:01 +08:00
**提醒:和项目相关的问题最好在 [issues](https://github.com/fatedier/frp/issues) 中反馈,这样方便其他有类似问题的人可以快速查找解决方法,并且也避免了我们重复回答一些问题。**
2016-08-24 13:36:38 +08:00
## 捐助
如果您觉得 frp 对你有帮助,欢迎给予我们一定的捐助来维持项目的长期发展。
2019-01-15 15:15:02 +08:00
### 知识星球
如果您想学习 frp 相关的知识和技术,或者寻求任何帮助,都可以通过微信扫描下方的二维码付费加入知识星球的官方社群:
![zsxq](/doc/pic/zsxq.jpg)
2016-08-24 13:36:38 +08:00
### 支付宝扫码捐赠
![donate-alipay](/doc/pic/donate-alipay.png)
2017-06-12 01:31:33 +08:00
### 微信支付捐赠
![donate-wechatpay](/doc/pic/donate-wechatpay.png)
2016-08-24 13:36:38 +08:00
### Paypal 捐赠
海外用户推荐通过 [Paypal](https://www.paypal.me/fatedier) 向我的账户 **fatedier@gmail.com** 进行捐赠。