用户认证

设计目标

我决定实现用户认证系统,让每个用户有独立的调用配额。

核心需求:

  1. 用户可以注册账号
  2. 系统分配唯一的 API Key
  3. 每次调用必须验证 API Key
  4. 限制每个用户的调用配额

这是一个完整的认证体系,我需要从零开始设计。

方案设计

API Key(访问密钥)的设计

API Key 是什么?

  • 一个唯一的字符串
  • 也可以理解为用户调用 API 时携带的访问密钥
  • 用来标识用户身份和调用权限
  • 需要在每次调用时携带

API Key 的格式:

ak_live_xxxxxxxxxxxxxxx  (正式环境)
ak_test_xxxxxxxxxxxxxxx  (测试环境)

格式说明:

  • ak_:前缀,表示 API Key
  • live/test:环境标识
  • 后面:随机字符串

我特意加了环境标识,这样开发和生产环境可以分开管理。

数据模型设计

usersFields
字段名类型约束 / 说明
idINTPRIMARY KEY, AUTO_INCREMENT
emailVARCHAR(255)UNIQUE, NOT NULL
password_hashVARCHAR(255)NOT NULL
api_keyVARCHAR(64)UNIQUE, NOT NULL
planVARCHAR(50)DEFAULT 'free'
daily_limitINTDEFAULT 1000
created_atTIMESTAMPDEFAULT CURRENT_TIMESTAMP
usersRows
idemailplandaily_limitcreated_at
1alice@demo.comfree10002026-04-08 10:32:11
2bob@demo.compro1000002026-04-11 09:15:02
3ops@demo.combasic100002026-04-13 21:44:36

API Key 生成

生成安全的 API Key

API Key 是用户在这套系统里的身份证,生成环节决定了它能不能被猜到、被复用。我要求随机源不可预测,并且数据库里永远不出现明文——这条约束一旦放松,后面所有的配额和审计都会失去意义。

设计流程

生成安全的 API Key

  1. 步骤 1:用 secrets 模块生成足够长的随机串,拼上 ak_ 前缀与环境标识
  2. 步骤 2:数据库只保存密钥的哈希值,明文仅在注册响应里返回一次
  3. 步骤 3:校验密钥时按相同算法哈希后比对,避免数据库泄露即失守
  4. 步骤 4:把密钥摘要、创建时间与归属用户写入密钥表,便于吊销与审计

关注点:密钥的不可预测性,以及明文只出现一次这件事怎么落地。

为什么使用 secrets 模块?

  • 加密安全的随机数生成
  • 不可预测
  • 防止碰撞

我当时想,API Key 是用户的身份标识,必须在源头上保证安全。

用户注册流程

注册接口

注册是这套认证体系的入口:用户表、密钥表、配额表要在同一次请求里建好,任何一张没写成功都不该留下半成品账号。密钥明文也必须在这一步一次性交出去。

设计流程

注册接口

  1. 步骤 1:校验邮箱格式、密码强度,并确认该邮箱尚未注册
  2. 步骤 2:在同一事务里写入用户记录、密钥哈希与初始配额
  3. 步骤 3:生成明文 API Key,在响应体里返回一次并提示用户保存,同时写入注册审计日志

关注点:一次注册要同时落下哪几张表,以及密钥明文的返回时机。

登录接口

登录和注册长得像,目的却不同:注册负责把账号建出来,登录负责证明「你是你」。这里最关键的是失败提示不能泄露账号是否存在,否则接口本身就变成枚举工具。

设计流程

登录接口

  1. 步骤 1:按邮箱查出用户记录,取出存储的密码哈希
  2. 步骤 2:用 bcrypt 比对输入的口令,失败时统一返回「邮箱或密码错误」
  3. 步骤 3:登录成功后签发新的 API Key 或会话令牌,并记录登录时间、来源 IP 与结果

关注点:口令校验的正确性,以及登录行为如何进入审计。

我特意让 API Key 只在注册时返回一次,之后就再也看不到了。这样设计是为了安全,但也带来了一些麻烦——用户如果弄丢了 API Key,就只能重置。

API 调用认证

修改天气 API 接口

原来天气接口自己判断要不要校验密钥,现在改成统一入口先校验、再进业务。这是关注点分离带来的好处:以后加新的 API,认证逻辑一行都不用重写。

设计流程

修改天气 API 接口

  1. 步骤 1:在天气接口之前插入统一的认证中间件,业务代码不再自己校验密钥
  2. 步骤 2:中间件取出请求头里的 API Key,比对哈希确认密钥有效且未停用
  3. 步骤 3:校验通过后把用户身份、权限范围和剩余配额写入请求上下文
  4. 步骤 4:校验不通过时,按缺失、无效、超额分别返回 401、403、429

关注点:认证逻辑从业务处理里剥离之后,调用链是否依然清晰可读。

通过统一认证入口,我可以把认证逻辑从业务流程中分离出来。这是我从之前做系统设计的经验中学到的——关注点分离。

客户端使用方式

正确的调用方式

同一套认证体系,调用姿势不同,安全结果差得很远。正确的做法只有一条原则:密钥全程走请求头、走 HTTPS、只留在服务端。

设计流程

正确的调用方式

  1. 步骤 1:用 HTTPS 传输,在请求头里带上 Authorization: Bearer ak_live_xxxx
  2. 步骤 2:密钥只保存在服务端或环境变量里,不写进前端代码和仓库
  3. 步骤 3:收到 401 时先确认密钥是否被重置,再决定是否需要重新获取
  4. 步骤 4:按业务节奏轮换密钥,轮换后同步更新调用方配置

关注点:密钥在传输链路上的暴露面有多大。

错误的调用方式

把正确的做法和错误的放在一起看,差别才明显。下面这些是真实项目里最常见的泄露姿势,每一条都会让密钥离开它该待的地方,事后只能靠重置来止损。

设计流程

错误的调用方式

  1. 步骤 1:典型错误是把密钥硬编码在前端代码里,任何人打开控制台都能拿到
  2. 步骤 2:另一种错误是把密钥拼进 URL 查询参数,它会出现在网关日志和访问记录中
  3. 步骤 3:还有把密钥提交进 Git 仓库的,删除文件也留有历史记录
  4. 步骤 4:这些做法都会让密钥扩散到日志、截图和第三方手里,必须逐条排查

关注点:常见的密钥泄露途径,以及泄露后能不能被发现。

安全考虑

API Key 的安全问题

问题 1:API Key 泄露

  • 如果 API Key 泄露,他人可以冒用
  • 配额被消耗
  • 产生费用

解决方案:

  1. 提醒用户妥善保管 API Key
  2. 提供重置 API Key 的功能
  3. 设置 IP 白名单(可选)
  4. 监控异常调用

密码存储

密码不能明文存,这是最基本的底线。这一版先做了带盐哈希,把「明文落库」这个风险堵住,但我心里清楚快速哈希在离线撞库面前几乎不设防。

设计流程

密码存储

  1. 步骤 1:明确密码只存哈希值,日志和数据库备份里都不能出现明文
  2. 步骤 2:用 sha256 加随机盐做一次快速哈希,校验时按同样的盐重新计算并比对
  3. 步骤 3:承认快速哈希扛不住离线撞库,为下一步换成慢哈希做准备

关注点:哈希方案是否足以抵御撞库与彩虹表。

更好的方案是使用 bcrypt:

bcrypt 的价值在于它故意算得慢,成本因子可以随硬件变强而调高。为了不让老用户全部重置密码,我在登录成功的那一刻顺手完成哈希算法的迁移。

设计流程

密码存储

  1. 步骤 1:改用 bcrypt 存储密码,把 cost 设为 12,并在库中记录算法与 cost
  2. 步骤 2:登录时先用 bcrypt 校验,通过后再用同一套参数重新哈希,顺手升级旧哈希
  3. 步骤 3:校验失败时也执行一次假哈希,抹平「账号是否存在」的耗时差异

关注点:工作因子取值,以及老用户密码如何平滑迁移。

我当时想,安全这件事,再怎么重视也不为过。

真实上线还要注意

  • 不要只验证“这个 Key 对不对”。 还要记录它是谁、什么时候、从哪里调用了什么接口。
  • Key 泄露要能止损。 用户应该能重置密钥,系统也应该能临时停用异常密钥。
  • 认证、限流、计费要串起来。 否则用户明明被限流了,账单和日志却说不清原因。

效果验证

上线后,我观察了一周的数据:

滥用情况

指标之前现在
异常 IP 调用每天 10+ 个0 个 ✅
外部 API 滥用频繁0 次 ✅
正常用户体验差优秀 ✅

用户增长

指标数值
注册用户200 个
日活用户80 个
平均每用户调用100 次/天

看到这些数据,我知道这条路走对了。

新的问题

虽然解决了滥用问题,但带来了一些新挑战:

问题 1:数据存储

用户数据和调用日志越来越多:

  • 用户表:200 条
  • 日志表:每天 5 万条
  • 增长速度:每月 150 万条

应该用什么数据库?

问题 2:查询性能

日志表查询越来越慢:

日志表变慢不是玄学,先用慢查询日志找出具体的访问模式,再决定是加索引、分区还是做汇总。手段不一样,代价差别很大,所以必须先定位再动手。

设计流程

问题 2:查询性能

  1. 步骤 1:用慢查询日志和 EXPLAIN 定位耗时最长的调用日志查询
  2. 步骤 2:在 (api_key, created_at) 这类过滤列上建复合索引,并按月对日志表分区
  3. 步骤 3:对高频统计口径改用汇总表预聚合,历史分区单独归档以减少扫描量

关注点:日志表上真正拖慢查询的是哪一类访问模式。

随着数据量增长,这个查询会越来越慢。

如何优化?

问题 3:数据备份

如果数据库挂了,所有用户数据都会丢失。

如何备份数据?

一个问题解决了,新的问题又来了。这就是做系统的常态吧。

当前架构

技术架构
客户端

用户请求

GET https://kuaiyizhi.cn/api/weather?city=北京&key=sk_***
应用服务

Nginx

Python

Public API + API Key

Admin API

Static

Admin Dashboard


MySQL

外部服务

MySQL 用户与密钥

外部天气 API

发现内容有问题?

告诉我们哪里需要改进。