在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 | 单个IP | Nginx等特定代理设置 | 只记录上一跳看到的IP，非通用标准 |
Forwarded | 结构化语法 | RFC 7239标准头 | 规范但普及率低，老设备不认 |
很多人一上来就取XFF的第一个IP当作真实客户端IP。这个策略只在单层代理时有效，放到CDN+SLB+Nginx这种多级链路里就会翻车。因为客户端完全可以在请求里手动塞一个假的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 List<String> trustedProxyPrefixes = new ArrayList<>(); private static volatile List<String> trustedProxyCidrs = new ArrayList<>(); private IpUtils() { } public static void setTrustedProxies(List<String> proxies) { List<String> prefixes = new ArrayList<>(); List<String> 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 List<String> trustedProxies = new ArrayList<>(); public List<String> getTrustedProxies() { return trustedProxies; } public void setTrustedProxies(List<String> trustedProxies) { this.trustedProxies = trustedProxies; } @PostConstruct public void init() { if (trustedProxies != null && !trustedProxies.isEmpty()) { IpUtils.setTrustedProxies(trustedProxies); } } }第二步，写一个OncePerRequestFilter，在请求进入Controller之前把解析出来的真实IP塞到请求属性里，这样后面所有业务代码直接取属性就行，不用到处传HttpServletRequest：
import 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里，这样就能拿到真实IP：
@GetMapping("/test") public Map<String, 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”拼接起来。也就是说，如果客户端带了假XFF，Nginx会在后面追加上一层真实看到的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_addr，Spring 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 Mono<Void> 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异常时对着表格看拓扑，能省大量时间。
我特别想强调中间两行：很多人在“SLB+Nginx”架构里，直接用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头，甚至放进一个根本不存在的IP：
curl -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问题折磨时，不要干瞪眼，按下面三步排查，基本十分钟内能定位。
第一步：打印完整的请求头。在拦截器或过滤器里临时输出所有Header：
for (Enumeration<String> 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 on，Nginx已经帮你把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所以代码随便抄”的结论，放到不同厂商身上往往不成立。
第三个：如果项目用了K8s，Pod的IP会频繁变化，但Pod网段一般是固定的。配置可信代理列表时，除了传统内网网段，还要把K8s集群的Service CIDR和Pod CIDR加进去，否则Cluster网络里的流量会被误判成外部IP。这个坑我见过不止一次，排查起来极其隐蔽。
第四个：IP解析结果一定要做空值兜底。前面代码里normalizeIp对null返回空串，但业务侧使用IP时，我建议再包一层默认值逻辑，比如未识别IP时统一记为0.0.0.0，避免数据库字段为NULL导致后续逻辑报错。
最后一个心得：真正困难的往往不是拿到IP，而是让所有环节的人对IP达成一致认知。前端传一个IP，Nginx改一个IP，网关又拼一个IP，后端再解析一次，各个环节各说各话，这才是项目里IP信息混乱的根源。用了这套方案之后，我们团队把IP的唯一权威来源收敛到过滤器里，上线半年多再没出过IP类事故。
