第 5 章:鉴权与密钥管理
每个接口都要回答一个问题:"我凭什么相信你"。这一章讲怎么把凭证带对,以及更重要的一件事——怎么保证它不泄漏。
学习目标
- 分清 Cookie、Bearer Token、API Key 三种凭证的用法
- 会把
Authorization头写对(前缀、空格、大小写) - 用
.env管理密钥,并确保它不进 Git - 遇到 401、403、429 知道分别该做什么
- 知道密钥泄漏的五条常见路径,以及最基本的防护
5.1 三种凭证,三种场景
| 方式 | 放在哪 | 谁在用 | 特点 |
|---|---|---|---|
| Cookie | 请求头 Cookie: session=... | 浏览器会话 | 浏览器自动携带,跨域受限 |
| Bearer Token | Authorization: Bearer <token> | API、移动端、OAuth | 手动带,跨服务通用 |
| API Key | 请求头或查询参数 | 第三方服务、大模型 API | 简单直接,长期有效 |
大模型 API 基本都用 API Key,通常放在请求头里:
Authorization: Bearer sk-xxxxxxxxxxxxxxxx三个细节容易错:
Bearer后面有一个空格,少了它服务端解析不到;Bearer大小写通常不敏感,但密钥本身区分大小写;- 不要把 Key 放查询参数(
?api_key=sk-...)。URL 会进日志、浏览器历史、Referer,泄漏面大得多。
5.2 短期 token 与长期 Key
有些服务不是直接给你一个 Key,而是"用 Key 换一个短期 token":
为什么要多这一层:短期 token 泄漏的损失有限(一小时后失效),长期 Key 可以一直用。企业级接口(飞书、Google、企业微信)基本都是这个模型。
写代码时对应两件事:
- 缓存 token,别每个请求都去换(换 token 本身也是一次网络请求);
- 收到 401 时先尝试刷新一次,再决定是否报错,而不是直接把 401 抛给用户。
5.3 .env:密钥不进代码
最危险的做法是把 Key 写死在代码里:
API_KEY = "sk-xxxxxxxx" # ❌ 一旦提交到 Git,等于公开正确的是放在环境变量里:
# .env 文件(不提交到 Git)
API_KEY=sk-xxxxxxxxxxxxxxxx
BASE_URL=https://api.example.comimport os
from dotenv import load_dotenv
load_dotenv() # 读取同目录的 .env
api_key = os.environ["API_KEY"] # 用 [] 而不是 get,缺失时直接报错
base_url = os.environ.get("BASE_URL", "https://api.example.com")pip install python-dotenv两个用法的差别:
| 写法 | 缺失时的行为 | 适合 |
|---|---|---|
os.environ["API_KEY"] | 抛 KeyError,启动失败 | 必需配置 |
os.environ.get("API_KEY") | 返回 None,错误延后 | 可选配置 |
必需配置用 []:启动就崩,比跑到一半才报"401"好排查得多。
不装 dotenv 也可以
服务器上通常直接用环境变量:
export API_KEY=sk-xxxx
python main.py或者在 Docker 里用 --env-file .env(Lv3 会讲)。.env 只是本地开发的便利,不是唯一方式。
5.4 密钥绝不能进 Git
三件事必须做:
.gitignore第一行加.env:
.env
.env.*
!.env.example- 提供
.env.example,只写键名不写值,让别人知道要配什么:
API_KEY=
BASE_URL=https://api.example.com- 万一已经提交了:光删文件没用,历史里还在。要清理历史(
git filter-repo)并立刻去平台吊销这个 Key——这是唯一稳妥的补救。
判断一个仓库"看起来专业不专业",看一眼有没有 .env.example 和 .gitignore 就够了。
5.5 401、403、429:三种"不让你过"
| 状态码 | 含义 | 该做什么 |
|---|---|---|
401 | 没认证 / 凭证无效或过期 | 检查 Key 是否带、格式对不对、是否需要刷新 |
403 | 认证了,但没权限 | 检查账号权限、接口是否对当前角色开放、IP 白名单 |
429 | 请求太频繁 | 看 Retry-After 头,按它等待;降低并发 |
429 响应通常带一个头:
HTTP/1.1 429 Too Many Requests
Retry-After: 12意思是"12 秒后再来"。遵守它,比自己拍一个 1 秒重试更有效——乱冲只会延长封禁。
还有一种隐蔽情况:401 但响应体说"余额不足"。有些平台把配额问题也用 401/403 返回,所以永远要读响应体,别只看状态码。
5.6 密钥是怎么泄漏的
五个高频场景,按危险程度排:
- 日志:
print(headers)把Authorization打进了日志文件,日志又被收集到第三方平台; - Git:
.env提交了,或者 Key 写在测试脚本里; - 前端:把 Key 写进 JS,浏览器里 F12 就能看到——前端代码里永远不该有服务端 Key;
- 报错回显:接口报错时把整个请求(含头)返回给前端;
- 截图与聊天:调试截图发群里,Key 在截图角落。
防护的最低要求:
def mask(key: str) -> str:
"""日志里只留前 4 位和后 4 位"""
return key[:4] + "..." + key[-4:] if len(key) > 8 else "***"打日志时用它,别直接打原值。
5.7 轮换与最小权限
两条习惯,能显著降低"泄漏一次就完蛋"的风险:
- 定期轮换:给 Key 设定有效期(比如 90 天),到期换新。轮换成本远小于泄漏成本;
- 最小权限:能只读的 Key 就别给写权限,能限定 IP 的就限 IP,能按项目分 Key 的就分开。一个 Key 通吃所有服务,泄漏时损失最大。
发现泄漏后的顺序:先吊销,再排查,最后改代码。不要先去查"怎么漏的"——那几分钟里 Key 还是可用的。
本章小结
| 要点 | 说明 |
|---|---|
| 三种凭证 | Cookie、Bearer Token、API Key |
Authorization 格式 | Bearer + 空格 + token |
| Key 不进 URL | URL 会进日志和浏览器历史 |
| 短期 token | 泄漏损失有限,401 时先刷新 |
.env + .gitignore | 密钥不入库,配 .env.example |
必需配置用 os.environ[] | 启动即失败,好排查 |
| 401/403/429 | 凭证、权限、限流三件事 |
遵守 Retry-After | 别自己拍重试间隔 |
| 泄漏五途径 | 日志、Git、前端、报错、截图 |
| 轮换 + 最小权限 | 降低单点泄漏的损失 |
下一章
最后一章讲一个"看起来不像 HTTP"的 HTTP 用法:流式响应。大模型为什么要一个字一个字地吐、data: 开头的那几行到底是什么、Python 里怎么边收边处理——这是把 API 调用做得"像 ChatGPT 一样"的关键一步。