一个后台管理系统原来只跑一台机器,登录状态用文件 session,一切正常。为了扛住流量加了第二台,前面挂了负载均衡,问题立刻出现:用户登录成功,刷新一下又回到登录页,再过一会儿又能进去。日志里没有任何报错,只有同一个用户在两台机器之间来回切。

原因很朴素:session 文件只存在各自机器的磁盘上,A 机发的会话 ID 到 B 机找不到对应文件,框架就当成未登录。负载均衡没做会话粘滞,请求随机落到两台机器,于是登录状态时有时无。

另一个项目走了另一条路:前端把登录返回的令牌存进 localStorage,每次请求放在 Authorization 头里。接口本身没问题,直到页面上线了一个第三方富文本组件,组件里一段脚本把 localStorage 全读走,攻击者拿着令牌直接调接口。这篇讲的就是这两条路线的分叉点:登录状态到底存在哪一层,以及每选一种要付什么代价。

两条路线:会话与令牌

先分清三个词。认证(authentication)回答「你是谁」,发生在登录那一刻;授权(authorization)回答「你能做什么」,发生在每个请求;会话(session)回答「这次访问怎么被记住」,是登录之后维持状态的机制。

Laravel 里对应两条路线。第一条是 Web session:登录成功后,服务端存一份会话数据,浏览器拿一个会话 ID 的 Cookie,后续请求带着 Cookie,服务端按 ID 找回数据。第二条是 API 令牌:登录接口返回一串令牌,客户端自己保存,每次请求放在请求头里,服务端按令牌查用户。

浏览器层只保存一个随机标识。Web 路线是 laravel_session Cookie,API 路线是客户端自己保管的令牌字符串。
服务端存储层Web 路线把用户 ID、闪存数据、CSRF 令牌存在 file、Redis 或数据库里;API 路线把令牌的哈希存在 personal_access_tokens 表里。
校验层每个请求由对应 guard 校验:session guard 读 Cookie 找会话,token guard 读请求头查令牌,再决定放行还是 401。

两条路线的安全假设不同。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否多机各存各的,必须做粘滞或共享目录
redisRedis 键值是多一个必须高可用的组件
databasesessions 表是每次请求多一到两次数据库读写
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;检查负载均衡是否粘滞
登录接口 419CSRF token 缺失或与 session 不匹配请求是否先拿 /sanctum/csrf-cookie;Cookie 域是否正确
带令牌仍返回 401请求头格式不对、令牌已撤销或过期看 Authorization: Bearer;查 personal_access_tokens
有权限却返回 403Policy 判断写反,或 can: 参数名与绑定不一致在 Policy 方法里打日志;确认模型绑定成功
退出后旧令牌还能用只清了前端状态,服务端令牌未删除登出逻辑里是否调用了 currentAccessToken()->delete()
XSS 后账号被冒用令牌存放在 localStorage,脚本可直接读取改为 HttpOnly Cookie 会话,或缩短令牌有效期
跨站请求带不上 CookieSameSite 与域名配置不匹配看 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,开放平台和移动端走令牌,各自守住自己的边界。

当天能自己验证的练习

  1. 把 SESSION_DRIVER 从 file 改成 redis,起两台本地实例(不同端口)共用一个 Redis,登录后交替请求,确认登录态保持。
  2. 用 curl 先请求 /sanctum/csrf-cookie,不带 X-XSRF-TOKEN 提交一次,记录 419;再带上 token 提交,确认成功。
  3. 用 php artisan tinker 给一个用户创建带 orders:read 能力的令牌,分别访问带 ability 和不带 ability 的路由,对比 200 与 403。
  4. 登录后调用登出接口,再用原来的 Cookie 或令牌请求受保护接口,确认返回 401。
  5. 写一个 Policy,让普通用户只能改自己的订单,用两个不同账号调用同一个接口,确认一个 200、一个 403。

小结

三句话:登录状态存在哪一层,决定了能不能多机和能不能撤销;浏览器场景用 HttpOnly Cookie 加 CSRF 防护,开放场景用不透明令牌加过期和 abilities;认证和授权分开做,401 和 403 不要混用。

下一篇讲后台任务。登录和下单这类请求必须当场返回,但发邮件、生成报表、同步库存这些事不能占着请求线程做。队列把「现在必须做完的」和「可以晚点做的」分开,代价是引入了新的失败模式:任务会重复、会丢、会堆积。下一篇从一次发布后队列积压的事故开始。