在 Laravel 应用开发中，通过 request()->ip() 获取客户端真实 IP 是一个常见需求。然而，许多开发者发现，在部署到生产环境后，该方法返回的 IP 总是形如 10.0.x.x、192.168.x.x 或 172.x.x.x 的私有地址，而不是用户真实的公网 IP。这一问题通常出现在使用了反代、负载均衡或容器编排的环境下，若不及时解决，将直接影响日志审计、区域限制、安全策略等功能。

问题根源：REMOTE_ADDR 的“欺骗”

Laravel 的 request()->ip() 底层依赖于 PHP 的 $_SERVER['REMOTE_ADDR'] 变量。当客户端直接连接到 Web 服务器时，该变量正确记录了客户端的公网 IP。但在实际部署中，服务器前往往接有 Nginx、HAProxy、AWS ELB、Docker 或 Kubernetes Ingress 等中间代理。此时，客户端请求先到达代理，再由代理转发给 Laravel 应用。在应用视角下，REMOTE_ADDR 变成了最后一级代理的 IP（通常是私有 IP），而非原始客户端 IP。

为了解决这一问题，HTTP 协议定义了 X-Forwarded-For（简称 XFF）头，代理在转发请求时会将原始客户端 IP 附加到该头部。然而，Laravel 默认不信任任何代理，也就不会从 XFF 中提取真实 IP。

影响范围：从开发到运维的连锁反应

当 request()->ip() 返回错误 IP 时，直接受影响的功能包括：

  • 用户行为日志：记录的 IP 全部变为代理内网地址，无法用于地理分析或防刷。
  • 基于 IP 的限制：如登录失败次数限制、黑名单/白名单策略失效。
  • 第三方服务集成：某些支付或风控接口需要提交用户 IP，错误 IP 可能导致误判或拒绝服务。
  • 安全审计：无法追踪攻击源的真实位置。

尤其是使用 Laravel Vapor、Forge 或 Docker 部署的场景，几乎都会遇到此问题。

官方解决方案：TrustProxies 中间件

Laravel 从 5.5 版本起内置了 TrustProxies 中间件，用于解决代理信任问题。该中间件位于 App\Http\Middleware\TrustProxies，通常需要在 app/Http/Kernel.php 中注册并配置。

核心配置项有两个：

  1. $proxies：声明可信任的代理 IP 列表。若直接使用 * 表示信任所有代理（仅在完全可控的网络中使用），或指定具体 IP 段。
  2. $headers：定义从哪个 HTTP 头获取真实 IP。默认已包含 HEADER_X_FORWARDED_FOR、HEADER_X_FORWARDED_HOST 等。

典型示例如下：

class TrustProxies extends Middleware
{
    protected $proxies = '*'; // 信任所有代理（适用于标准 LB 环境）

    protected $headers = Request::HEADER_X_FORWARDED_FOR;
}

若需要指定代理 IP，例如 AWS ELB 的内网 IP 段：

protected $proxies = [
    '10.0.0.0/8',
    '172.16.0.0/12',
    '192.168.0.0/16',
];

常见陷阱与升级注意

  • 中间件优先级：TrustProxies 必须位于中间件栈最外层（即 $middleware 全局数组），而非路由组内。否则可能在其他中间件之后才执行，导致 IP 仍未修正。
  • Symfony 版本差异：Laravel 8 及以上版本基于 Symfony 5+，其 TrustProxies 行为略有不同，需确保 $headers 常量与 Symfony 版本匹配。若使用 * 后 IP 仍为私有，可尝试显式设置 Request::HEADER_X_FORWARDED_FOR | Request::HEADER_X_FORWARDED_HOST。
  • CDN 场景：如 Cloudflare、Akamai 等 CDN 会额外增加 CF-Connecting-IP 或 True-Client-IP 头。此时可能需要自定义 TrustProxies 逻辑，或通过 Request::setTrustedProxies() 方法手动处理。

社区建议与最佳实践

Stack Overflow 上大量类似提问都指向了同一根因：开发者忘记配置 TrustProxies。Laravel 在 config/trustedproxy.php 配置文件中提供了一个备选方案，但实际部署中仍推荐直接修改中间件。

此外，若应用运行在 Kubernetes 环境下，务必确认 Ingress Controller 是否正确传递了 XFF 头，并配置 $proxies 为 ['0.0.0.0/0'] 或精准的子网。

总结

request()->ip() 返回私有 IP 并非 Laravel 的 Bug，而是代理环境下的预期行为。正确配置 TrustProxies 中间件是唯一的解决之道。随着无服务器架构和边缘计算的普及，IP 获取问题将越来越常见。开发者应在上线前就做好代理信任设置，避免业务逻辑因错误 IP 而偏离预期。

如果问题依然存在，不妨检查 Nginx 或负载均衡的配置，确保未在转发过程中丢弃或修改 XFF 头。同时在 Laravel 中打印 request()->header('X-Forwarded-For') 与 request()->ip() 对比，即可快速定位故障点。