跳到主要内容

运维生产方案总览(小企业级架构师视角)

· 阅读需 7 分钟

来自 I_Kubernetes基础笔记 ~ II_Jenkins_CICD实战笔记 的综合:架构选型、拓扑、部署顺序、容量估算、备份与安全。

适用规模:150 个业务服务 / 节点 1030 台 / 日请求 100w ~ 1000w。


1. 整体拓扑(屋顶图)​

┌───────────────────────────────────────────┐
│ 内网办公网 │
│ │
│ ┌──────────┐ ┌──────────────────┐ │
│ │ Gitea │ │ Harbor 镜像库 │ │
│ │ (Git) │ │ harbor.example │ │
│ └────┬─────┘ └────────┬─────────┘ │
│ │ push/PR │ pull │
│ ▼ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ Jenkins Controller │ │
│ │ (jenkins.example.com, K3s 上跑) │ │
│ └────────────────┬─────────────────────┘ │
│ │ 调度 │
│ ▼ (临时 Agent Pod) │
│ ┌────────────────────────┐ │
│ │ 业务 K3s 集群 │ │
│ │ ┌─────────────────────┐│ │
│ │ │ web / api / frontend ││ │
│ │ │ worker / jobs ││ │
│ │ └─────────────────────┘│ │
│ │ ┌─────────────────────┐│ │
│ │ │ postgresql / redis ││ │
│ │ │ (StatefulSet) ││ │
│ │ └─────────────────────┘│ │
│ └──────────────┬────────────┘ │
│ │ Longhorn │
│ ▼ │
│ ┌──────────────────┐ │
│ │ 块存储节点 │ │
│ └──────────────────┘ │
│ │
│ ┌───────────────────────┐ │
│ │ Rancher 管理控制台 │ │
│ │ rancher.example.com │ │
│ └───────────────────────┘ │
│ │
│ ┌──────────┐ ┌──────────────┐ │
│ │ Prometheus│ │ Grafana │ │
│ │ + Alertmgr│ │ (含仪表盘) │ │
│ └──────────┘ └──────────────┘ │
│ │
│ ┌──────────────────────────────────────┐ │
│ │ Loki + Promtail(日志) │ │
│ └──────────────────────────────────────┘ │
└───────────────────────────────────────────┘
│
▼ 公网(按需)
┌──────────────────────┐
│ 外部 DNS / LB │
│ + cert-manager │
└──────────────────────┘

2. 组件选型小结​

组件选型引用
K8s 发行版K3s(HA,3 server)III_K3s笔记
集群管理Rancher(Helm on K3s)IV_Rancher笔记
镜像仓库Harbor(Helm on K3s)Harbor笔记
CI/CDJenkins(Helm on K3s)+ K8s pluginI_Jenkins基础笔记 / II_Jenkins_CICD实战笔记
存储Longhorn单独文档(可选)
负载均衡servicelb(小)/ MetalLB(生产)单独文档
IngressNginx Ingress Controller单独文档
监控Prometheus + Grafana(kube-prometheus-stack)单独文档
日志Loki + Promtail单独文档
证书cert-manager + Let's Encrypt单独文档
GitOps(可选)ArgoCD单独文档

3. 服务器规划(小企业典型)​

**10 台机器(中型)**为示例。可视规模缩减/扩展。

角色数量机器规格(建议)备注
Rancher 控制台3 (HA)4C8G x3跑 Rancher + 内置数据库或外部 DB
K3s server (HA)34C8G x3业务集群 master
K3s worker38C16G x3跑 Pod
存储节点38C16G + 100G SSD x3Longhorn 卷副本
Harbor2 (主+备份)4C16G + 500G SSD x2跑 Harbor + 数据库
Jenkins2 (主备)4C8G x2跑 Jenkins + 调度 agent pod
Gitea12C4G x1Git 仓库
监控 + 日志24C16G x2Prometheus + Grafana + Loki
合计~19 台-含冗余

3.1 容量估算​

  • 每业务服务 K8s Pod 资源约:0.52C / 14G
  • 50 服务 × 3 副本 = 150 pod
  • 假设平均 1C/2G → 总需求 150C / 300G
  • worker 10 台每台预留 8C/16G → 足够
  • 存储需求:约 1T(DB)+ 500G(应用 logs)→ Longhorn 1.5T 起

3.2 网络规划​

用途CIDR
节点管理网192.168.1.0/24
存储网192.168.2.0/24
Service 网段(K3s 默认)10.43.0.0/16
Pod 网段10.42.0.0/16
MetalLB IP 池192.168.10.0/24

4. 部署顺序​

严格按以下顺序,前一阶段不稳别进下一阶段。

① 安装 K3s 集群(HA,3 server) ← 半天
↓
② 安装 Helm、kubectl、配置镜像加速 ← 1h
↓
③ 安装 Rancher(Helm on K3s) ← 2h
↓
④ 导入已有 K3s(如有) ← 1h
↓
⑤ 安装 cert-manager(Helm) ← 1h
↓
⑥ 安装 Longhorn(Helm) ← 2h + 副本验证
↓
⑦ 安装 MetalLB(可选,Helm) ← 1h
↓
⑧ 安装 Nginx Ingress Controller(Helm) ← 1h
↓
⑨ 安装 Harbor(Helm,持久化用 Longhorn) ← 2h + 推拉验证
↓
⑩ 安装 Gitea / 对接外部 Git ← 1h
↓
⑪ 安装 Jenkins(Helm,K8s plugin) ← 3h
↓
⑫ 安装 kube-prometheus-stack ← 3h
↓
⑬ 安装 Loki + Promtail ← 2h
↓
⑭ 安装 ArgoCD(可选,开启 GitOps) ← 2h
↓
⑮ 业务系统逐个迁移 ← 持续

5. 安全规范(必须)​

5.1 镜像安全​

  • ✅ 业务镜像全部推 Harbor(不直接用 Docker Hub)
  • ✅ Trivy 漏洞扫描:CRITICAL/HIGH 失败则门禁
  • ✅ 关键服务(生产)使用 Cosign 签名
  • ✅ 镜像镜像签名验证(Kyverno 策略)
  • ❌ 禁止 --privileged 容器

5.2 RBAC​

  • ✅ 业务 namespace 加 pod-security.kubernetes.io/enforce: restricted
  • ✅ 默认用户(Dashboard 默认 SA)不能直接用
  • ✅ Rancher 用 LDAP/OIDC 集成
  • ✅ Jenkins 用机器人账号(不用真实用户)

5.3 网络隔离​

  • ✅ 启用 NetworkPolicy(用 Calico/Cilium)
  • ✅ namespace 之间默认隔离;显式白名单
  • ✅ 内部服务不暴露 NodePort;走 Ingress

5.4 凭据管理​

  • ✅ 所有凭据走 Vault / ExternalSecrets
  • ✅ Jenkins 凭据走 JCasC + Credentials plugin
  • ✅ kubeconfig 最小权限:只为对应 namespace

6. 备份与恢复​

对象方法频率备注
K3s etcdk3s etcd-snapshot → S3每 6h自动
Harbor 数据backup.sh → S3每天含镜像 + 元数据 + 配置
Jenkins 数据ThinBackup → S3每天含 job + 凭据(加密)
Giteapg dump + 备份目录每天全量
业务数据库pg_dump / mysqldump每 1h + 全量每天与 Longhorn 快照结合
K8s manifestsGit(GitOps)持续真理之源
Longhorn 卷内置 Snapshot + S3每天防勒索

6.1 演练​

每季度做一次灾备演练:

  • 从零搭一个 K3s 集群
  • 导入最新 etcd snapshot → 集群数据恢复
  • 验证 Harbor / Jenkins / 业务服务的状态

7. 监控告警​

7.1 关键仪表盘(Grafana)​

  • K8s cluster overview
  • Node CPU/内存/磁盘/网络
  • Pod / Namespace 资源使用
  • 关键业务 QPS / 延迟 / 错误率
  • 镜像仓库容量 / 拉取速率
  • Jenkins Job 运行状态

7.2 告警项(Alertmanager)​

指标阈值
节点 CPU > 80%5min 持续 → 报警
节点内存 > 90%5min 持续
节点磁盘 > 85%立即
K8s Pod CrashLoopBackOff立即
K8s Pod OOMKilled立即
节点 NotReady2min 持续
镜像扫描 CRITICAL立即
Jenkins Job 失败立即
Longhorn 卷副本丢失立即
证书 7 天内过期1 天前提前通知

7.3 通知通道​

  • 飞书 / 钉钉(工作群)
  • 邮件(次要)
  • 值班 oncall 机器(PagerDuty / 自建系统)

8. 日志聚合​

8.1 Loki + Promtail 替代 ELK 的理由​

  • 资源占用小(10x)
  • 与 Grafana / Prometheus 集成天然
  • 适合「按 label 筛选」

8.2 落地​

helm repo add grafana https://grafana.github.io/helm-charts
helm install loki grafana/loki-stack \
--namespace logging \
--set promtail.enabled=true \
--set loki.persistence.enabled=true \
--set loki.persistence.storageClassName=longhorn \
--set loki.persistence.size=100Gi

应用内日志标准:

env:
- name: TZ
value: Asia/Shanghai
- name: LOG_LEVEL
value: info

应用写 stdout/stderr(不要写文件),Promtail 自动收集。


9. 持续维护清单​

9.1 每周​

  • 看 Grafana 仪表盘,确认无异常
  • 看 Jenkins Job 失败列表
  • 看 Cert-manager 证书过期列表

9.2 每月​

  • K3s / Rancher / Jenkins / Harbor 升级评估
  • etcd snapshot 演练
  • 镜像仓库清理(release 过期的 tag)
  • 容量评估(CPU / 内存 / 磁盘)

9.3 季度​

  • 全量灾备演练
  • 安全审计(过期凭据 / 未授权 RBAC)
  • 备份归档到冷存储

10. 从零到生产的 8 步实施路径​

step 1: 学习 + 本地 minikube / k3d [1 周]
↓
step 2: 部署 K3s 测试集群(1 server) [1 天]
↓
step 3: 部署 Rancher + 接入 K3s 集群 [2 天]
↓
step 4: 部署 Harbor + 配置镜像推送 [1 天]
↓
step 5: 部署 Jenkins + 第一个 Pipeline [3 天]
↓
step 6: 把一个非关键服务迁过来跑 [1 周]
↓
step 7: 优化:监控 + 日志 + 告警 [1 周]
↓
step 8: HA + 灾备 + 安全加固 [1 周]

全过程约 6~8 周 1 人投入(含学习)。


11. 一句话总结​

  • 小企业 K8s 选 K3s + Rancher,上手快、社区成熟
  • CI/CD 选 Jenkins(K8s plugin)+ Harbor + Kaniko + Trivy,生态最全、门禁最严
  • 把备份 / 监控 / 安全当基础设施而不是后期补救,按"日备、周演、月审计"做
  • GitOps 是省事省心的进阶,强烈推荐

12. 推荐参考阅读​

标签:#docker #kubernetes #harbor #jenkins

数据库设计相关笔记

· 阅读需 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

权限模型笔记

· 阅读需 10 分钟

原 旧稿(RBAC / ABAC / ReBAC 三模型对比)的重写。 原笔记是定性对比,本笔记在此基础上补充 Casbin 库的落地实现(Python 版 PERM 模型、policy 文件、FastAPI 集成、RBAC with Domains、ReBAC 关系建模),让模型能真正用起来。

登录与鉴权流程见 [[鉴权与登录笔记]]。 网关中的鉴权中间件见 [[API网关原理与选型笔记]]。

目录​

  1. 三模型对比(RBAC / ReBAC / ABAC)
  2. RBAC 模型详解
  3. ReBAC 模型详解
  4. ABAC 模型简述
  5. Casbin 库核心(Python 版)
  6. RBAC 最小可运行示例(含角色继承)
  7. RBAC with Domains(多租户)
  8. ReBAC 关系建模(Casbin g2)
  9. RESTful 路径权限检查(keyMatch2)
  10. Casbin 在 FastAPI 中集成
  11. 实战:RBAC + ReBAC 混合

1. 三模型对比(RBAC / ReBAC / ABAC)​

模型一句话典型问题典型场景
RBAC你是什么身份你是不是管理员?后台菜单 / 按钮权限 / 组织架构
ReBAC你和它什么关系你是这个文档的 owner 吗?协作 / 项目 / 社交
ABAC你满足什么条件你是不是这个部门 + 当前是工作时间?数据权限 / 部门隔离 / 时段限制

口诀:

  • RBAC → 身份 / 角色
  • ReBAC → 关系 / 邻居
  • ABAC → 属性 / 规则

现实项目里很少只用一种:

场景组合
企业后台RBAC(菜单/按钮) + ABAC(数据范围)
多租户协作RBAC(平台角色) + ReBAC(项目成员)
复杂 SaaSRBAC + ABAC + ReBAC 三者混合

2. RBAC 模型详解​

2.1 三层结构​

用户 ──绑定──► 角色 ──绑定──► 权限

Alice ──► admin ──► [删除用户, 管理订单, 查看报表]
Bob ──► editor ──► [创建文章, 修改文章]
Tom ──► viewer ──► [查看文章]

2.2 角色继承​

admin ──继承──► user
editor ──继承──► user

admin 自动拥有 user 的所有权限,不必重复配置。

2.3 为什么 RBAC 是后台系统的默认选择​

  • 管理简单:权限挂在角色上,增删用户不动权限
  • 符合直觉:组织架构天然是角色化(部门 / 职位)
  • 实现成本低:一张 user_role 表 + 一张 role_permission 表就够

2.4 RBAC 不擅长什么​

editor 可以修改文章

但具体能改哪些文章?RBAC 答不了:

  • 所有文章?
  • 自己部门的?
  • 自己创建的?

答不了就走 ReBAC 或 ABAC(见下文)。


3. ReBAC 模型详解​

3.1 核心思想​

权限不是由角色或属性决定,而是由"用户和资源之间的关系"决定。

Alice ──[owner]──► doc_123
Bob ──[editor]──► doc_123
Carol ──[viewer]──► doc_123

Alice ──[member]──► team_A
team_A ──[owns]──► project_X
project_X ──[contains]──► doc_123
↓ 推导
Alice ──[viewer (继承)]──► doc_123 (因为她是 team_A 成员)

3.2 ReBAC 的直觉理解​

模型问的问题
RBAC你是谁?
ABAC你有哪些特征?
ReBAC你和这个对象是什么关系?

3.3 典型 ReBAC 场景​

场景关系
协作文档owner / editor / viewer
GitHub 仓库member / outside-collaborator
Notion / 飞书workspace member + page permission
社交friend / follower / blocked
项目team member / project owner / approver

3.4 ReBAC 的"关系链推导"​

用户 --[member]--> 团队
团队 --[owns]--> 项目
项目 --[contains]--> 仓库

↓ 推导
用户对该仓库有 [member] 权限

这种"从关系图推导权限"是 ReBAC 的核心特点,也是它实现起来比 RBAC 复杂的地方。


4. ABAC 模型简述​

ABAC 通过属性规则动态判断:

IF user.department == resource.department
AND user.level >= 2
AND action == "read"
THEN allow

四类属性:

  • 用户属性:部门 / 岗位 / 级别 / 地区
  • 资源属性:创建人 / 所属部门 / 敏感等级 / 状态
  • 操作属性:read / write / approve
  • 环境属性:时间 / IP / 地理位置 / 设备

适用:规则复杂多变(金融 / 医疗 / 政务)、需要细粒度条件。

代价:规则易膨胀,调试难。所以实际项目通常 RBAC 主导 + ABAC 补充。


5. Casbin 库核心(Python 版)​

Casbin 是一个通用的授权库,支持多种模型(RBAC / ABAC / ReBAC / RESTful),多种语言(Go / Java / Python / Node.js / PHP)。

核心思想:配置文件定义模型 + 策略文件定义数据,库帮你做"请求 → 决策"。

5.1 PERM 模型(Policy / Effect / Request / Matchers)​

任何 Casbin 模型都包含 4 段:

# 1. 请求定义:用户要做什么请求
[request_definition]
r = sub, obj, act

# 2. 策略定义:一条权限规则是什么样子
[policy_definition]
p = sub, obj, act

# 3. 角色定义(RBAC 用):用户到角色的映射
[role_definition]
g = _, _

# 4. 匹配器:请求和策略如何匹配(核心规则)
[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

# 5. 效果:满足策略时的最终决定
[policy_effect]
e = some(where (p.eft == allow))

5.2 策略文件​

# policy.csv
p, alice, data1, read
p, bob, data2, write
p, data2_admin, data2, read
p, data2_admin, data2, write

g, alice, data2_admin # alice 继承 data2_admin 的所有权限

5.3 Python API 速查​

import casbin

e = casbin.Enforcer("model.conf", "policy.csv")

# 鉴权(核心)
e.enforce("alice", "data1", "read") # True(直接策略)
e.enforce("alice", "data2", "write") # True(通过 g 继承)
e.enforce("bob", "data1", "read") # False

# 运行时增删策略
e.add_policy("eve", "data3", "read")
e.remove_policy("eve", "data3", "read")

# 角色绑定
e.add_grouping_policy("alice", "data2_admin")
e.remove_grouping_policy("alice", "data2_admin")
e.get_roles_for_user("alice") # ["data2_admin"]
e.get_implicit_roles_for_user("alice") # 含继承传递
e.get_users_for_role("data2_admin") # ["alice"]

# 持久化
e.save_policy() # 写回 adapter

5.4 Adapter 选型​

Adapter适用
FileAdapter(CSV)demo / 小项目
casbin-sqlalchemy-adapter关系型数据库(推荐生产)
casbin-redis-adapter高频读 + 集群
casbin-mongodb-adapter文档型场景
# SQLAlchemy adapter 用法
from casbin_sqlalchemy_adapter import Adapter
import casbin

adapter = Adapter("postgresql://user:pass@host/db")
e = casbin.Enforcer("model.conf", adapter)
e.load_policy() # 从 DB 加载

6. RBAC 最小可运行示例(含角色继承)​

6.1 model.conf​

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub) && r.obj == p.obj && r.act == p.act

6.2 policy.csv​

p, alice, data1, read
p, bob, data2, write
p, data2_admin, data2, read
p, data2_admin, data2, write

g, alice, data2_admin

6.3 验证​

import casbin
e = casbin.Enforcer("model.conf", "policy.csv")

e.enforce("alice", "data1", "read") # True(直接)
e.enforce("alice", "data2", "write") # True(继承自 data2_admin)
e.enforce("bob", "data2", "write") # True(直接)
e.enforce("bob", "data1", "read") # False

7. RBAC with Domains(多租户)​

问题:同一用户在不同租户有不同角色(如:Alice 在公司 A 是 admin,在公司 B 只是 user)。

7.1 model.conf(域扩展)​

[request_definition]
r = sub, dom, obj, act

[policy_definition]
p = sub, dom, obj, act

[role_definition]
g = _, _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub, r.dom) && r.dom == p.dom && r.obj == p.obj && r.act == p.act

7.2 policy.csv​

p, admin, tenant1, data1, read
p, admin, tenant2, data2, read
p, user, tenant2, data2, read

g, alice, admin, tenant1
g, alice, user, tenant2
g, bob, user, tenant2

7.3 验证​

e.enforce("alice", "tenant1", "data1", "read") # True(admin@tenant1)
e.enforce("alice", "tenant2", "data2", "read") # True(user@tenant2)
e.enforce("alice", "tenant2", "data1", "read") # False(tenant1 的 admin 不跨租户)
e.enforce("bob", "tenant1", "data1", "read") # False(bob 不是 tenant1 成员)

8. ReBAC 关系建模(Casbin g2)​

Casbin 默认 g 是用户-角色继承;g2 用于角色-角色继承,但更常见的用法是用 g 模拟"对象-关系"。

8.1 思路:把"关系"建模为 policy​

# 用户与资源的关系
p, doc_owner, doc_123, read
p, doc_owner, doc_123, write
p, doc_owner, doc_123, delete
p, doc_editor, doc_123, read
p, doc_editor, doc_123, write
p, doc_viewer, doc_123, read

# 谁是什么关系
g, alice, doc_owner, doc_123
g, bob, doc_editor, doc_123
g, carol, doc_viewer, doc_123

8.2 model.conf​

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _, _ # 用户, 关系角色, 资源

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub, r.obj) && r.obj == p.obj && r.act == p.act

8.3 验证​

e.enforce("alice", "doc_123", "delete") # True(owner)
e.enforce("bob", "doc_123", "write") # True(editor)
e.enforce("carol", "doc_123", "read") # True(viewer)
e.enforce("carol", "doc_123", "write") # False

生产环境关系数量爆炸(每个文档 × 3 种关系),需要把关系存数据库(adapter), 不要写 CSV 文件。


9. RESTful 路径权限检查(keyMatch2)​

场景:权限按 URL 路径 + HTTP 方法控制(如 alice 能访问 /api/users/* GET,admin 能访问 /api/* 任意方法)。

9.1 model.conf​

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = g(r.sub, p.sub) && keyMatch2(r.obj, p.obj) && (r.act == p.act || r.act == "ANY")

9.2 policy.csv​

p, alice, /api/users/*, GET
p, bob, /api/orders/*, GET
p, admin, /api/*, ANY

g, alice, admin # alice 继承 admin 所有权限

9.3 验证​

e.enforce("alice", "/api/users/123", "GET") # True
e.enforce("alice", "/api/orders/1", "GET") # True(admin 继承)
e.enforce("bob", "/api/users/123", "GET") # False
e.enforce("admin", "/api/anything", "DELETE") # True(ANY)

keyMatch2 支持的路径模式:

  • /foo/:id 匹配 /foo/123
  • /foo/* 匹配 /foo/anything/more

10. Casbin 在 FastAPI 中集成​

10.1 单例 Enforcer​

# deps.py
import casbin
from functools import lru_cache

@lru_cache()
def get_enforcer() -> casbin.Enforcer:
return casbin.Enforcer("policy/model.conf", "policy/policy.csv")

# 用 SQLAlchemy adapter
# from casbin_sqlalchemy_adapter import Adapter
# @lru_cache()
# def get_enforcer():
# adapter = Adapter("sqlite:///casbin.db")
# return casbin.Enforcer("policy/model.conf", adapter)

10.2 依赖链:先鉴权(JWT)→ 再鉴权(Casbin)​

# main.py
from fastapi import Depends, FastAPI, HTTPException
from deps import get_enforcer
from auth import get_current_user # 见 [[鉴权与登录笔记]]

app = FastAPI()
enforcer = get_enforcer()


def check_permission(sub: str, obj: str, act: str):
if not enforcer.enforce(sub, obj, act):
raise HTTPException(403, "Forbidden")


@app.get("/api/users/{user_id}")
def get_user(
user_id: int,
user: dict = Depends(get_current_user),
):
check_permission(user["sub"], f"/api/users/{user_id}", "GET")
return {"user_id": user_id}


@app.delete("/api/users/{user_id}")
def delete_user(
user_id: int,
user: dict = Depends(get_current_user),
):
check_permission(user["sub"], f"/api/users/{user_id}", "DELETE")
# ... 业务逻辑
return {"deleted": user_id}

10.3 多租户 Casbin​

def check_permission_with_tenant(sub: str, tenant: str, obj: str, act: str):
if not enforcer.enforce(sub, tenant, obj, act): # 见 §7 模型
raise HTTPException(403, "Forbidden")

11. 实战:RBAC + ReBAC 混合​

11.1 场景​

某 SaaS 平台:

  • 平台层面:用户有 admin / member 角色(RBAC)
  • 项目层面:用户与项目有 owner / collaborator / viewer 关系(ReBAC)

11.2 model.conf(同时定义 RBAC 和 ReBAC)​

[request_definition]
r = sub, obj, act

[policy_definition]
p = sub, obj, act

[role_definition]
g = _, _ # RBAC: 用户 - 平台角色
g2 = _, _, _ # ReBAC: 用户 - 资源关系 - 资源 ID

[policy_effect]
e = some(where (p.eft == allow))

[matchers]
m = (g(r.sub, p.sub) || g2(r.sub, p.sub, r.obj)) \
&& r.obj == p.obj \
&& r.act == p.act

含义:用户要么通过平台角色(RBAC)要么通过资源关系(ReBAC)满足权限。

11.3 policy.csv​

# RBAC: 平台角色权限
p, admin, /api/projects/*, ANY
p, member, /api/projects/*, GET

# ReBAC: 项目关系 → 项目权限
p, owner, /api/projects/proj_123, ANY
p, collaborator, /api/projects/proj_123, GET
p, collaborator, /api/projects/proj_123, POST
p, viewer, /api/projects/proj_123, GET

# 平台角色绑定
g, alice, admin

# ReBAC 关系绑定
g2, alice, owner, proj_123
g2, bob, collaborator, proj_123
g2, carol, viewer, proj_123

11.4 验证​

# alice 是 admin,能操作任何项目
e.enforce("alice", "/api/projects/proj_123", "DELETE") # True(admin)
e.enforce("alice", "/api/projects/proj_999", "POST") # True(admin)

# bob 是 proj_123 的 collaborator
e.enforce("bob", "/api/projects/proj_123", "POST") # True(collaborator)
e.enforce("bob", "/api/projects/proj_123", "DELETE") # False(collaborator 没 DELETE)
e.enforce("bob", "/api/projects/proj_999", "GET") # False(不是 proj_999 成员)

关联笔记​

  • 登录鉴权流程(拿到用户身份):[[鉴权与登录笔记]]
  • 网关(鉴权中间件放哪):[[API网关原理与选型笔记]]
  • 数据库设计(角色表 / 权限表怎么设计):[[数据库设计与索引优化笔记]]

Demo​

完整代码:

Sources​

标签:#fastapi

消息队列对比与选型笔记

· 阅读需 9 分钟

RabbitMQ vs Kafka 横向对比 + 选型决策 + 可视化平台 + CLI/UI 操作实践。 单库详情:RabbitMQ笔记 · Kafka笔记。 本笔记聚焦"什么场景选哪个"和"生产环境怎么用",避免把两者当同类产品对比。

目录​

  1. 一句话定位
  2. 维度对比表
  3. 性能 / 吞吐对比
  4. 消息模型本质差异
  5. 场景选型决策
  6. 可视化平台对比
  7. CLI vs UI 操作实践
  8. 反向场景 + 共存架构

1. 一句话定位​

消息队列一句话
RabbitMQ复杂路由 + 低延迟 + 传统任务队列的消息代理(Broker 范式)
Kafka高吞吐 + 持久化 + 可重放的分布式日志(Log 范式)

最本质差异:RabbitMQ 投递后默认删除消息(队列消费);Kafka 默认保留消息(日志消费,consumer 各自维护 offset)。


2. 维度对比表​

维度RabbitMQKafka
架构范式消息代理(Broker)分布式日志(Log)
消息模型队列(消费后删除)日志(保留期 + offset)
路由能力✅ 4 种 Exchange(direct/topic/fanout/headers)❌ 仅按 topic + partition
投递语义At-most-once / At-least-onceAt-most-once / At-least-once / Exactly-Once
消息保留投递后删除保留期(默认 7 天,可设数月)
顺序保证单队列单消费者 FIFO单 partition 内严格有序
单机吞吐万~十万 QPS十万~百万 TPS
延迟微秒~毫秒级毫秒~十几毫秒
协议AMQP 0.9.1 / 1.0 / MQTT / STOMP自定义二进制协议
集群协调Erlang 分布式(4.0+ Quorum)KRaft(4.x)/ ZK(≤3.9)
持久化可选始终
多消费者抢消费(一条消息只给一个 consumer)各自消费(每 group 一份)
重放历史❌ 不支持✅ offset 可回退
适用规模中小规模(百万级 QPS 以下)大规模(百万 TPS+)
运维复杂度中(集群 + 镜像)中(KRaft / ZK 复杂度转移)
生态成熟度老牌、传统企业广泛使用互联网 / 大数据领域事实标准
客户端库所有主流语言所有主流语言
云厂商支持AWS MQ / Azure Service BusConfluent Cloud / MSK / 所有云厂

3. 性能 / 吞吐对比​

3.1 数量级参考​

指标RabbitMQ(Quorum Queue 3 节点)Kafka(3 broker + RF=3)
峰值吞吐5~10 万 msg/s50~100 万 msg/s
单消息延迟< 1ms5~15ms
消息体大小推荐 < 1MB推荐 < 1MB(默认 1MB,可调到数 MB)
堆积能力弱(百万级就开始告警)强(TB 级常态)

3.2 性能特征差异​

  • RabbitMQ:每条消息走队列、ack、DLX 等流程,单条延迟低,但堆积后性能急剧下降
  • Kafka:顺序写 + 零拷贝 + 页缓存,批量吞吐高,延迟主要来自 batch + fsync

3.3 选型参考​

场景性能指标推荐
高频交易(万 TPS + 毫秒延迟)延迟 < 10msRabbitMQ
日志聚合(10 万+ TPS)吞吐优先Kafka
事件溯源(消息可重放)历史可重读Kafka
复杂任务路由(多 Exchange)路由能力RabbitMQ
实时数据管道(流处理)吞吐 + 重放Kafka

4. 消息模型本质差异​

4.1 队列消费(RabbitMQ)​

[Producer] → Exchange → [Queue: msg1, msg2, msg3]
↓
Consumer A
(msg1 被 ack 后从队列删除)
  • 消息消费后即删除(ack 后)
  • 多个 consumer 抢同一条消息
  • 适合任务分发(一个任务被一个 worker 消费)

4.2 日志消费(Kafka)​

[Producer] → Topic partition: [msg0, msg1, msg2, msg3, ...] (append-only)
↓
Consumer Group A: offset=2
Consumer Group B: offset=0
(两个 group 各自维护 offset,互不影响)
  • 消息保留期内不删除
  • 多个 Consumer Group 各自维护 offset,各看各的
  • 适合事件流(同一事件被多个服务消费:搜索 + 缓存 + 审计)

4.3 业务影响​

  • 想"消费完删掉" → RabbitMQ
  • 想"消费完还能查" → Kafka(offset 可回放、replay 历史)
  • 想"一条事件被多服务处理" → Kafka
  • 想"一个任务被一个 worker 抢走" → RabbitMQ

5. 场景选型决策​

5.1 决策流程图​

业务核心诉求是什么?
├── 复杂路由 / 多 Exchange / 主题分发 ──→ ✅ RabbitMQ
├── RPC 风格 / 同步请求-响应 ──→ ✅ RabbitMQ(原生支持)
├── 消息保留 + 可重放 + 流处理 ──→ ✅ Kafka
├── 事件溯源 / 日志聚合 / CDC ──→ ✅ Kafka
├── 延迟敏感(毫秒级) ──→ ✅ RabbitMQ
├── 极致吞吐(10 万+ TPS) ──→ ✅ Kafka
├── 与大数据生态对接(Spark/Flink) ──→ ✅ Kafka
├── 简单任务队列(小规模) ──→ ✅ RabbitMQ(Quorum)
└── 不确定 ──→ 简单用 RabbitMQ;需要扩展时再考虑 Kafka

5.2 按场景列表​

场景推荐理由
订单 / 支付核心业务RabbitMQ低延迟、强可靠投递、复杂路由
异步通知(短信 / 邮件)RabbitMQ简单、延迟不敏感
微服务间事件总线Kafka多服务订阅、消息可重放
日志聚合Kafka高吞吐、可被多个消费者解析
用户行为埋点Kafka高吞吐、可重放计算
CDC(数据库变更捕获)KafkaDebezium → Kafka 是业界标准
实时流处理KafkaFlink / Spark Streaming 原生支持
IoT 设备数据Kafka高吞吐、消息保留可追溯
RPC 同步请求RabbitMQ原生 RPC 支持
大文件传输都不合适走对象存储 / 大文件专用通道

5.3 两者共存(业界常见)​

大型系统两个都用是常态:

[Web 业务] ──→ RabbitMQ(核心交易,复杂路由)
├──→ [订单服务]
├──→ [库存服务]
└──→ [审计服务(同时投递到 Kafka 归档)]
↓
Kafka(事件流 / 大数据 / 风控)
├──→ [实时风控]
├──→ [BI 分析]
├──→ [数据湖归档]
└──→ [实时推荐]

典型分层:

  • 业务关键路径 → RabbitMQ(强一致)
  • 跨域事件流 / 数据管道 → Kafka(高吞吐 + 重放)

6. 可视化平台对比​

6.1 RabbitMQ 工具​

工具类型优势限制
Management UI官方自带装 RMQ 就有,队列/连接/Channel 可视化大集群性能差
Prometheus + Grafana监控指标丰富、告警灵活需自建
rabbitmqadminCLI批量操作、API 化学习曲线

6.2 Kafka 工具​

工具类型优势限制
AKHQ(akhq.io)开源 Web UI多集群 + Schema Registry + Connect中等规模
Redpanda Console开源 Web UI轻量、UI 简洁功能较基础
Confluent Control Center商业官方最全、监控 + 告警 + 治理重 + 付费
Conduktor桌面端桌面级 + 企业功能商业
Kowl(已被 Redpanda 收购)开源轻量已停更
kafka-ui(UI for Apache Kafka)开源部署简单维护节奏一般
Prometheus JMX Exporter + Grafana监控指标丰富需自建

6.3 推荐组合​

团队规模RMQKafka
小团队 / 中小规模Management UI + PrometheusAKHQ(开源免费)
中大型Prometheus + GrafanaRedpanda Console + Prometheus
企业付费Prometheus + Grafana + 商业 APMConfluent Control Center

7. CLI vs UI 操作实践​

7.1 生产实践原则​

日常查问题用 UI,批量操作 / 灾备 / 监控告警用 CLI + 自动化脚本。

场景用什么原因
查看消息内容(debug)UI直观、过滤方便
看队列长度、Consumer LagUI / Grafana实时面板
创建/删除队列/TopicCLI(脚本化)可审计、可批量
调整 partition / 配额CLIUI 容易误操作
灾备数据导入导出CLI可写脚本、可定时
监控告警Prometheus + Alertmanager自动化
跨环境同步配置CLI + IaC(Terraform)幂等、可追溯

7.2 RabbitMQ CLI 速查​

# 查看队列列表
rabbitmqctl list_queues name messages_ready messages_unacknowledged

# 启用 Prometheus 插件
rabbitmq-plugins enable rabbitmq_prometheus

# 设置 Policy(动态改 DLX)
rabbitmqctl set_policy DLX "orders.*" \
'{"dead-letter-exchange":"orders.dlx"}' --apply-to queues --priority 7

# rabbitmqadmin(HTTP API 封装)
rabbitmqadmin -u admin -p admin list queues
rabbitmqadmin -u admin -p admin publish exchange=orders routing_key=order.created payload='{"id":1}'

7.3 Kafka CLI 速查​

# 启动 kafka-shell 容器后操作(或在 broker 容器内)

# Topic 管理
kafka-topics.sh --bootstrap-server localhost:9092 --create --topic orders --partitions 6 --replication-factor 3
kafka-topics.sh --bootstrap-server localhost:9092 --list
kafka-topics.sh --bootstrap-server localhost:9092 --describe --topic orders
kafka-topics.sh --bootstrap-server localhost:9092 --alter --topic orders --partitions 12

# 生产/消费
kafka-console-producer.sh --bootstrap-server localhost:9092 --topic orders
kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic orders --from-beginning

# Consumer Group 管理
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group order-processor
kafka-consumer-groups.sh --bootstrap-server localhost:9092 --reset-offsets --group order-processor --topic orders --to-earliest --execute

7.4 生产实践 tips​

  • Topic 创建走 IaC(Terraform / Ansible),不靠人肉 CLI
  • 监控告警 100% CLI + Prometheus,不用 UI 报警(UI 是给人看的)
  • 生产变更 全留操作记录(CLI 配 shell history / audit log)
  • 查问题 先 UI 看现象,再 CLI 拉日志,再加 debug

8. 反向场景 + 共存架构​

8.1 什么时候不选 RabbitMQ​

  • ❌ 消息要保留几天到几周(用 Kafka)
  • ❌ 日志 / 事件流(用 Kafka)
  • ❌ 单集群 > 50 万 QPS(Kafka 集群更划算)
  • ❌ 需要多个服务独立消费同一事件流(Kafka 多 Consumer Group)

8.2 什么时候不选 Kafka​

  • ❌ 复杂路由(topic + partition 不够灵活)
  • ❌ RPC / 同步请求-响应
  • ❌ 极小消息量(运维成本不划算)
  • ❌ 团队完全没接触过(学习曲线陡)

8.3 共存架构​

[Web 业务]
↓
[RabbitMQ 集群] ← 核心交易,Quorum Queue,复杂路由
├── 订单服务
├── 支付服务
├── 库存服务
└── 审计服务
↓ (投递到 Kafka 归档)
[Kafka 集群] ← 事件流,跨域,高吞吐
├── 实时风控
├── 数据湖
├── 推荐系统
└── BI 报表

优点:

  • 业务关键路径用 RMQ(强一致)
  • 数据管道用 Kafka(高吞吐 + 重放)
  • 各取所长

代价:

  • 两套运维
  • 数据双写一致性要自己处理

关联笔记​

  • RabbitMQ 详情:RabbitMQ笔记
  • Kafka 详情:Kafka笔记
  • Demo:example/mq/(docker-compose + 生产级 Producer/Consumer + 事务示例)

标签:#rabbitmq #kafka

鉴权与登录笔记

· 阅读需 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