frp TCP隧道 + Nginx Proxy Protocol V2 透传真实访客IP完整实践

frp TCP隧道 + Nginx Proxy Protocol V2 透传真实访客IP完整实践

前言

很多人在用 frp 的 TCP 类型内网穿透部署 Web 服务时,都会遇到同一个痛点:后端拿到的客户端IP永远是 127.0.0.1,日志、登录风控、访问统计全部失效。 如果用 frp 的 HTTP 代理模式,会受限于 Host、路径、Header 的各种限制,对前后端分离、Headless CMS 项目(比如我自研的 VibePressPro,NestJS+Nuxt)并不友好。

Proxy Protocol(代理协议)就是这个场景下的最优解:frpc 在建立 TCP 连接时,先发送一段二进制协议头,把访客真实IP+端口信息提前给到 Nginx,Nginx 解析后再把真实IP通过 X-Real-IP / X-Forwarded-For 传给后端服务。

本文是我自己跑通 VibePressPro 生产隧道后的落地总结,包含完整可直接复制的 frpc.toml + Nginx 配置、原理讲解、版本要求、踩坑清单、验证方案。

架构简述:访客公网访问 frps → frps 转发给本机 frpc → frpc 携带 Proxy Protocol v2 包头连接 Nginx → Nginx 解析包头拿到真实IP → 反向代理到 NestJS 后端服务 127.0.0.1:3009

一、版本前置要求(非常关键)

transport.proxyProtocolVersion 这个配置项,frp 从 v0.44.0 版本才正式加入主线,低于这个版本的 frpc 不支持该参数,配置直接报错。

  • 推荐使用:frp >= 0.52.0,官方主推 TOML/YAML 格式,INI 格式逐步废弃

  • frps 和 frpc 版本尽量接近,新frpc搭配老frps一般没问题,反向不推荐

  • Nginx:需要编译包含 ngx_http_realip_module,主流发行版(Debian/Ubuntu/CentOS)自带,无需额外编译

查看frpc版本命令:

./frpc --version

二、完整配置文件

2.1 frpc.toml 客户端配置

[[proxies]]
name = "server-prod"
type = "tcp"
localIP = "127.0.0.1"
localPort = 8011
remotePort = 3009
transport.proxyProtocolVersion = "v2"

参数说明:

  • type = "tcp":纯TCP隧道,不使用frp内置HTTP处理

  • localPort = 8011:frpc连接本机Nginx的端口,Nginx监听8011并开启proxy_protocol

  • remotePort = 3009:frps公网服务器对外暴露的端口,用户访问 公网IP:3009 进入隧道

  • transport.proxyProtocolVersion = "v2":开启v2版本Proxy Protocol,二进制格式,支持IPv4/IPv6

2.2 Nginx 配置(nginx.conf / sites-available 站点配置)

server {
    listen 8011 proxy_protocol;
    listen [::]:8011 proxy_protocol;
    set_real_ip_from 127.0.0.1;
    real_ip_header proxy_protocol;
    real_ip_recursive on;

    location / {
        proxy_pass [http://127.0.0.1:3009](http://127.0.0.1:3009);
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

逐行解析:

  1. listen 8011 proxy_protocol;:这个端口强制要求所有TCP连接必须先发Proxy Protocol包头,没有包头的普通HTTP请求会直接返回 400 Bad Request(这是最容易踩的坑)

  2. listen [::]:8011 proxy_protocol; 同时监听IPv4 + IPv6

  3. set_real_ip_from 127.0.0.1;:信任来源限制,只信任本机127.0.0.1发来的proxy协议头,防止伪造IP,安全至关重要

  4. real_ip_header proxy_protocol;:指定从proxy protocol包头提取真实IP

  5. real_ip_recursive on;:多层代理递归解析IP

  6. 三个proxy_set_header:把解析后的真实IP传递给NestJS/Nuxt后端,后端读取 X-Real-IP 拿到访客地址

三、核心原理:为什么加上 proxy_protocol 就不能浏览器直接访问 8011?

这是很多新手卡很久的地方:

  • 只要 listen 端口 proxy_protocol; 生效,Nginx对这个端口上所有TCP连接,第一件事就是等待客户端发送一段Proxy Protocol包头,读完包头之后,才会继续解析后面的HTTP报文。

  • 浏览器、curl 这类标准HTTP客户端,建立TCP连接之后,直接发送 GET / HTTP/1.1,不会发送proxy协议包头。Nginx一直等待包头超时,直接返回 400 Bad Request。

  • 只有开启了 transport.proxyProtocolVersion = "v2" 的frpc,在连接Nginx 8011端口的瞬间,主动先发送v2二进制包头,Nginx才能正常解析、继续处理HTTP流量。

✅ 结论:8011端口是专门给frpc隧道使用的端口,不支持浏览器直接访问,属于预期现象,不是故障。

如果你需要局域网本地调试网站,单独新增一套不带 proxy_protocol 的Nginx server块,监听另一个端口(例如8012),专门内网调试,两套隔离互不干扰。

内网调试配套示例(可选,加到nginx):

# 局域网调试专用,无proxy_protocol,浏览器可以直接访问
server {
    listen 8012;
    listen [::]:8012;
    location / {
        proxy_pass [http://127.0.0.1:3009](http://127.0.0.1:3009);
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

四、启动顺序 & 校验命令(按顺序执行)

4.1 校验Nginx配置语法

nginx -t

输出 test is successful 才代表语法没问题,然后重载配置

nginx -s reload

4.2 查看端口监听状态

ss -ltnp | grep :8011

确认 nginx 进程监听 0.0.0.0:8011

4.3 启动顺序(很重要,避免连接失败)

  1. 启动后端服务(NestJS/VibePressPro,监听127.0.0.1:3009)

  2. 启动 Nginx

  3. 启动 frpc

4.4 验证真实IP是否透传成功

访问公网隧道,查看后端(NestJS)日志:

  • ✅ 成功:日志里拿到的IP是访客公网IP

  • ❌ 失败:日志IP是 127.0.0.1,说明proxy protocol链路没有生效

五、避坑清单(踩过的坑汇总)

  1. 防火墙放行区分:本机8011端口只给127.0.0.1的frpc连接,本机防火墙不需要对外放行8011;只需要在frps公网服务器的安全组/防火墙放行 remotePort(本例3009)

  2. 不要在同一个listen同时写 proxy_protocol; ssl;,逻辑容易混乱,SSL证书建议放到frps侧,或者单独另起Nginx服务处理HTTPS

  3. set_real_ip_from 一定要精准限制信任源,不要写 0.0.0.0/0,否则恶意客户端可以伪造任意IP,带来安全风险

  4. 隧道连通但是一直400:优先排查两点:frpc版本过低、frpc配置忘记写 transport.proxyProtocolVersion = "v2"

  5. 后端拿不到 X-Forwarded-Proto:后续上HTTPS的时候,注意SSL终结位置,协议头由SSL终结点负责传递

六、适用场景

这套方案非常适合我这种自研Headless CMS、全栈项目:NestJS后端 + Nuxt SSR前端,不希望被frp内置HTTP代理的各种限制束缚,同时又要保留访客真实IP用于日志、风控、访问统计。 不限于Web,所有支持Proxy Protocol的TCP服务都可以复用这套方案。

七、结语

对比HTTP代理、XFF头伪造IP等方案,Proxy Protocol 四层透传真实IP是TCP隧道场景下最干净、稳定的方案。代价就是端口需要隔离:隧道专用端口带proxy_protocol,本地调试端口不带,做好端口职责划分,就能稳定长期跑生产。

评论 (0)

暂无评论,来抢占沙发吧~