通用功能 on frp

配置文件

Mon, 01 Jan 0001 00:00:00 +0000

从 v0.52.0 版本开始，frp 开始支持 TOML、YAML 和 JSON 作为配置文件格式。

请注意，INI 已被弃用，并将在未来的发布中移除。新功能只能在TOML、YAML 或 JSON 中使用。希望使用这些新功能的用户应相应地切换其配置格式。

格式

可使用 TOML/YAML/JSON 任何一个您喜欢的格式来编写配置文件，frp 会自动适配进行解析。

文档示例主要通过 TOML 编写，如下的示例配置将本地 SSH 服务穿透到公网。

frps 配置：

bindPort = 7000

frpc 配置：

serverAddr = "x.x.x.x"
serverPort = 7000

[[proxies]]
name = "ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = 6000

同一个客户端可以配置多个代理，但是 name 必须确保唯一。

不同的客户端之间，可以通过配置不同的 user 来确保代理名称唯一。

模版渲染

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

示例配置如下：

serverAddr = "{{ .Envs.FRP_SERVER_ADDR }}"
serverPort = 7000

[[proxies]]
name = "ssh"
type = "tcp"
localIP = "127.0.0.1"
localPort = 22
remotePort = {{ .Envs.FRP_SSH_REMOTE_PORT }}

启动 frpc 程序：

export FRP_SERVER_ADDR="x.x.x.x"
export FRP_SSH_REMOTE_PORT="6000"
./frpc -c ./frpc.toml

frpc 会自动使用环境变量渲染配置文件模版，所有环境变量需要以 .Envs 为前缀。

监控

Mon, 01 Jan 0001 00:00:00 +0000

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

内存监控

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

请注意，内存中的监控数据在每次重启进程后会被清空，或者保留 7 天。监控数据可以通过 Dashboard 的地址发送 HTTP 请求获取，但目前此 API 尚不规范，不建议直接使用。

Prometheus 监控

由于设计问题，Prometheus 对外提供的查询接口与 Dashboard 的地址重用，因此要使用 Prometheus 监控，必须首先启用 Dashboard。

在 frps.toml 中启用 Dashboard 并设置 enablePrometheus = true，然后你可以通过访问 http://{dashboard_addr}/metrics 来获取 Prometheus 的监控数据。

身份认证

Mon, 01 Jan 0001 00:00:00 +0000

目前 frpc 和 frps 之间支持两种身份验证方式，token 和 oidc，默认为 token。这些认证方式允许您验证客户端与服务端之间的通信，并确保只有授权用户能够建立连接。

Token

Token 身份认证是一种简单的身份认证方式，只需要在 frp 的客户端 frpc 和服务端 frps 配置文件中配置相同的 token 即可。

配置示例

# frps.toml
bindPort = 7000
auth.token = "abc"

# frpc.toml
auth.token = "abc"

从文件加载 Token

Added in v0.64.0

frp 支持使用 tokenSource 从文件中加载认证 token，而不是在配置文件中硬编码。这个功能可以避免在配置文件中直接暴露敏感信息。

配置方式

tokenSource 与 token 字段互斥，只能选择其中一种方式配置。

服务端配置示例：

# frps.toml
bindPort = 7000
auth.tokenSource.type = "file"
auth.tokenSource.file.path = "/etc/frp/server_token"

客户端配置示例：

# frpc.toml
auth.tokenSource.type = "file"
auth.tokenSource.file.path = "/etc/frp/client_token"

注意事项

token 文件应该设置适当的权限（如 600），确保只有运行 frp 的用户可以读取
文件中的 token 会自动去除首尾空白字符
tokenSource 在配置加载时解析，不支持运行时动态重新加载

通过外部命令获取 Token

Added in v0.66.0

Web 界面

Mon, 01 Jan 0001 00:00:00 +0000

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

服务端 Dashboard

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

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

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

# 默认为 127.0.0.1，如果需要公网访问，需要修改为 0.0.0.0。
webServer.addr = "0.0.0.0"
webServer.port = 7500
# dashboard 用户名密码，可选，默认为空
webServer.user = "admin"
webServer.password = "admin"

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

你也可以通过配置 TLS 证书来启用 HTTPS 接口:

webServer.tls.certFile = "server.crt"
webServer.tls.keyFile = "server.key"

客户端管理界面

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

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

# frpc.toml
webServer.addr = "127.0.0.1"
webServer.port = 7400
webServer.user = "admin"
webServer.password = "admin"

打开浏览器通过 http://127.0.0.1:7400 访问 Admin UI。

负载均衡与健康检查

Mon, 01 Jan 0001 00:00:00 +0000

负载均衡

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

目前支持的代理类型包括：tcp, http, https, tcpmux。

# frpc.toml
[[proxies]]
name = "test1"
type = "tcp"
localPort = 8080
remotePort = 80
loadBalancer.group = "web"
loadBalancer.groupKey = "123"

[[proxies]]
name = "test2"
type = "tcp"
localPort = 8081
remotePort = 80
loadBalancer.group = "web"
loadBalancer.groupKey = "123"

当用户连接 frps 服务器的 80 端口时，frps 会将接收到的用户连接随机分发给其中一个存活的代理。这可以确保即使一台 frpc 机器挂掉，仍然有其他节点能够提供服务。

对于 tcp 类型代理，需要确保 groupKey 相同以进行权限验证，同时 remotePort 也需一致。

对于 http 类型代理，需要保证 groupKey, customDomains(自定义域名)，subdomain 和 locations 相同。

健康检查

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

要启用健康检查功能，需要在每个代理的配置中添加 healthCheck.type = {type}。

目前支持的类型有 tcp 和 http。

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

以下是 tcp 示例配置：

获取用户真实 IP

Mon, 01 Jan 0001 00:00:00 +0000

HTTP X-Forwarded-For

目前只有 http 类型的代理或者启用了 https2http 或 https2https 插件的代理支持这一功能。

可以通过 HTTP 请求 header 中的 X-Forwarded-For 来获取用户真实 IP，默认启用。

Proxy Protocol

frp 支持通过 Proxy Protocol 协议来传递经过 frp 代理的请求的真实 IP。

Proxy Protocol 功能启用后，frpc 在和本地服务建立连接后，会先发送一段 Proxy Protocol 的协议内容给本地服务，本地服务通过解析这一内容可以获得访问用户的真实 IP。所以不仅仅是 HTTP 服务，任何的 TCP 服务，只要支持这一协议，都可以获得用户的真实 IP 地址。

UDP 代理类型也支持 Proxy Protocol 功能，能够保留真实客户端 IP 地址。

需要注意的是，在代理配置中如果要启用此功能，需要本地的服务能够支持 Proxy Protocol 这一协议，目前 nginx 和 haproxy 都能够很好的支持。

TCP/HTTPS 代理示例

这里以 HTTPS 类型为例:

# frpc.toml
[[proxies]]
name = "web"
type = "https"
localPort = 443
customDomains = ["test.yourdomain.com"]

# 目前支持 v1 和 v2 两个版本的 proxy protocol 协议。
transport.proxyProtocolVersion = "v2"

只需要在代理配置中增加一行 transport.proxyProtocolVersion = "v2" 即可开启此功能。

端口范围映射

Mon, 01 Jan 0001 00:00:00 +0000

Added in v0.56.0

我们可以利用 Go template 的 range 语法结合内置的 parseNumberRangePair 函数来实现端口范围映射。

下面的示例，应用运行后会创建 8 个代理，名称为 test-6000, test-6001 ... test-6007，分别将远端的端口映射到本地。

{{- range $_, $v := parseNumberRangePair "6000-6006,6007" "6000-6006,6007" }}
[[proxies]]
name = "tcp-{{ $v.First }}"
type = "tcp"
localPort = {{ $v.First }}
remotePort = {{ $v.Second }}
{{- end }}

客户端

Mon, 01 Jan 0001 00:00:00 +0000

动态配置更新

当你需要修改 frpc 的代理配置时，你可以使用 frpc reload 命令来实现动态加载配置文件，通常在数秒内完成代理的更新。

要启用此功能，需要在 frpc 中启用 webServer，以提供 API 服务。配置如下：

webServer.addr = "127.0.0.1"
webServer.port = 7400

然后执行以下命令来重载配置：

frpc reload -c ./frpc.toml

等待一段时间后，客户端将根据新的配置文件创建、更新或删除代理。需要注意的是，非代理相关的公共部分的参数除了 start 外目前无法被修改。

命令行查看代理状态

frpc 支持通过 frpc status -c ./frpc.toml 命令查看代理的状态信息，此功能需要在 frpc 中启用 webServer。

使用代理连接 frps

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

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

仅在 transport.protocol = "tcp" 时生效。

serverAddr = "x.x.x.x"
serverPort = 7000
transport.proxyURL = "http://user:pwd@192.168.1.128:8080"

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

服务端管理

Mon, 01 Jan 0001 00:00:00 +0000

端口白名单

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

# frps.ini
allowPorts = [
  { start = 2000, end = 3000 },
  { single = 3001 },
  { single = 3003 },
  { start = 4000, end = 50000 }
]

allowPorts 可以配置允许使用的某个指定端口或者是一个范围内的所有端口。

端口复用

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

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

需要注意的是，如果你想将 vhostHTTPSPort 和 bindPort 配置为相同的端口，需要首先将 transport.tls.disableCustomTLSFirstByte 设置为false。

限速

代理限速

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

# frpc.toml
[[proxies]]
name = "ssh"
type = "tcp"
localPort = 22
remotePort = 6000
transport.bandwidthLimit = "1MB"

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

限速能力默认在客户端实现，如果希望启用服务端限速，需要额外配置 transport.bandwidthLimitMode = "server"。

客户端插件

Mon, 01 Jan 0001 00:00:00 +0000

默认情况下，frpc 仅会将请求转发到本地 TCP 或 UDP 端口，即通过 localIP 和 localPort 指定的本地服务地址。

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

在每个代理的配置中，你可以通过 plugin 来配置要使用的插件和相关参数。启用客户端插件后，无需再配置 localIP 和 localPort。

客户端插件可用于各种类型的代理，前提是插件本身支持的协议。例如，静态文件访问插件可以通过 TCP 或 HTTP 代理进行暴露。

以下是使用 http_proxy 插件的示例：

[[proxies]]
name = "http_proxy"
type = "tcp"
remotePort = 6000
[proxies.plugin]
type = "http_proxy"
httpUser = "abc"
httpPassword = "abc"

httpUser 和 httpPassword 即为 http_proxy 插件可选的配置参数。

其他插件和相关配置请参考 Reference 中的内容。

服务端插件

Mon, 01 Jan 0001 00:00:00 +0000

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、CloseProxy、Ping、NewWorkConn 和 NewUserConn。

SSH Tunnel Gateway

Mon, 01 Jan 0001 00:00:00 +0000

Added in v0.53.0

概念

SSH 支持反向代理能力 rfc。

frp 支持在 frps 端监听一个 ssh 端口，通过走 ssh -R 协议来完成 TCP 协议代理，该模式下不需要依赖 frpc。

SSH 反向隧道代理和通过 frp 代理 SSH 端口是不同的 2 个概念。SSH 反向隧道代理本质上是在你不想使用 frpc 的时候，通过 ssh client 连接 frps 来完成基本的反向代理。

参数

# frps.toml

sshTunnelGateway.bindPort = 0
sshTunnelGateway.privateKeyFile = ""
sshTunnelGateway.autoGenPrivateKeyPath = ""
sshTunnelGateway.authorizedKeysFile = ""

Field	Type	Description	Required
bindPort	int	frps 监听的 ssh server 端口。	YES
privateKeyFile	string	默认为空。ssh server 使用的私钥文件，为空frps会读取 autoGenPrivateKeyPath 路径下的私钥文件。可复用本地 /home/user/.ssh/id_rsa 文件或自定义路径。	No
autoGenPrivateKeyPath	string	默认为 ./.autogen_ssh_key。文件不存在或内容为空，frps会自动生成 RSA 私钥文件内容存入该文件。	No
authorizedKeysFile	string	默认为空。空不对ssh客户端进行鉴权认证。不空可实现ssh免密登录认证，可复用本地 /home/user/.ssh/authorized_keys 文件或自定义路径。	No

基本使用

服务端 frps

最简配置

虚拟网络 (VirtualNet)

Mon, 01 Jan 0001 00:00:00 +0000

Alpha feature, added in v0.62.0

注意：VirtualNet 是一个 Alpha 阶段的特性，目前不稳定，其配置方式和功能可能会在后续版本中随时调整变更。请勿在生产环境中使用此功能，仅建议用于测试和评估目的。

概述

虚拟网络（VirtualNet）功能允许 frp 通过 TUN 接口创建和管理客户端之间的虚拟网络连接。这一功能将 frp 的能力扩展到了传统端口转发之外，实现了完整的网络层通信。

通过 VirtualNet 功能，你可以：

在不同客户端之间建立 IP 层级的网络连接，不需要为每个服务单独配置端口转发
使应用程序无需感知 frp 的存在，直接通过 IP 访问远程服务
建立类似 VPN 的连接，但由 frp 负责管理

使用要求

使用 VirtualNet 功能需要满足以下条件：

权限要求：创建 TUN 接口需要 root/管理员权限
平台支持：目前仅支持 Linux 和 macOS 平台
特性门控：需要通过配置 featureGates = { VirtualNet = true } 显式启用
地址分配：每个端点必须配置唯一的 IP 地址/CIDR

配置方法

启用 VirtualNet

由于 VirtualNet 是 Alpha 特性，需要在配置中显式启用：

# frpc.toml
featureGates = { VirtualNet = true }

服务端配置

首先，为 frpc 配置虚拟网络地址：