Skip to content
Lv1HTTP 与 JSON进度 5 / 6

第 5 章:鉴权与密钥管理 ​

每个接口都要回答一个问题:"我凭什么相信你"。这一章讲怎么把凭证带对,以及更重要的一件事——怎么保证它不泄漏。


学习目标 ​

  • 分清 Cookie、Bearer Token、API Key 三种凭证的用法
  • 会把 Authorization 头写对(前缀、空格、大小写)
  • 用 .env 管理密钥,并确保它不进 Git
  • 遇到 401、403、429 知道分别该做什么
  • 知道密钥泄漏的五条常见路径,以及最基本的防护

5.1 三种凭证,三种场景 ​

方式放在哪谁在用特点
Cookie请求头 Cookie: session=...浏览器会话浏览器自动携带,跨域受限
Bearer TokenAuthorization: Bearer <token>API、移动端、OAuth手动带,跨服务通用
API Key请求头或查询参数第三方服务、大模型 API简单直接,长期有效

大模型 API 基本都用 API Key,通常放在请求头里:

http
Authorization: Bearer sk-xxxxxxxxxxxxxxxx

三个细节容易错:

  1. Bearer 后面有一个空格,少了它服务端解析不到;
  2. Bearer 大小写通常不敏感,但密钥本身区分大小写;
  3. 不要把 Key 放查询参数(?api_key=sk-...)。URL 会进日志、浏览器历史、Referer,泄漏面大得多。

5.2 短期 token 与长期 Key ​

有些服务不是直接给你一个 Key,而是"用 Key 换一个短期 token":

为什么要多这一层:短期 token 泄漏的损失有限(一小时后失效),长期 Key 可以一直用。企业级接口(飞书、Google、企业微信)基本都是这个模型。

写代码时对应两件事:

  • 缓存 token,别每个请求都去换(换 token 本身也是一次网络请求);
  • 收到 401 时先尝试刷新一次,再决定是否报错,而不是直接把 401 抛给用户。

5.3 .env:密钥不进代码 ​

最危险的做法是把 Key 写死在代码里:

python
API_KEY = "sk-xxxxxxxx"   # ❌ 一旦提交到 Git,等于公开

正确的是放在环境变量里:

bash
# .env 文件(不提交到 Git)
API_KEY=sk-xxxxxxxxxxxxxxxx
BASE_URL=https://api.example.com
python
import 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")
bash
pip install python-dotenv

两个用法的差别:

写法缺失时的行为适合
os.environ["API_KEY"]抛 KeyError,启动失败必需配置
os.environ.get("API_KEY")返回 None,错误延后可选配置

必需配置用 []:启动就崩,比跑到一半才报"401"好排查得多。

不装 dotenv 也可以 ​

服务器上通常直接用环境变量:

bash
export API_KEY=sk-xxxx
python main.py

或者在 Docker 里用 --env-file .env(Lv3 会讲)。.env 只是本地开发的便利,不是唯一方式。


5.4 密钥绝不能进 Git ​

三件事必须做:

  1. .gitignore 第一行加 .env:
gitignore
.env
.env.*
!.env.example
  1. 提供 .env.example,只写键名不写值,让别人知道要配什么:
API_KEY=
BASE_URL=https://api.example.com
  1. 万一已经提交了:光删文件没用,历史里还在。要清理历史(git filter-repo)并立刻去平台吊销这个 Key——这是唯一稳妥的补救。

判断一个仓库"看起来专业不专业",看一眼有没有 .env.example 和 .gitignore 就够了。


5.5 401、403、429:三种"不让你过" ​

状态码含义该做什么
401没认证 / 凭证无效或过期检查 Key 是否带、格式对不对、是否需要刷新
403认证了,但没权限检查账号权限、接口是否对当前角色开放、IP 白名单
429请求太频繁看 Retry-After 头,按它等待;降低并发

429 响应通常带一个头:

http
HTTP/1.1 429 Too Many Requests
Retry-After: 12

意思是"12 秒后再来"。遵守它,比自己拍一个 1 秒重试更有效——乱冲只会延长封禁。

还有一种隐蔽情况:401 但响应体说"余额不足"。有些平台把配额问题也用 401/403 返回,所以永远要读响应体,别只看状态码。


5.6 密钥是怎么泄漏的 ​

五个高频场景,按危险程度排:

  1. 日志:print(headers) 把 Authorization 打进了日志文件,日志又被收集到第三方平台;
  2. Git:.env 提交了,或者 Key 写在测试脚本里;
  3. 前端:把 Key 写进 JS,浏览器里 F12 就能看到——前端代码里永远不该有服务端 Key;
  4. 报错回显:接口报错时把整个请求(含头)返回给前端;
  5. 截图与聊天:调试截图发群里,Key 在截图角落。

防护的最低要求:

python
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 不进 URLURL 会进日志和浏览器历史
短期 token泄漏损失有限,401 时先刷新
.env + .gitignore密钥不入库,配 .env.example
必需配置用 os.environ[]启动即失败,好排查
401/403/429凭证、权限、限流三件事
遵守 Retry-After别自己拍重试间隔
泄漏五途径日志、Git、前端、报错、截图
轮换 + 最小权限降低单点泄漏的损失

下一章 ​

最后一章讲一个"看起来不像 HTTP"的 HTTP 用法:流式响应。大模型为什么要一个字一个字地吐、data: 开头的那几行到底是什么、Python 里怎么边收边处理——这是把 API 调用做得"像 ChatGPT 一样"的关键一步。

👉 第 6 章:流式响应与 SSE

本文阅读--次|全站访问--次|访客--人