public/FastapiAdmin
1
0
Fork 0
mirror of https://github.com/fastapiadmin/FastapiAdmin.git synced 2026-09-20 20:39:55 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
5fa3a3a7591da42e639b4ffaa0089c9f969e83cd
FastapiAdmin/PROJECT_DOCUMENTATION.md
T

404 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# FastAPI Vue3 Admin 项目详细说明文档
<div align="center">
<h1>FastAPI Vue3 Admin</h1>
<h3>现代化全栈中后台管理系统</h3>
<p>基于 FastAPI + Vue3 + TypeScript + Element Plus 的企业级后台管理解决方案</p>
</div>
## 📋 目录
- [项目概述](#项目概述)
- [技术架构](#技术架构)
- [功能特性](#功能特性)
- [项目结构](#项目结构)
- [核心模块](#核心模块)
- [技术栈详解](#技术栈详解)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [部署指南](#部署指南)
- [API文档](#api文档)
- [开发规范](#开发规范)
## 📖 项目概述
**FastAPI Vue3 Admin** 是一套完全开源、高度模块化、技术先进的现代化快速开发平台。该项目采用前后端分离架构，融合了 Python 后端框架 FastAPI 和前端主流框架 Vue3，为企业级中后台系统开发提供了一站式解决方案。
### 🎯 设计理念
- **模块化设计**：系统功能高度解耦，便于扩展和维护
- **开箱即用**：提供完整的基础功能模块，快速启动项目开发
- **技术先进**：采用最新的技术栈，保证项目的先进性和可维护性
- **开发友好**：完善的中文文档和开发工具链，降低学习成本
- **企业级**：满足企业级应用的性能、安全、稳定性要求
### 🌟 核心优势
1. **全栈整合**：前后端技术栈统一，开发效率高
2. **高性能**：异步框架 + Redis 缓存，响应速度快
3. **安全可靠**：JWT 认证 + RBAC 权限模型，安全性强
4. **易于扩展**：模块化架构，便于功能扩展
5. **部署简单**：支持 Docker 容器化部署
6. **文档完善**：提供详细的开发文档和 API 文档
## 🏗️ 技术架构
### 整体架构图
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 前端应用层 │ │ 移动端应用 │ │ 管理后台 │
│ (Vue3 SPA) │ │ (UniApp H5) │ │ (Element Plus)│
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────────────────────┼─────────────────────────────────┐
│ API 网关层 │ │
│ (Nginx) │ │
└─────────────────────────────────┼─────────────────────────────────┘
│
┌─────────────────────────────────┼─────────────────────────────────┐
│ 应用服务层 │ │
│ (FastAPI) │ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 控制器层 │ │ 服务层 │ │ 数据访问层 │ │
│ │ Controller │ │ Service │ │ CRUD │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────┼─────────────────────────────────┘
│
┌─────────────────────────────────┼─────────────────────────────────┐
│ 数据存储层 │ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ MySQL │ │ Redis │ │ 文件存储 │ │
│ │ 主数据库 │ │ 缓存/会话 │ │ 静态资源 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### 前后端分离架构
- **前端**：Vue3 + TypeScript + Element Plus + Vite
- **后端**：FastAPI + SQLAlchemy + Pydantic + Alembic
- **数据库**：MySQL 8.0+ (主数据库) + Redis 7.0+ (缓存)
- **部署**：Docker + Nginx + Docker Compose
## ✨ 功能特性
### 🔐 认证授权
- JWT Token 认证机制
- OAuth2 标准实现
- 用户登录/登出
- 密码加密存储
- 会话管理
### 👥 用户管理
- 用户信息管理
- 用户状态控制
- 密码重置
- 个人资料编辑
- 头像上传
### 🛡️ 权限管理 (RBAC)
- 基于角色的访问控制
- 菜单权限控制
- 按钮权限控制
- 数据权限控制
- 角色分配管理
### 📊 系统监控
- 在线用户监控
- 服务器性能监控
- Redis 缓存监控
- 系统日志管理
- 操作日志记录
### ⚙️ 系统配置
- 系统参数配置
- 字典数据管理
- 公告通知管理
- 定时任务管理
- 代码生成器
### 🎨 界面特性
- 响应式布局设计
- 多主题切换
- 国际化支持
- 暗黑模式
- 全屏功能
- 面包屑导航
## 📁 项目结构
```
fastapi_vue3_admin/
├── backend/ # 后端工程
│ ├── app/ # 应用核心代码
│ │ ├── v1/ # API v1 版本
│ │ │ ├── controllers/ # 控制器层
│ │ │ ├── services/ # 业务逻辑层
│ │ │ ├── cruds/ # 数据访问层
│ │ │ ├── models/ # 数据模型
│ │ │ ├── schemas/ # 数据验证模式
│ │ │ ├── params/ # 请求参数模型
│ │ │ └── urls/ # 路由配置
│ │ ├── core/ # 核心配置
│ │ ├── middleware/ # 中间件
│ │ ├── utils/ # 工具函数
│ │ └── scripts/ # 初始化脚本
│ ├── env/ # 环境配置
│ ├── static/ # 静态文件
│ ├── sql/ # SQL 脚本
│ ├── main.py # 应用入口
│ └── requirements.txt # Python 依赖
├── frontend/ # 前端工程
│ ├── src/ # 源代码
│ │ ├── api/ # API 接口
│ │ ├── assets/ # 静态资源
│ │ ├── components/ # 公共组件
│ │ ├── layouts/ # 布局组件
│ │ ├── router/ # 路由配置
│ │ ├── store/ # 状态管理
│ │ ├── styles/ # 样式文件
│ │ ├── utils/ # 工具函数
│ │ ├── views/ # 页面组件
│ │ └── main.ts # 应用入口
│ ├── public/ # 公共资源
│ ├── package.json # 依赖配置
│ └── vite.config.ts # 构建配置
├── fastapp/ # 移动端工程 (UniApp)
├── fastdocs/ # 文档工程
├── devops/ # 部署配置
│ ├── nginx/ # Nginx 配置
│ ├── backend/ # 后端部署配置
│ └── redis/ # Redis 配置
├── docker-compose.yaml # Docker 编排文件
└── deploy.sh # 部署脚本
```
## 🧩 核心模块
### 仪表盘模块
- **工作台**：常用功能快捷入口，系统概览
- **分析页**：数据统计图表，业务指标展示
### 系统管理模块
- **用户管理**：用户信息CRUD，状态管理
- **角色管理**：角色权限分配，角色层级管理
- **菜单管理**：系统菜单配置，权限绑定
- **部门管理**：组织架构管理，部门层级
- **岗位管理**：职位信息管理
- **字典管理**：系统字典数据维护
- **配置管理**：系统参数配置
- **公告管理**：系统公告发布
- **日志管理**：操作日志记录查询
### 监控管理模块
- **在线用户**：当前在线用户监控
- **定时任务**：系统定时任务管理
- **服务器监控**：服务器性能指标监控
- **缓存监控**：Redis缓存状态监控
### 代码生成模块
- **代码生成器**：根据数据表自动生成CRUD代码
### 接口文档模块
- **Swagger文档**：自动生成的API文档
- **Redoc文档**：美化版API文档
## 💻 技术栈详解
### 前端技术栈
| 技术 | 版本 | 描述 |
|------|------|------|
| Vue3 | ^3.5.17 | 渐进式JavaScript框架 |
| TypeScript | ^5.8.3 | JavaScript的超集，提供类型支持 |
| Vite | ^6.3.5 | 新一代前端构建工具 |
| Element Plus | ^2.10.4 | Vue3组件库 |
| Vue Router | ^4.5.1 | Vue官方路由管理器 |
| Pinia | ^3.0.3 | Vue状态管理库 |
| Axios | ^1.10.0 | HTTP客户端 |
| ECharts | ^5.6.0 | 数据可视化图表库 |
| UnoCSS | 66.2.3 | 原子化CSS引擎 |
| Vue I18n | ^11.1.10 | 国际化插件 |
### 后端技术栈
| 技术 | 描述 |
|------|------|
| FastAPI | 现代、高性能的Python Web框架 |
| SQLAlchemy 2.0 | Python SQL工具包和ORM |
| Pydantic 2.0 | 数据验证和设置管理 |
| Alembic | 数据库迁移工具 |
| PyJWT | JWT令牌处理 |
| APScheduler | 定时任务调度器 |
| Redis | 内存数据库，用于缓存和会话 |
| MySQL | 关系型数据库 |
### 开发工具
| 工具 | 描述 |
|------|------|
| ESLint | JavaScript代码检查工具 |
| Prettier | 代码格式化工具 |
| Husky | Git hooks工具 |
| Commitizen | 规范化提交信息 |
| Docker | 容器化部署 |
| Nginx | Web服务器和反向代理 |
## 🔧 环境要求
### 开发环境
| 环境 | 版本要求 |
|------|----------|
| Node.js | >= 20.0 |
| Python | >= 3.10 |
| MySQL | >= 8.0 |
| Redis | >= 7.0 |
| pnpm | >= 8.1.0 |
### 生产环境
| 环境 | 版本要求 |
|------|----------|
| Docker | >= 20.0 |
| Docker Compose | >= 2.0 |
| Nginx | >= 1.20 |
## 🚀 快速开始
### 1. 克隆项目
```bash
git clone https://gitee.com/tao__tao/fastapi_vue3_admin.git
cd fastapi_vue3_admin
```
### 2. 后端启动
```bash
cd backend
pip install -r requirements.txt
python main.py run --env=dev
```
### 3. 前端启动
```bash
cd frontend
pnpm install
pnpm run dev
```
### 4. 访问系统
- 前端地址：http://localhost:5180/web
- 后端API：http://localhost:8000
- API文档：http://localhost:8000/docs
### 5. 默认账号
- 管理员：admin / 123456
- 演示账号：demo / 123456
## 📦 部署指南
### Docker 部署
```bash
# 一键部署
chmod +x deploy.sh
./deploy.sh
# 查看服务状态
docker-compose ps
# 查看日志
docker logs -f <容器名>
```
### 手动部署
1. **数据库配置**
- 创建MySQL数据库
- 配置Redis服务
2. **后端部署**
- 配置环境变量
- 安装Python依赖
- 运行数据库迁移
- 启动FastAPI服务
3. **前端部署**
- 构建前端项目
- 配置Nginx
- 部署静态文件
## 📚 API文档
### 接口规范
- 基础路径：`/api/v1`
- 认证方式：Bearer Token (JWT)
- 数据格式：JSON
- 字符编码：UTF-8
### 响应格式
```json
{
"code": 200,
"message": "success",
"data": {},
"timestamp": 1640995200
}
```
### 状态码说明
| 状态码 | 说明 |
|--------|------|
| 200 | 请求成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |
## 📝 开发规范
### 代码规范
- 使用ESLint + Prettier进行代码格式化
- 遵循Vue3 Composition API规范
- 使用TypeScript进行类型约束
- 组件命名采用PascalCase
- 文件命名采用kebab-case
### Git规范
- 使用Conventional Commits规范
- 分支命名：feature/功能名、bugfix/问题描述
- 提交信息：type(scope): description
### 目录规范
- 组件按功能模块组织
- 公共组件放在components目录
- 页面组件放在views目录
- 工具函数放在utils目录
---
## 📞 联系方式
- 项目地址：https://gitee.com/tao__tao/fastapi_vue3_admin
- 在线演示：https://service.fastapiadmin.com/web
- 问题反馈：https://gitee.com/tao__tao/fastapi_vue3_admin/issues
## 📄 许可证
本项目基于 [MIT](./LICENSE) 许可证开源。
Reference in New Issue View Git Blame Copy Permalink