1.配置文件

frp 目前仅支持 ini 格式的配置文件，frps 和 frpc 各自支持不同的参数。

frps 主要配置服务端的一些通用参数，frpc 则需要额外配置每一个代理的详细配置。

格式

目前仅支持 ini 格式的配置，如下的示例配置将本地 SSH 服务穿透到公网。

frps 配置：

[common] 
bind_port = 7000

frpc 配置：

[common] 
server_addr = x.x.x.x 
server_port = 7000 

[ssh] 
type = tcp 
local_ip = 127.0.0.1 
local_port = 22 
remote_port = 6000

[common] 是固定名称的段落，用于配置通用参数。

[ssh] 仅在 frpc 中使用，用于配置单个代理的参数。代理名称必须唯一，不能重复。

同一个客户端可以配置多个代理。

模版渲染

配置文件支持使用环境变量进行模版渲染，模版格式采用 Go 的标准格式。

示例配置如下：

# 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 为前缀。

配置校验

通过执行 frpc verify -c ./frpc.ini 或 frps verify -c ./frps.ini 可以对配置文件中的参数进行预先校验。

frpc: the configuration file ./frpc.ini syntax is ok

如果出现此结果，则说明新的配置文件没有错误，否则会输出具体的错误信息。

配置拆分

通过 includes 参数可以在主配置中包含其他配置文件，从而实现将代理配置拆分到多个文件中管理。

# frpc.ini 
[common] 
server_addr = x.x.x.x 
server_port = 7000 
includes = ./confd/*.ini

# ./confd/test.ini 
[ssh] 
type = tcp 
local_ip = 127.0.0.1 
local_port = 22 
remote_port = 6000

上述配置在 frpc.ini 中通过 includes 额外包含了 ./confd 目录下所有的 ini 文件的代理配置内容，效果等价于将这两个文件合并成一个文件。

需要注意的是 includes 指定的文件中只能包含代理配置，common 段落的配置只能放在主配置文件中。

完整配置参数

由于 frp 目前支持的功能和配置项较多，未在文档中列出的功能参数可以在 参考 中查看。

2.监控

目前 frps 服务端支持内存和 Prometheus 两种监控系统。

内存

内存中存储的监控数据主要用于 Dashboard 展示，当在 frps 配置中开启 Dashboard 功能后会默认开启内部的监控。

内存中的监控数据每次重启进程后会清空，监控数据可以通过 Dashboard 的地址发送 HTTP 请求获取，但是目前此 API 尚不规范，不推荐直接使用。

Prometheus

由于设计问题，Prometheus 对外提供的查询接口复用了 Dashboard 的地址，所以要使用 Prometheus 监控，必须要首先开启 Dashboard。

在 frps.ini 中启用 Dashboard，并设置 enable_prometheus = true，则通过 http://{dashboard_addr}/metrics 可以获取到 Prometheus 的监控数据。

3.身份认证

目前 frpc 和 frps 之间支持两种身份验证方式，token 和 oidc，默认为 token。

通过 frpc.ini 和 frps.ini 的 [common] 段落中配置 authentication_method 来指定要使用的身份验证方式。

只有通过身份验证的客户端(frpc)才能成功连接 frps。

Token

基于 Token 的身份验证方式比较简单，需要在 frpc 和 frps 的 [common] 段落中配置上相同的 token 参数即可。

OIDC

OIDC 是 OpenID Connect 的简称，验证流程参考 Client Credentials Grant。

启用这一验证方式，参考配置如下：

# frps.ini 
[common] 
authentication_method = oidc 
oidc_issuer = https://example-oidc-issuer.com/ 
oidc_audience = https://oidc-audience.com/.default

# frpc.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

参数说明

4.Web 界面

目前 frpc 和 frps 分别内置了相应的 Web 界面方便用户使用。

服务端 Dashboard

服务端 Dashboard 使用户可以通过浏览器查看 frp 的状态以及代理统计信息。

注：Dashboard 尚未针对大量的 proxy 数据展示做优化，如果出现 Dashboard 访问较慢的情况，请不要启用此功能。

需要在 frps.ini 中指定 dashboard 服务使用的端口，即可开启此功能：

# frps.ini 
[common] 
dashboard_port = 7500 
# dashboard 用户名密码，可选，默认为空 
dashboard_user = admin 
dashboard_pwd = admin

打开浏览器通过 http://[server_addr]:7500 访问 Dashboard 界面，输入用户名密码 admin。

客户端管理界面

frpc 内置的 Admin UI 可以帮助用户通过浏览器来查询和管理客户端的 proxy 状态和配置。

需要在 frpc.ini 中指定 admin 服务使用的端口，即可开启此功能：

# frpc.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 UI，可以将 7400 端口通过 frp 映射出去即可，但需要重视安全风险。

# frpc.ini 
[admin_ui] 
type = tcp 
local_port = 7400 
remote_port = 7400

5.通信安全及优化

加密与压缩

每一个代理都可以选择是否启用加密和压缩的功能。

加密算法采用 aes-128-cfb，压缩算法采用 snappy。

在每一个代理的配置中使用如下参数指定：

# frpc.ini 
[ssh] 
type = tcp 
local_port = 22 
remote_port = 6000 
use_encryption = true 
use_compression = true

通过设置 use_encryption = true，将 frpc 与 frps 之间的通信内容加密传输，将会有效防止传输内容被截取。

如果传输的报文长度较长，通过设置 use_compression = true 对传输内容进行压缩，可以有效减小 frpc 与 frps 之间的网络流量，加快流量转发速度，但是会额外消耗一些 CPU 资源。

TCP 多路复用

客户端和服务器端之间的连接支持多路复用，不再需要为每一个用户请求创建一个连接，使连接建立的延迟降低，并且避免了大量文件描述符的占用，使 frp 可以承载更高的并发数。

该功能默认启用，如需关闭，可以在 frps.ini 和 frpc.ini 中配置，该配置项在服务端和客户端必须一致：

# frps.ini 和 frpc.ini 中 
[common] 
tcp_mux = false

连接池

默认情况下，当用户请求建立连接后，frps 才会请求 frpc 主动与后端服务建立一个连接。当为指定的代理启用连接池后，frp 会预先和后端服务建立起指定数量的连接，每次接收到用户请求后，会从连接池中取出一个连接和用户连接关联起来，避免了等待与后端服务建立连接以及 frpc 和 frps 之间传递控制信息的时间。

这一功能适合有大量短连接请求时开启。

1. 首先可以在 frps.ini 中设置每个代理可以创建的连接池上限，避免大量资源占用，客户端设置超过此配置后会被调整到当前值：

# frps.ini 
[common] 
max_pool_count = 5

  2. 在 frpc.ini 中为客户端启用连接池，指定预创建连接的数量：

# frpc.ini 
[common] 
pool_count = 1

支持 KCP 协议

底层通信协议支持选择 KCP 协议，相比于 TCP，在弱网环境下传输效率提升明显，但是会有一些额外的流量消耗。

开启 KCP 协议支持：

1. 在 frps.ini 中启用 KCP 协议支持，指定一个 udp 端口用于接收客户端请求：

# frps.ini 
[common] 
bind_port = 7000 
# kcp 绑定的是 udp 端口，可以和 bind_port 一样 
kcp_bind_port = 7000

 2. 在 frpc.ini 指定需要使用的协议类型，目前只支持 TCP 和 KCP。其他代理配置不需要变更：

# frpc.ini 
[common] 
server_addr = x.x.x.x 
# server_port 指定为 frps 的 kcp_bind_port 
server_port = 7000 
protocol = kcp

自定义 TLS 协议加密

use_encryption 和 STCP 等功能能有效防止流量内容在通信过程中被盗取，但是无法判断对方的身份是否合法，存在被中间人攻击的威胁。为此 frp 支持 frpc 和 frps 之间的流量通过 TLS 协议加密，并且支持客户端或服务端单向验证，双向验证等功能。

当 frpc.ini 的 common 中 tls_enable = true 时，表示开启 TLS 协议加密。

当 frps.ini 的 common 中 tls_only = true 时，表示 server 端只接受 TLS 连接的客户端，这也是 frps 验证 frpc 身份的前提条件。如果 frps.ini 的 common 中 tls_trusted_ca_file 内容是有效的话，那么默认就会开启 tls_only = true。

注意：启用此功能后除 xtcp 外，可以不用再设置 use_encryption 重复加密

TLS 默认开启方式 

# frpc.ini 
[common] 
tls_enable = true

frpc 开启 TLS 加密功能，但是默认不校验 frps 的证书。

frpc 单向校验 frps 身份 

# frpc.ini 
[common] 
tls_enable = true 
tls_trusted_ca_file = /to/ca/path/ca.crt 

# frps.ini 
[common] 
tls_cert_file = /to/cert/path/server.crt 
tls_key_file = /to/key/path/server.key

frpc 需要额外加载 ca 证书，frps 需要额外指定 TLS 配置。frpc 通过 ca 证书单向验证 frps 的身份。这就要求 frps 的 server.crt 对 frpc 的 ca 是合法的。

合法: 如果证书是 ca 签发的，或者证书是在 ca 的信任链中，那即认为: 该证书对 ca 而言是合法的。

frps 单向验证 frpc 的身份

# frpc.ini 
[common] 
tls_enable = true 
tls_cert_file = /to/cert/path/client.crt 
tls_key_file = /to/key/path/client.key 

# frps.ini 
[common] 
tls_trusted_ca_file = /to/ca/path/ca.crt

frpc 需要额外加载 TLS 配置，frps 需要额外加载 ca 证书。frps 通过 ca 证书单向验证 frpc 的身份。这就要求 frpc 的 client.crt 对 frps 的 ca 是合法的。

双向验证

# frpc.ini 
[common] 
tls_enable = true 
tls_cert_file = /to/cert/path/client.crt 
tls_key_file = /to/key/path/client.key 
tls_trusted_ca_file = /to/ca/path/ca.crt 

# frps.ini 
[common] 
tls_cert_file = /to/cert/path/server.crt 
tls_key_file = /to/key/path/server.key 
tls_trusted_ca_file = /to/ca/path/ca.crt

双向验证即 frpc 和 frps 通过本地 ca 证书去验证对方的身份。理论上 frpc 和 frps 的 ca 证书可以不同，只要能验证对方身份即可。

OpenSSL 生成证书示例

x509: certificate relies on legacy Common Name field, use SANs or temporarily enable Common Name matching with GODEBUG=x509ignoreCN=0

如果出现上述报错，是因为 go 1.15 版本开始废弃 CommonName，因此推荐使用 SAN 证书。 如果想兼容之前的方式，需要设置环境变量 GODEBUG 为 x509ignoreCN=0。

下面简单示例如何用 openssl 生成 ca 和双方 SAN 证书。

准备默认 OpenSSL 配置文件于当前目录。此配置文件在 linux 系统下通常位于 /etc/pki/tls/openssl.cnf，在 mac 系统下通常位于 /System/Library/OpenSSL/openssl.cnf。

如果存在，则直接拷贝到当前目录，例如 cp /etc/pki/tls/openssl.cnf ./my-openssl.cnf。如果不存在可以使用下面的命令来创建。

cat > my-openssl.cnf << EOF
[ ca ]
default_ca = CA_default
[ CA_default ]
x509_extensions = usr_cert
[ req ]
default_bits        = 2048
default_md          = sha256
default_keyfile     = privkey.pem
distinguished_name  = req_distinguished_name
attributes          = req_attributes
x509_extensions     = v3_ca
string_mask         = utf8only
[ req_distinguished_name ]
[ req_attributes ]
[ usr_cert ]
basicConstraints       = CA:FALSE
nsComment              = "OpenSSL Generated Certificate"
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid,issuer
[ v3_ca ]
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid:always,issuer
basicConstraints       = CA:true
EOF

生成默认 ca:

openssl genrsa -out ca.key 2048
openssl req -x509 -new -nodes -key ca.key -subj "/CN=example.ca.com" -days 5000 -out ca.crt

生成 frps 证书:

openssl genrsa -out server.key 2048

openssl req -new -sha256 -key server.key \
    -subj "/C=XX/ST=DEFAULT/L=DEFAULT/O=DEFAULT/CN=server.com" \
    -reqexts SAN \
    -config <(cat my-openssl.cnf <(printf "\n[SAN]\nsubjectAltName=DNS:localhost,IP:127.0.0.1,DNS:example.server.com")) \
    -out server.csr

openssl x509 -req -days 365 \
	-in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
	-extfile <(printf "subjectAltName=DNS:localhost,IP:127.0.0.1,DNS:example.server.com") \
	-out server.crt

生成 frpc 的证书:

openssl genrsa -out client.key 2048
openssl req -new -sha256 -key client.key \
    -subj "/C=XX/ST=DEFAULT/L=DEFAULT/O=DEFAULT/CN=client.com" \
    -reqexts SAN \
    -config <(cat my-openssl.cnf <(printf "\n[SAN]\nsubjectAltName=DNS:client.com,DNS:example.client.com")) \
    -out client.csr

openssl x509 -req -days 365 \
    -in client.csr -CA ca.crt -CAkey ca.key -CAcreateserial \
	-extfile <(printf "subjectAltName=DNS:client.com,DNS:example.client.com") \
	-out client.crt

在本例中，server.crt 和 client.crt 都是由默认 ca 签发的，因此他们对默认 ca 是合法的。

6.负载均衡与健康检查

负载均衡

可以将多个相同类型的代理加入到同一个 group 中，从而实现负载均衡的能力。

目前支持的代理类型：tcp, http, tcpmux

# frpc.ini 
[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 机器挂掉后仍然有其他节点能够提供服务。

tcp 类型代理要求 group_key 相同，做权限验证，且 remote_port 相同。

http 类型代理要求 group_key, custom_domains 或 subdomain 和 locations 相同。

健康检查

通过给代理配置健康检查的参数，可以在要反向代理的服务出现故障时，将这个服务从 frps 中摘除，搭配负载均衡的功能，可以用来实现高可用的架构，避免服务单点故障。

在每一个 proxy 的配置下加上 health_check_type = {type} 来启用健康检查功能。

type 目前可选 tcp 和 http。

tcp 只要能够建立连接则认为服务正常，http 会发送一个 http 请求，服务需要返回 2xx 的状态码才会被认为正常

tcp 示例配置如下：

# 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 示例配置如下：

# 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

7.获取用户真实 IP

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 类型为例:

# 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。

8.范围端口映射

在 frpc 的配置文件中可以指定映射多个端口，目前只支持 TCP 和 UDP 的代理类型。

这一功能通过 range: 段落标记来实现，客户端会解析这个标记中的配置，将其拆分成多个 proxy，每一个 proxy 以数字为后缀命名。

例如要映射本地 6000-6005, 6007 这7个端口，主要配置如下：

# frpc.ini 
[range:test_tcp] 
type = tcp 
local_ip = 127.0.0.1 
local_port = 6000-6005,6007 
remote_port = 6000-6005,6007

实际连接成功后会创建 7 个 proxy，命名为 test_tcp_0, test_tcp_1 ... test_tcp_6。

9.客户端

热加载配置文件

当修改了 frpc 中的代理配置，可以通过 frpc reload 命令来动态加载配置文件，通常会在 10 秒内完成代理的更新。

启用此功能需要在 frpc 中启用 admin 端口，用于提供 API 服务。配置如下：

# frpc.ini 
[common] 
admin_addr = 127.0.0.1 
admin_port = 7400

之后执行重启命令：

frpc reload -c ./frpc.ini

等待一段时间后客户端会根据新的配置文件创建、更新、删除代理。

需要注意的是，[common] 中的参数除了 start 外目前无法被修改。

命令行查看代理状态

frpc 支持通过 frpc status -c ./frpc.ini 命令查看代理的状态信息，此功能需要在 frpc 中配置 admin 端口。

通过代理连接 frps

在只能通过代理访问外网的环境内，frpc 支持通过 HTTP 或 SOCKS5 代理和 frps 建立连接。

可以通过设置 HTTP_PROXY 系统环境变量或者通过在 frpc 的配置文件中设置 http_proxy 参数来使用此功能。

仅在 protocol = tcp 时生效。

# frpc.ini 
[common] 
server_addr = x.x.x.x 
server_port = 7000 
http_proxy = http://user:pwd@192.168.1.128:8080

将 http_proxy 设置为 socks5://user:pwd@192.168.1.128:8080 也可以连接到 SOCKS5 代理。

10.服务端管理

端口白名单

为了防止端口被滥用，可以手动指定允许哪些端口被使用，在服务端配置中通过 allow_ports 来指定：

# frps.ini 
[common] 
allow_ports = 2000-3000,3001,3003,4000-50000

allow_ports 可以配置允许使用的某个指定端口或者是一个范围内的所有端口，以 , 分隔，指定的范围以 - 分隔。

端口复用

目前 frps 中的 vhost_http_port 和 vhost_https_port 支持配置成和 bind_port 为同一个端口，frps 会对连接的协议进行分析，之后进行不同的处理。

例如在某些限制较严格的网络环境中，可以将 bind_port 和 vhost_https_port 都设置为 443。

限速

代理限速

目前支持在客户端的代理配置中设置代理级别的限速，限制单个 proxy 可以占用的带宽。

# frpc.ini 
[ssh] 
type = tcp 
local_port = 22 
remote_port = 6000 
bandwidth_limit = 1MB

在代理配置中增加 bandwidth_limit 字段启用此功能，目前仅支持 MB 和 KB 单位。

11.客户端插件

默认情况下，frpc 只会转发请求到本地 TCP 或 UDP 端口，也就是通过 local_ip 和 local_port 指定的本地服务地址。

通过客户端插件的功能将一些简单的本地服务内置在 frpc 中，可以帮助用户在只启动 frpc 的情况下实现原本需要额外启动其他服务才能实现的功能。

在每一个代理的配置中，通过 plugin 指定需要使用的插件，插件的配置参数都以 plugin_ 开头。当启用客户端插件后，local_ip 和 local_port 不再需要配置。

客户端插件可以被应用在任意类型的代理中，但是需要插件本身的协议能够支持。例如静态文件访问插件可以通过 TCP 或者 HTTP 的代理暴露出去。

使用 http_proxy 插件的示例:

# 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 插件可选的配置参数。

http_proxy

HTTP 代理插件，用于将内网机器作为 HTTP 代理暴露给其他服务，可以通过此代理访问到此内网机器能够访问到的其他服务。

socks5

SOCKS5 代理。

static_file

静态文件浏览服务，通过暴露一个简单的 HTTP 服务查看指定的目录下的文件。

unix_domain_socket

代理本地 Unix 域套接字的服务。

http2https

将本地的 HTTPS 服务以 HTTP 的形式暴露出去。

https2http

将本地的 HTTP 服务以 HTTPS 的形式暴露出去。

https2https

将本地的 HTTPS 服务以 HTTPS 的形式暴露出去。

12.服务端插件

frp 服务端插件的作用是在不侵入自身代码的前提下，扩展 frp 服务端的能力。

frp 服务端插件会以单独进程的形式运行，并且监听在一个端口上，对外提供 RPC 接口，响应 frps 的请求。

frps 在执行某些操作前，会根据配置向服务端插件发送 RPC 请求，根据插件的响应来执行相应的操作。

RPC 请求

服务端插件接收到操作请求后，可以给出三种回应。

• 拒绝操作，需要返回拒绝操作的原因。

• 允许操作，不需要修改操作内容。

• 允许操作，对操作请求进行修改后，返回修改后的内容。

接口

接口路径可以在 frps 配置中为每个插件单独配置，这里以 /handler 为例。

Request

POST /handler?version=0.1.0&op=Login
{
    "content": {
        ... // 具体的操作信息
    }
}

请求 Header
X-Frp-Reqid: 用于追踪请求

Response

非 200 的返回都认为是请求异常。

拒绝执行操作

{
    "reject": true,
    "reject_reason": "invalid user"
}

允许且内容不需要变动

{
    "reject": false,
    "unchange": true
}

允许且需要替换操作内容

{
    "unchange": "false",
    "content": {
        ... // 替换后的操作信息，格式必须和请求时的一致
    }
}

操作类型

目前插件支持管理的操作类型有 Login、NewProxy、Ping、NewWorkConn 和 NewUserConn。

Login

用户登录操作信息

{
    "content": {
        "version": <string>,
        "hostname": <string>,
        "os": <string>,
        "arch": <string>,
        "user": <string>,
        "timestamp": <int64>,
        "privilege_key": <string>,
        "run_id": <string>,
        "pool_count": <int>,
        "metas": map<string>string
    }
}

NewProxy

创建代理的相关信息

{
    "content": {
        "user": {
            "user": <string>,
            "metas": map<string>string
            "run_id": <string>
        },
        "proxy_name": <string>,
        "proxy_type": <string>,
        "use_encryption": <bool>,
        "use_compression": <bool>,
        "group": <string>,
        "group_key": <string>,

        // tcp and udp only
        "remote_port": <int>,

        // http and https only
        "custom_domains": []<string>,
        "subdomain": <string>,
        "locations": <string>,
        "http_user": <string>,
        "http_pwd": <string>,
        "host_header_rewrite": <string>,
        "headers": map<string>string,

        // stcp only
        "sk": <string>,

        // tcpmux only
        "multiplexer": <string>

        "metas": map<string>string
    }
}

Ping

心跳相关信息

{
    "content": {
        "user": {
            "user": <string>,
            "metas": map<string>string
            "run_id": <string>
        },
        "timestamp": <int64>,
        "privilege_key": <string>
    }
}

NewWorkConn

创建工作连接

{
    "content": {
        "user": {
            "user": <string>,
            "metas": map<string>string
            "run_id": <string>
        },
        "run_id": <string>
        "timestamp": <int64>,
        "privilege_key": <string>
    }
}

NewUserConn

创建用户连接 (支持 tcp、stcp、https 和 tcpmux 协议)。

{
    "content": {
        "user": {
            "user": <string>,
            "metas": map<string>string
            "run_id": <string>
        },
        "proxy_name": <string>,
        "proxy_type": <string>,
        "remote_addr": <string>
    }
}

frps 中插件配置

[common] 
bind_port = 7000 

[plugin.user-manager] 
addr = 127.0.0.1:9000 
path = /handler ops = Login 

[plugin.port-manager] 
addr = https://127.0.0.1:9001 
path = /handler 
ops = NewProxy 
tls_verify = true

addr: 插件监听的网络地址，支持 HTTP 和 HTTPS，默认为 HTTP。 path: 插件监听的请求路径。 ops: 插件需要处理的操作列表，多个 op 以英文逗号分隔。 tls_verify: 如果是 HTTPS 协议，支持忽略 TLS 身份验证。

元数据

为了减少 frps 的代码修改，同时提高管理插件的扩展能力，在 frpc 的配置文件中引入自定义元数据的概念。元数据会在调用 RPC 请求时发送给插件。

元数据以 meta_ 开头，可以配置多个，元数据分为两种，一种配置在 common 下，一种配置在各个 proxy 中。

# frpc.ini
[common]
server_addr = 127.0.0.1
server_port = 7000
user = fake
meta_token = fake
meta_version = 1.0.0

[ssh]
type = tcp
local_port = 22
remote_port = 6000
meta_id = 123

13.TCP & UDP

TCP 和 UDP 是 frp 中两种最基础的代理类型，用于代理监听在 TCP 和 UDP 端口的服务。

[ssh] 
type = tcp 
local_ip = 127.0.0.1 
local_port = 22 
remote_port = 6000

通过 type 指定代理类型。

frp 会为本地服务的 22 端口，在 frps 所在的服务端监听 6000 端口，将 6000 端口接收到的连接和本地服务的 22 端口关联，透传流量，从而实现让用户在外部访问到内部服务。

14.HTTP & HTTPS

HTTP 和 HTTPS 是 frp 中针对这两种协议额外提供了一些特殊的能力。本质上目前这两种应用层协议的底层协议都是 TCP。

如果不需要用到相关的特殊功能，可以直接使用 TCP 类型的代理，更加简单方便。

HTTP 和 HTTPS 协议的一个特点是发送的请求都具有 Host 字段，通过该字段描述要访问的服务。基于这个特点，frp 服务端只需要监听在一个端口(通过 vhost_http_port 和 vhost_https_port 指定)。就可以根据请求的 Host 来决定需要路由给哪一个代理，而不需要像 TCP 类型那样为每一个服务绑定一个端口。

修改 HTTP 请求 Header

修改 Host Header

通常情况下 frp 不会修改转发的任何数据。但有一些后端服务会根据 HTTP 请求 header 中的 Host 字段来展现不同的网站，例如 nginx 的虚拟主机服务，启用 Host Header 的修改功能可以动态修改 HTTP 请求中的 Host 字段。需要注意的是，该功能仅限于 HTTP 类型的代理。

# 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。

设置普通 Header

对于类型为 HTTP 的代理，可以设置在转发中动态添加的 Header 参数

# 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。

设置 BasicAuth 鉴权

由于所有客户端共用一个 frps 的 HTTP 服务端口，任何知道你的域名和 URL 的人都能访问到你部署在内网的服务，但是在某些场景下需要确保只有限定的用户才能访问。

frp 支持通过 HTTP Basic Auth 来保护你的 web 服务，使用户需要通过用户名和密码才能访问到你的服务。

该功能目前仅限于 HTTP 类型的代理，需要在 frpc 的代理配置中添加用户名和密码的设置。

# frpc.ini 
[web] 
type = http 
local_port = 80 
custom_domains = test.yourdomain.com 
http_user = abc 
http_pwd = abc

通过浏览器访问 http://test.yourdomain.com，需要输入配置的用户名和密码才能访问。

自定义二级域名

在多人同时使用一个 frps 时，通过自定义二级域名的方式来使用会更加方便。

通过在 frps 的配置文件中配置 subdomain_host，就可以启用该特性。之后在 frpc 的 http、https 类型的代理中可以不配置 custom_domains，而是配置一个 subdomain 参数。

只需要将 *.{subdomain_host} 解析到 frps 所在服务器。之后用户可以通过 subdomain 自行指定自己的 web 服务所需要使用的二级域名，通过 {subdomain}.{subdomain_host} 来访问自己的 web 服务。

# frps.ini 
[common] 
subdomain_host = frps.com

将泛域名 *.frps.com 解析到 frps 所在服务器的 IP 地址。

# frpc.ini 
[web] 
type = http 
local_port = 80 
subdomain = test

frps 和 frpc 都启动成功后，通过 test.frps.com 就可以访问到内网的 web 服务。

注：如果 frps 配置了 subdomain_host，则 custom_domains 中不能是属于 subdomain_host 的子域名或者泛域名。

同一个 HTTP 或 HTTPS 类型的代理中 custom_domains 和 subdomain 可以同时配置。

15.路由

URL 路由

frp 支持根据请求的 URL 路径路由转发到不同的后端服务。

通过配置文件中的 locations 字段指定一个或多个 proxy 能够匹配的 URL 前缀(目前仅支持最大前缀匹配，之后会考虑正则匹配)。例如指定 locations = /news，则所有 URL 以 /news 开头的请求都会被转发到这个服务。

# 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。

16.STCP & SUDP

STCP 和 SUDP 的 (S) 的含义是 Secret。其作用是为 TCP 和 UDP 类型的服务提供一种安全访问的能力，避免让端口直接暴露在公网上导致任何人都能访问到。

这两种代理要求在被访问服务的机器上以及要访问的用户的机器上都部署上 frp 的客户端。被访问的服务所在机器叫做服务端，另一端叫做访问端。

frp 会在访问端监听一个端口和服务端的端口做映射。访问端的用户需要提供相同的密钥才能连接成功，从而保证安全性。

17.XTCP

XTCP 的配置方式和 STCP 很类似。但是会采用 P2P 的方式进行打洞穿透，如果成功，后续的流量将不会经过 frps，而是直接通信，不再受到 frps 所在服务器的带宽限制。

由于打洞成功率较低，所以 XTCP 的可用性和稳定性无法保证。在需要可靠连接的情况下，建议使用 STCP 替代。

18.TCPMUX

frp 支持将单个端口收到的连接路由到不同的代理，类似 vhost_http_port 和 vhost_https_port。

目前支持的复用器只有 httpconnect。

当在 frps.ini 的 [common] 中设置 tcpmux_httpconnect_port，frps 将会监听在这个端口，接收 HTTP CONNECT 请求。

frps 会根据 HTTP CONNECT 请求中的 host 路由到不同的后端代理。

示例配置如下：

# frps.ini 
[common] 
bind_port = 7000 
tcpmux_httpconnect_port = 1337

# 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 。

19.参考

服务端配置

基础配置

权限验证

管理配置

Dashboard, 监控

HTTP & HTTPS

TCPMUX

客户端配置

基础配置

权限验证

UI

代理配置

通用配置

通用配置是指不同类型的代理共同使用的一些配置参数。

基础配置

本地服务配置

local_ip 和 plugin 的配置必须配置一个，且只能生效一个，如果配置了 plugin，则 local_ip 配置无效。

负载均衡和健康检查

TCP

UDP

HTTP

custom_domains 和 subdomain 必须要配置其中一个，两者可以同时生效。

HTTPS

custom_domains 和 subdomain 必须要配置其中一个，两者可以同时生效。

STCP

SUDP

XTCP