Skip to content

Laravel 怎么给每个请求打 IP 属地标签?中间件 + Cache + 队列回填(完整代码) ​

一个做本地生活的 Laravel 项目找到我,问题是首页的「同城活动」模块。他们最初的写法很直接:在控制器里拿 $request->ip(),拼上 ?ip= 请求一次归属地接口,判断城市,然后查本城活动。

上线一周出了三件事:接口偶尔超时把首页拖到 8 秒;缓存没做,热门时段每分钟几千次请求直接触发限流;最要命的是上了 CDN 之后,所有访客的 IP 都变成了同一个回源地址,首页开始给全国人民推同一个城市的火锅券。

这三件事指向同一个结论:IP 属地这件事不该散落在各个控制器里,它应该是一个请求级别的中间件,只做一次,做好缓存,失败可降级。

一、先确认你拿到的是谁的 IP ​

Laravel 的 $request->ip() 返回的是 Request::getClientIp() 的结果,它依赖 Symfony 对「可信代理」的判断。默认情况下它是不信任任何代理的,所以:

  • 直连 PHP-FPM(少见):拿到真实访客 IP,没问题。
  • Nginx 反代到 PHP-FPM:拿到的是 Nginx 所在机器的内网 IP,通常是 127.0.0.1。
  • 前面再加一层 Cloudflare / 阿里云 CDN:拿到的是 CDN 回源 IP,全国访客一个样。

Laravel 11/12 在 bootstrap/app.php 里配:

php
->withMiddleware(function (Middleware $middleware) {
    // 只填你自己的反代/CDN 段,千万别写 '*'
    $middleware->trustProxies(at: [
        '127.0.0.1',
        '172.16.0.0/12',
        '2408:8000::/20',   // 举例:CDN 的 IPv6 回源段,按实际填
    ]);
    $middleware->append(\App\Http\Middleware\TagIpRegion::class);
})

trustProxies 写成 '*' 是最常见的错误:任何人都能自己加一个 X-Forwarded-For: 1.1.1.1 把属地伪装成任意城市,风控直接失效。这个坑我在另一篇讲 XFF 伪造的文章里拆过,结论一样——只信任你确实控制得了的段。

如果 CDN 用的是 CF-Connecting-IP 这类自定义头,Symfony 认不出来,需要在自己的中间件里读,读之前同样要校验来源 IP 是否属于 CDN 段。

二、方案:一个服务类 + 一个中间件 + 一层缓存 ​

结构尽量小:

层职责不做什么
App\Services\IpRegion调接口、解析字段、写缓存、失败降级不碰 Request,不依赖 HTTP 上下文
TagIpRegion 中间件每个请求查一次,结果挂到 $request->attributes 和视图不做业务判断
队列 Job给历史订单/登录日志补属地不在请求链路里跑

缓存的粒度是「IP → 归属地」,TTL 30 天。这个数字有依据:IP 段的归属地变动是以月为单位的,运营商重新规划一个段之后才会变;缓存 30 天,既能把接口调用量压到极低,又不至于把变更拖太久。查询失败的结果单独缓存 10 分钟,防止一个坏 IP 每次请求都去打接口。

三、代码 ​

先写服务类。注意它永远返回数组,不返回 null,失败时 ok=false。这样调用方只需要判断 ok,不用在每个地方写 if ($geo === null)。

php
<?php
// app/Services/IpRegion.php —— Laravel 侧唯一的「IP → 城市」入口
namespace App\Services;

use Illuminate\Support\Facades\Cache;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Log;

class IpRegion
{
    private const API = 'https://ip9.com.cn/get';

    /**
     * 永远返回数组,不返回 null:
     * ['ok'=>bool,'ip'=>..,'country'=>..,'prov'=>..,'city'=>..,'isp'=>..,'lng'=>..,'lat'=>..]
     * 失败时 ok=false,调用方按「未知属地」处理,不用到处写 null 判断
     */
    public function lookup(?string $ip): array
    {
        $ip  = $ip ?: '';
        $key = 'ipgeo:' . ($ip === '' ? 'self' : $ip);

        // 成功缓存 30 天;失败缓存 10 分钟(负缓存,防止坏 IP 反复打接口)
        $cached = Cache::get($key);
        if (is_array($cached)) {
            return $cached;
        }

        $geo = $this->fetch($ip);
        Cache::put($key, $geo, $geo['ok'] ? now()->addDays(30) : now()->addMinutes(10));

        return $geo;
    }

    private function fetch(string $ip): array
    {
        $empty = ['ok' => false, 'ip' => $ip, 'country' => '', 'country_code' => '',
                  'prov' => '', 'city' => '', 'isp' => '', 'lng' => '', 'lat' => ''];

        try {
            $resp = Http::timeout(3)->get(self::API, $ip === '' ? [] : ['ip' => $ip]);

            if ($resp->status() === 429) {          // 触发限速,先退避
                Log::warning('ipgeo throttled');
                return $empty;
            }
            if (!$resp->ok()) {
                return $empty;
            }

            $json = $resp->json();
            if (($json['ret'] ?? 0) !== 200 || empty($json['data'])) {
                return $empty;                       // ret=400:非法 IP
            }

            $d = $json['data'];

            return [
                'ok'           => true,
                'ip'           => $d['ip'] ?? $ip,
                'country'      => $d['country'] ?? '',
                'country_code' => strtoupper($d['country_code'] ?? ''),
                'prov'         => $d['prov'] ?? '',
                'city'         => $d['city'] ?? '',
                'isp'          => $d['isp'] ?? '',
                'lng'          => $d['lng'] ?? '',
                'lat'          => $d['lat'] ?? '',
            ];
        } catch (\Throwable $e) {
            Log::warning('ipgeo lookup failed', ['ip' => $ip, 'msg' => $e->getMessage()]);
            return $empty;
        }
    }
}

有一点值得说:这里没有用 Cache::remember。原因是 remember 在回调返回 null 时,get 拿回来还是 null,等于负缓存根本没生效,坏 IP 会一直穿透。手动 get + put,把「失败」也当成一个值存起来,才是真正的一次调用。

中间件只做三件事:跳过静态资源、查一次、把结果挂到请求和视图上。

php
<?php
// app/Http/Middleware/TagIpRegion.php
namespace App\Http\Middleware;

use App\Services\IpRegion;
use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\View;
use Symfony\Component\HttpFoundation\Response;

class TagIpRegion
{
    public function __construct(private IpRegion $geo) {}

    public function handle(Request $request, Closure $next): Response
    {
        // 静态资源、健康检查不用查
        if ($request->is('assets/*', 'favicon.ico', 'up')) {
            return $next($request);
        }

        // $request->ip() 在反代后面拿到的可能是代理 IP,见上文 TrustProxies
        $region = $this->geo->lookup($request->ip());

        // 挂到请求上,控制器/表单验证/日志都能用
        $request->attributes->set('ip_region', $region);
        $request->attributes->set('city', $region['ok'] ? $region['city'] : null);

        // 视图里直接 {{ $geo['city'] ?? '全国' }}
        View::share('geo', $region);

        return $next($request);
    }
}

控制器里就这么用,不再关心接口:

php
public function index(Request $request)
{
    $geo  = $request->attributes->get('ip_region');
    $city = $geo['ok'] ? $geo['city'] : null;

    // 没有城市就退到全省,再没有就退到全国,逐级降级
    $acts = Activity::query()
        ->when($city, fn ($q) => $q->where('city', $city))
        ->when(!$city && $geo['ok'], fn ($q) => $q->where('prov', $geo['prov']))
        ->orderByDesc('starts_at')
        ->limit(20)
        ->get();

    return view('home', compact('acts', 'geo'));
}

历史数据怎么办?订单表里存了 ip 却没有 prov/city 的那批,不要写个脚本同步跑——接口 60 次/分钟,一万条订单要跑三个小时,中途挂了还得重来。丢队列里慢慢补:

php
// app/Jobs/BackfillOrderRegion.php
class BackfillOrderRegion implements ShouldQueue
{
    public function __construct(public int $orderId) {}

    public function handle(IpRegion $geo): void
    {
        $order = Order::find($this->orderId);
        if (!$order || $order->city) {
            return;                       // 已有属地,幂等跳过
        }
        $r = $geo->lookup($order->ip);
        if ($r['ok']) {
            $order->update(['prov' => $r['prov'], 'city' => $r['city']]);
        }
    }
}

下单成功后用 dispatch(new BackfillOrderRegion($order->id))->afterResponse(),让它等响应返回了再进队列,别让用户多等那 100 毫秒。

四、上线前要定的几个参数 ​

超时和降级。 中间件里的 Http::timeout(3) 是上限,实际生产建议 1.5 秒,并且给接口加一个熔断:连续失败 N 次就跳过查询一段时间,直接给「全国」。用户看到的是默认内容,比看到 502 好。

首页别同步查。 如果首页 QPS 很高、缓存命中率又低(第一次上线必然是),中间件同步查会把接口延迟直接叠到 TTFB 上。折中做法是:中间件只读缓存,没有就用 cookie 里上次的城市,真正的查询放到队列里预热。这一点取决于你的流量规模,几十 QPS 的站没必要这么复杂。

限速是 60 次/分钟。 这不是「每分钟只能查 60 个不同 IP」以外的意思——同一个 IP 重复查也算次数,所以缓存不是优化项,是必需品。真到了每天都有一批新 IP 的量级,再考虑 VIP 版(按次计费、18 万次/分钟)。

字段边界。 area(区县)在免费版是空串,要区县级展示必须上 VIP;lng/lat 是城市中心点,别拿来做「距离我多远」;isp 可以用来做运营商维度的分流,但不代表 IP 类型,判断机房 IP 要用 VIP 的 ip_type。

合规。 IP 是个人信息。缓存里存 IP 明文没问题,但别把 ipgeo:* 这种 key 暴露给外部;日志里记录 IP 时最好截断或哈希,只留省市做分析。用户协议里写明「为提供本地化内容与安全审计,我们会记录访问 IP 并解析到城市级」。

总结 ​

这套写法的核心不是代码量,而是把「查 IP」从业务代码里抽出来,变成一个可缓存、可降级、可观测的基础设施。上线后你会得到三个直接收益:控制器变干净、接口调用量掉一个数量级、CDN 换回源也不会再让全站显示同一个城市。

接口本身没什么花样,https://ip9.com.cn/get?ip=<ip> 就够用,不传 ip 参数时返回请求方自己的归属地;中文字段名和返回样例在 https://www.ip9.com.cn 上能直接对着看。