跳到正文
零到全栈 · 卷 6 · 数据与状态

状态与会话

本合集目录
本章目录

单册说明:本文件是卷 6 的第 6 章,可独立阅读。前置:第 5 章(事务与迁移)。本章解释为什么"登录"这件事需要一个服务端的表,把 cookie 的每个属性讲清楚,再用 curl 的 -c/-b 走完登录、访问、登出的完整闭环。

项 内容
所属卷 卷 6 · 数据与状态(第 6 / 8 章)
前置章节 6.5 事务、并发与迁移
本章产出 sessions 表 + login/logout/me 三个端点 + 一次完整的 cookie 往返记录
对应代码 app/migrations/002_sessions.sql、app/services/auth.py、app/routers/auth.py、app/deps.py
配图 无(后续统一制图)
读完的判定 能用 curl -c / -b 手工完成一次登录并解释每一行响应头的含义

6.6.1 一句话结论:HTTP 不认识你,是浏览器每次替你递一张纸条

HTTP 是无状态协议:每个请求都是独立的,服务器不会记得上一个请求是谁发的。 所以"登录状态"不是服务器记性好,而是浏览器每次请求都自动附上一段凭证。

先说一个真实翻车。卷 5 为了省事,登录接口返回 {"id": 3},前端把它存进 localStorage,之后每次请求带 ?uid=3。功能全对,直到有人在 F12 里把 uid 改成 1:

GET /api/notes?uid=1     → 返回了另一个人的全部摘录

身份信息只要存在浏览器能改的地方,就等于没有身份。 浏览器里的一切(localStorage、URL 参数、请求头)都是用户可以任意修改的,区别只在于改起来费不费劲。

正确的形状是三段式:服务端生成一个猜不出来的随机串,存进数据库,只把这个串发给浏览器;浏览器每次自动带回;服务端拿串去查"这是谁"。

6.6.2 原理与方法

无状态到底意味着什么

说法 含义 后果
"服务器不记得你" 第 2 个请求到达时,服务器没有任何关于第 1 个请求的记忆 每个请求都得自带"我是谁"的凭证
"凭证放客户端" 浏览器负责保存和自动携带 客户端能改,所以凭证必须是"随机且服务端可验证"的
"会话是服务端的一张表" 真正的状态在数据库里 客户端拿的只是一个编号(token)

一句话:状态在服务端,凭证在客户端。

cookie 是什么

cookie 就是浏览器帮你维护的一个"域名 → 键值"小仓库。服务器用响应头写入,浏览器之后对同域请求自动带上:

服务器 → 浏览器:  Set-Cookie: sid=abc123; HttpOnly; SameSite=Lax; Path=/
浏览器 → 服务器:  Cookie: sid=abc123

属性决定了它能被谁读到、什么时候发:

属性 作用 本项目的取值 不设的后果
HttpOnly JS 读不到(document.cookie 里没有它) 开 XSS 注入一段脚本就能偷走 token
Secure 只在 HTTPS 下发送 上线开,本地关 明文 HTTP 上被中间人抓走
SameSite 跨站请求要不要带它 Lax 别的站点发起的请求也会带上,CSRF 敞口变大
Path 哪些路径带它 / 只对某子路径生效,/api 下反而带不上
Max-Age / Expires 多久过期 7 天 关掉浏览器就没了(会话 cookie)
Domain 哪些子域共享 不设(只当前域) 设成 .example.com 会让所有子域都收到

Secure 这一项有个非常典型的现象:本地 http://127.0.0.1 下开了 Secure,浏览器不会报错,只是安静地不保存这个 cookie。于是"登录成功,刷新又是未登录"。所以本书用环境变量控制它:本地 0,上线 1。

三种方案对比

把身份放 localStorage JWT 服务端 session
状态存在哪 浏览器 令牌自身(签名保护) 数据库一张表
客户端能改吗 能,随便改 改了就签名失效 改了就查不到
服务端能不能撤销 能(但没东西可撤) 很难,要维护黑名单 删一行,立刻生效
改密码后强制下线 要自己实现 令牌到期前仍然有效 DELETE FROM sessions WHERE user_id = ?
多机部署 无所谓 天然支持 需要共享会话存储
每请求开销 0 验签(CPU) 一次主键查询(微秒级)
体积 小 几百字节到 1KB 几十字节
实现复杂度 最低,也最不安全 高(签名、刷新、撤销策略) 中

JWT 不是不好,它的优势在"无状态、跨服务"。代价写在同一张表里:撤销难。用户手机丢了想"踢掉所有设备",JWT 方案要么等过期,要么再建一张"已注销令牌"表——那张表就是状态,无状态的好处又还回去了。

本卷选 session,理由只有一条:这个项目需要"立刻能踢人",而且只有一台机器。 单机场景下 session 的"要多一次查询"根本不是成本,SQLite 主键查询是微秒级。

一次会话的完整生命周期

动作 服务端 浏览器
登录 校验密码 → 生成 32 字节随机 token → 插 sessions 一行 → Set-Cookie 存下 cookie
访问 拿 cookie 里的 token 查 sessions JOIN users → 得到 current_user 自动带上 cookie
过期 查询条件带 expires_at > now,过期行查不到即视为未登录 无感知,表现为"要重新登录"
续期 两种做法:固定 7 天;或每次访问把 expires_at 往后推(滑动过期) 无感知
登出 DELETE FROM sessions WHERE token = ? + 清 cookie 删掉本地 cookie

续期怎么选:固定过期更安全(token 泄露的有效期有上限),滑动过期体验更好(活跃用户不掉线)。本项目用固定 7 天,简单且够用;要改只需动 SESSION_TTL_SECONDS 一处。

过期还有两件收尾的事。第一,判断过期用的是 SQL 里的时间比较,不是 Python 里的:

WHERE s.token = ? AND s.expires_at > strftime('%Y-%m-%dT%H:%M:%SZ','now')

因为时间是"现在"这个瞬间决定的,让数据库算比让应用算更不容易出错(多台机器时钟不一致时尤其明显)。这也依赖第 2 章那个决定:时间统一存成 YYYY-MM-DDTHH:MM:SSZ,字典序就是时间序。

第二,过期的行不会自己消失。如果不清理,sessions 表只涨不跌。最省事的做法是在登录时顺手清一批:

with transaction(con):
    store.purge_expired(con)      # DELETE FROM sessions WHERE expires_at <= now
    store.insert_session(con, token, user["id"], expires_at)

一次登录删几十行,成本可以忽略,也省掉了额外的定时任务。清理放在"已经有写事务"的地方,比单独开一个后台线程简单得多。

两个容易被忽略的细节:

细节 现象 说明
cookie 按"主机名"绑定 前端开 localhost:3000、后端在 127.0.0.1:8000,登录后 cookie 带不上 localhost 与 127.0.0.1 是两个不同的主机名,cookie 不共享。开发时两边用同一个写法
token 在库里是明文 库文件被人拿走,等于所有登录态被接管 更严的做法是存 sha256(token),查询时先哈希再比对;本项目规模下先记着这件事,第 8 章安全清单里再处理

第一条尤其坑:同一个人眼里的"本机",在浏览器看来是两个站点。排查时先去 DevTools 的 Application → Cookies 里看 Domain 列,比读十遍代码快。

CSRF:借你的 cookie 发请求

攻击场景:你登录了 dudao.example.com,浏览器里有有效 cookie。你打开另一个站点,页面里藏了一个表单:

<form action="https://dudao.example.com/api/notes/5" method="POST">
  <input name="title" value="被改掉的标题">
</form>
<script>document.forms[0].submit()</script>

提交时浏览器会自动带上 dudao 的 cookie——它分不清这个请求是你点的还是别人页面发的。这就是 CSRF(跨站请求伪造)。

SameSite 挡掉了大部分:

取值 跨站 POST 跨站顶级导航(点链接跳过来) 备注
None 带 cookie 带 必须同时设 Secure
Lax(默认) 不带 带 挡掉表单/fetch 类攻击
Strict 不带 不带 从别的站跳过来会显示未登录,体验差

Lax 留下的缺口是"顶级 GET 导航"——所以还有一条铁律:GET 请求不许改数据。如果哪天真做了"点链接即删除",SameSite 就保护不了它,得加 CSRF token 或要求二次确认。

6.6.3 动手:三个端点,一次闭环

第一步:建 sessions 表

-- app/migrations/002_sessions.sql
CREATE TABLE sessions (
    token      TEXT    PRIMARY KEY,
    user_id    INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    created_at TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%SZ','now')),
    expires_at TEXT    NOT NULL
);
CREATE INDEX idx_sessions_user ON sessions(user_id);

token 做主键:查询"这个 token 是谁"就是一次主键查找,最快。ON DELETE CASCADE:删用户时他的会话一起清掉。

第二步:生成一个猜不出来的 token

import secrets
token = secrets.token_urlsafe(32)     # 43 个字符,约 256 位熵

不要用 uuid4()(122 位,够但没必要少),更不要用 hash(时间戳)(可预测)。secrets 是标准库中专为安全场景设计的模块。

第三步:登录时写库 + 设置 cookie

@router.post("/login", response_model=UserOut)
def login(data: LoginIn, response: Response, con=Depends(get_db)):
    token = service.login(con, data.email.strip().lower(), data.password)
    response.set_cookie(
        key=COOKIE_NAME, value=token, max_age=SESSION_TTL_SECONDS,
        httponly=True, samesite="lax", secure=COOKIE_SECURE, path="/",
    )
    user = service.user_from_token(con, token)
    return {"id": user["id"], "email": user["email"], "created_at": user["created_at"]}

第四步:用 curl 走一遍

B=http://127.0.0.1:8099

# 1) 注册
curl -s -i -X POST $B/api/auth/register -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"s3cret-pass"}'

# 2) 登录,把 cookie 存到文件
curl -s -i -c cookies.txt -X POST $B/api/auth/login -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"s3cret-pass"}'

实测响应头里这一行是关键:

set-cookie: sid=WqOkrAvXRQKTEnmYO2EIV3ffKQyC10loVVDFkc_PMu8; HttpOnly; Max-Age=604800; Path=/; SameSite=lax

-c cookies.txt 把浏览器该做的事替你做了一遍。文件内容:

#HttpOnly_127.0.0.1	FALSE	/	FALSE	1795458041	sid	WqOkrAvXRQKTEnmYO2EIV3ffKQyC10loVVDFkc_PMu8

#HttpOnly_ 前缀说明 curl 知道这条不该被脚本读到——和浏览器的行为一致。

# 3) 带着 cookie 访问
curl -s -i -b cookies.txt $B/api/auth/me
# HTTP/1.1 200 OK
# {"id":1,"email":"[email protected]","created_at":"2026-11-16T18:20:41Z"}

# 4) 不带 cookie
curl -s -i $B/api/auth/me
# HTTP/1.1 401 Unauthorized
# {"error":{"code":"unauthorized","message":"请先登录"}}

# 5) 登出
curl -s -i -b cookies.txt -X POST $B/api/auth/logout
# HTTP/1.1 204 No Content
# set-cookie: sid=""; expires=...; Max-Age=0; Path=/; SameSite=lax

# 6) 用登出前的 cookie 再试一次
curl -s -o /dev/null -w '%{http_code}\n' -b cookies.txt $B/api/auth/me
# 401

第 6 步是整章最重要的一步。它证明登出不只是删了浏览器里的 cookie,服务端那行记录也没了。查一下数据库:

登录后 sessions: (2,)
登出后 sessions: (1,)
用旧 cookie 再请求: 401

(2 是因为之前还有一次登录没退,这次登出精确删掉了 1 行。)

6.6.4 三个坑

坑一:前端 fetch 不带凭据,每次都是"未登录"

症状:后端 curl 一切正常,浏览器里登录成功后再拉列表就 401。Network 面板里能看到请求确实发了,但请求头里没有 Cookie。

成因:前后端不同源(localhost:3000 调 localhost:8000)时,fetch 默认不发送跨源 cookie。而且 CORS 不允许 Access-Control-Allow-Origin: * 与凭据共存,浏览器会直接拒绝:

The value of the 'Access-Control-Allow-Origin' header in the response must not
be the wildcard '*' when the request's credentials mode is 'include'.

修法:前端每个请求加 credentials: 'include';后端 CORS 写明确源(不能是 *)并 allow_credentials=True。这两边必须同时改,改一边的表现是"请求被浏览器拦掉"或"cookie 就是不带"。判断到底改没改对,最快的办法是看 Network 里那条请求的 Request Headers 有没有 Cookie: 一行——没有就是前端或跨源的问题,有但后端仍返回 401,才是会话本身的问题。

坑二:本地开了 Secure,登录"成功"但状态没了

症状:POST /login 返回 200,响应头里也有 Set-Cookie,但下一个请求就是 401。DevTools 的 Application → Cookies 里找不到那条 cookie。

成因:Secure 属性要求 HTTPS。在 http://127.0.0.1 下浏览器会静默丢弃这条 cookie,不报错、不提示。127.0.0.1 被当作"安全上下文",但 cookie 的 Secure 检查仍然按协议走。

修法:用环境变量区分环境,本地 DUDAO_COOKIE_SECURE=0,上线设 1。别为了本地调试把 Secure 永久关掉——那会在上线时忘掉,token 走明文。

坑三:只在前端删 cookie,旧 token 还能用

症状:点了登出,页面回到登录页,看起来没问题。但把登录时的 cookie 复制出来,用 curl -b 再请求,依然 200。

成因:登出接口只做了 response.delete_cookie(...),服务端的 sessions 行还在。cookie 只是"凭证的载体",删掉载体不等于作废凭证——攻击者早就复制走了。

修法:登出必须"服务端删记录 + 客户端清 cookie"两件事都做,顺序无所谓,缺一不可。更彻底的做法是提供"退出所有设备":DELETE FROM sessions WHERE user_id = ?。

本章验收

  • sessions 表建好,登录后能查到一行,expires_at 是 7 天后
  • 用 curl -c / -b 完成登录、访问、登出三步
  • 能说出 HttpOnly、Secure、SameSite=Lax 各挡住了什么攻击
  • 登出后用旧 cookie 请求返回 401,且数据库里对应行已消失
  • 能说出本项目为什么不用 JWT,以及 JWT 在什么场景下更合适

自测

Q1:为什么不能把 user_id 存在 localStorage 里当登录态?

看答案 因为 localStorage 完全由客户端控制,用户在 F12 里改一个数字就能变成别人,服务端没有任何办法分辨。登录态的本质是"服务端能验证的凭证",不是"客户端声称的身份"。正确做法是服务端生成不可猜的随机 token 存库,客户端只保管这个 token——改 token 只会变成一个查不到的随机串。

Q2:HttpOnly 和 SameSite 分别防的是什么?它们能互相替代吗?

看答案 `HttpOnly` 防的是"读":JS 拿不到 cookie,XSS 注入的脚本没法把 token 发到攻击者服务器。`SameSite` 防的是"用":别的站点发起的请求不会自动带上 cookie,挡掉 CSRF。两者方向不同,不能替代——`HttpOnly` 挡不住"借浏览器自动发请求",`SameSite` 也挡不住脚本读取。所以两个都要开。

Q3:JWT "撤销难"具体难在哪?为什么加一张黑名单表就把它变回去了?

看答案 JWT 的验证方式是"签名对不对",签名对了就认,服务端不查任何存储。所以要作废一个还没过期的令牌,只能额外维护一份"已作废"清单,每个请求都去查——这份清单就是状态。既然都要查状态,那和直接用 session 表查一次没有本质区别,只是多了一层签名解析。JWT 真正的优势在于"多个服务各自验签、不共享存储",单机项目用不上。

下一步

能认出"你是谁"了,但还没管"你能碰哪些数据"。下一章处理最容易出人命的一环:注册、密码哈希,以及那个"功能全对、数据全泄"的越权漏洞。

→ 卷6-07-多用户与鉴权.md