用户认证
我决定实现用户认证系统,让每个用户有独立的调用配额。
核心需求:
- 用户可以注册账号
- 系统分配唯一的 API Key
- 每次调用必须验证 API Key
- 限制每个用户的调用配额
这是一个完整的认证体系,我需要从零开始设计。
API Key(访问密钥)的设计
API Key 是什么?
- 一个唯一的字符串
- 也可以理解为用户调用 API 时携带的访问密钥
- 用来标识用户身份和调用权限
- 需要在每次调用时携带
API Key 的格式:
ak_live_xxxxxxxxxxxxxxx (正式环境)
ak_test_xxxxxxxxxxxxxxx (测试环境)
格式说明:
ak_:前缀,表示 API Keylive/test:环境标识- 后面:随机字符串
我特意加了环境标识,这样开发和生产环境可以分开管理。
| 字段名 | 类型 | 约束 / 说明 |
|---|---|---|
id | BIGINT | PRIMARY KEY, AUTO_INCREMENT |
endpoint | VARCHAR(255) | NOT NULL |
params | TEXT | 请求参数 |
response_status | INT | HTTP 状态码 |
response_time | INT | 响应时间(ms) |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
| id | endpoint | params | response_status | response_time | created_at |
|---|---|---|---|---|---|
1 | /api/weather | city=北京 | 200 | 118 | 2026-03-31 14:00:00 |
2 | /api/weather | city=上海 | 200 | 132 | 2026-03-31 14:01:00 |
3 | /api/weather | city=广州 | 500 | 240 | 2026-03-31 14:02:00 |
| 字段名 | 类型 | 约束 / 说明 |
|---|---|---|
id | INT | PRIMARY KEY, AUTO_INCREMENT |
email | VARCHAR(255) | UNIQUE, NOT NULL |
password_hash | VARCHAR(255) | NOT NULL |
api_key | VARCHAR(64) | UNIQUE, NOT NULL |
plan | VARCHAR(50) | DEFAULT 'free' |
daily_limit | INT | DEFAULT 1000 |
created_at | TIMESTAMP | DEFAULT CURRENT_TIMESTAMP |
| id | plan | daily_limit | created_at | |
|---|---|---|---|---|
1 | alice@demo.com | free | 1000 | 2026-04-08 10:32:11 |
2 | bob@demo.com | pro | 100000 | 2026-04-11 09:15:02 |
3 | ops@demo.com | basic | 10000 | 2026-04-13 21:44:36 |
生成安全的 API Key
API Key 是用户在这套系统里的身份证,生成环节决定了它能不能被猜到、被复用。我要求随机源不可预测,并且数据库里永远不出现明文——这条约束一旦放松,后面所有的配额和审计都会失去意义。
生成安全的 API Key
- 步骤 1:用 secrets 模块生成足够长的随机串,拼上 ak_ 前缀与环境标识
- 步骤 2:数据库只保存密钥的哈希值,明文仅在注册响应里返回一次
- 步骤 3:校验密钥时按相同算法哈希后比对,避免数据库泄露即失守
- 步骤 4:把密钥摘要、创建时间与归属用户写入密钥表,便于吊销与审计
关注点:密钥的不可预测性,以及明文只出现一次这件事怎么落地。
为什么使用 secrets 模块?
- 加密安全的随机数生成
- 不可预测
- 防止碰撞
我当时想,API Key 是用户的身份标识,必须在源头上保证安全。
注册接口
注册是这套认证体系的入口:用户表、密钥表、配额表要在同一次请求里建好,任何一张没写成功都不该留下半成品账号。密钥明文也必须在这一步一次性交出去。
注册接口
- 步骤 1:校验邮箱格式、密码强度,并确认该邮箱尚未注册
- 步骤 2:在同一事务里写入用户记录、密钥哈希与初始配额
- 步骤 3:生成明文 API Key,在响应体里返回一次并提示用户保存,同时写入注册审计日志
关注点:一次注册要同时落下哪几张表,以及密钥明文的返回时机。
登录接口
登录和注册长得像,目的却不同:注册负责把账号建出来,登录负责证明「你是你」。这里最关键的是失败提示不能泄露账号是否存在,否则接口本身就变成枚举工具。
登录接口
- 步骤 1:按邮箱查出用户记录,取出存储的密码哈希
- 步骤 2:用 bcrypt 比对输入的口令,失败时统一返回「邮箱或密码错误」
- 步骤 3:登录成功后签发新的 API Key 或会话令牌,并记录登录时间、来源 IP 与结果
关注点:口令校验的正确性,以及登录行为如何进入审计。
我特意让 API Key 只在注册时返回一次,之后就再也看不到了。这样设计是为了安全,但也带来了一些麻烦——用户如果弄丢了 API Key,就只能重置。
修改天气 API 接口
原来天气接口自己判断要不要校验密钥,现在改成统一入口先校验、再进业务。这是关注点分离带来的好处:以后加新的 API,认证逻辑一行都不用重写。
修改天气 API 接口
- 步骤 1:在天气接口之前插入统一的认证中间件,业务代码不再自己校验密钥
- 步骤 2:中间件取出请求头里的 API Key,比对哈希确认密钥有效且未停用
- 步骤 3:校验通过后把用户身份、权限范围和剩余配额写入请求上下文
- 步骤 4:校验不通过时,按缺失、无效、超额分别返回 401、403、429
关注点:认证逻辑从业务处理里剥离之后,调用链是否依然清晰可读。
通过统一认证入口,我可以把认证逻辑从业务流程中分离出来。这是我从之前做系统设计的经验中学到的——关注点分离。
正确的调用方式
同一套认证体系,调用姿势不同,安全结果差得很远。正确的做法只有一条原则:密钥全程走请求头、走 HTTPS、只留在服务端。
正确的调用方式
- 步骤 1:用 HTTPS 传输,在请求头里带上 Authorization: Bearer ak_live_xxxx
- 步骤 2:密钥只保存在服务端或环境变量里,不写进前端代码和仓库
- 步骤 3:收到 401 时先确认密钥是否被重置,再决定是否需要重新获取
- 步骤 4:按业务节奏轮换密钥,轮换后同步更新调用方配置
关注点:密钥在传输链路上的暴露面有多大。
错误的调用方式
把正确的做法和错误的放在一起看,差别才明显。下面这些是真实项目里最常见的泄露姿势,每一条都会让密钥离开它该待的地方,事后只能靠重置来止损。
错误的调用方式
- 步骤 1:典型错误是把密钥硬编码在前端代码里,任何人打开控制台都能拿到
- 步骤 2:另一种错误是把密钥拼进 URL 查询参数,它会出现在网关日志和访问记录中
- 步骤 3:还有把密钥提交进 Git 仓库的,删除文件也留有历史记录
- 步骤 4:这些做法都会让密钥扩散到日志、截图和第三方手里,必须逐条排查
关注点:常见的密钥泄露途径,以及泄露后能不能被发现。
API Key 的安全问题
问题 1:API Key 泄露
- 如果 API Key 泄露,他人可以冒用
- 配额被消耗
- 产生费用
解决方案:
- 提醒用户妥善保管 API Key
- 提供重置 API Key 的功能
- 设置 IP 白名单(可选)
- 监控异常调用
密码存储
密码不能明文存,这是最基本的底线。这一版先做了带盐哈希,把「明文落库」这个风险堵住,但我心里清楚快速哈希在离线撞库面前几乎不设防。
密码存储
- 步骤 1:明确密码只存哈希值,日志和数据库备份里都不能出现明文
- 步骤 2:用 sha256 加随机盐做一次快速哈希,校验时按同样的盐重新计算并比对
- 步骤 3:承认快速哈希扛不住离线撞库,为下一步换成慢哈希做准备
关注点:哈希方案是否足以抵御撞库与彩虹表。
更好的方案是使用 bcrypt:
bcrypt 的价值在于它故意算得慢,成本因子可以随硬件变强而调高。为了不让老用户全部重置密码,我在登录成功的那一刻顺手完成哈希算法的迁移。
密码存储
- 步骤 1:改用 bcrypt 存储密码,把 cost 设为 12,并在库中记录算法与 cost
- 步骤 2:登录时先用 bcrypt 校验,通过后再用同一套参数重新哈希,顺手升级旧哈希
- 步骤 3:校验失败时也执行一次假哈希,抹平「账号是否存在」的耗时差异
关注点:工作因子取值,以及老用户密码如何平滑迁移。
我当时想,安全这件事,再怎么重视也不为过。
真实上线还要注意
- 不要只验证“这个 Key 对不对”。 还要记录它是谁、什么时候、从哪里调用了什么接口。
- Key 泄露要能止损。 用户应该能重置密钥,系统也应该能临时停用异常密钥。
- 认证、限流、计费要串起来。 否则用户明明被限流了,账单和日志却说不清原因。
上线后,我观察了一周的数据:
滥用情况
| 指标 | 之前 | 现在 |
|---|---|---|
| 异常 IP 调用 | 每天 10+ 个 | 0 个 ✅ |
| 外部 API 滥用 | 频繁 | 0 次 ✅ |
| 正常用户体验 | 差 | 优秀 ✅ |
用户增长
| 指标 | 数值 |
|---|---|
| 注册用户 | 200 个 |
| 日活用户 | 80 个 |
| 平均每用户调用 | 100 次/天 |
看到这些数据,我知道这条路走对了。
虽然解决了滥用问题,但带来了一些新挑战:
问题 1:数据存储
用户数据和调用日志越来越多:
- 用户表:200 条
- 日志表:每天 5 万条
- 增长速度:每月 150 万条
应该用什么数据库?
问题 2:查询性能
日志表查询越来越慢:
日志表变慢不是玄学,先用慢查询日志找出具体的访问模式,再决定是加索引、分区还是做汇总。手段不一样,代价差别很大,所以必须先定位再动手。
问题 2:查询性能
- 步骤 1:用慢查询日志和 EXPLAIN 定位耗时最长的调用日志查询
- 步骤 2:在 (api_key, created_at) 这类过滤列上建复合索引,并按月对日志表分区
- 步骤 3:对高频统计口径改用汇总表预聚合,历史分区单独归档以减少扫描量
关注点:日志表上真正拖慢查询的是哪一类访问模式。
随着数据量增长,这个查询会越来越慢。
如何优化?
问题 3:数据备份
如果数据库挂了,所有用户数据都会丢失。
如何备份数据?
一个问题解决了,新的问题又来了。这就是做系统的常态吧。
用户请求
GET https://kuaiyizhi.cn/api/weather?city=北京&key=sk_***Nginx
Public API + API Key
Admin API
Admin Dashboard
MySQL
MySQL 用户与密钥
外部天气 API
发现内容有问题?
告诉我们哪里需要改进。
