在Spring Boot项目里获取真实客户端IP大概是所有后端开发都会踩的坑之一。你以为request.getRemoteAddr()拿到的就是用户IP等你把项目丢到Nginx后面再打印出来看看十有八九拿到的全是127.0.0.1或者内网网关地址。这个问题看起来只是几行代码的事但牵涉HTTP代理链、反向代理配置、安全边界、IPv6兼容一堆细节真能把人绕晕。这篇文章我直接把我多年踩坑后沉淀下来的完整方案写出来工具类怎么写、过滤器怎么接、Nginx和网关怎么配、IP被伪造怎么办一条龙全部讲透照着抄就能用。1. 为什么获取真实客户端IP是个“坑”1.1 从“这不是我的IP”说起先说个我自己遇到的场景。几年前给一个商城系统做订单风控模块本机联调一切都正常用户IP精确到地市。结果一部署到测试环境所有订单的IP全部变成了127.0.0.1线上更是直接变成了一堆内网地址。排查了大半天发现测试环境前面挂了Nginx做反向代理而代码里用的正是request.getRemoteAddr()。技术原理其实一句话就能讲透getRemoteAddr()返回的是当前TCP连接对端的IP地址。如果你的服务直接被浏览器访问那对端就是用户电脑拿到的自然是真实IP但只要中间有任何一层代理后端服务建立的TCP连接对端就是那台代理服务器拿到的是代理的内网IP跟用户一毛钱关系都没有。我习惯把这个过程类比成快递中转。你从网上下单包裹从卖家手里发出经过一个又一个中转站才送到你手上。如果你只看最后一段运输记录的“发件人”看到的永远是最后一个中转站而不是真实的发货人。所以核心结论先记住只要项目部署在反向代理、负载均衡、CDN后面就必须依赖代理转发过来的请求头来还原真实IP不能直接信getRemoteAddr()。1.2 X-Forwarded-For不是魔法它是接力棒解决“最后一跳看不到真实IP”问题的标准做法是让每一层代理把自己看到的客户端IP追加到X-Forwarded-For简称XFF请求头里。XFF的格式长这样X-Forwarded-For: 2001:db8::1, 10.0.0.2, 10.0.0.10第一个IP是最初发起请求的客户端IP后面依次是每一层代理服务器的IP。整个链路是这样的客户端发出请求没有携带XFF头第一层代理比如CDN收到请求后追加客户端IP第二层代理比如Nginx收到后追加第一层代理的IP后端服务最终看到的XFF里就包含了从客户端到最近一跳的完整链路。注意一个关键细节每一层代理在使用XFF之前还应该先检查一下客户端是否自己伪造了XFF头。如果客户端直接伪造了一个X-Forwarded-For: 8.8.8.8发过来代理的正确做法是把客户端IP追加在真实IP的位置而不是保留伪造值。但现实中很多代理默认就是简单拼接这也是后面安全章节要重点处理的问题。1.3 真实链路中的三个标准头在实战中你会反复跟三个头打交道我整理了一张对照表方便你一眼看清各自职责请求头格式来源特点与局限X-Forwarded-For逗号分隔的IP列表每层代理向后追加信息最全但最容易被伪造X-Real-IP单个IPNginx等特定代理设置只记录上一跳看到的IP非通用标准Forwarded结构化语法RFC 7239标准头规范但普及率低老设备不认很多人一上来就取XFF的第一个IP当作真实客户端IP。这个策略只在单层代理时有效放到CDNSLBNginx这种多级链路里就会翻车。因为客户端完全可以在请求里手动塞一个假的XFF头如果代理不做覆盖处理第一个IP就是完全可控的伪造值。所以真正可靠的做法不是“从左往右取第一个”而是从右往左跳过所有你自己信任的代理IP找到第一个不在可信列表里的IP。这个思路是整个方案的核心我后面会给出完整代码实现。2. 终极方案可信代理链IP解析工具2.1 方案设计思路不是取第一个而是信任最后一跳有了上面的原理设计思路就很清晰了要知道哪个IP可信必须先定义“可信代理范围”。什么意思呢假设你的架构是用户 - CDN - SLB - Nginx - Spring Boot服务。那对于后端服务来说这条链路里从右往左数Nginx是可信的SLB是可信的CDN也是可信的因为它们都是你自己的基础设施它们追加的IP是真实转发的。但再往左的第一个IP就应该是原始客户端了因为外部用户你控制不了。但如果是用户 - 公共代理 - 你的服务那这个公共代理是不可信的它写的XFF可以随便伪造。这时候如果还按“跳过可信代理”来取可能取到一个中间代理的IP甚至取到伪造值。我习惯用小区门禁来类比你住的小区有保安门禁保安登记访客信息是你信任的但路边随便一个陌生人告诉你“刚进来的人是某某某”你就得掂量掂量。同理代理链可信代理链上的记录才可信。2.2 完整工具类代码直接上干货。下面这个IpUtils工具类是我目前用过最稳的版本兼顾了XFF解析、可信代理跳过、IPv6和localhost处理import jakarta.servlet.http.HttpServletRequest; import org.springframework.util.StringUtils; import java.net.InetAddress; import java.net.UnknownHostException; import java.util.ArrayList; import java.util.List; public class IpUtils { private static final String UNKNOWN unknown; private static final String LOCALHOST_IPV4 127.0.0.1; private static final String LOCALHOST_IPV6 0:0:0:0:0:0:0:1; private static final String LOCALHOST_IPV6_SHORT ::1; /** * 可信代理IP前缀列表由Spring配置注入。 * 支持精确IP、IP前缀和IPv4网段简写如10.0.0.0/8 */ private static volatile ListString trustedProxyPrefixes new ArrayList(); private static volatile ListString trustedProxyCidrs new ArrayList(); private IpUtils() { } public static void setTrustedProxies(ListString proxies) { ListString prefixes new ArrayList(); ListString cidrs new ArrayList(); for (String p : proxies) { p p.trim(); if (p.contains(/)) { cidrs.add(p); } else { prefixes.add(p); } } trustedProxyPrefixes prefixes; trustedProxyCidrs cidrs; } public static String getClientIp(HttpServletRequest request) { String remoteAddr request.getRemoteAddr(); String xff request.getHeader(X-Forwarded-For); if (StringUtils.hasText(xff) !UNKNOWN.equalsIgnoreCase(xff)) { String[] ips xff.split(,); // 从右往左跳过所有可信代理找到第一个外部IP for (int i ips.length - 1; i 0; i--) { String ip ips[i].trim(); if (isUnknown(ip)) { continue; } if (!isTrustedProxy(ip)) { return normalizeIp(ip); } } } // 没有XFF或者XFF里全是可信IP时直接返回remoteAddr return normalizeIp(remoteAddr); } private static boolean isUnknown(String ip) { return !StringUtils.hasText(ip) || UNKNOWN.equalsIgnoreCase(ip); } private static boolean isTrustedProxy(String ip) { if (LOCALHOST_IPV4.equals(ip) || LOCALHOST_IPV6.equals(ip) || LOCALHOST_IPV6_SHORT.equals(ip)) { return true; } for (String prefix : trustedProxyPrefixes) { if (ip.startsWith(prefix)) { return true; } } for (String cidr : trustedProxyCidrs) { if (isIpInCidr(ip, cidr)) { return true; } } return false; } private static boolean isIpInCidr(String ip, String cidr) { try { String[] parts cidr.trim().split(/); int prefixLen Integer.parseInt(parts[1]); InetAddress addr InetAddress.getByName(ip); InetAddress networkAddr InetAddress.getByName(parts[0]); byte[] addrBytes addr.getAddress(); byte[] networkBytes networkAddr.getAddress(); if (addrBytes.length ! networkBytes.length) { return false; } int fullBytes prefixLen / 8; int remainingBits prefixLen % 8; for (int i 0; i fullBytes; i) { if (addrBytes[i] ! networkBytes[i]) { return false; } } if (remainingBits 0) { int mask 0xFF (8 - remainingBits); int b indexByte(addrBytes, fullBytes); int n indexByte(networkBytes, fullBytes); if ((b mask) ! (n mask)) { return false; } } return true; } catch (Exception e) { return false; } } private static int indexByte(byte[] array, int i) { return array[i] 0xFF; } /** * 统一IPv6和IPv4的本地地址表示 */ private static String normalizeIp(String ip) { if (ip null) { return ; } if (LOCALHOST_IPV6.equals(ip)) { return LOCALHOST_IPV4; } return ip; } }这段代码的核心逻辑在getClientIp方法里先从右往左解析XFF跳过可信代理IP找到第一个外部IP如果XFF不存在或者全是可信IP就返回getRemoteAddr()。很多人会问为什么要从右往左因为XFF里越往右的IP离服务端越近。离得越近经过的可信代理层数越多被伪造的难度也越高。如果直接把左边的IP拿来当用户IP敌人只需要发一个X-Forwarded-For: 8.8.8.8就能伪装成任意地址。2.3 在Spring Boot中接入配置注入与过滤器工具类写好了怎么接进Spring Boot项目才是完整落地。我的做法是两步配置可信代理列表然后通过过滤器统一计算真实IP并写入请求属性。第一步在application.yml里定义可信代理一般就是内网网段app: trusted-proxies: - 10.0.0.0/8 - 172.16.0.0/12 - 192.168.0.0/16 - 127.0.0.1然后写一个配置类把值注入工具类import org.springframework.beans.factory.annotation.Value; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.context.annotation.Configuration; import org.springframework.util.StringUtils; import jakarta.annotation.PostConstruct; import java.util.ArrayList; import java.util.List; Configuration ConfigurationProperties(prefix app) public class ClientIpConfig { private ListString trustedProxies new ArrayList(); public ListString getTrustedProxies() { return trustedProxies; } public void setTrustedProxies(ListString trustedProxies) { this.trustedProxies trustedProxies; } PostConstruct public void init() { if (trustedProxies ! null !trustedProxies.isEmpty()) { IpUtils.setTrustedProxies(trustedProxies); } } }第二步写一个OncePerRequestFilter在请求进入Controller之前把解析出来的真实IP塞到请求属性里这样后面所有业务代码直接取属性就行不用到处传HttpServletRequestimport jakarta.servlet.FilterChain; import jakarta.servlet.ServletException; import jakarta.servlet.http.HttpServletRequest; import jakarta.servlet.http.HttpServletResponse; import org.springframework.core.Ordered; import org.springframework.core.annotation.Order; import org.springframework.stereotype.Component; import org.springframework.web.filter.OncePerRequestFilter; import java.io.IOException; Component Order(Ordered.HIGHEST_PRECEDENCE) public class ClientIpFilter extends OncePerRequestFilter { public static final String CLIENT_IP_ATTR X-Client-IP; Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { String clientIp IpUtils.getClientIp(request); request.setAttribute(CLIENT_IP_ATTR, clientIp); filterChain.doFilter(request, response); } }之后在Controller或者Service里这样就能拿到真实IPGetMapping(/test) public MapString, String test(HttpServletRequest request) { String clientIp (String) request.getAttribute(ClientIpFilter.CLIENT_IP_ATTR); return Map.of(clientIp, clientIp null ? : clientIp); }这里我特意用了Order(Ordered.HIGHEST_PRECEDENCE)因为IP解析尽量放在最前面避免后续流程依赖的IP值不一致。实际项目里我还见过有人在拦截器里解析、在切面里解析都行但一定要全项目统一一个入口否则很容易出现A接口拿的是新IP、B接口拿的是老IP的诡异现象。3. 配套网关与中间件配置3.1 Nginx层必须做的事工具类写得再漂亮Nginx不配合也白搭。Nginx作为最常用的反向代理需要注意两个地方一是透传XFF二是用real_ip模块做一层提前解析。先说透传。一个标准的location配置长这样server { listen 80; server_name api.example.com; location / { proxy_set_header Host $host; 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; proxy_pass http://backend_servers; } }关键是第三行X-Forwarded-For $proxy_add_x_forwarded_for。$proxy_add_x_forwarded_for不是简单取一个变量而是把“客户端原样带上来的XFF”加上“当前请求的$remote_addr”拼接起来。也就是说如果客户端带了假XFFNginx会在后面追加上一层真实看到的IP后端靠“从右往左找第一个非可信IP”的策略就能绕过伪造值。再说real_ip模块。它可以直接在Nginx层解析出真实IP后面传给Spring Boot的是改写过remote_addr的原始IP后端最简单粗暴# 信任内网代理 set_real_ip_from 10.0.0.0/8; set_real_ip_from 172.16.0.0/12; set_real_ip_from 192.168.0.0/16; # 解析XFF头 real_ip_header X-Forwarded-For; # 递归解析直到找到最左的真实客户端IP real_ip_recursive on;real_ip_recursive on表示对XFF里的IP逐个递归处理直到处理到第一个非内网IP。这个配置一旦生效Nginx会直接改写$remote_addrSpring Boot里request.getRemoteAddr()拿到的就是真实客户端IP。那还需要Java端的解析吗我的答案是仍然需要理由后面讲。3.2 Spring Cloud Gateway场景怎么处理用Spring Cloud Gateway做网关时默认情况下它会把请求转发下去但不会自动帮你拼XFF。很多团队网关用了半年下游一直拿不到IP最后发现网关层压根没设置这个头。最简单的做法是加一个GlobalFilter做统一改写import org.springframework.cloud.gateway.filter.GlobalFilter; import org.springframework.core.Ordered; import org.springframework.stereotype.Component; import org.springframework.web.server.ServerWebExchange; import reactor.core.publisher.Mono; import org.springframework.http.server.reactive.ServerHttpRequest; Component public class XForwardedGlobalFilter implements GlobalFilter, Ordered { Override public MonoVoid filter(ServerWebExchange exchange, GatewayFilterChain chain) { ServerHttpRequest request exchange.getRequest(); String remoteAddr request.getRemoteAddress() ! null ? request.getRemoteAddress().getAddress().getHostAddress() : ; String existingXff request.getHeaders().getFirst(X-Forwarded-For); String newXff (existingXff null || existingXff.isEmpty()) ? remoteAddr : existingXff , remoteAddr; ServerHttpRequest mutated request.mutate() .header(X-Forwarded-For, newXff) .header(X-Real-IP, remoteAddr) .build(); return chain.filter(exchange.mutate().request(mutated).build()); } Override public int getOrder() { return -1; } }注意这个过滤器和前面Nginx的$proxy_add_x_forwarded_for逻辑一致如果上游带了XFF就追加上一跳IP如果没带就以当前remoteAddr作为第一个值。不要把客户端传入的XFF直接覆盖掉否则又给了用户伪造IP的机会。3.3 典型部署拓扑下的取值对照表为了让你彻底搞懂不同架构下的期望值我把常见部署形态整理成了表格部署拓扑remoteAddr拿到什么XFF长什么样正确取值策略浏览器直连后端真实客户端IP通常为空直接取remoteAddr浏览器 - Nginx - 后端Nginx内网IP客户端IP取XFF第一个浏览器 - SLB - Nginx - 后端Nginx内网IP客户端IP, SLB内网IP跳过SLB后取XFF第一个浏览器 - CDN - Nginx - 后端Nginx内网IP客户端IP, CDN节点IP, CDN回源IP跳过可信代理后取第一个非可信IP浏览器 - 公共代理 - 后端公共代理IP伪造IP, 公共代理IP永远不要全信需结合其他策略这张表建议直接保存排查IP异常时对着表格看拓扑能省大量时间。我特别想强调中间两行很多人在“SLBNginx”架构里直接用XFF第一个IP结果拿到的是SLB的IP然后发现每个用户IP都长一样一脸懵。正确顺序一定是先跳过所有可信代理再取最左的非可信IP。4. 常见问题与排查技巧实录4.1 IPv6、localhost与本地调试开发环境最常见的坑本机启动Spring Boot用localhost:8080访问拿到0:0:0:0:0:0:0:1这是IPv6的localhost。如果不处理日志里全是这串长东西数据库字段存不下前端展示也难看。我的处理办法已经在工具类里体现判断0:0:0:0:0:0:0:1或::1时统一转成127.0.0.1。另外如果你的服务部署在纯IPv6环境IP字符串里会带方括号和端口号比如[2001:db8::1]:8080一定要用getAddress().getHostAddress()拿纯地址不要直接拿整段拼出来的字符串。还有一个很隐蔽的坑IPv6地址有多种压缩写法比如2001:0db8:0000:0000:0000:0000:0000:0001和2001:db8::1是同一个地址但字符串完全不相等。做IP归一化、IP段比较时不要直接比字符串先转成InetAddress或者用现成的网络库比如com.github.seancfoley:ipaddress再比。4.2 伪造X-Forwarded-For怎么办这个问题必须严肃对待。如果你的服务直接暴露在公网上没有可信代理在转发那么客户端可以随意构造XFF头甚至放进一个根本不存在的IPcurl -H X-Forwarded-For: 1.2.3.4 http://your-service/api/test后端如果直接信任XFF就会拿到1.2.3.4。这种情况下无论解析逻辑多完善只要“可信代理列表”为空理论上任何XFF值都是可疑的。我的经验是在完全不可信的直连场景不要用XFF做任何与安全相关的判断比如风控、限流、审计最多用来做数据分析展示而且要在展示时明确标注“不可信来源”。反过来如果服务前面有自己控制的Nginx/网关那就把公网入口封住只允许内网访问后端然后信任可信代理列表。这样外部用户就算伪造XFF也会在Nginx层被追加新的真实IP攻击成本高得多。补充一个非常实用的配置技巧如果你用的是Nginxreal_ip模块并且set_real_ip_from只配置了内网网段那外部直连时Nginx不会改写remoteAddr此时真实的remoteAddr会被保留后端就不会误信伪造XFF。这也是我推荐Nginx层做一次解析的原因——它不是替代Java端解析而是作为一道安全防线。4.3 排查技巧三步定位IP链路被IP问题折磨时不要干瞪眼按下面三步排查基本十分钟内能定位。第一步打印完整的请求头。在拦截器或过滤器里临时输出所有Headerfor (EnumerationString names request.getHeaderNames(); names.hasMoreElements();) { String name names.nextElement(); log.info(Header [{}] [{}], name, request.getHeader(name)); } log.info(remoteAddr [{}], request.getRemoteAddr());第二步用curl模拟多级代理场景构造不同XFF验证解析逻辑# 模拟两层代理最后一跳是10.0.0.2应该解析出8.8.8.8前提10.0.0.2在可信列表 curl -H X-Forwarded-For: 8.8.8.8, 10.0.0.2 http://localhost:8080/test # 模拟完全伪造最左边是假IP但最右边是真实代理 curl -H X-Forwarded-For: 6.6.6.6, 8.8.8.8, 10.0.0.2 http://localhost:8080/test # 不带XFF应该直接走remoteAddr curl http://localhost:8080/test第三步看返回结果对照部署拓扑表判断是解析问题、代理配置问题还是数据源问题。如果remoteAddr和X-Real-IP不一致优先查Nginx的proxy_set_header有没有配如果XFF第一个IP是正确的工具类却取错了优先查可信代理列表是否覆盖了你的内网网段。我在实际项目里还会在网关层把所有IP相关日志都打出来统一格式remoteAddr{} | XFF{} | realIp{}。这样不管是CDN厂商、运维还是开发拿到一行日志就能快速对齐现状省去无数扯皮时间。5. 一些值得补充的细节与心得关于获取真实IP这件事代码只是表象背后其实是“链路可信度”和“部署拓扑认知”的问题。我最后再分享几个容易忽略的细节。第一个如果你用了real_ip_recursive onNginx已经帮你把remoteAddr改成真实IP了但此时XFF头仍然保留着原始链路信息。后端如果同时信getRemoteAddr()和XFF可能出现两套不同的“真实IP”。我的建议是团队内部明确一个标准——到底以谁的解析结果为准。我个人更倾向于后端自己做可信代理解析因为Nginx配置不够灵活时后端还有机会兜底。第二个CDN场景下很多CDN厂商会回源到你的Nginx这时XFF的格式可能变成客户端IP, CDN节点IP甚至某些CDN会多出cdn-request-id之类的自定义头。务必先找CDN官方文档确认它回源时带的是XFF还是X-Real-IP不要靠猜。网上那些“CDN自带XFF所以代码随便抄”的结论放到不同厂商身上往往不成立。第三个如果项目用了K8sPod的IP会频繁变化但Pod网段一般是固定的。配置可信代理列表时除了传统内网网段还要把K8s集群的Service CIDR和Pod CIDR加进去否则Cluster网络里的流量会被误判成外部IP。这个坑我见过不止一次排查起来极其隐蔽。第四个IP解析结果一定要做空值兜底。前面代码里normalizeIp对null返回空串但业务侧使用IP时我建议再包一层默认值逻辑比如未识别IP时统一记为0.0.0.0避免数据库字段为NULL导致后续逻辑报错。最后一个心得真正困难的往往不是拿到IP而是让所有环节的人对IP达成一致认知。前端传一个IPNginx改一个IP网关又拼一个IP后端再解析一次各个环节各说各话这才是项目里IP信息混乱的根源。用了这套方案之后我们团队把IP的唯一权威来源收敛到过滤器里上线半年多再没出过IP类事故。