frp 配置踩坑记：官方文档的 TOML 配置语法陷阱

行止95
4 阅读4分钟

前言

最近在项目中需要使用 frp 进行内网穿透，服务端我选择了使用宝塔面板部署（非 Docker 方案）。本以为按照官方教程一步步操作就能顺利完成，没想到在部署客户端的过程中却遇到了各种问题，折腾了好久才解决。今天就把这次踩坑的经历分享给大家，希望能帮到同样遇到这个问题的朋友。

什么是 frp？

在开始之前，先简单介绍一下 frp。frp（Fast Reverse Proxy）是一个高性能的反向代理应用，主要用于内网穿透。简单来说，它可以帮助你从公网访问内网中的服务，非常适合开发测试、远程办公等场景。

遇到的问题

按照官方教程（gofrp.org/zh-cn/docs/…

踩坑记录

官方文档的配置陷阱

虽然官方文档中给出了 TOML 格式的配置文件示例，但是其语法存在错误，不能直接使用。这一点对于新手来说非常容易踩坑，因为你会认为官方文档肯定是正确的，结果照搬之后却发现无法运行。

错误的配置示例

serverAddr = "x.x.x.x"
serverPort = 7000
# 如果默认的 STUN 服务器不可用，可以配置一个新的 STUN 服务器
# natHoleStunServer = "xxx"

[[visitors]]
name = "p2p_ssh_visitor"
type = "xtcp"
# 要访问的 P2P 代理的名称
serverName = "p2p_ssh"
secretKey = "abcdefg"
# 绑定本地端口以访问 SSH 服务
bindAddr = "127.0.0.1"
bindPort = 6000
# 如果需要自动保持隧道打开，将其设置为 true
# keepTunnelOpen = false

这段配置看起来没什么问题，但实际上存在语法错误，导致 frp 客户端无法正确解析。

正确的配置方式

经过多次尝试和查阅资料，我找到了正确的配置方式。关键在于使用正确的 TOML 语法结构：

[common]
server_addr = "你的服务器IP"
server_port = 7500
user = "local_server"

[common.auth]
method = "token"
token = "你的认证token"

[common.log]
file_path = "./frpc.log"
level = "info"
max_days = 7
disable_color = true

[common.transport]
protocol = "tcp"
tcp_mux = true
heartbeat_interval = -1
tcp_mux_keepalive_interval = 30

[[proxies]]
name = "local_web"
type = "tcp"
local_ip = "127.0.0.1"
local_port = 8080
remote_port = 8081
pool_count = 5

配置详解

基础配置

  • [common]：通用配置段
  • server_addr：frp 服务器的 IP 地址
  • server_port：frp 服务器的监听端口
  • user：客户端标识，用于区分不同的客户端

认证配置

  • [common.auth]：认证配置段
  • method：认证方式，这里使用 token
  • token：认证密钥，需要与服务端配置一致

日志配置

  • [common.log]：日志配置段
  • file_path：日志文件路径
  • level：日志级别（info/debug/warn/error）
  • max_days：日志保留天数
  • disable_color：是否禁用彩色日志

传输配置

  • [common.transport]：传输配置段
  • protocol：传输协议，通常使用 tcp
  • tcp_mux：是否启用 TCP 多路复用
  • heartbeat_interval：心跳间隔，-1 表示使用默认值
  • tcp_mux_keepalive_interval：TCP 多路复用保活间隔

代理配置

  • [[proxies]]：代理配置段（注意是双中括号，表示数组）
  • name：代理名称，需要唯一
  • type：代理类型（tcp/http/https 等）
  • local_ip：本地服务 IP 地址
  • local_port：本地服务端口
  • remote_port：远程访问端口
  • pool_count：连接池大小

关键要点总结

  1. 注意 TOML 语法：TOML 格式要求使用点号（.）来表示嵌套结构，而不是直接写在一起
  2. 使用正确的配置段：基础配置要放在 [common] 段下，子配置使用 [common.xxx] 的格式
  3. 数组配置使用双中括号：如 [[proxies]] 表示这是一个数组，可以配置多个代理

结语

这次 frp 配置的经历让我深刻体会到，即使是官方文档也可能存在错误（我也不知道是不是错误，总之是不对的结果，也可能呢有别的问题，如果有错误，欢迎评论给我和大家说明） ，作为开发者我们需要保持怀疑精神，遇到问题时要善于排查和验证。希望这篇文章能帮助到正在使用 frp 的朋友们，少走一些弯路。

作者：行止 日期：2026-01-17 版本：1.0

avatar
文章
阅读
粉丝