audio/dashboard
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cacee5f294a215a7b3f0feff568df5431d8ac8b4
dashboard/.qoder/repowiki/zh/content/数据库设计/用户模型.md
T
eafonyang 08da279275 新增项目文档
2026-06-30 14:46:52 +08:00

12 KiB
Raw Blame History

用户模型

**本文档引用的文件** - [DashboardUser.js](file://backend/src/models/DashboardUser.js) - [auth.js](file://backend/src/middleware/auth.js) - [password.js](file://backend/src/utils/password.js) - [jwt.js](file://backend/src/utils/jwt.js) - [users.js](file://backend/src/routes/users.js) - [auth.js](file://backend/src/routes/auth.js) - [response.js](file://backend/src/utils/response.js) - [index.js](file://backend/src/models/index.js) - [userBootstrap.js](file://backend/src/services/userBootstrap.js) - [auth.js](file://frontend/src/utils/auth.js) - [auth.js](file://frontend/src/api/auth.js)

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构概览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排除指南
  9. 结论

简介

DashboardUser 模型是本系统用户身份管理的核心数据结构，负责存储和管理后台系统的用户账户信息。该模型实现了完整的用户认证和授权机制，包括密码加密、JWT 令牌管理、会话控制以及基于角色的权限管理。

系统采用基于角色的访问控制（RBAC）模型，支持超级管理员和普通用户的权限区分，确保了系统的安全性和可维护性。

项目结构

用户管理系统在前后端分离架构中分布如下：

graph TB
subgraph "后端架构"
A[DashboardUser 模型] --> B[认证中间件]
B --> C[用户管理路由]
B --> D[认证路由]
E[密码工具] --> A
F[JWT 工具] --> B
G[响应格式化] --> C
G --> D
end
subgraph "前端架构"
H[认证工具] --> I[请求封装]
I --> J[登录接口]
K[用户信息存储] --> H
end
subgraph "数据库层"
L[(MySQL 数据库)]
M[dashboard_user 表]
end
A --> L
L --> M

图表来源

章节来源

核心组件

DashboardUser 模型定义

DashboardUser 模型使用 Sequelize ORM 定义，包含以下核心字段：

字段名 类型 约束 描述
id INTEGER 主键, 自增 用户唯一标识符
username STRING(64) 非空, 唯一 登录用户名
password_hash STRING(255) 非空 密码哈希值
is_super_admin TINYINT 非空, 默认0 是否为超级管理员
status TINYINT 非空, 默认1 用户状态（1=启用, 0=禁用）
last_login_at DATE 可空 最近登录时间
create_at DATE 非空, 默认当前时间 创建时间
update_at DATE 非空, 默认当前时间 更新时间

章节来源

权限管理机制

系统实现了两级权限控制：

  • 超级管理员权限：拥有系统所有功能的操作权限
  • 普通用户权限：仅能进行基本的用户操作

权限验证通过中间件实现，确保只有具备相应权限的用户才能访问特定资源。

章节来源

架构概览

用户认证和授权系统采用分层架构设计，确保了安全性、可扩展性和易维护性：

sequenceDiagram
participant Client as 客户端应用
participant AuthRoute as 认证路由
participant UserModel as 用户模型
participant PasswordUtil as 密码工具
participant JWTUtil as JWT工具
participant UserRoute as 用户管理路由
Client->>AuthRoute : POST /api/auth/login
AuthRoute->>UserModel : 查询用户信息
UserModel-->>AuthRoute : 返回用户记录
AuthRoute->>PasswordUtil : 验证密码
PasswordUtil-->>AuthRoute : 返回验证结果
AuthRoute->>UserModel : 更新最后登录时间
AuthRoute->>JWTUtil : 创建访问令牌
JWTUtil-->>AuthRoute : 返回JWT令牌
AuthRoute-->>Client : 返回认证响应
Client->>UserRoute : 访问受保护资源
UserRoute->>JWTUtil : 解析JWT令牌
JWTUtil-->>UserRoute : 返回用户信息
UserRoute->>UserRoute : 验证权限级别
UserRoute-->>Client : 返回资源数据

图表来源

详细组件分析

密码加密与验证

系统采用 PBKDF2 算法进行密码加密，确保密码存储的安全性：

flowchart TD
Start([开始密码处理]) --> Hash["生成随机盐值<br/>PBKDF2 加密"]
Hash --> Store["存储格式：<br/>pbkdf2:算法:迭代次数:盐值:哈希值"]
Store --> Verify["验证流程：<br/>解析存储格式<br/>提取参数<br/>重新计算哈希值<br/>安全比较"]
Verify --> Result{"验证结果"}
Result --> |匹配| Success["验证通过"]
Result --> |不匹配| Fail["验证失败"]
Success --> End([结束])
Fail --> End

图表来源

密码加密特性：

  • 使用 PBKDF2 算法，迭代次数为 310000
  • 随机生成 16 字节盐值
  • 输出十六进制格式的哈希值
  • 采用定时安全比较防止时序攻击

章节来源

JWT 令牌管理

系统使用 JSON Web Token 进行无状态认证，令牌包含必要的用户信息：

classDiagram
class AccessToken {
+sub : number
+username : string
+is_super_admin : boolean
+iat : number
+exp : number
+createAccessToken(user) : string
+decodeToken(token) : object
+getTokenTtlSeconds() : number
}
class User {
+id : number
+username : string
+is_super_admin : boolean
+status : number
}
class AuthMiddleware {
+authMiddleware(req, res, next)
+requireSuperAdmin(req, res, next)
}
AccessToken --> User : "包含用户信息"
AuthMiddleware --> AccessToken : "验证令牌"
AuthMiddleware --> User : "设置用户上下文"

图表来源

JWT 令牌配置：

  • 算法：HS256
  • 有效期：12 小时
  • 包含字段：用户ID、用户名、是否超级管理员、签发时间、过期时间

章节来源

用户管理操作流程

系统提供了完整的用户生命周期管理：

flowchart TD
subgraph "用户管理流程"
A[创建用户] --> B[输入验证]
B --> C{用户名唯一性检查}
C --> |已存在| D[返回错误]
C --> |不存在| E[密码加密]
E --> F[创建用户记录]
F --> G[记录创建日志]
H[更新用户] --> I[权限验证]
I --> J[状态变更检查]
J --> K{超级管理员数量检查}
K --> |最后一个超级管理员| L[阻止操作]
K --> |正常| M[更新用户信息]
N[删除用户] --> O[权限验证]
O --> P{目标用户检查}
P --> |自己| Q[阻止删除]
P --> |其他用户| R{超级管理员检查}
R --> |最后一个超级管理员| S[阻止删除]
R --> |正常| T[删除用户]
end

图表来源

章节来源

前端认证集成

前端使用本地存储管理认证状态，实现了完整的用户会话管理：

sequenceDiagram
participant UI as 用户界面
participant AuthUtil as 认证工具
participant LocalStorage as 本地存储
participant API as 后端API
UI->>AuthUtil : 登录操作
AuthUtil->>API : 发送登录请求
API-->>AuthUtil : 返回JWT令牌
AuthUtil->>LocalStorage : 存储令牌
AuthUtil->>LocalStorage : 存储用户信息
UI->>AuthUtil : 获取用户信息
AuthUtil->>LocalStorage : 读取令牌
AuthUtil->>AuthUtil : 解析JWT载荷
AuthUtil-->>UI : 返回用户信息
UI->>AuthUtil : 退出登录
AuthUtil->>LocalStorage : 清除令牌和用户信息

图表来源

章节来源

依赖关系分析

用户系统各组件之间的依赖关系如下：

graph TD
subgraph "核心依赖"
A[DashboardUser 模型] --> B[Sequelize ORM]
C[认证中间件] --> D[JWT 工具]
C --> E[用户模型]
F[用户管理路由] --> G[密码工具]
F --> H[响应格式化]
I[认证路由] --> J[密码工具]
I --> K[JWT 工具]
end
subgraph "外部依赖"
L[jsonwebtoken] --> D
M[bcrypt] --> G
N[mysql2] --> B
O[sequelize] --> B
end
subgraph "前端依赖"
P[localStorage API] --> Q[认证工具]
R[fetch API] --> S[请求封装]
S --> I
end

图表来源

章节来源

性能考虑

密码哈希性能

系统采用 PBKDF2 算法，迭代次数为 310000，提供了良好的安全性和性能平衡：

  • 安全性：高迭代次数有效防止暴力破解
  • 性能：单次验证耗时约几十毫秒，对用户体验影响最小
  • 扩展性：可根据硬件性能调整迭代次数

数据库优化

  • 索引策略：用户名字段建立唯一索引，提高查询效率
  • 查询优化：用户列表查询支持分页和模糊搜索
  • 缓存策略：JWT 令牌无状态存储，减少数据库压力

并发控制

  • 事务管理：关键操作使用数据库事务确保数据一致性
  • 并发限制：超级管理员数量检查避免竞态条件
  • 锁机制：用户状态变更时的原子性操作

故障排除指南

常见问题及解决方案

问题类型 症状 可能原因 解决方案
登录失败 返回"用户名或密码错误" 用户名不存在或密码错误 检查用户名大小写和密码长度
权限不足 返回"需要超级管理员权限" 当前用户权限不够 确认用户角色设置
令牌过期 返回"登录已过期" JWT 令牌超过12小时有效期 重新登录获取新令牌
用户被禁用 返回"账号不存在或已禁用" 用户状态为0 联系管理员启用账户
密码修改失败 返回"原密码错误" 旧密码验证失败 确认输入的旧密码正确

调试建议

  1. 查看服务器日志：关注认证相关的错误信息
  2. 检查环境变量：确认 JWT_SECRET 和数据库连接配置
  3. 验证数据库连接：确保 dashboard_user 表存在且可访问
  4. 测试密码加密：使用系统提供的密码验证功能

章节来源

结论

DashboardUser 模型及其相关组件构成了一个完整、安全、高效的用户身份管理系统。系统通过以下特点确保了良好的用户体验和安全性：

  • 安全性：采用 PBKDF2 密码加密和 JWT 令牌认证
  • 可扩展性：基于 RBAC 的权限模型支持灵活的角色管理
  • 易用性：前后端分离的架构提供了清晰的 API 接口
  • 可靠性：完善的错误处理和日志记录机制

该系统为后续的功能扩展和维护奠定了坚实的基础，能够满足现代 Web 应用对用户管理的各种需求。

Reference in New Issue View Git Blame Copy Permalink