SpringBoot中获取真实客户端IP的解决方案与实践-代码聚汇网

SpringBoot中获取真实客户端IP的解决方案与实践

风扇爱好者·2026-10-25·阅读 25 GEO检测（免费）

SpringBoot客户端IPX-Forwarded-For

|难度：普通|阅读约 25 分钟

1. 为什么获取真实客户端IP这么难？

在SpringBoot应用中获取客户端IP看似简单，但实际开发中我们会遇到各种"意外"情况。最常见的就是无论怎么获取，拿到的都是127.0.0.1或者负载均衡器的IP。这不是你的代码写错了，而是现代网络架构带来的必然结果。

现代Web应用通常部署在多层代理之后：

第一层可能是CDN（如Cloudflare）
第二层是负载均衡（如Nginx、AWS ALB）
第三层才是你的SpringBoot应用

每经过一层网络设备，HTTP请求中的源IP就会被替换为上一跳设备的IP。这就是为什么你调用request.getRemoteAddr()总是得到错误结果的根本原因。

关键误区：很多人以为只要在Controller里调用HttpServletRequest.getRemoteAddr()就够了，实际上这个值在代理环境下毫无意义。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. 标准解决方案：X-Forwarded-For头解析

2.1 X-FF头的工作原理

行业标准做法是使用X-Forwarded-For（X-FF）请求头。这个头的格式是这样的：

code复制X-Forwarded-For: client1, proxy1, proxy2

最左边的IP就是原始客户端IP，后续每个代理服务器都会把自己的IP追加到右边。

但这里有个重要细节：X-FF头可以被任意客户端伪造！所以直接取第一个IP是极其危险的。

2.2 安全解析方案

正确的解析逻辑应该是：

从右向左遍历X-FF中的IP列表
跳过所有已知的信任代理IP（如你的Nginx服务器IP）
第一个非信任代理的IP就是真实客户端IP

示例代码：

java复制public String getClientIp(HttpServletRequest request) {
    String xff = request.getHeader("X-Forwarded-For");
    if (xff == null) {
        return request.getRemoteAddr();
    }
    
    String[] ips = xff.split(",");
    Set<String> trustedProxies = Set.of("10.0.0.1", "192.168.1.1"); // 配置你的信任代理
    
    for (int i = ips.length - 1; i >= 0; i--) {
        String ip = ips[i].trim();
        if (!trustedProxies.contains(ip)) {
            return ip;
        }
    }
    
    return request.getRemoteAddr(); // 回退方案
}

3. 生产环境必须考虑的边界情况

3.1 多层代理的特殊处理

当你的应用前面有CDN+LB+Nginx三层代理时，可能需要检查多个头：

CF-Connecting-IP（Cloudflare专用）
X-Real-IP（Nginx常用）
X-Forwarded-For（通用标准）

处理顺序应该是：

先检查CDN专用头
然后检查X-Real-IP
最后回退到X-Forwarded-For

3.2 IPv6地址处理

现代网络环境中IPv6越来越普遍，你的代码需要兼容IPv6格式：

java复制// 错误的简单判断
if (ip.contains(":")) {
    // 可能是IPv6
}

// 正确的IPv6验证
try {
    InetAddress inet = InetAddress.getByName(ip);
    if (inet instanceof Inet6Address) {
        // IPv6特殊处理
    }
} catch (UnknownHostException e) {
    // 非法IP格式
}

3.3 日志记录的最佳实践

获取IP后如果要记录日志，建议：

先对IP进行脱敏处理（如192.168.x.x）
记录原始头和解析结果用于审计
添加请求ID方便追踪

java复制logger.info("ClientIP={}, XFF={}, XRI={}", 
    maskIp(clientIp),
    request.getHeader("X-Forwarded-For"),
    request.getHeader("X-Real-IP"));

4. SpringBoot中的完整实现方案

4.1 过滤器(Filter)实现

最可靠的方式是实现一个Filter：

java复制public class ClientIpFilter implements Filter {
    private Set<String> trustedProxies;
    
    @Override
    public void init(FilterConfig config) {
        trustedProxies = loadTrustedProxies();
    }
    
    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain) {
        HttpServletRequest request = (HttpServletRequest) req;
        String clientIp = parseClientIp(request);
        
        request.setAttribute("X-Client-Real-IP", clientIp);
        chain.doFilter(request, res);
    }
    
    private String parseClientIp(HttpServletRequest request) {
        // 实现前面的解析逻辑
    }
}

然后在配置类中注册：

java复制@Bean
public FilterRegistrationBean<ClientIpFilter> clientIpFilter() {
    FilterRegistrationBean<ClientIpFilter> bean = new FilterRegistrationBean<>();
    bean.setFilter(new ClientIpFilter());
    bean.addUrlPatterns("/*");
    bean.setOrder(Ordered.HIGHEST_PRECEDENCE); // 最高优先级
    return bean;
}

4.2 与Spring Security集成

如果你用了Spring Security，可以在认证流程中使用客户端IP：

java复制public class IpAwareAuthenticationFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(HttpServletRequest req, 
                                   HttpServletResponse res,
                                   FilterChain chain) {
        String clientIp = (String) req.getAttribute("X-Client-Real-IP");
        
        // 可以用于登录风控等场景
        if (isSuspiciousIp(clientIp)) {
            throw new BadCredentialsException("IP blocked");
        }
        
        chain.doFilter(req, res);
    }
}

4.3 测试方案

编写测试验证你的实现：

java复制@Test
public void testIpParsing() {
    MockHttpServletRequest request = new MockHttpServletRequest();
    
    // 模拟多层代理
    request.addHeader("X-Forwarded-For", "203.0.113.1, 198.51.100.1, 192.168.1.1");
    request.setRemoteAddr("192.168.1.1");
    
    String clientIp = ipService.getClientIp(request);
    assertEquals("203.0.113.1", clientIp);
}

5. 高级话题：IP地理位置和风控

获取真实IP后，常见的进阶用法包括：

5.1 IP地理位置查询

可以使用MaxMind GeoIP2等库：

java复制File database = new File("GeoLite2-City.mmdb");
DatabaseReader reader = new DatabaseReader.Builder(database).build();

InetAddress ipAddress = InetAddress.getByName(clientIp);
CityResponse response = reader.city(ipAddress);

String country = response.getCountry().getName();
String city = response.getCity().getName();

5.2 基于IP的访问控制

实现简单的IP白名单：

java复制@RestController
@RequestMapping("/api")
public class ApiController {
    private Set<String> allowedIps = Set.of("192.168.1.100", "10.0.0.1");
    
    @GetMapping("/secure")
    public ResponseEntity secureEndpoint(@RequestAttribute String clientIp) {
        if (!allowedIps.contains(clientIp)) {
            return ResponseEntity.status(403).build();
        }
        // 业务逻辑
    }
}

5.3 速率限制

结合Redis实现IP-based限流：

java复制public boolean allowRequest(String clientIp) {
    String key = "rate_limit:" + clientIp;
    long current = redisTemplate.opsForValue().increment(key);
    
    if (current == 1) {
        redisTemplate.expire(key, 1, TimeUnit.MINUTES);
    }
    
    return current <= 100; // 每分钟100次
}

6. 性能优化与监控

6.1 解析性能优化

IP解析可能成为性能瓶颈，建议：

使用IP地址缓存（Guava Cache）
预编译正则表达式
避免在Filter中做耗时操作

java复制private LoadingCache<String, Boolean> ipCache = CacheBuilder.newBuilder()
    .maximumSize(10000)
    .expireAfterWrite(1, TimeUnit.HOURS)
    .build(new CacheLoader<>() {
        public Boolean load(String ip) {
            return isTrustedProxy(ip);
        }
    });

6.2 监控指标

建议监控：

无效IP格式的出现频率
IP解析耗时
各代理层的IP分布

java复制@Aspect
@Component
public class IpMonitoringAspect {
    @Around("@annotation(org.springframework.web.bind.annotation.RequestMapping)")
    public Object monitorIpResolution(ProceedingJoinPoint pjp) throws Throwable {
        long start = System.nanoTime();
        Object result = pjp.proceed();
        long duration = System.nanoTime() - start;
        
        metrics.recordTiming("ip.resolution", duration);
        return result;
    }
}

7. 常见陷阱与解决方案

7.1 代理服务器未正确配置

症状：X-Forwarded-For头缺失
解决方案：

Nginx需要配置：proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
Apache需要配置：RequestHeader set X-Forwarded-For %{REMOTE_ADDR}e

7.2 客户端伪造IP头

攻击者可能发送：

code复制X-Forwarded-For: 8.8.8.8
X-Real-IP: 8.8.8.8

防御方案：

最外层代理（如Nginx）应该覆盖这些头
不要信任来自客户端的任何IP头

7.3 私有IP地址泄露

内网IP可能通过X-FF头泄露：

code复制X-Forwarded-For: 192.168.1.100, 10.0.0.1

解决方案：

最外层代理应该过滤私有IP
应用层再次验证IP有效性

8. 云原生环境特别注意事项

8.1 Kubernetes Ingress

不同Ingress控制器的行为：

Nginx Ingress：默认会设置X-Forwarded-For
AWS ALB Ingress：使用X-Forwarded-For但格式特殊
GKE Ingress：可能使用额外的头

8.2 Service Mesh（如Istio）

在Service Mesh中：

Envoy代理会自动处理X-FF头
可能需要检查x-envoy-external-address头
注意mTLS场景下的特殊处理

8.3 Serverless环境

在AWS Lambda等场景：

真实IP在event对象的requestContext.identity.sourceIp
需要检查API Gateway的映射配置

9. 终极解决方案代码实现

以下是生产级实现：

java复制public class ClientIpResolver {
    private static final List<String> IP_HEADERS = List.of(
        "X-Forwarded-For",
        "Proxy-Client-IP",
        "WL-Proxy-Client-IP",
        "HTTP_X_FORWARDED_FOR",
        "HTTP_X_FORWARDED",
        "HTTP_X_CLUSTER_CLIENT_IP",
        "HTTP_CLIENT_IP",
        "HTTP_FORWARDED_FOR",
        "HTTP_FORWARDED",
        "HTTP_VIA",
        "X-Real-IP"
    );
    
    private final Set<String> trustedProxies;
    private final Pattern ipPattern = Pattern.compile(
        "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$");
    
    public ClientIpResolver(Set<String> trustedProxies) {
        this.trustedProxies = trustedProxies;
    }
    
    public String resolve(HttpServletRequest request) {
        String ip = checkHeaders(request);
        if (ip != null) return ip;
        
        ip = request.getRemoteAddr();
        return isValidPublicIp(ip) ? ip : null;
    }
    
    private String checkHeaders(HttpServletRequest request) {
        for (String header : IP_HEADERS) {
            String value = request.getHeader(header);
            if (value == null || value.isEmpty()) {
                continue;
            }
            
            String[] ips = value.split(",");
            for (int i = ips.length - 1; i >= 0; i--) {
                String candidate = ips[i].trim();
                if (isValidPublicIp(candidate) && !trustedProxies.contains(candidate)) {
                    return candidate;
                }
            }
        }
        return null;
    }
    
    private boolean isValidPublicIp(String ip) {
        if (!ipPattern.matcher(ip).matches()) {
            return false;
        }
        
        return !ip.startsWith("10.") 
            && !ip.startsWith("192.168.") 
            && !ip.startsWith("172.16.") 
            && !ip.equals("127.0.0.1");
    }
}

使用方式：

java复制@RestController
public class MyController {
    private final ClientIpResolver ipResolver;
    
    public MyController(ClientIpResolver ipResolver) {
        this.ipResolver = ipResolver;
    }
    
    @GetMapping("/ip")
    public String getIp(HttpServletRequest request) {
        return ipResolver.resolve(request);
    }
}

10. 部署检查清单

上线前请确认：

所有代理服务器已正确配置X-Forwarded-For
信任代理IP列表已完整配置
测试用例覆盖了各种代理场景
监控指标已配置
性能测试通过
安全团队已审核代码
应急预案准备（如IP解析失败时的降级方案）

最后提醒：不要在生产环境直接使用本文示例代码，应该根据你的具体架构调整实现细节。特别是信任代理列表必须严格配置，否则可能造成安全漏洞。