一个后台管理系统原来只跑一台机器,登录状态用文件 session,一切正常。为了扛住流量加了第二台,前面挂了负载均衡,问题立刻出现:用户登录成功,刷新一下又回到登录页,再过一会儿又能进去。日志里没有任何报错,只有同一个用户在两台机器之间来回切。
原因很朴素:session 文件只存在各自机器的磁盘上,A 机发的会话 ID 到 B 机找不到对应文件,框架就当成未登录。负载均衡没做会话粘滞,请求随机落到两台机器,于是登录状态时有时无。
另一个项目走了另一条路:前端把登录返回的令牌存进 localStorage,每次请求放在 Authorization 头里。接口本身没问题,直到页面上线了一个第三方富文本组件,组件里一段脚本把 localStorage 全读走,攻击者拿着令牌直接调接口。这篇讲的就是这两条路线的分叉点:登录状态到底存在哪一层,以及每选一种要付什么代价。
两条路线:会话与令牌
先分清三个词。认证(authentication)回答「你是谁」,发生在登录那一刻;授权(authorization)回答「你能做什么」,发生在每个请求;会话(session)回答「这次访问怎么被记住」,是登录之后维持状态的机制。
Laravel 里对应两条路线。第一条是 Web session:登录成功后,服务端存一份会话数据,浏览器拿一个会话 ID 的 Cookie,后续请求带着 Cookie,服务端按 ID 找回数据。第二条是 API 令牌:登录接口返回一串令牌,客户端自己保存,每次请求放在请求头里,服务端按令牌查用户。
laravel_session Cookie,API 路线是客户端自己保管的令牌字符串。personal_access_tokens 表里。两条路线的安全假设不同。Web session 的凭证在 HttpOnly Cookie 里,JavaScript 读不到,XSS 拿不走会话本身,但服务端要防 CSRF;API 令牌如果放在 localStorage,JavaScript 能读,XSS 直接拿走,但因为没有 Cookie,天然不受 CSRF 影响。选哪条,本质是在 XSS 和 CSRF 之间分配风险,而不是在「哪种更安全」之间二选一。
框架里这两条路线由 guard 区分。config/auth.php 里默认有一个 web guard,驱动是 session,用户来源是 App\Models\User;装了 Sanctum 之后会多出一个 sanctum guard,驱动是 sanctum,它先尝试 Cookie 会话,再尝试请求头里的令牌。路由上写 auth 用的是默认 guard,写 auth:sanctum 才走 Sanctum。搞混这两个名字,会出现「明明登录了却 401」。
选型前先回答两个问题:客户端里有没有浏览器页面?业务需不需要「立即踢人下线」?两个答案都是「是」,就用 Cookie 会话;客户端全是移动端或第三方,且能接受令牌只存哈希、撤销靠删记录,就用不透明令牌。两个问题答案不一样时,两条路线并存比强行统一更实际。
Session 存在哪里,决定能不能多机
Laravel 的 session 驱动在 config/session.php 里由 SESSION_DRIVER 决定。可选项不多,但每个的边界都很清楚:
| 驱动 | 存在哪 | 多机可用 | 代价 |
|---|---|---|---|
file | 本机 storage/framework/sessions | 否 | 多机各存各的,必须做粘滞或共享目录 |
redis | Redis 键值 | 是 | 多一个必须高可用的组件 |
database | sessions 表 | 是 | 每次请求多一到两次数据库读写 |
cookie | 加密后放回 Cookie | 是 | 会话数据全在客户端,容量和泄露风险都要考虑 |
array | 进程内存 | 否 | 只适合测试,请求结束即丢 |
多机部署的默认答案应该是 Redis 或数据库,而不是共享目录。把 storage/framework/sessions 挂成 NFS 看似省事,但文件锁、网络延迟和单点故障会一起进来,session 写入在请求结束时才落盘,机器一多,锁竞争会很直接地反映在响应时间上。
会话还有两个参数要一起看:lifetime 是「多久不活动就失效」,单位分钟;expire_on_close 控制关浏览器是否立刻失效。前者太长会让被盗的会话存活更久,太短会让用户频繁重新登录。文件驱动还需要垃圾回收,Laravel 按一定概率在请求中清理过期文件,概率配置在 config/session.php 里;换成 Redis 后靠键的过期时间自动清理,这一点反而省心。
切到 Redis 需要在 .env 里改三处:SESSION_DRIVER=redis、REDIS_HOST、REDIS_PORT,并确认装了 phpredis 扩展或 predis 包。切完之后所有机器共享同一个会话空间,用户落到哪台机器都能认出登录态。代价是 Redis 成为登录链路上的关键依赖,它挂掉时所有人都登不进去,所以要么做主从加哨兵,要么保留数据库驱动作为降级方案。
还有一个容易漏的点:切换驱动不会迁移旧会话,已经在线的用户会全部掉一次登录。这类变更要放在低峰,并提前通知。切换之后旧驱动里的数据不会自动清理,需要单独写一次清理任务。
Cookie、CSRF 与 SameSite
Web 路线里,浏览器只保存一个会话 ID。Laravel 默认会给这个 Cookie 加 HttpOnly,JavaScript 读不到;同时给 Cookie 内容做加密,即使被篡改也解不开。这两个默认值不要改,它们是这条路线安全性的基础。
CSRF(跨站请求伪造)是 Cookie 方案必须面对的问题:攻击者在自己页面上构造一个表单,向你的站点发请求,浏览器会自动带上 Cookie,服务端分不清这是用户本意还是伪造。Laravel 的 web 中间件组里有一个 CSRF 校验中间件,要求请求带一个 token,这个 token 存在 session 里,同时渲染到页面或写进 XSRF-TOKEN Cookie。
令牌对不上时返回 419,这是很常见的「页面放太久,提交失败」。SPA 场景要先请求 /sanctum/csrf-cookie 拿到 XSRF-TOKEN,之后由前端框架在请求头里带 X-XSRF-TOKEN。这个过程不对,表现就是登录接口 419。
SameSite 是另一道防线。它告诉浏览器「跨站请求要不要带这个 Cookie」,Lax 表示顶层导航的 GET 可以带,POST 不带;Strict 更严;None 必须同时开 Secure,只适合确有必要跨站的场景。Laravel 的默认值可以通过 config/session.php 的 same_site 调整,多数业务保持 lax 即可。
SPA 场景要额外注意 Cookie 的作用域。前端和后端如果不在同一个域名下,config/session.php 的 domain 必须覆盖两者共同的父域,CORS 配置还要允许携带凭证(supports_credentials 为 true),否则浏览器不会把 Cookie 带回来。这三处(domain、SameSite、CORS 凭证)任意一处不对,表现都是「登录接口返回成功,下一个请求却是 401」。
SameSite 改成 none 之前先确认确实需要跨站携带 Cookie,比如支付回调、嵌入式页面。放宽之后 CSRF 防线会变薄,必须确保 CSRF token 校验没有被关掉。Sanctum:不透明令牌怎么做
Sanctum 是 Laravel 官方提供的一套轻量鉴权方案,同时支持两种用法:SPA 用 Cookie 会话,移动端和第三方用个人访问令牌(personal access token)。这里先讲令牌,因为它最常被误解成 JWT。
Sanctum 的令牌是不透明的:一串带前缀的随机字符,服务端在 personal_access_tokens 表里存它的哈希和所属用户,校验时查表。它不是 JWT,没有把用户信息编码进令牌本身,所以每一次校验都要访问数据库或缓存;换来的是可以随时撤销、可以给每个令牌单独设权限和过期时间。
安装命令是 php artisan install:api,它会装 Sanctum、生成 routes/api.php、发布配置文件并执行迁移,建出 personal_access_tokens 表。用户模型要加 HasApiTokens trait,之后就能创建令牌:
$token = $user->createToken(
'mobile-app',
['orders:read', 'orders:write'],
now()->addDays(30)
);
return response()->json([
'token' => $token->plainTextToken,
]);
三个参数分别是令牌名、能力列表和过期时间。能力(abilities)是字符串数组,配合 tokenCan 做粗粒度授权;过期时间不传时是否过期取决于 config/sanctum.php 的 expiration,生产环境建议设一个明确值,不要让令牌永久有效。
plainTextToken 只在创建那一刻返回一次,之后数据库里只有哈希。所以创建接口必须把明文响应给客户端,客户端自己保存;服务端日志、监控、错误上报里都不能打印它。把这个字段打进日志,是比「令牌泄露」更常见的事故来源。
校验用 auth:sanctum 中间件,路由上这样写:
Route::middleware('auth:sanctum')->group(function () {
Route::get('/v1/me', [ProfileController::class, 'show']);
Route::get('/v1/orders', [OrderController::class, 'index'])
->middleware('ability:orders:read');
});
ability 中间件接在 auth:sanctum 之后,先确认身份,再确认这个令牌有没有对应能力。顺序反了会先检查能力再确认用户,拿不到令牌对象。
撤销令牌很简单:登出时删掉当前令牌,改密码时删掉该用户所有令牌。currentAccessToken()->delete() 只作用于本次请求用的那一个;$user->tokens()->delete() 会清空全部设备。改密后全量删除是安全默认值,代价是用户要在所有设备重新登录。过期和已删的令牌记录不会自动消失,需要定时执行 php artisan sanctum:prune-expired --hours=24,否则表会一直涨。
登录与登出的完整代码
Web 路线的登录,核心是 Auth::attempt 加会话重新生成。重新生成的目的是防止会话固定攻击:攻击者事先把一个会话 ID 塞给用户,用户登录后如果沿用同一个 ID,攻击者就拿到了已登录的会话。
public function login(LoginRequest $request)
{
$credentials = $request->validated();
if (! Auth::attempt($credentials, true)) {
return response()->json(['message' => '邮箱或密码不正确'], 401);
}
$request->session()->regenerate();
return response()->json(['user' => $request->user()]);
}
public function logout(Request $request)
{
Auth::guard('web')->logout();
$request->session()->invalidate();
$request->session()->regenerateToken();
return response()->noContent();
}
登出不是删掉前端状态就完事。服务端的会话必须作废,否则用户以为退出了,旧 Cookie 还能用。invalidate 清空会话数据并换 ID,regenerateToken 换 CSRF token,这两步缺一不可。
登录接口本身要有速率限制,否则会被撞库。Laravel 自带 throttle 中间件,按 IP 或按「IP 加邮箱」限速都可以,超限返回 429。密码校验要用 Hash::check 或 Auth::attempt,不要自己写字符串比较,也不要把明文密码存进日志。
登录失败的信息也要克制。统一返回「邮箱或密码不正确」,不要分别提示「用户不存在」和「密码错误」,后者等于给撞库的人一个确认账号是否存在的接口。同样,登录成功和失败的响应时间要接近,避免通过耗时差异推断账号状态。
API 令牌路线的登录接口不写 session,直接创建令牌。下面这组命令和请求把「登录、拿令牌、带令牌访问」串起来:
php artisan migrate
php -S 127.0.0.1:8030 -t public
curl -i -X POST http://127.0.0.1:8030/api/v1/tokens \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{"email":"demo@example.com","password":"secret"}'
本机实测返回 200,响应体是 {"token":"2|DSfR8FeQvaDWivsDBIseF1DeLa2RTWUeDPc5vmlX77ecde77"},令牌值每次登录都不同。再用这个令牌访问受保护接口:
curl -i http://127.0.0.1:8030/api/v1/me \
-H "Accept: application/json" \
-H "Authorization: Bearer 2|DSfR8FeQvaDWivsDBIseF1DeLa2RTWUeDPc5vmlX77ecde77"
本机实测:带令牌返回 200 和用户 JSON({"id":1,"name":"Demo User","email":"demo@example.com",...});去掉 Authorization 头再请求一次,返回 401 和 {"message":"Unauthenticated."}。Sanctum 的 personal_access_tokens 表由 php artisan install:api 加 vendor:publish --tag=sanctum-migrations 建出,随后 migrate 生效。
Gate 与 Policy:授权别塞进控制器
认证解决「是谁」,授权解决「能不能做」。Laravel 的授权有两层:Gate 适合简单规则,Policy 适合按模型组织的规则。
Gate 的写法是一个名字加一个闭包,Gate::define('view-audit', fn (User $user) => $user->hasRole('admin')),用到的地方写 Gate::allows('view-audit') 或 @can。规则只有一两行、又不针对某个模型时,用 Gate 比建一个 Policy 类轻。规则一旦开始按模型区分,就换成 Policy,否则 Gate 里会堆满 if。
Policy 是一个类,对应一个模型,方法名就是动作名,比如 view、update、delete。生成命令是 php artisan make:policy OrderPolicy --model=Order。
public function update(User $user, Order $order): bool
{
return $user->id === $order->user_id
|| $user->hasRole('admin');
}
控制器里用 $this->authorize('update', $order),失败抛 403;路由上用 ->middleware('can:update,order'),框架会自动做路由模型绑定再调 Policy。两种方式选一种即可,不要把判断写成 if ($order->user_id !== auth()->id()) 散落在每个方法里——那种写法漏一处就是越权。
401 和 403 的区别要分清:401 是「没登录或令牌无效」,403 是「登录了,但没权限」。前端对 401 的处理通常是跳登录,对 403 是提示无权限。如果把 403 写成 401,用户会被反复踢回登录页,问题却一直存在。
现象、原因与第一步
| 现象 | 真实原因 | 第一步查什么 |
|---|---|---|
| 多机部署后刷新掉登录 | session 存在本机文件,机器之间不共享 | 看 SESSION_DRIVER;检查负载均衡是否粘滞 |
| 登录接口 419 | CSRF token 缺失或与 session 不匹配 | 请求是否先拿 /sanctum/csrf-cookie;Cookie 域是否正确 |
| 带令牌仍返回 401 | 请求头格式不对、令牌已撤销或过期 | 看 Authorization: Bearer;查 personal_access_tokens |
| 有权限却返回 403 | Policy 判断写反,或 can: 参数名与绑定不一致 | 在 Policy 方法里打日志;确认模型绑定成功 |
| 退出后旧令牌还能用 | 只清了前端状态,服务端令牌未删除 | 登出逻辑里是否调用了 currentAccessToken()->delete() |
| XSS 后账号被冒用 | 令牌存放在 localStorage,脚本可直接读取 | 改为 HttpOnly Cookie 会话,或缩短令牌有效期 |
| 跨站请求带不上 Cookie | SameSite 与域名配置不匹配 | 看 config/session.php 的 same_site 和 domain |
| 切换驱动后全员掉线 | 旧会话没有迁移,新驱动里没有记录 | 确认切换窗口与通知;必要时做兼容读取 |
边界与代价
Web session 的边界在「服务端必须存」。存储层挂了,登录链路就挂;存储层要扩容,会话数据要跟着迁。好处是撤销能力完整:管理员可以强制下线、改密可以踢掉所有会话、可以按用户查当前登录设备。这些能力在纯 JWT 方案里要靠额外的黑名单表才能实现,等于又把状态存了回去。
API 令牌的边界在「每次校验都要查库」。Sanctum 的不透明令牌查询很轻,走主键或哈希索引,单次成本可控;但高并发下这是一次额外的数据库往返,通常要加缓存或接受这点开销。令牌表会随登录次数增长,必须定期清理过期和已撤销的记录,否则表会越来越大。
JWT 的卖点是服务端无状态、校验不用查库,适合服务间调用和超大规模读场景。代价是撤销困难:令牌签发后在过期前一直有效,要立刻失效只能维护黑名单,或者把有效期压到几分钟再加刷新令牌。业务里只要有「封号立即生效」「改密踢人」这类需求,纯 JWT 就不合适。
如果确实要把令牌放在浏览器里,位置也有讲究。localStorage 读写方便,但任何一段页面脚本都能读;sessionStorage 只活到标签页关闭,泄露窗口小一些;放在内存变量里最安全,代价是刷新就丢,需要重新用 HttpOnly Cookie 换取。现实中的折中是:短期访问令牌放内存,刷新令牌放 HttpOnly Cookie,并且服务端对刷新令牌做轮换和一次性校验。这套方案复杂度不低,项目没有明确的跨端需求时,直接用 Sanctum 的 Cookie 模式更省事。
换成别的方案的成本也要提前算。Web session 换成令牌,前端所有请求的凭证方式要改,CSRF 逻辑要拆,跨域配置要重做;反过来把令牌换成 Cookie 会话,移动端和第三方调用又没法直接用。多数项目的现实做法是两条并存:浏览器用 Sanctum 的 SPA 模式走 Cookie,开放平台和移动端走令牌,各自守住自己的边界。
当天能自己验证的练习
- 把
SESSION_DRIVER从file改成redis,起两台本地实例(不同端口)共用一个 Redis,登录后交替请求,确认登录态保持。 - 用 curl 先请求
/sanctum/csrf-cookie,不带X-XSRF-TOKEN提交一次,记录 419;再带上 token 提交,确认成功。 - 用
php artisan tinker给一个用户创建带orders:read能力的令牌,分别访问带ability和不带ability的路由,对比 200 与 403。 - 登录后调用登出接口,再用原来的 Cookie 或令牌请求受保护接口,确认返回 401。
- 写一个 Policy,让普通用户只能改自己的订单,用两个不同账号调用同一个接口,确认一个 200、一个 403。
小结
三句话:登录状态存在哪一层,决定了能不能多机和能不能撤销;浏览器场景用 HttpOnly Cookie 加 CSRF 防护,开放场景用不透明令牌加过期和 abilities;认证和授权分开做,401 和 403 不要混用。
下一篇讲后台任务。登录和下单这类请求必须当场返回,但发邮件、生成报表、同步库存这些事不能占着请求线程做。队列把「现在必须做完的」和「可以晚点做的」分开,代价是引入了新的失败模式:任务会重复、会丢、会堆积。下一篇从一次发布后队列积压的事故开始。