在Java Web应用开发中，获取客户端的真实IP地址是很多业务场景的基础需求，比如访问频率限制、地域识别、安全审计等。当请求经过Nginx、F5等反向代理或负载均衡设备转发时，直接使用常规方法获取到的往往是代理服务器的IP，此时就需要解析请求头中的X-Forwarded-For字段来拿到客户端的真实IP。
基础的IP获取方式
在不经过任何代理的情况下，我们可以通过HttpServletRequest的getRemoteAddr()方法直接获取客户端IP，这个方法返回的是发送请求的客户端或者最后一个代理的IP地址。
import javax.servlet.http.HttpServletRequest;
public class IpUtil {
public static String getBasicIp(HttpServletRequest request) {
// 直接获取请求的远程地址
return request.getRemoteAddr();
}
}
但是当请求经过代理转发后，getRemoteAddr()返回的就是代理服务器的IP，无法得到真实客户端的IP，这时候就需要借助请求头中的代理相关字段。
X-Forwarded-For的格式说明
X-Forwarded-For是一个HTTP扩展头，用于标识通过代理服务器连接到Web服务器的客户端的原始IP地址。它的格式是多个IP地址用逗号加空格分隔，第一个IP就是客户端的真实IP，后面的IP依次是经过的各个代理服务器的IP。
例如一个请求经过了客户端、代理1、代理2、代理3最终到达服务端，那么X-Forwarded-For的值就是：客户端IP, 代理1IP, 代理2IP, 代理3IP。如果请求没有经过代理，那么请求头中可能不会包含这个字段。
解析X-Forwarded-For获取真实IP
我们需要先判断请求头中是否存在X-Forwarded-For字段，如果存在就取其第一个逗号前的IP作为客户端真实IP，如果不存在再尝试获取其他代理相关的请求头，最后才使用getRemoteAddr()作为兜底方案。
常见的代理相关请求头还有Proxy-Client-IP、WL-Proxy-Client-IP等，部分代理服务器会使用这些字段传递客户端IP，所以解析时需要做兼容处理。
完整工具类实现
import javax.servlet.http.HttpServletRequest;
import java.net.InetAddress;
import java.net.UnknownHostException;
public class IpUtil {
private static final String UNKNOWN = "unknown";
private static final String LOCALHOST_IP = "127.0.0.1";
private static final String LOCALHOST_IPV6 = "0:0:0:0:0:0:0:1";
/**
* 获取客户端真实IP地址
* @param request HttpServletRequest对象
* @return 客户端真实IP
*/
public static String getClientIp(HttpServletRequest request) {
String ip = request.getHeader("X-Forwarded-For");
if (!isValidIp(ip)) {
ip = request.getHeader("Proxy-Client-IP");
}
if (!isValidIp(ip)) {
ip = request.getHeader("WL-Proxy-Client-IP");
}
if (!isValidIp(ip)) {
ip = request.getHeader("HTTP_CLIENT_IP");
}
if (!isValidIp(ip)) {
ip = request.getHeader("HTTP_X_FORWARDED_FOR");
}
// 以上都没有获取到，使用getRemoteAddr
if (!isValidIp(ip)) {
ip = request.getRemoteAddr();
// 如果是本地IPv6地址，转换为本地IPv4地址
if (LOCALHOST_IPV6.equals(ip)) {
ip = LOCALHOST_IP;
}
}
// 如果X-Forwarded-For包含多个IP，取第一个非unknown的IP
if (ip != null && ip.contains(",")) {
String[] ipArray = ip.split(",");
for (String subIp : ipArray) {
if (isValidIp(subIp)) {
ip = subIp;
break;
}
}
}
return ip;
}
/**
* 校验IP是否有效
* @param ip IP字符串
* @return 是否有效
*/
private static boolean isValidIp(String ip) {
if (ip == null || ip.length() == 0 || UNKNOWN.equalsIgnoreCase(ip)) {
return false;
}
return true;
}
/**
* 判断是否为内网IP
* @param ip IP字符串
* @return 是否为内网IP
*/
public static boolean isInternalIp(String ip) {
if (ip == null || ip.equals(LOCALHOST_IP) || ip.equals(LOCALHOST_IPV6)) {
return true;
}
// 简单判断内网IP段：10.x.x.x、172.16.x.x-172.31.x.x、192.168.x.x
if (ip.startsWith("10.") || ip.startsWith("192.168.")) {
return true;
}
if (ip.startsWith("172.")) {
String[] parts = ip.split("\.");
if (parts.length >= 2) {
try {
int secondPart = Integer.parseInt(parts[1]);
if (secondPart >= 16 && secondPart <= 31) {
return true;
}
} catch (NumberFormatException e) {
return false;
}
}
}
return false;
}
}
使用注意事项
首先，X-Forwarded-For头是可以被客户端伪造的，如果业务中IP地址用于安全相关的判断，比如登录地校验、访问权限控制，不能单纯依赖该字段，需要结合其他验证手段。
其次，需要确保反向代理服务器正确配置了X-Forwarded-For头的传递，比如Nginx需要在配置中添加proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;，否则请求头中可能不会携带该字段。
另外，如果应用直接部署在公网，没有经过任何代理，那么X-Forwarded-For头可能不存在，此时直接获取getRemoteAddr()的结果即可，工具类中的兜底逻辑已经覆盖了这种场景。
测试验证
可以在Controller中调用该工具类，打印获取到的IP进行验证：
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.servlet.http.HttpServletRequest;
@RestController
public class TestController {
@GetMapping("/test-ip")
public String testIp(HttpServletRequest request) {
String clientIp = IpUtil.getClientIp(request);
return "客户端IP：" + clientIp;
}
}
部署后通过不同的访问方式（直接访问、经过代理访问）测试，即可验证IP获取逻辑是否符合预期。
JavaHttpServletRequestX-Forwarded-ForIP地址获取修改时间：2026-06-15 17:06:16