nex_docus/docs/sdd/specs/DV-0001-auth/design.md

DV-0001：认证与会话 – 设计（Design）

上下文

涉及 auth.py（API）、security.py（JWT/bcrypt）、deps.py（依赖注入）、redis_client.py（TokenCache）。

数据模型

• users（id/username/password_hash/…）——细节见 DATABASE.md。

接口设计

• POST /api/v1/auth/{register,login,logout}
• GET /api/v1/auth/me
• PUT /api/v1/auth/profile
• POST /api/v1/auth/change-password
• POST /api/v1/auth/upload-avatar
• GET /api/v1/auth/avatar/{user_id}/{filename}
• GET/POST /api/v1/auth/mcp-credentials{,/rotate-secret}

认证流程

1. 登录成功：bcrypt 校验 → 生成 JWT（sub=user_id）→ 写入 Redis TokenCache。
2. 每次请求：get_current_user 校验 Redis 中 token→user_id，再 decode JWT，两项一致且用户启用才放行。
3. 登出：移除 Redis 中的 token，实现即时失效。

状态与降级

• Redis 不可用 → 认证失败（受 NFR-2 约束）；可选认证（get_current_user_optional）返回 None 而非报错。

变更影响

• NFR-9 敏感日志：security.py/deps.py 的 SECRET_KEY/JWT 载荷日志需脱敏（TS-12）。