Appearance
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 上能直接对着看。