mirror of
https://github.com/fastapiadmin/FastapiAdmin.git
synced 2026-09-20 20:39:55 +00:00
13 KiB
13 KiB
FastAPI Vue3 Admin 项目详细说明文档
FastAPI Vue3 Admin
现代化全栈中后台管理系统
基于 FastAPI + Vue3 + TypeScript + Element Plus 的企业级后台管理解决方案
📋 目录
📖 项目概述
FastAPI Vue3 Admin 是一套完全开源、高度模块化、技术先进的现代化快速开发平台。该项目采用前后端分离架构，融合了 Python 后端框架 FastAPI 和前端主流框架 Vue3，为企业级中后台系统开发提供了一站式解决方案。
🎯 设计理念
- 模块化设计：系统功能高度解耦，便于扩展和维护
- 开箱即用：提供完整的基础功能模块，快速启动项目开发
- 技术先进：采用最新的技术栈，保证项目的先进性和可维护性
- 开发友好：完善的中文文档和开发工具链，降低学习成本
- 企业级：满足企业级应用的性能、安全、稳定性要求
🌟 核心优势
- 全栈整合：前后端技术栈统一，开发效率高
- 高性能：异步框架 + Redis 缓存，响应速度快
- 安全可靠：JWT 认证 + RBAC 权限模型，安全性强
- 易于扩展：模块化架构，便于功能扩展
- 部署简单：支持 Docker 容器化部署
- 文档完善：提供详细的开发文档和 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. 克隆项目
git clone https://gitee.com/tao__tao/fastapi_vue3_admin.git
cd fastapi_vue3_admin
2. 后端启动
cd backend
pip install -r requirements.txt
python main.py run --env=dev
3. 前端启动
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 部署
# 一键部署
chmod +x deploy.sh
./deploy.sh
# 查看服务状态
docker-compose ps
# 查看日志
docker logs -f <容器名>
手动部署
-
数据库配置
- 创建MySQL数据库
- 配置Redis服务
-
后端部署
- 配置环境变量
- 安装Python依赖
- 运行数据库迁移
- 启动FastAPI服务
-
前端部署
- 构建前端项目
- 配置Nginx
- 部署静态文件
📚 API文档
接口规范
- 基础路径：
/api/v1 - 认证方式：Bearer Token (JWT)
- 数据格式：JSON
- 字符编码：UTF-8
响应格式
{
"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 许可证开源。