wangdl/api-server
2
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

M0-13 Admin Auth & RBAC 基础版 #13

New Issue
Open
opened 2026-05-22 21:00:16 +08:00 by wangdl · 0 comments
wangdl commented 2026-05-22 21:00:16 +08:00
Owner
Copy Link

目标

设计知习后端 Admin 认证与权限模块，为 Admin 后台提供独立的登录体系、角色管理和权限校验。

本 Issue 只做架构设计，不直接实现代码。

背景说明

知习有 Admin 后台用于运维管理，Admin 用户体系必须与 C 端用户完全隔离。Admin 有自己的登录接口（/admin-api/auth/*），有独立的 JWT Token，Token 不能用来访问 C 端接口，反之亦然。

Admin 需要角色和权限控制：不同 Admin 用户可能有不同的操作权限（如只能查看不能修改、只能管理用户不能管理密钥等）。

模块职责

  1. 本模块负责：

    • Admin 用户管理（账号、密码哈希、状态）
    • Admin 登录和登出
    • Admin JWT Token 签发和校验
    • Admin Session 管理
    • 角色定义和管理
    • 权限定义和管理
    • 角色-权限关联
    • Admin 用户-角色关联
    • Admin 权限 Guard（供其他 Admin 模块使用）

  2. 本模块不负责：

    • C 端用户登录（走 User & Account Module）
    • 操作审计日志（走 Audit & Security Module）
    • Admin 操作限流（走 Traffic Protection Module）
    • 2FA 实现（预留，当前阶段不做）

候选数据对象

  • AdminUser（Admin 用户）
  • AdminSession / AdminRefreshToken
  • AdminRole（角色）
  • AdminPermission（权限）
  • AdminUserRole（用户-角色关联）

基础设施依赖判断

  • MySQL：是（Admin 用户、角色、权限数据）
  • Redis：是（Session 缓存、登录限流、Token 黑名单）
  • BullMQ：否
  • Qdrant：否
  • AI Gateway：否
  • COS：否

API 设计

  1. AAPI：

    • Admin 登录
    • Admin 登出
    • 刷新 Token
    • 获取当前 Admin 用户信息

  2. AAPI（用户管理，需要权限）：

    • Admin 用户列表
    • 新增 Admin 用户
    • 修改 Admin 用户状态
    • 角色列表和管理
    • 权限列表
    • 分配角色给用户

安全设计

  1. 密码安全：

    • 密码哈希算法（bcrypt 或 argon2，请判断）
    • 密码强度要求

  2. Token 安全：

    • JWT AccessToken 有效期
    • RefreshToken 轮换策略
    • Token 失效机制（用户被禁用后 Token 立即失效）

  3. 登录安全：

    • 登录失败次数限制和锁定
    • 异常登录检测（新 IP/设备）

  4. 最小权限原则：新创建的 Admin 用户默认无权限，需手动分配角色

Domain Event 设计

  • AdminLoggedIn：Admin 登录
  • AdminLoggedOut：Admin 登出
  • AdminUserCreated：Admin 用户创建
  • AdminUserDisabled：Admin 用户被禁用
  • AdminRoleChanged：Admin 角色变更

Admin 视图设计

  1. Admin 用户管理页：用户列表（用户名、角色、状态、最后登录时间）、新增用户表单、启用/禁用用户、分配角色
  2. 角色管理页：角色列表、权限矩阵、新增/编辑角色

交付检查

  • 路由归属：AAPI
  • 是否需要 Prisma migration：是
  • 是否需要 MySQL：是
  • 是否需要 Redis：是
  • 是否需要 BullMQ：否
  • 是否需要 Qdrant：否
  • 是否需要 AI Gateway：否
  • 是否需要 Content Safety：否
  • 是否需要 Cost 记录：否
  • 是否需要 AuditLog：是（Admin 用户增删改、角色变更、登录记录）
  • 是否需要 Domain Event：是
  • 是否需要 Admin 视图：是
  • 是否需要 E2E/集成测试：是

验收标准

  1. AdminUser / AdminRole / AdminPermission Prisma schema
  2. Admin 登录流程设计（JWT + RefreshToken）
  3. 角色-权限模型设计
  4. AdminAuthGuard 实现（供所有 Admin 接口使用）
  5. 登录安全策略设计（失败锁定、异常检测）
  6. Admin 管理视图设计
  7. 集成测试覆盖登录/权限校验/角色管理

禁止事项

  • 禁止 Admin 用户和 C 端用户混用同一张表
  • 禁止 Admin Token 可以访问 C 端接口
  • 禁止 C 端 Token 可以访问 Admin 接口
  • 禁止密码明文存储
  • 禁止 RefreshToken 明文存储
  • 禁止 Admin 用户删除自己
  • 禁止无权限的 Admin 用户看到越权数据

不建议当前阶段实现

  • 2FA 双因素认证
  • SSO 单点登录
  • OAuth 第三方登录（GitHub/Google 等）
  • 细粒度的字段级别权限
  • 权限变更审批流程
## 目标 设计知习后端 Admin 认证与权限模块，为 Admin 后台提供独立的登录体系、角色管理和权限校验。 本 Issue 只做架构设计，不直接实现代码。 ## 背景说明 知习有 Admin 后台用于运维管理，Admin 用户体系必须与 C 端用户完全隔离。Admin 有自己的登录接口（/admin-api/auth/*），有独立的 JWT Token，Token 不能用来访问 C 端接口，反之亦然。 Admin 需要角色和权限控制：不同 Admin 用户可能有不同的操作权限（如只能查看不能修改、只能管理用户不能管理密钥等）。 ## 模块职责 1. 本模块负责： - Admin 用户管理（账号、密码哈希、状态） - Admin 登录和登出 - Admin JWT Token 签发和校验 - Admin Session 管理 - 角色定义和管理 - 权限定义和管理 - 角色-权限关联 - Admin 用户-角色关联 - Admin 权限 Guard（供其他 Admin 模块使用） 2. 本模块不负责： - C 端用户登录（走 User & Account Module） - 操作审计日志（走 Audit & Security Module） - Admin 操作限流（走 Traffic Protection Module） - 2FA 实现（预留，当前阶段不做） ## 候选数据对象 - AdminUser（Admin 用户） - AdminSession / AdminRefreshToken - AdminRole（角色） - AdminPermission（权限） - AdminUserRole（用户-角色关联） ## 基础设施依赖判断 - MySQL：是（Admin 用户、角色、权限数据） - Redis：是（Session 缓存、登录限流、Token 黑名单） - BullMQ：否 - Qdrant：否 - AI Gateway：否 - COS：否 ## API 设计 1. AAPI： - Admin 登录 - Admin 登出 - 刷新 Token - 获取当前 Admin 用户信息 2. AAPI（用户管理，需要权限）： - Admin 用户列表 - 新增 Admin 用户 - 修改 Admin 用户状态 - 角色列表和管理 - 权限列表 - 分配角色给用户 ## 安全设计 1. 密码安全： - 密码哈希算法（bcrypt 或 argon2，请判断） - 密码强度要求 2. Token 安全： - JWT AccessToken 有效期 - RefreshToken 轮换策略 - Token 失效机制（用户被禁用后 Token 立即失效） 3. 登录安全： - 登录失败次数限制和锁定 - 异常登录检测（新 IP/设备） 4. 最小权限原则：新创建的 Admin 用户默认无权限，需手动分配角色 ## Domain Event 设计 - AdminLoggedIn：Admin 登录 - AdminLoggedOut：Admin 登出 - AdminUserCreated：Admin 用户创建 - AdminUserDisabled：Admin 用户被禁用 - AdminRoleChanged：Admin 角色变更 ## Admin 视图设计 1. Admin 用户管理页：用户列表（用户名、角色、状态、最后登录时间）、新增用户表单、启用/禁用用户、分配角色 2. 角色管理页：角色列表、权限矩阵、新增/编辑角色 ## 交付检查 - [ ] 路由归属：AAPI - [ ] 是否需要 Prisma migration：是 - [ ] 是否需要 MySQL：是 - [ ] 是否需要 Redis：是 - [ ] 是否需要 BullMQ：否 - [ ] 是否需要 Qdrant：否 - [ ] 是否需要 AI Gateway：否 - [ ] 是否需要 Content Safety：否 - [ ] 是否需要 Cost 记录：否 - [ ] 是否需要 AuditLog：是（Admin 用户增删改、角色变更、登录记录） - [ ] 是否需要 Domain Event：是 - [ ] 是否需要 Admin 视图：是 - [ ] 是否需要 E2E/集成测试：是 ## 验收标准 1. AdminUser / AdminRole / AdminPermission Prisma schema 2. Admin 登录流程设计（JWT + RefreshToken） 3. 角色-权限模型设计 4. AdminAuthGuard 实现（供所有 Admin 接口使用） 5. 登录安全策略设计（失败锁定、异常检测） 6. Admin 管理视图设计 7. 集成测试覆盖登录/权限校验/角色管理 ## 禁止事项 - 禁止 Admin 用户和 C 端用户混用同一张表 - 禁止 Admin Token 可以访问 C 端接口 - 禁止 C 端 Token 可以访问 Admin 接口 - 禁止密码明文存储 - 禁止 RefreshToken 明文存储 - 禁止 Admin 用户删除自己 - 禁止无权限的 Admin 用户看到越权数据 ## 不建议当前阶段实现 - 2FA 双因素认证 - SSO 单点登录 - OAuth 第三方登录（GitHub/Google 等） - 细粒度的字段级别权限 - 权限变更审批流程
wangdl added this to the M0：后端基础能力与架构规范闭环（P0） milestone 2026-05-22 21:00:16 +08:00
wangdl self-assigned this 2026-05-22 21:00:16 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone M0：后端基础能力与架构规范闭环（P0）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees wangdl
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#13
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?