新增项目文档
This commit is contained in:
eafonyang
@@ -0,0 +1,369 @@
|
||||
# 用户模型
|
||||
|
||||
<cite>
|
||||
**本文档引用的文件**
|
||||
- [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)
|
||||
</cite>
|
||||
|
||||
## 目录
|
||||
1. [简介](#简介)
|
||||
2. [项目结构](#项目结构)
|
||||
3. [核心组件](#核心组件)
|
||||
4. [架构概览](#架构概览)
|
||||
5. [详细组件分析](#详细组件分析)
|
||||
6. [依赖关系分析](#依赖关系分析)
|
||||
7. [性能考虑](#性能考虑)
|
||||
8. [故障排除指南](#故障排除指南)
|
||||
9. [结论](#结论)
|
||||
|
||||
## 简介
|
||||
|
||||
DashboardUser 模型是本系统用户身份管理的核心数据结构，负责存储和管理后台系统的用户账户信息。该模型实现了完整的用户认证和授权机制，包括密码加密、JWT 令牌管理、会话控制以及基于角色的权限管理。
|
||||
|
||||
系统采用基于角色的访问控制（RBAC）模型，支持超级管理员和普通用户的权限区分，确保了系统的安全性和可维护性。
|
||||
|
||||
## 项目结构
|
||||
|
||||
用户管理系统在前后端分离架构中分布如下：
|
||||
|
||||
```mermaid
|
||||
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.js:1-58](file://backend/src/models/DashboardUser.js#L1-L58)
|
||||
- [auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
|
||||
- [users.js:1-180](file://backend/src/routes/users.js#L1-L180)
|
||||
|
||||
**章节来源**
|
||||
- [DashboardUser.js:1-58](file://backend/src/models/DashboardUser.js#L1-L58)
|
||||
- [auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
|
||||
- [users.js:1-180](file://backend/src/routes/users.js#L1-L180)
|
||||
|
||||
## 核心组件
|
||||
|
||||
### 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 | 非空, 默认当前时间 | 更新时间 |
|
||||
|
||||
**章节来源**
|
||||
- [DashboardUser.js:4-54](file://backend/src/models/DashboardUser.js#L4-L54)
|
||||
|
||||
### 权限管理机制
|
||||
|
||||
系统实现了两级权限控制：
|
||||
- **超级管理员权限**：拥有系统所有功能的操作权限
|
||||
- **普通用户权限**：仅能进行基本的用户操作
|
||||
|
||||
权限验证通过中间件实现，确保只有具备相应权限的用户才能访问特定资源。
|
||||
|
||||
**章节来源**
|
||||
- [auth.js:28-33](file://backend/src/middleware/auth.js#L28-L33)
|
||||
- [users.js:12-13](file://backend/src/routes/users.js#L12-L13)
|
||||
|
||||
## 架构概览
|
||||
|
||||
用户认证和授权系统采用分层架构设计，确保了安全性、可扩展性和易维护性：
|
||||
|
||||
```mermaid
|
||||
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 : 返回资源数据
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [auth.js:24-64](file://backend/src/routes/auth.js#L24-L64)
|
||||
- [auth.js:1-112](file://backend/src/routes/auth.js#L1-L112)
|
||||
- [jwt.js:7-21](file://backend/src/utils/jwt.js#L7-L21)
|
||||
|
||||
## 详细组件分析
|
||||
|
||||
### 密码加密与验证
|
||||
|
||||
系统采用 PBKDF2 算法进行密码加密，确保密码存储的安全性：
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [password.js:10-34](file://backend/src/utils/password.js#L10-L34)
|
||||
|
||||
密码加密特性：
|
||||
- 使用 PBKDF2 算法，迭代次数为 310000
|
||||
- 随机生成 16 字节盐值
|
||||
- 输出十六进制格式的哈希值
|
||||
- 采用定时安全比较防止时序攻击
|
||||
|
||||
**章节来源**
|
||||
- [password.js:1-37](file://backend/src/utils/password.js#L1-L37)
|
||||
|
||||
### JWT 令牌管理
|
||||
|
||||
系统使用 JSON Web Token 进行无状态认证，令牌包含必要的用户信息：
|
||||
|
||||
```mermaid
|
||||
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.js:7-21](file://backend/src/utils/jwt.js#L7-L21)
|
||||
- [auth.js:3-26](file://backend/src/middleware/auth.js#L3-L26)
|
||||
|
||||
JWT 令牌配置：
|
||||
- 算法：HS256
|
||||
- 有效期：12 小时
|
||||
- 包含字段：用户ID、用户名、是否超级管理员、签发时间、过期时间
|
||||
|
||||
**章节来源**
|
||||
- [jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
|
||||
- [auth.js:1-36](file://backend/src/middleware/auth.js#L1-L36)
|
||||
|
||||
### 用户管理操作流程
|
||||
|
||||
系统提供了完整的用户生命周期管理：
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [users.js:63-98](file://backend/src/routes/users.js#L63-L98)
|
||||
- [users.js:100-147](file://backend/src/routes/users.js#L100-L147)
|
||||
- [users.js:149-177](file://backend/src/routes/users.js#L149-L177)
|
||||
|
||||
**章节来源**
|
||||
- [users.js:1-180](file://backend/src/routes/users.js#L1-L180)
|
||||
|
||||
### 前端认证集成
|
||||
|
||||
前端使用本地存储管理认证状态，实现了完整的用户会话管理：
|
||||
|
||||
```mermaid
|
||||
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 : 清除令牌和用户信息
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [auth.js:4-50](file://frontend/src/utils/auth.js#L4-L50)
|
||||
- [auth.js:1-24](file://frontend/src/api/auth.js#L1-L24)
|
||||
|
||||
**章节来源**
|
||||
- [auth.js:1-99](file://frontend/src/utils/auth.js#L1-L99)
|
||||
- [auth.js:1-24](file://frontend/src/api/auth.js#L1-L24)
|
||||
|
||||
## 依赖关系分析
|
||||
|
||||
用户系统各组件之间的依赖关系如下：
|
||||
|
||||
```mermaid
|
||||
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
|
||||
```
|
||||
|
||||
**图表来源**
|
||||
- [DashboardUser.js:1-2](file://backend/src/models/DashboardUser.js#L1-L2)
|
||||
- [auth.js:1](file://backend/src/middleware/auth.js#L1)
|
||||
- [password.js:1](file://backend/src/utils/password.js#L1)
|
||||
- [jwt.js:1](file://backend/src/utils/jwt.js#L1)
|
||||
|
||||
**章节来源**
|
||||
- [index.js:1-8](file://backend/src/models/index.js#L1-L8)
|
||||
|
||||
## 性能考虑
|
||||
|
||||
### 密码哈希性能
|
||||
|
||||
系统采用 PBKDF2 算法，迭代次数为 310000，提供了良好的安全性和性能平衡：
|
||||
|
||||
- **安全性**：高迭代次数有效防止暴力破解
|
||||
- **性能**：单次验证耗时约几十毫秒，对用户体验影响最小
|
||||
- **扩展性**：可根据硬件性能调整迭代次数
|
||||
|
||||
### 数据库优化
|
||||
|
||||
- **索引策略**：用户名字段建立唯一索引，提高查询效率
|
||||
- **查询优化**：用户列表查询支持分页和模糊搜索
|
||||
- **缓存策略**：JWT 令牌无状态存储，减少数据库压力
|
||||
|
||||
### 并发控制
|
||||
|
||||
- **事务管理**：关键操作使用数据库事务确保数据一致性
|
||||
- **并发限制**：超级管理员数量检查避免竞态条件
|
||||
- **锁机制**：用户状态变更时的原子性操作
|
||||
|
||||
## 故障排除指南
|
||||
|
||||
### 常见问题及解决方案
|
||||
|
||||
| 问题类型 | 症状 | 可能原因 | 解决方案 |
|
||||
|----------|------|----------|----------|
|
||||
| 登录失败 | 返回"用户名或密码错误" | 用户名不存在或密码错误 | 检查用户名大小写和密码长度 |
|
||||
| 权限不足 | 返回"需要超级管理员权限" | 当前用户权限不够 | 确认用户角色设置 |
|
||||
| 令牌过期 | 返回"登录已过期" | JWT 令牌超过12小时有效期 | 重新登录获取新令牌 |
|
||||
| 用户被禁用 | 返回"账号不存在或已禁用" | 用户状态为0 | 联系管理员启用账户 |
|
||||
| 密码修改失败 | 返回"原密码错误" | 旧密码验证失败 | 确认输入的旧密码正确 |
|
||||
|
||||
### 调试建议
|
||||
|
||||
1. **查看服务器日志**：关注认证相关的错误信息
|
||||
2. **检查环境变量**：确认 JWT_SECRET 和数据库连接配置
|
||||
3. **验证数据库连接**：确保 dashboard_user 表存在且可访问
|
||||
4. **测试密码加密**：使用系统提供的密码验证功能
|
||||
|
||||
**章节来源**
|
||||
- [auth.js:5-25](file://backend/src/middleware/auth.js#L5-L25)
|
||||
- [auth.js:38-46](file://backend/src/routes/auth.js#L38-L46)
|
||||
|
||||
## 结论
|
||||
|
||||
DashboardUser 模型及其相关组件构成了一个完整、安全、高效的用户身份管理系统。系统通过以下特点确保了良好的用户体验和安全性：
|
||||
|
||||
- **安全性**：采用 PBKDF2 密码加密和 JWT 令牌认证
|
||||
- **可扩展性**：基于 RBAC 的权限模型支持灵活的角色管理
|
||||
- **易用性**：前后端分离的架构提供了清晰的 API 接口
|
||||
- **可靠性**：完善的错误处理和日志记录机制
|
||||
|
||||
该系统为后续的功能扩展和维护奠定了坚实的基础，能够满足现代 Web 应用对用户管理的各种需求。
|
||||
Reference in New Issue
Block a user