/zh-cn/docs/features/common/ Recent content in 通用功能 on frp Hugo zh-cn /zh-cn/docs/features/common/configure/ Mon, 01 Jan 0001 00:00:00 +0000 /zh-cn/docs/features/common/configure/ 从 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. /zh-cn/docs/features/common/monitor/ Mon, 01 Jan 0001 00:00:00 +0000 /zh-cn/docs/features/common/monitor/ 目前，frps 服务端支持两种监控系统：内存监控和 Prometheus 监控。 内存监控 内存中存储的监控数据主要用于 Dashboard 展示。当在 frps 配置中开启 Dashboard 功能后，内存监控默认启用。 请注意，内存中的监控数据在每次重启进程后会被清空，或者保留 7 天。监控数据可以通过 Dashboard 的地址发送 HTTP 请求获取，但目前此 API 尚不规范，不建议直接使用。 Prometheus 监控 由于设计问题，Prometheus 对外提供的查询接口与 Dashboard 的地址重用，因此要使用 Prometheus 监控，必须首先启用 Dashboard。 在 frps.toml 中启用 Dashboard 并设置 enablePrometheus = true，然后你可以通过访问 http://{dashboard_addr}/metrics 来获取 Prometheus 的监控数据。 /zh-cn/docs/features/common/authentication/ Mon, 01 Jan 0001 00:00:00 +0000 /zh-cn/docs/features/common/authentication/ 目前 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. /zh-cn/docs/features/common/ui/ Mon, 01 Jan 0001 00:00:00 +0000 /zh-cn/docs/features/common/ui/ 目前 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 状态和配置。 /zh-cn/docs/features/common/load-balancer/ Mon, 01 Jan 0001 00:00:00 +0000 /zh-cn/docs/features/common/load-balancer/ 负载均衡 你可以将多个相同类型的代理加入到同一个 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 相同。 /zh-cn/docs/features/common/realip/ Mon, 01 Jan 0001 00:00:00 +0000 /zh-cn/docs/features/common/realip/ 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. /zh-cn/docs/features/common/range/ Mon, 01 Jan 0001 00:00:00 +0000 /zh-cn/docs/features/common/range/ 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 }} /zh-cn/docs/features/common/client/ Mon, 01 Jan 0001 00:00:00 +0000 /zh-cn/docs/features/common/client/ 动态配置更新 当你需要修改 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. /zh-cn/docs/features/common/server-manage/ Mon, 01 Jan 0001 00:00:00 +0000 /zh-cn/docs/features/common/server-manage/ 端口白名单 为了防止端口被滥用，可以手动指定允许哪些端口被使用，在服务端配置中通过 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. /zh-cn/docs/features/common/client-plugin/ Mon, 01 Jan 0001 00:00:00 +0000 /zh-cn/docs/features/common/client-plugin/ 默认情况下，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 中的内容。 /zh-cn/docs/features/common/server-plugin/ Mon, 01 Jan 0001 00:00:00 +0000 /zh-cn/docs/features/common/server-plugin/ 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。 /zh-cn/docs/features/common/ssh/ Mon, 01 Jan 0001 00:00:00 +0000 /zh-cn/docs/features/common/ssh/ 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 默认为 . /zh-cn/docs/features/common/virtualnet/ Mon, 01 Jan 0001 00:00:00 +0000 /zh-cn/docs/features/common/virtualnet/ 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 配置虚拟网络地址：