刚被安全扫描点名,第一件事就是重写鉴权:FastAPI 这套 JWT 接法,很多人第一步就错了
刚被安全扫描点名,第一件事就是重写鉴权:FastAPI 这套 JWT 接法,很多人第一步就错了
最近科技圈被一条安全消息刷了屏:有媒体报道,Python 世界里下载量惊人的 Starlette 组件被曝出身份验证绕过问题,而它正是 FastAPI 的“地基”,一票 AI 应用、智能体服务都架在上面。消息一出,不少做后端的团队连夜排查版本。
但说句实在话,底层组件打补丁,运维同学十分钟就能搞定。真正让人睡不着的,是另一件事:自家那套登录、发令牌、验身份的代码,到底是照规范写的,还是拍脑袋拼出来的?
很多项目平时跑得好好的,一扫就露馅:令牌永不过期、密钥直接写在代码里、密码明文存库、接口忘了校验……漏洞往往不是黑客多厉害,而是自己门口没锁。
FastAPI 其实早就把一套“标准门禁系统”摆在那儿了,只是很多人没用对。今天就用大白话聊聊,JWT 和 OAuth2 到底该怎么接。
一、先搞懂:JWT 和 OAuth2 到底是个啥?
别被英文缩写吓到,用生活场景一秒理解。
OAuth2 是一套“进门规矩”,规定了谁能进门、进门要出示什么、能进哪几个房间。你在很多 App 上见过的“用微信登录”“用 Google 登录”,背后跑的就是它。
JWT 则是一张“防伪手环”。你去游乐园玩,门口检票后给你戴一个手环,之后玩每个项目,工作人员只看手环,不用再查身份证。
这张手环上有你的名字、有效期、能玩哪些项目,内容谁都看得见——它不加密。但它上面有一个只有乐园能盖出来的“防伪章”(签名)。谁要是偷偷把手环上的“有效期”改成十年,章就对不上了,工作人员一眼识破。
FastAPI 官方文档里把这件事讲得很直白:JWT 就是一串很长、没有空格的字符,内容公开,但签名不可伪造。所以你可以放心地给它设一个有效期,比如一周。一周内用户拿着它随便逛,一周后自动失效,重新登录换新的。
这套机制的好处,说白了就一句:服务器不用记住谁登录过,只看手环真假就行。用户量涨到几十万,后端也不会被“登录状态”压垮。
二、真正好用的地方:把“查证件”变成一道自动关卡
很多人写鉴权,是在每个接口开头复制粘贴一段“解析令牌、查用户、判断权限”。接口一多,总有几个忘了写——这就是安全事故的高发区。
FastAPI 最聪明的一招,是把校验做成了“依赖”:你只要声明“这个接口需要登录”,它就会在业务代码跑起来之前,自动完成查证件、找用户、判权限的全套动作。写业务的人根本不用操心门有没有锁。
这就像公司前台:不管你来谈合作还是送快递,先过前台这一关,前台核实完身份才放你进办公区,而不是每个部门自己派人去门口盯。
更贴心的是,它连“试衣间”都给你准备好了。
FastAPI 会自动生成一份可交互的接口文档。你打开页面,右上角有个 Authorize 按钮,点一下输入账号密码,浏览器就会替你去换令牌,之后所有请求自动带上身份,直接点“执行”就能测。

如果你打开浏览器的开发者工具,还能清楚看到:真正的密码只在第一次登录时传了一次,后面每次请求带的都只是一枚令牌,形如“Bearer 加一串字符”。

这个细节很关键:密码传得越少,泄露的机会就越少。
三、三个最容易被扫出来的坑,看看你中了几个
FastAPI 官方文档里其实反复提醒过,但每年还是有人往里跳。
第一个坑:手写中间件拦截所有请求。
不少人觉得“我自己写个中间件,统一拦一下不就行了”。问题是,中间件拦的是“所有请求”,它分不清哪个接口需要登录、哪个接口本来就该公开。结果要么把登录接口自己也拦死了,要么为了放行又开了一堆后门。用官方那套依赖声明,公开接口和受保护接口各写各的,边界清清楚楚,不会互相牵连。
第二个坑:自己搓签名算法。
有人嫌装库麻烦,拿个哈希函数自己拼一套“令牌”。这种东西看着能跑,但漏洞往往藏在细节里:签名比较时机的差异、算法可以被替换、令牌过期没校验……安全圈有专门的攻击手法就盯着这些缝隙。官方的做法很省事:装一个成熟的 JWT 库,签名、解码、过期校验全交给它,你只负责写业务。
顺带一提,密钥千万别用示例里的那串。文档里写得很清楚,那只是演示用的,正式环境要用随机生成的密钥,而且只能放在环境变量里,绝不能进代码仓库。多少事故,就是密钥跟着代码一起被推到公开仓库开始的。
第三个坑:密码存明文,或者用错了哈希。
密码在数据库里必须是“哈希”——一段看起来像乱码的字符串。它的特点是:同样的密码算出来永远一样,但你没法从乱码反推出原密码。这样即使数据库被拖走,小偷也拿不到用户的真实密码,更没法拿去撞别的网站。
FastAPI 文档现在推荐的是 Argon2 算法,属于目前比较硬核的选择。还有一个特别容易被忽略的细节:当用户不存在时,也要假装验一次密码。
为什么?因为如果“用户不存在”秒回、“密码错误”慢半拍,攻击者靠计时就能猜出哪些账号真实存在,这叫“时序攻击”。文档里专门用一个假密码哈希来抹平这个时间差,这种细节,自己手写基本想不到。
另外,令牌也不能“一发了之”。官方示例给的是 30 分钟有效期,短期令牌加刷新令牌才是正解。真要踢人下线,还得有一份“吊销名单”,不然手环丢了,只能等它自己过期。
四、普通人能上手吗?门槛比想象中低
这套东西听起来专业,实际动手门槛并不高。
不需要显卡,不需要服务器集群,一台普通笔记本就够。装两个常用的小库——一个负责签发和校验令牌,一个负责密码哈希——然后照官方文档的示例走一遍,半小时内就能跑出“登录拿令牌、带令牌访问受保护接口”的完整闭环。
它最适合谁?
做 AI 应用和智能体的开发者,这是眼下最需要补课的一群人。很多 Agent 服务为了赶进度,接口裸奔上线,一旦被扫到,调用额度、用户数据全暴露。这次底层组件出事,恰好给所有人提了个醒。
做小程序、App 后端的团队,用户账号体系是命根子,鉴权写错一次,代价可能是全量用户数据。
正在从 Flask 或 Django 迁移的工程师,FastAPI 这套安全写法几乎是“教科书式”的,照着抄都不会跑偏。
当然,如果你只是写个内部小工具、本地跑跑脚本,那确实没必要上这么完整的方案。安全要跟业务价值匹配,这话也得说清楚。
五、写在最后
这次漏洞风波,最值得记住的不是哪个版本号要升级,而是一个朴素的道理:
安全从来不是加一个补丁,而是把门锁对。
底层组件会出问题,这很正常,全世界的基础设施都在被反复审视。但你自己的登录流程、令牌有效期、密码存储方式、密钥管理,这些是别人替不了你的。
FastAPI 把标准答案摆在文档里很多年了:OAuth2 定规矩,JWT 发手环,依赖注入当门卫,密码只存哈希,密钥只进环境变量。没有一行是黑魔法,难的是愿不愿意老老实实照做。
最后留个话题给大家:你们公司的登录令牌,有效期设的是多久?有没有那种“一次登录,终身有效”的系统? 欢迎在评论区聊聊,说不定能帮哪位朋友提前避个雷。
