LQAI-middle-platform/文档/Token管理说明.md

统一认证平台已全面使用 Redis 进行 Token 的保存和失效控制。

具体实现如下：

1. 核心 Redis Token 管理模块

src/app/utils/redis_token_manager.py 是专门的 Redis Token 管理模块，统一维护以下 5 类数据：

┌────────────────┬───────────────────────────────────────┬──────────────────────────────────────────┐
│ 数据类型 │ Redis Key 前缀 │ 用途 │
├────────────────┼───────────────────────────────────────┼──────────────────────────────────────────┤
│ Access Token │ auth:access:{token} │ 存储用户登录后的 access_token，TTL │
│ │ │ 控制失效 │
├────────────────┼───────────────────────────────────────┼──────────────────────────────────────────┤
│ Refresh Token │ auth:refresh:{token} │ 存储 refresh_token，TTL 控制失效 │
├────────────────┼───────────────────────────────────────┼──────────────────────────────────────────┤
│ Token 黑名单 │ auth:blacklist:{token} │ 用户登出或撤销后写入，TTL 为 token │
│ │ │ 剩余过期时间 │
├────────────────┼───────────────────────────────────────┼──────────────────────────────────────────┤
│ OAuth 授权码 │ auth:oauth_code:{code} │ 存储 OAuth2 授权码，默认 10 分钟 │
│ │ │ TTL，一次性使用 │
├────────────────┼───────────────────────────────────────┼──────────────────────────────────────────┤
│ OAuth Access │ auth:oauth_access:{client_id}:{token} │ 存储第三方应用授权的 access_token，TTL │
│ Token │ │ 控制失效 │
└────────────────┴───────────────────────────────────────┴──────────────────────────────────────────┘

1. 认证服务层（auth_service.py）

• 登录时：生成 JWT 后，立即调用 rtm.store_access_token() 和 rtm.store_refresh_token() 写入 Redis。
  
• 刷新时：从 Redis 校验 refresh_token 是否存在且不在黑名单，再生成新的 access_token 写入 Redis。
  
• 登出时：调用 rtm.add_token_to_blacklist() 将 token 加入 Redis 黑名单，并删除 Redis 中的活跃 token。
  
• 验证时：JWT 签名通过后，必须再查 Redis（rtm.validate_access_token()）确认 token 存在且未失效。
  

1. OAuth 服务层（oauth_service.py）

• 授权码：生成后写入 Redis（rtm.store_oauth_code()），验证时从 Redis 读取并删除（rtm.get_and_delete_oauth_code()）。
• Access Token：生成后写入 Redis（rtm.store_oauth_access_token()）。

1. 认证依赖/中间件

• auth_dependency.py 和 token_refresh_middleware.py 在每次请求时，除了验证 JWT 签名，都会调用 rtm.validate_access_token() 做 Redis 存在性/黑名单校验。
• 滑动过期刷新出新 token 时，会同步调用 rtm.update_access_token() 更新 Redis。

1. MySQL 表的现状

虽然 src/app/models/token.py 仍定义了 t_oauth_access_tokens、t_oauth_authorization_codes、t_oauth_token_blacklist 三张表，但从服务层代码看，活跃 Token 的增删查改已经完全迁移到 Redis，MySQL 中的这几张表目前仅作为遗留结构（或可能用于历史审计），不再参与实时的认证校验逻辑。

1. 失效控制机制

• TTL 过期：所有 Token 在写入 Redis 时都设置了 setex（带 TTL 的写入），到期自动失效。
• 主动失效（登出/撤销）：写入 auth:blacklist:{token} 黑名单，并删除原活跃 key。
• 滑动过期：当 token 使用时间超过总有效期一半时，生成新 token 并替换 Redis 中的旧 key。