状态与会话
本合集目录
本章目录
单册说明:本文件是卷 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 真正的优势在于"多个服务各自验签、不共享存储",单机项目用不上。下一步
能认出"你是谁"了,但还没管"你能碰哪些数据"。下一章处理最容易出人命的一环:注册、密码哈希,以及那个"功能全对、数据全泄"的越权漏洞。