跳到主要内容

3 篇博文 含有标签「Redis」

查看所有标签

Django + FastAPI 秒杀系统课程

· 阅读需 1 分钟

由旧稿整理而来,内容未改,仅做结构与排版优化。旧稿目录已清理,当前以本文为准。

本笔记是网课资料汇总:课程观看入口 + 配套课件(语雀文档)+ 课程代码(百度网盘)。


1. 课程观看​

项链接
网易云课堂https://study.163.com/course/courseMain.htm?courseId=1213775829&_trace_c_p_k2_=a0edcec470e944d58a10b7445ae6e84e

2. 配套课件(语雀)​

全部为知了传课 / 知了课堂的语雀文档,对应模块密码见表格。

#模块课件链接文档标题访问密码
1异步 Djangohttps://www.yuque.com/hynever/async-django异步 Django 课件ra32
2微服务https://www.yuque.com/hynever/micro-service知了传课 - 微服务ancc
3FastAPIhttps://www.yuque.com/hynever/wms8gi知了传课 - FastAPIpuvz
4uniapphttps://www.yuque.com/hynever/uniapp知了课堂 - uniapp 课件kri4
5电商秒杀项目实战https://www.yuque.com/hynever/shtqfp知了课堂 - 电商系统实战zy6l

3. 课程代码(百度网盘)​

项内容
链接https://pan.baidu.com/s/19Pg3LWTjoqYhjRl1kWcjpw?pwd=gxem
提取码gxem

标签:#django #fastapi #redis #celery

数据库设计相关笔记

· 阅读需 12 分钟

工业化生产环境下的数据库设计规范 + 慢 SQL 排查与索引优化流程(FastAPI + SQLAlchemy + Alembic),覆盖关系型数据库(MySQL / PostgreSQL / SQLite)+ Redis + MongoDB。 本笔记旧稿 仅含 2 个外链 + 4 行小结,已完整重构;旧稿目录已清理,当前以本文为准。 演示代码示例在 example/db-design/(慢查询埋点 + Alembic 加索引完整脚本 + Redis key 模板)。

目录​

  1. 生产环境数据库设计原则(核心原则)
  2. 关系型数据库表设计要点
  3. Redis 键设计规范
  4. MongoDB Schema 设计
  5. 慢 SQL 排查与索引优化
  6. 加索引:走代码层 Alembic Migration,不走裸 SQL

1. 生产环境数据库设计原则​

1.1 一句话原则​

ER 图保留表与表的关联(沟通用);DB 层不加外键约束(性能 / 扩展性);业务约束在代码层做。

1.2 DB 层保留 / 不保留的约束​

约束类型DB 层代码层原因
主键(PK)✅ 必须—物理寻址唯一标识
非空(NOT NULL)✅ 尽量—减少三值逻辑复杂度
唯一约束(UNIQUE)✅ 保留部分—DB 层是 race-condition 天然防线(防止并发重复)
外键(FK)❌ 不加✅ Service / ORM见 1.3
CHECK 约束❌ 不加✅ 代码层不同 DB 实现差异大
复杂业务约束(如余额 ≥ 0)❌ 不加✅ Service 层事务单条 SQL 内做约束容易死锁

1.3 不在 DB 层加外键的理由(业界共识)​

  1. DDL 锁表:外键级联检查会延长 INSERT/UPDATE 持锁时间,影响并发
  2. 分库分表后失效:跨库 / 分表场景下 FK 无法落地
  3. 微服务拆分后失效:跨服务调用根本无法做 DB 层 FK
  4. 性能损耗:每次写多一次约束校验(InnoDB 即时有 foreign_key_checks 开关)
  5. 循环依赖:ORM 双向关系 + DB FK 容易形成导入循环

1.4 ER 图怎么画​

  • 仍然在设计文档 / dbdiagram.io / draw.io 画出表与表关联
  • 用虚线箭头标注「逻辑外键」,明确写「DB 层不加约束」
  • 在 Service 层 / Repository 层做「插入前查存在性 + 事务兜底」
  • 必要时用兜底清理 job(孤儿数据检测 / 软删除关联)

2. 关系型数据库表设计要点​

2.1 主键策略​

方案适用注意
自增 BIGINT单库 OLTP 主流分库分表要换方案
雪花 ID / Sonyflake分布式、跨库13~53 bit 信息 + 趋势递增
UUID v7分布式 + 时序PG / MySQL 8 默认不支持,需应用生成
UUID v4几乎不推荐索引页分裂、存储膨胀

2.2 必备字段(按需)​

CREATE TABLE orders (
id BIGINT PRIMARY KEY,
-- 业务字段 ...
created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
deleted_at TIMESTAMP NULL DEFAULT NULL -- 软删除按场景
);
  • created_at / updated_at 必加,便于排查与排序
  • deleted_at 看业务是否需要软删除(物理删除有数据恢复 / 审计风险)

2.3 字段类型选择​

业务类型备注
金额DECIMAL(M, D) / NUMERIC永远不要 FLOAT / DOUBLE
状态字段TINYINT / ENUM(PG)比 VARCHAR 索引小
布尔TINYINT(1) / BOOLEANMySQL 中 BOOLEAN = TINYINT(1)
JSONMySQL 5.7+ JSON / PG JSONB(推荐)JSONB 支持索引(PG)
时间TIMESTAMP(到 2038) / DATETIME(MySQL) / TIMESTAMPTZ(PG 推荐)跨时区优先 TIMESTAMPTZ

2.4 NOT NULL 原则​

  • 能 NOT NULL 就 NOT NULL,少用 NULL(NULL 有三值逻辑:=NULL 永远 false,需 IS NULL)
  • 业务上「没有」就用空串 / 0 / 默认值,而不是 NULL

3. Redis 键设计规范​

3.1 命名约定(业界主流)​

  • 分隔符:冒号 :(兼容 RedisInsight、redis-cli 的展示)
  • 模板:业务:模块:业务ID:字段
  • 必备规则:
    • 必须设 TTL(防内存膨胀)
    • 长度可控(不要拿 JSON 整段当 key,存 hash / json 字符串作为 value)
    • 不用空格 / 换行 / 特殊字符
    • 统一小写

3.2 典型场景 key 模板​

场景模板示例
缓存cache:模块:keycache:user:profile:1000
Sessionsess:{sessionId}sess:abc123def456
限流ratelimit:{userId}:windowratelimit:{1000}:1m
分布式锁lock:resource:xxxlock:order:5678
计数器counter:场景:idcounter:views:homepage
Streamstream:events:topicstream:events:order_created
Pub/Subchannel:notifications:{userId}channel:notifications:{1000}

3.3 Cluster Hash Tag {...}(关键)​

Redis Cluster 用整个 key 做 CRC16 分 slot;多 key 操作(MGET / MSET / 事务 / Lua)必须在同一 slot,否则报错 CROSSSLOT。

# ❌ 不带 hash tag:key 落在不同 slot,MGET 报错
> MGET user:1000:profile user:1000:settings
(error) CROSSSLOT Keys in request don't hash to the same slot

# ✅ 用 {userId} 强制同一 slot
> SET user:{1000}:profile "Alice" OK
> SET user:{1000}:settings "dark_mode" OK
> MGET user:{1000}:profile user:{1000}:settings
1) "Alice"
2) "dark_mode"

规则:

  • 只识别第一个 {}:foo{{bar}}zap hash 的是 {bar}zap
  • 空 {} 忽略
  • 禁忌:避免 {global} 这种全局 tag(热点 shard);按业务 ID 散开

3.4 实际应用举例​

# 限流(原子 INCR + EXPIRE)
RATE_KEY = f"ratelimit:{{{user_id}}}:1m" # {1000}:1m
pipe = redis.pipeline()
pipe.incr(RATE_KEY)
pipe.expire(RATE_KEY, 60)
count, _ = pipe.execute()

# 分布式锁(带随机 token + Lua 释放)
LOCK_KEY = f"lock:order:{order_id}"
TOKEN = uuid4().hex
redis.set(LOCK_KEY, TOKEN, nx=True, ex=10)
# 释放用 Lua 脚本保证「只删自己持有的锁」

完整示例:example/db-design/redis_key_examples.py


4. MongoDB Schema 设计​

4.1 嵌入 vs 引用决策矩阵​

关系嵌入引用
1:1✅极少
1:少(few)✅视查询模式
1:多(many)❌✅
多:多❌✅(用 array of refs)

嵌入的条件:读写一起、数据有界、文档大小可控(< 16 MB)。

4.2 MongoDB 官方 6 大模式速查​

模式用途典型场景
Subset主文档只存最常用字段子集商品列表只存 name / price,详细页再查
Extended Reference引用对象 + 复制少量常用字段订单复制 user 的 name / phone 避免 join
Bucket时序分桶(按时间窗口)IoT 设备 1 分钟 1 个 bucket
Outlier异常大对象单独存99% 帖子 < 10 KB,1% 是 5 MB 长文
Computed预计算冗余字段评论数 +1 写入(避免每次 count)
Tree树形结构评论 / 分类树用 Materialized Path

4.3 反模式(绝对不要做)​

  • ❌ 无界数组:数组持续增长 → document 持续迁移 → 性能崩塌(最常见坑)
  • ❌ 巨量 collection:一个用户 / 租户一个 collection(应该加 tenantId 字段 + 索引分区)
  • ❌ 缺索引:每个查询字段(外键、过滤、排序)必须有索引
  • ❌ 把 MongoDB 当关系库用:坚持 join / 事务,丢失文档库优势

4.4 索引建议​

// 单字段
db.users.createIndex({ email: 1 }, { unique: true })

// 复合索引(注意 ESR 原则:Equality → Sort → Range)
db.orders.createIndex({ user_id: 1, status: 1, created_at: -1 })

// 部分索引(只索引部分文档)
db.orders.createIndex({ created_at: -1 }, { partialFilterExpression: { status: "active" } })

// TTL 索引(自动过期)
db.sessions.createIndex({ created_at: 1 }, { expireAfterSeconds: 3600 })

5. 慢 SQL 排查与索引优化​

5.1 数据库层:MySQL 慢日志​

# my.cnf
slow_query_log = 1
slow_query_log_file = /var/log/mysql/slow.log
long_query_time = 2 # 秒,默认 10 太松
log_queries_not_using_indexes = 1 # 没走索引也记
min_examined_row_limit = 100 # 扫描行太少不算
log_output = FILE # 或 TABLE(写 mysql.slow_log)

运行时开启:

SET GLOBAL slow_query_log = 1;
SET GLOBAL long_query_time = 2;
SET GLOBAL log_queries_not_using_indexes = 1;

分析工具:

# 内置(最常用入门)
mysqldumpslow -s c -t 20 /var/log/mysql/slow.log # 调用次数 Top 20
mysqldumpslow -s at -t 10 /var/log/mysql/slow.log # 平均耗时 Top 10

# Percona Toolkit(更强,推荐生产用)
pt-query-digest /var/log/mysql/slow.log > digest.txt

5.2 数据库层:PostgreSQL pg_stat_statements​

优势:无需开启慢日志,聚合等价 SQL(字面量归一为 $1),直接 SELECT 排序。

启用:

# postgresql.conf + 重启
shared_preload_libraries = 'pg_stat_statements'
pg_stat_statements.max = 10000
pg_stat_statements.track = top
CREATE EXTENSION pg_stat_statements;

-- Top 5 慢查询
SELECT round((100 * total_exec_time / SUM(total_exec_time) OVER ())::numeric, 2) AS percent,
calls,
round(mean_exec_time::numeric, 2) AS mean_ms,
query
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 5;

5.3 应用层:SQLAlchemy 慢查询埋点(FastAPI 推荐)​

数据库层慢日志是「事后」工具;应用层埋点能拿到业务上下文(哪个 endpoint、哪个 user、哪个 trace_id)。

完整示例:example/db-design/slow_query_logger.py

核心思路(SQLAlchemy Core / ORM 共用 Engine event):

from sqlalchemy import create_engine, event
import time, logging

engine = create_engine("postgresql+psycopg2://...")

@event.listens_for(engine, "before_cursor_execute")
def _before(conn, cursor, statement, parameters, context, executemany):
context._query_start_time = time.perf_counter()

@event.listens_for(engine, "after_cursor_execute")
def _after(conn, cursor, statement, parameters, context, executemany):
elapsed_ms = (time.perf_counter() - context._query_start_time) * 1000
if elapsed_ms >= 200: # 阈值,业界常用 200ms 报警 / 1s P0
logging.warning("slow query (%.1f ms): %s", elapsed_ms, statement)

ORM 层补充(SQLAlchemy 2.0):

from sqlalchemy.orm import Session

@event.listens_for(Session, "do_orm_execute")
def _slow_orm(state):
start = time.perf_counter()
state.invoke_statement()
elapsed = (time.perf_counter() - start) * 1000
if elapsed >= 200:
logging.warning("slow ORM (%.1f ms): %s", elapsed, state.statement)

注意:do_orm_execute 不包含 flush 阶段的 SQL;flush 用 before_cursor_execute 兜底。

5.4 阈值参考(业界常用)​

阈值等级
> 100 ms一般查询警告
> 200 ms慢查询埋点
> 500 ms性能问题
> 1 sP0 工单
> 3 s几乎一定有索引问题

阈值根据业务调整(OLTP 200ms,OLAP 数秒级合理)。

5.5 EXPLAIN 分析(MySQL / PostgreSQL 通用)​

拿到慢 SQL 后第一步是 EXPLAIN:

EXPLAIN SELECT * FROM orders WHERE user_id = 1000 AND created_at > '2026-01-01' ORDER BY id;

关键看:

字段含义危险信号
type访问类型ALL = 全表扫描 = 缺索引
key实际使用的索引NULL = 没走索引
rows预估扫描行数远大于实际返回 = 索引选错
Extra附加信息Using filesort / Using temporary / Using where 无 Using index

5.6 索引决策流程​

发现慢 SQL
↓
EXPLAIN 看执行计划
↓
判断:
├── type=ALL 且 rows 巨大 → 缺索引,加索引
├── type=range 但 Extra 有 filesort → 复合索引顺序错(排序字段加索引列末位)
├── type=index 但慢 → 索引列选择性差(基数太低),考虑删除或换列
├── 已用索引但仍慢 → 看是否回表过多(覆盖索引 / 索引下推 ICP)
└── 大数据量 → 考虑分库分表 / 读写分离

6. 加索引:走代码层 Alembic Migration,不走裸 SQL​

6.1 为什么必须走 Alembic(业界共识)​

方式DDL 进版本控制团队协作升级 / 回滚对称生产事故
Alembic migration✅✅✅可回滚
裸 SQL / Navicat 直接改库❌❌ 别人不知道❌上线后才发现,灾难

反例:开发 A 用裸 SQL 在生产加了索引,开发 B 跑 alembic upgrade 时会因索引已存在而失败(或反之,索引漏加导致线上慢 SQL)。

6.2 Alembic 索引操作速查​

# alembic/versions/xxxx_add_orders_user_created_idx.py
from alembic import op
from sqlalchemy import text

def upgrade():
# 单列索引
op.create_index(
"ix_orders_user_id", "orders", ["user_id"],
)
# 复合索引(顺序:等值字段 → 排序字段 → 范围字段)
op.create_index(
"ix_orders_user_created", "orders", ["user_id", "created_at"],
)
# 唯一索引
op.create_index(
"ix_users_phone", "users", ["phone"], unique=True,
)
# 函数索引
op.create_index(
"ix_users_email_lower", "users", [text("lower(email)")],
)
# 条件索引(PG)
# op.execute("CREATE INDEX ix_orders_active ON orders (created_at) WHERE status = 'active';")

def downgrade():
# 必须对称,否则回滚失败
op.drop_index("ix_orders_user_id", table_name="orders")
op.drop_index("ix_orders_user_created", table_name="orders")
op.drop_index("ix_users_phone", table_name="users")
op.drop_index("ix_users_email_lower", table_name="users")

SQLite 注意点:SQLite 对 ALTER TABLE 支持有限,DDL 用 batch_alter_table:

with op.batch_alter_table("users") as batch_op:
batch_op.create_index("ix_users_email", ["email"])

6.3 完整脚本示例(从慢 SQL 到加索引)​

完整可读脚本:example/db-design/alembic_add_index.py

展示真实场景:

场景:运营报障「我的订单列表加载慢」,抓到的慢 SQL:

SELECT * FROM orders WHERE user_id = 12345 ORDER BY created_at DESC LIMIT 20;

EXPLAIN 发现 type=ALL,扫 50 万行。决定加复合索引 (user_id, created_at)。

完整 alembic revision 文件见 demo。

6.4 大表在线加索引(生产必备)​

直接 CREATE INDEX 在大表上会长时间锁表(MySQL 5.6 之前 = 全程锁,PG = CONCURRENTLY 选项)。生产常用:

数据库工具 / 选项原理
MySQLpt-online-schema-change(Percona)建影子表 + 触发器 + 增量拷贝
MySQLgh-ost(GitHub)binlog + 影子表,无触发器
MySQLALTER TABLE ... ALGORITHM=INPLACE, LOCK=NONE(5.6+)部分索引支持在线
PostgreSQLCREATE INDEX CONCURRENTLY不锁表,但 alembic 内要特殊处理

Alembic + PG CONCURRENTLY 注意事项:

# Alembic 默认每个 migration 一个事务,CONCURRENTLY 不能在事务里
# alembic.ini:
# transaction_per_ddl = False
# 或者用 op.execute("COMMIT") 切事务
op.execute("COMMIT")
op.execute("CREATE INDEX CONCURRENTLY ix_orders_user_created ON orders (user_id, created_at)")

6.5 索引禁忌(不要做的事)​

反模式后果替代方案
给低基数列加索引(gender、is_deleted boolean)索引选择性差,几乎没用用复合索引带上
单表索引 > 5~6 个写放大(每次 INSERT/UPDATE 维护所有索引)看慢 SQL 按需加,定期清理未用索引
索引列做函数 / 类型转换索引失效用函数索引 / 改 SQL
不看 EXPLAIN 盲目加可能加错索引 / 加重复索引先 EXPLAIN,再决定
每次 release 都加索引索引膨胀加索引前先看是否有现成的能用

6.6 加索引 checklist​

[ ] 慢 SQL 已用 pt-query-digest / pg_stat_statements 确认是热点
[ ] EXPLAIN 已看,确认 type=ALL / rows 巨大 / 没走索引
[ ] 复合索引顺序已按 ESR 原则(等值 → 排序 → 范围)
[ ] 唯一索引确认 DB 现有数据无重复
[ ] 大表确认是否走在线 DDL(pt-osc / gh-ost / CONCURRENTLY)
[ ] migration 脚本已写完整的 downgrade
[ ] 已在测试环境跑过 upgrade + downgrade
[ ] 已在 staging 观察索引生效、慢 SQL 消失
[ ] 已通知 DBA / 团队 review migration

关联笔记​

标签:#mysql #postgres #redis

鉴权与登录笔记

· 阅读需 13 分钟

原 旧稿(JWT 概念)+ 旧稿(OAuth2 + GitHub 第三方登录)的合并重写。 原笔记是概念罗列,本笔记在此基础上补全 4 种主流登录方式的完整流程、JWT 生产级实践(双 Token / 撤销 / 攻击防御)、扫码登录的时序设计。

权限模型(RBAC / ReBAC / Casbin)见 [[权限模型与Casbin实践笔记]]。 API 网关与鉴权中间件见 [[API网关原理与选型笔记]]。

目录​

  1. 登录方式全景对比
  2. 账号密码 + JWT(最常用)
  3. OAuth2 第三方登录(含 GitHub 完整流程)
  4. 扫码登录(PC + 移动 App)
  5. 手机号验证码登录
  6. Token 存储位置安全对比
  7. JWT 安全攻击与防御(RFC 8725)
  8. Token 撤销 / 黑名单
  9. JWT 完整代码示例 + 选型

1. 登录方式全景对比​

方式用户体验安全性适用场景关键技术
账号密码 + JWT中(要注册)中(密码泄漏风险)通用 Web / Appbcrypt + JWT 双 Token
手机号验证码好(无需密码)中(短信劫持)国内移动端短信网关 + 验证码缓存
OAuth2 第三方登录最好(点一下)高(委托给第三方)通用 Web / App授权码模式
扫码登录好(无需输入)高(依赖 App 端鉴权)PC 端 + 已装 App二维码 + 轮询 / WebSocket
SSO 单点登录好(一次登录多处用)高(统一 IdP)企业内部 / 跨产品SAML / OIDC / CAS
密钥 / Passkey最好(指纹 / 面部)最高高安全场景WebAuthn / FIDO2

选型原则:

  • 通用 Web → 账号密码 + JWT,第三方登录作为补充(降低注册门槛)
  • 国内移动 App → 手机号验证码是主流
  • PC + 移动 App 联动 → 扫码登录
  • 企业内多产品 → SSO
  • 高安全 / 支付 → Passkey 补充

2. 账号密码 + JWT(最常用)​

2.1 完整流程时序图​

用户 前端 网关 用户服务 Redis
│ 输入密码 │ │ │ │
│ ──────────────► │ │ │ │
│ │ POST /login │ │ │
│ │ ────────────────► │ 转发 │ │
│ │ │ ────────────────►│ │
│ │ │ │ 查 user + bcrypt │
│ │ │ │ 校验密码 │
│ │ │ │ 生成 access+refresh│
│ │ │ │ save refresh ───►│
│ │ │ ◄────────────────│ │
│ │ ◄────────────────│ 返回 tokens │ │
│ 存 token │ │ │ │
│ ──────────────► │ │ │ │
│ │ │ │ │
│ 访问受保护资源 │ │ │ │
│ ──────────────► │ GET /api/orders │ │ │
│ │ Authorization: │ │ │
│ │ Bearer eyJhbG... │ │ │
│ │ ────────────────► │ 校验 JWT 签名 │ │
│ │ │ 转发 + X-User-Id │ │
│ │ │ ────────────────►│ │
│ │ │ ◄────────────────│ │
│ │ ◄────────────────│ 返回数据 │ │

2.2 JWT 三段结构​

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9. ← Header (Base64Url)
eyJzdWIiOiIxMjM0NSIsIm5hbWUiOiJBbGljZSIsImlhdCI6MTUxMjIzOTAyMn0. ← Payload
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c ← Signature

Header:

{ "alg": "HS256", "typ": "JWT" }

Payload(claims):

claim含义必填?
subsubject(用户 ID)✅
iatissued at(签发时间)推荐
expexpiration time(过期时间)✅
ississuer(签发方)推荐
audaudience(接收方)推荐
jtiJWT ID(唯一标识,用于黑名单)推荐
nbfnot before(生效时间)可选
自定义user_id / roles / tenant_id视业务

⚠️ JWT payload 是明文 Base64Url 编码,不是加密!禁止放密码等敏感信息。需要加密用 JWE(RFC 7516)。

Signature:

HMACSHA256(
base64UrlEncode(header) + "." + base64UrlEncode(payload),
secret
)

服务端用相同算法 + secret 重算,对比签名 → 验签通过 = 数据未被篡改。

2.3 生产实践:双 Token 模式​

单 Token 模式有死结:短过期 → 用户频繁登录;长过期 → token 泄露后无法撤销。

Access Token + Refresh Token 双 Token:

Access TokenRefresh Token
过期时间15 分钟 ~ 2 小时7 ~ 30 天
用途访问受保护 API换新的 Access Token
存储内存 / httpOnly cookiehttpOnly cookie / 加密存储
泄露后影响时间窗有限(短过期)可撤销(jti 黑名单)

Refresh Token 轮换(rotation):

客户端 → /token/refresh (refresh_token)
← { access_token: new1, refresh_token: new2 } ← 同时返回新的 refresh
← 旧 refresh_token 立即失效

每次刷新都换新的 refresh,旧 refresh 入黑名单 → 即使被窃也只能用一次。

2.4 密码安全​

必须用 bcrypt / argon2 哈希,不能用 MD5/SHA1:

import bcrypt

# 注册
password_bytes = password.encode()
salt = bcrypt.gensalt(rounds=12) # cost factor 12~14
hashed = bcrypt.hashpw(password_bytes, salt)
db.save(user.password_hash=hashed)

# 登录
if bcrypt.checkpw(input_password.encode(), stored_hash):
# 正确

bcrypt 哈希里包含 salt,无需单独存。cost factor 12 大约 250ms,够慢且安全。


3. OAuth2 第三方登录​

3.1 OAuth2 四种授权模式​

模式令牌存放位置适用推荐度
授权码 (authorization_code)后端有后端的 Web 应用(首选)⭐⭐⭐⭐⭐
隐藏式 (implicit)前端 URL fragment纯前端 SPA(已不推荐,OAuth2.1 已废弃)⭐
密码式 (password)—高度信任的自家应用(同公司产品)⭐⭐
客户端凭证 (client_credentials)—服务对服务(无用户参与)⭐⭐⭐⭐

现代实践:Authorization Code + PKCE(防止拦截攻击,前端 SPA 也能用)。

3.2 GitHub OAuth 第三方登录完整流程(5 步)​

基于由旧稿内容补全与校正。

前置:注册应用

到 GitHub → Settings → Developer settings → OAuth Apps → New OAuth App:

字段填什么
Homepage URLhttps://yourapp.com
Authorization Callback URLhttps://yourapp.com/oauth/callback

提交后获得 client_id(公开)和 client_secret(必须保密,只放服务端)。


第 1 步:用户点击"GitHub 登录"

前端跳转:

https://github.com/login/oauth/authorize
?client_id=Iv1.abc123
&redirect_uri=https://yourapp.com/oauth/callback
&scope=read:user user:email
&state=random_csrf_token ← 防 CSRF,必带

第 2 步:用户在 GitHub 上同意授权

GitHub 显示应用名 + 申请的 scope,用户点 Authorize。

第 3 步:GitHub 回调到 redirect_uri

https://yourapp.com/oauth/callback
?code=859310e7cecc9196f4af ← 一次性授权码(10 分钟过期)
&state=random_csrf_token ← 必须校验等于第 1 步的 state

第 4 步:服务端用 code 换 token

POST https://github.com/login/oauth/access_token
Headers:
Accept: application/json
Body:
client_id=Iv1.abc123
&client_secret=<your_secret>
&code=859310e7cecc9196f4af
&redirect_uri=https://yourapp.com/oauth/callback

Response:
{
"access_token": "gho_xxxxxxxxxxxxxxxxxxxx",
"scope": "read:user,user:email",
"token_type": "bearer"
}

第 5 步:服务端用 access_token 拉用户信息

GET https://api.github.com/user
Headers:
Authorization: Bearer gho_xxxxxxxxxxxxxxxxxxxx

Response:
{ "id": 12345, "login": "alice", "name": "Alice", "email": "..." }

服务端据此自动注册 / 登录本地账户,签发自己的 access + refresh token 给前端。

3.3 OAuth2 关键安全点​

风险防御
client_secret 泄露只在服务端用,前端绝不能出现
redirect_uri 被劫持必须预注册且严格匹配(GitHub 不允许 query string 差异)
CSRF 攻击用 state 参数(随机字符串,登录后校验一致)
授权码被重用授权码 10 分钟过期 + 一次性
scope 越权只申请必要的 scope(如 read:user 而非全部)

3.4 OAuth2 / OIDC / JWT 关系​

OAuth 2.0 = 授权框架("你能做什么") → RFC 6749
OIDC = OAuth 2.0 之上的身份层("你是谁") → OpenID Connect Core 1.0
JWT = Token 格式(OAuth2 不限定 Token 格式,OIDC 用 JWT 标准化 ID Token)

第三方登录走的是 OAuth2 流程;最终给用户签发的 token 通常是 JWT。


4. 扫码登录(PC + 移动 App)​

4.1 核心思想​

PC 端显示二维码 → 手机 App 扫码 → App 已登录态自动确认 → PC 端登录成功。

不需要 PC 端输入账号密码——App 已经登录,凭 App 端身份为 PC 授权。

4.2 5 步时序图​

PC 浏览器 后端 手机 App Redis / DB
│ │ │ │
│ 1. 生成二维码 │ │ │
│ GET /qr/gen │ │ │
│ ────────────►│ │ │
│ │ 生成 qr_id │ │
│ │ 存 status=等待扫码 │
│ │ ────────────────────────────────► │
│ ◄────────────│ 返回 {qr_id, qr_token (含临时密钥)}│
│ 显示二维码 │ │ │
│ │ │ │
│ │ │ 扫码(解码出 URL │
│ │ │ + qr_token) │
│ │ │ │
│ │ 2. App 上确认登录 │ │
│ │ POST /qr/scan │ │
│ │ + qr_token │ │
│ │ + App 用户身份 │ │
│ │ ◄────────────────│ │
│ │ 校验 qr_token │ │
│ │ 存 status=已确认 │
│ │ + 临时 login_code │
│ │ ────────────────────────────────► │
│ │ │ │
│ 3. PC 轮询状态 │ │ │
│ GET /qr/status/{qr_id} │ │
│ ────────────►│ │ │
│ │ ◄────查 status ──┼──────────────────│
│ ◄────────────│ {status:已确认, │ │
│ │ login_code} │ │
│ 4. 用 login_code 换 token │ │
│ POST /qr/login {login_code} │ │
│ ────────────►│ │ │
│ │ 校验 login_code │ │
│ │ 返回 access+refresh │
│ ◄────────────│ │ │
│ │ │ │

4.3 关键设计点​

步骤关键点
生成二维码qr_id 唯一 + qr_token 含临时密钥(HMAC 签名,防伪造)
二维码内容通常是 URL:https://yourapp.com/qr/scan?qr_id=xxx&sig=xxx
PC 轮询 vs 长连接简单场景用 2s 轮询;体验好场景用 WebSocket 推送(见 [[websocket笔记]])
扫码过期二维码 60~120 秒过期,防恶意截屏
login_code一次性,使用后立即失效
已扫码未确认 vs 已确认两个状态,前端 UI 要区分("已扫码,请在手机上确认")

4.4 防伪关键​

qr_token 必须服务端签发 + App 端校验签名:

qr_token = jwt.encode(
{"qr_id": qr_id, "exp": now + 90},
SECRET,
algorithm="HS256",
)

App 端不信任二维码内容(因为可以伪造截图),但信任服务端签名。


5. 手机号验证码登录​

5.1 流程​

前端 后端 短信网关 Redis
│ POST /sms/send │ │ │
│ {phone: 138...} │ │ │
│ ────────────────►│ │ │
│ │ 检查 60s 间隔 │ │
│ │ 检查单日上限 │ │
│ │ 生成 6 位验证码 │ │
│ │ 存 redis ────────┼─────────────────►│
│ │ 调用短信网关 │ │
│ │ ────────────────►│ │
│ │ │ 发短信 │
│ ◄────────────────│ 返回 ok │ │
│ │ │ │
│ POST /login │ │ │
│ {phone, code} │ │ │
│ ────────────────►│ │ │
│ │ 查 redis 验证码 │ │
│ │ 校验 + 删除 │ │
│ │ 自动注册/登录 │ │
│ ◄────────────────│ 返回 tokens │ │

5.2 防刷要点​

  • 图形验证码:调 /sms/send 前必须通过滑块 / 点选验证
  • 60 秒间隔:同一手机号 60 秒内只能发一次
  • 单日上限:同一手机号每天最多 5~10 条
  • IP 限流:同一 IP 每小时最多 20 条
  • 验证码 5 分钟过期,且只能用一次
  • 错误次数限制:连续 3 次错误验证码 → 该手机号当日锁定

6. Token 存储位置安全对比​

位置XSS 风险CSRF 风险适用推荐度
localStorage❌ 高(JS 可读)✅ 低—❌ 不推荐
sessionStorage❌ 高(JS 可读)✅ 低短期敏感操作⚠️ 一般
httpOnly Cookie✅ 低(JS 读不到)❌ 高(自动携带)Web 主流方案⭐⭐⭐⭐
内存(React state)✅ 低✅ 低高安全 SPA⭐⭐⭐⭐

推荐方案:httpOnly + Secure + SameSite=Lax Cookie 存 Refresh Token,Access Token 存内存。

# 后端 Set-Cookie
response.set_cookie(
key="refresh_token",
value=refresh_token,
httponly=True,
secure=True, # 仅 HTTPS
samesite="lax",
max_age=7 * 24 * 3600,
)

Access Token 放内存(React state / Pinia):刷新页面就丢,重新用 refresh 换。XSS 拿不到,安全性高。


7. JWT 安全攻击与防御(RFC 8725)​

攻击原理防御
alg=none 绕过攻击者改 header alg: none,服务器若没校验就直接放过强制算法白名单 algorithms=["HS256"]
RS256 → HS256 密钥混淆服务端用公钥验签,攻击者把 alg 改成 HS256、用公钥作 HMAC secret强制密钥与算法绑定(pyjwt 自动)
弱对称密钥短 secret 被暴力破解enforce_minimum_key_length=True(HS256 ≥ 256 bit)
嵌套 JWT 漏验内层 JWT 没递归验签库实现需逐层验签
kid 注入kid 字段指向攻击者控制的路径 / SQLkid 白名单 / 不解析为路径
jku / x5u SSRF指向恶意 JWKS endpoint不支持这些 header / 严格白名单
跨 JWT 替代同一 secret 签发不同用途 JWT 互相替代用不同 aud / typ / iss 隔离

pyjwt 防御示例:

jwt.decode(
token,
SECRET,
algorithms=["HS256"], # 强制白名单(关键!)
audience="myapp",
issuer="my-auth-server",
options={"require": ["exp", "sub"]},
)

8. Token 撤销 / 黑名单​

JWT 本身无状态,签发后无法主动失效。生产必须做撤销机制。

8.1 撤销策略(按效果递减)​

策略实现适用
短 Access + Refresh 轮换access 15min,refresh 每次换新所有生产
jti 黑名单(Redis)登出时 SET jwt:blacklist:{jti} 1 EX <剩余exp>主动登出 / 改密
Refresh Token 撤销表DB 存有效 refresh,校验时查高安全场景
全局密钥轮换紧急事件立刻换 secret(所有 token 失效)极端情况

8.2 实现:jti 黑名单​

import jwt
import redis
import uuid

r = redis.Redis()

def issue_access(sub: str) -> str:
return jwt.encode({
"sub": sub,
"jti": str(uuid.uuid4()),
"exp": datetime.now(tz=timezone.utc) + timedelta(minutes=15),
"type": "access",
}, SECRET, algorithm="HS256")

def issue_refresh(sub: str) -> str:
jti = str(uuid.uuid4())
r.setex(f"jwt:active:{jti}", 7 * 24 * 3600, sub) # 存 7 天
return jwt.encode({
"sub": sub, "jti": jti,
"exp": datetime.now(tz=timezone.utc) + timedelta(days=7),
"type": "refresh",
}, SECRET, algorithm="HS256")

def revoke(jti: str):
r.delete(f"jwt:active:{jti}")

def verify_with_blacklist(token: str) -> dict:
payload = jwt.decode(token, SECRET, algorithms=["HS256"])
jti = payload.get("jti")
if jti and not r.exists(f"jwt:active:{jti}"):
raise jwt.InvalidTokenError("revoked")
return payload

9. JWT 完整代码示例 + 选型​

9.1 算法选型​

算法类型密钥适用
HS256HMAC 对称单一密钥单服务 / 内部系统
RS256RSA 非对称私钥签 / 公钥验多服务 / 对外提供 SSO
ES256ECDSA更短移动端 / 高性能
EdDSAEd25519现代高性能新系统

原则:单服务用 HS256,多服务 / 对外交互用 RS256(公钥可对外发布验签)。

9.2 pyjwt 双 Token 完整示例​

import jwt
import uuid
import redis
from datetime import datetime, timezone, timedelta

SECRET = "your-256-bit-secret-from-env" # ≥ 32 字节
ALG = "HS256"
ACCESS_TTL = timedelta(minutes=15)
REFRESH_TTL = timedelta(days=7)
r = redis.Redis()


def _now() -> datetime:
return datetime.now(tz=timezone.utc)


def issue_tokens(sub: str, extra: dict | None = None) -> dict:
"""签发 access + refresh 双 token。"""
base = {"sub": sub, "iat": _now()}
if extra:
base.update(extra)

access_jti = str(uuid.uuid4())
access = jwt.encode(
{**base, "jti": access_jti,
"exp": _now() + ACCESS_TTL, "type": "access"},
SECRET, algorithm=ALG,
)

refresh_jti = str(uuid.uuid4())
refresh = jwt.encode(
{**base, "jti": refresh_jti,
"exp": _now() + REFRESH_TTL, "type": "refresh"},
SECRET, algorithm=ALG,
)
r.setex(f"jwt:active:{refresh_jti}", int(REFRESH_TTL.total_seconds()), sub)

return {"access_token": access, "refresh_token": refresh, "token_type": "bearer"}


def refresh(refresh_token: str) -> dict:
"""用 refresh 换新的双 token(旧 refresh 立即失效)。"""
payload = jwt.decode(refresh_token, SECRET, algorithms=[ALG])
if payload.get("type") != "refresh":
raise jwt.InvalidTokenError("not a refresh token")

jti = payload["jti"]
if not r.exists(f"jwt:active:{jti}"):
raise jwt.InvalidTokenError("refresh token revoked or expired")

# 撤销旧 refresh + 颁发新双 token
r.delete(f"jwt:active:{jti}")
return issue_tokens(payload["sub"], {k: v for k, v in payload.items()
if k not in ("exp", "iat", "jti", "type")})


def verify_access(token: str) -> dict:
"""校验 access token(不做黑名单校验,因为 access TTL 短)。"""
return jwt.decode(
token, SECRET, algorithms=[ALG],
options={"require": ["exp", "sub"]},
)

9.3 与 OAuth2 / OIDC 的边界​

  • 自己的账号系统(账号密码 / 手机号 / 扫码登录)→ 直接发 JWT
  • 第三方登录 → 走 OAuth2 流程(让用户授权),最终仍发自己的 JWT
  • 对外提供登录能力(SSO) → 自己是 OAuth2 Server + OIDC(返回标准 ID Token / UserInfo)

关联笔记​

  • 权限模型(拿到 token 后能做什么):[[权限模型与Casbin实践笔记]]
  • API 网关(鉴权中间件放在哪):[[API网关原理与选型笔记]]
  • WebSocket 扫码登录长连接:[[websocket笔记]]
  • 网络安全(TLS / HTTPS):[[TCP_IP四层网络模型笔记]]

Demo​

完整代码(JWT + 扫码登录 + Casbin 鉴权):

标签:#fastapi #redis