添加了readme文件
This commit is contained in:
carry
parent
b5651448b4
commit
f3d70d064c
242
README.md
Normal file
242
README.md
Normal file
@ -0,0 +1,242 @@
|
||||
# 用户管理系统
|
||||
|
||||
## 项目概述
|
||||
|
||||
本项目是一个基于现代 Web 技术栈开发的用户管理系统，支持三种用户角色：**系统管理员**、**管理员** 和 **普通用户**。系统通过角色权限控制，实现对用户数据的安全管理和操作。
|
||||
|
||||
### 核心功能
|
||||
1. **用户管理**：
|
||||
- 系统管理员在项目启动时自动生成，且唯一。
|
||||
- 所有账户必须由管理员手动创建。
|
||||
- 用户表包含密码、ID、角色、描述等信息。
|
||||
- 管理员可以对用户表进行增删改查操作。
|
||||
- 普通用户仅能读取用户列表。
|
||||
|
||||
2. **权限控制**：
|
||||
- 基于角色的权限管理（RBAC），确保不同角色只能访问其权限范围内的功能。
|
||||
- 系统管理员和管理员可操作修改和删除按钮，普通用户仅能查看用户列表。
|
||||
|
||||
3. **安全认证**：
|
||||
- 使用 JWT（JSON Web Token）实现身份验证和权限控制。
|
||||
- Access Token 和 Refresh Token 的自动刷新机制，保障用户会话的安全性和连续性。
|
||||
- 密码使用 bcrypt 加密存储，确保数据安全。
|
||||
|
||||
4. **前后端分离架构**：
|
||||
- 前端采用 Vue.js 框架，结合 Vue Router、Pinia 和 Element Plus，提供响应式和交互性强的用户界面。
|
||||
- 后端基于 FastAPI 框架，提供 RESTful API 接口，与 MySQL 数据库交互，完成用户认证、权限管理和数据操作。
|
||||
|
||||
5. **容器化部署**：
|
||||
- 支持 Docker 容器化部署，简化开发和生产环境配置。
|
||||
- 包括前端、后端、数据库和 Nginx 反向代理服务，便于快速搭建和扩展。
|
||||
|
||||
### 技术亮点
|
||||
- **现代化技术栈**：涵盖前端、后端、数据库和安全认证等多个领域。
|
||||
- **完整的开发流程**：从数据库设计到 API 开发，从前端页面到生产部署，覆盖全生命周期。
|
||||
- **高可扩展性**：模块化设计，易于扩展新功能或集成第三方服务。
|
||||
|
||||
|
||||
## 技术栈
|
||||
|
||||
### 后端技术栈
|
||||
- FastAPI
|
||||
- SQLAlchemy
|
||||
- MySQL
|
||||
- bcrypt
|
||||
- PyJWT
|
||||
- logging
|
||||
|
||||
### 前端技术栈
|
||||
- Typescript
|
||||
- Vue.js
|
||||
- Vue Router
|
||||
- Pinia
|
||||
- Element Plus
|
||||
- Axios
|
||||
- Vite
|
||||
- npm
|
||||
- pinia-plugin-persistedstate
|
||||
- jwt-decode
|
||||
|
||||
## 数据库设计
|
||||
|
||||
### 用户表结构
|
||||
|
||||
| 字段名 | 数据类型 | 约束条件 | 默认值 | 说明 |
|
||||
| -------- | ---------- | ---------- | -------- | ---------------------------------------------------- |
|
||||
| `id` | `INT` | `PRIMARY KEY`, `AUTO_INCREMENT` | - | 用户ID，主键，自增 |
|
||||
| `username` | `VARCHAR(50)` | `NOT NULL`, `UNIQUE` | - | 用户名，唯一 |
|
||||
| `password` | `VARCHAR(255)` | `NOT NULL` | - | 用户密码，使用哈希加密存储 |
|
||||
| `role` | `ENUM` | `NOT NULL` | `UserRole.USER` | 用户角色，枚举类型，可选值为 `UserRole.SYSTEM_ADMIN`, `UserRole.ADMIN`, `UserRole.USER` |
|
||||
| `description` | `TEXT` | - | - | 用户描述，可选 |
|
||||
| `created_at` | `DATETIME` | - | `当前UTC时间` | 用户创建时间，默认值为当前UTC时间 |
|
||||
| `updated_at` | `DATETIME` | - | `当前UTC时间，更新时自动更新` | 用户信息更新时间，默认值为当前UTC时间，更新时自动更新 |
|
||||
|
||||
### 数据库初始化
|
||||
- 系统初始化时，后端控制层会检查表是否存在，若不存在则自动创建表。
|
||||
- 检查表中是否存在系统管理员，若不存在则创建一个名为`admin`、密码为`password`、描述为`default system admin`的系统管理员。
|
||||
|
||||
## 鉴权设计
|
||||
|
||||
### 角色权限
|
||||
- **系统管理员、管理员**：可以访问所有 API，包括用户增删改查。
|
||||
- **普通用户**：只能访问用户列表（只读）。
|
||||
|
||||
### JWT 鉴权
|
||||
JWT（JSON Web Token）用于用户身份验证和权限控制。JWT 包含以下信息：
|
||||
- **Payload**：用户 ID、用户名、角色、Token 过期时间、token_type等。
|
||||
- **签名**：使用后端密钥对 Payload 进行签名，确保 Token 的完整性和安全性。
|
||||
|
||||
### JWT Token 数据结构
|
||||
```python
|
||||
class TokenPayload:
|
||||
id: int # 用户ID
|
||||
username: str # 用户名
|
||||
role: str # 用户角色
|
||||
exp: int # Token过期时间
|
||||
token_type: str # Token类型（access或refresh）
|
||||
```
|
||||
|
||||
### JWT 自动过期机制
|
||||
- **Access Token**：用于常规 API 请求，有效期较短（如 30 分钟）。
|
||||
- **Refresh Token**：用于刷新 Access Token，有效期较长（如 7 天）。
|
||||
|
||||
#### Token 刷新流程
|
||||
1. 客户端使用 Refresh Token 请求 `/api/auth/refresh` 接口。
|
||||
2. 服务端验证 Refresh Token 的有效性。
|
||||
3. 服务端生成新的 Access Token 和 Refresh Token，并返回给客户端。
|
||||
4. 客户端更新本地存储的 Token。
|
||||
|
||||
### Token 验证
|
||||
- **verify_access_token**：验证access token有效性并返回payload，如果token无效或类型不匹配则返回None
|
||||
- **verify_refresh_token**：验证refresh token有效性并返回payload，如果token无效或类型不匹配则返回None
|
||||
|
||||
## 前端页面设计
|
||||
|
||||
### 1. 登录页面 (`loginPage`)
|
||||
#### UI 组件安排
|
||||
- 用户名输入框：使用 Element Plus 的 `el-input` 组件，用于输入用户名。
|
||||
- 密码输入框：使用 Element Plus 的 `el-input` 组件，类型为 `password`，用于输入密码。
|
||||
- 登录按钮：使用 Element Plus 的 `el-button` 组件，点击后触发登录逻辑。
|
||||
|
||||
#### 功能描述
|
||||
- 用户输入用户名和密码后，点击登录按钮，前端通过 Axios 发送登录请求到后端 `/api/auth/login` 接口。
|
||||
- 登录成功后，前端将获取到的 `access_token` 和 `refresh_token` 存储在 Pinia 状态管理中，并跳转到用户管理页面。
|
||||
- 登录失败时，前端显示错误提示。
|
||||
|
||||
### 2. 用户管理页面 (`managePage`)
|
||||
#### UI 组件安排
|
||||
- 导航栏：使用 Element Plus 的 `el-menu` 组件，显示欢迎信息和当前用户信息
|
||||
- 登出按钮：使用 Element Plus 的 `el-button` 组件，位于页面右上角，点击后触发登出逻辑。
|
||||
- 用户列表：使用 Element Plus 的 `el-table` 组件，展示用户信息，包括 `ID`、`用户名`、`角色`、`描述` 等字段。
|
||||
- 创建用户按钮：使用 Element Plus 的 `el-button` 组件，仅管理员可见，点击后弹出创建用户对话框。
|
||||
- 修改按钮：使用 Element Plus 的 `el-button` 组件，位于每一行的操作列中，点击后弹出修改对话框。
|
||||
- 删除按钮：使用 Element Plus 的 `el-button` 组件，位于每一行的操作列中，点击后触发删除逻辑。
|
||||
- 修改对话框：使用 Element Plus 的 `el-dialog` 组件，用于修改用户信息。
|
||||
|
||||
#### 功能描述
|
||||
- 用户列表展示：前端通过 Axios 发送请求到 `/api/users` 接口，获取用户列表数据，并在表格中展示。
|
||||
- 创建用户：管理员点击创建用户按钮后，弹出创建用户对话框，填写信息后提交。
|
||||
- 修改按钮的显示与隐藏：根据当前登录用户的角色，动态控制修改按钮的显示与隐藏。只有 `系统管理员` 和 `管理员` 可以看到并操作修改按钮。
|
||||
- 删除按钮的显示与隐藏：根据当前登录用户的角色，动态控制删除按钮的显示与隐藏。只有 `系统管理员` 和 `管理员` 可以看到并操作删除按钮。
|
||||
- 修改用户信息：点击修改按钮后，弹出修改对话框，用户可以在对话框中修改用户名、角色和描述信息。修改完成后，前端通过 Axios 发送请求到 `/api/users/{user_id}` 接口，更新用户信息。
|
||||
- 删除用户：点击删除按钮后，前端通过 Axios 发送请求到 `/api/users/{user_id}` 接口，删除对应用户。
|
||||
|
||||
## 权限控制
|
||||
|
||||
### 1. 修改和删除按钮的权限控制
|
||||
- 系统管理员、管理员：可以看到并操作所有用户的修改和删除按钮。
|
||||
- 普通用户：无法看到修改和删除按钮，只能查看用户列表。
|
||||
|
||||
#### 实现逻辑
|
||||
- 前端在用户登录成功后，从后端获取用户角色信息，并存储在 Pinia 状态管理中。
|
||||
- 在用户管理页面中，前端根据当前用户的角色动态渲染表格中的操作列。如果当前用户是 `普通用户`，则不渲染修改和删除按钮；如果是 `系统管理员` 或 `管理员`，则渲染这些按钮。
|
||||
|
||||
### 2. 路由权限控制
|
||||
- 登录页面：所有用户都可以访问。
|
||||
- 用户管理页面：只有登录成功的用户才能访问。如果用户未登录，尝试访问用户管理页面时，前端应自动跳转到登录页面。
|
||||
|
||||
#### 实现逻辑
|
||||
- 使用 Vue Router 的导航守卫（`beforeEach`）进行路由权限控制。在每次路由跳转前，检查 Pinia 中是否存储了有效的 `access_token`。如果没有，则跳转到登录页面。
|
||||
|
||||
## Token 管理
|
||||
|
||||
### 1. Access Token 和 Refresh Token 的存储
|
||||
- 登录成功后，前端将 `access_token` 和 `refresh_token` 存储在 Pinia 状态管理中，并设置 `access_token` 的过期时间。
|
||||
- 每次发送 API 请求时，前端从 Pinia 中获取 `access_token` 并添加到请求头中。
|
||||
- 使用 pinia-plugin-persistedstate 插件将 token 存储在 localStorage 中，实现状态持久化
|
||||
|
||||
### 2. Token 自动刷新
|
||||
- 前端在每次发送 API 请求前，检查 `access_token` 是否即将过期（例如，剩余有效期小于 5 分钟）。如果即将过期，前端使用 `refresh_token` 调用 `/api/auth/refresh` 接口，获取新的 `access_token` 和 `refresh_token`，并更新 Pinia 中的存储。
|
||||
- 使用 Axios 的拦截器统一处理 token 刷新逻辑，避免在每个请求中重复编写代码。
|
||||
|
||||
## 状态管理
|
||||
|
||||
### 用户登录状态
|
||||
- 使用 Pinia 存储用户登录状态，包括 `access_token`、`refresh_token`、用户角色、用户名、用户ID等信息。
|
||||
- 在用户登出时，清除 Pinia 中的登录状态。
|
||||
- 使用 pinia-plugin-persistedstate 插件进行状态持久化，在应用启动时自动从 localStorage 恢复状态
|
||||
|
||||
## 开发环境配置
|
||||
|
||||
### 后端
|
||||
1. 安装依赖：
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
2. 启动开发服务器：
|
||||
```bash
|
||||
uvicorn main:app --reload
|
||||
```
|
||||
|
||||
### 前端
|
||||
1. 安装依赖：
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
2. 启动开发服务器：
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
3. 构建生产环境：
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
## Docker 部署
|
||||
|
||||
### 1. 环境要求
|
||||
- Docker 20.10.0 或更高版本
|
||||
- Docker Compose 2.0.0 或更高版本
|
||||
|
||||
### 2. 部署步骤
|
||||
1. 确保已安装 Docker 和 Docker Compose
|
||||
2. 在项目根目录下运行以下命令：
|
||||
```bash
|
||||
docker-compose up --build
|
||||
```
|
||||
3. 应用启动后，可以通过以下地址访问：
|
||||
- 前端：http://localhost
|
||||
- 后端API：http://localhost/api
|
||||
4. 停止并移除容器：
|
||||
```bash
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
### 3. 服务说明
|
||||
- **frontend**: 前端服务，基于Vue.js构建
|
||||
- **backend**: 后端服务，基于FastAPI构建
|
||||
- **mysql**: MySQL数据库服务
|
||||
- **nginx**: Nginx反向代理服务
|
||||
|
||||
### 4. 环境变量配置
|
||||
所有环境变量配置在 `docker-compose.yml` 文件中，包括：
|
||||
- 数据库连接信息
|
||||
- JWT配置
|
||||
- 日志配置
|
||||
- 系统管理员初始配置
|
||||
|
||||
## 后续开发
|
||||
- **CI/CD 流程**：自动化构建和部署流程
|
||||
Loading…
x
Reference in New Issue
Block a user