# FastAPI Vue3 Admin 项目详细说明文档

FastAPI Vue3 Admin

现代化全栈中后台管理系统

基于 FastAPI + Vue3 + TypeScript + Element Plus 的企业级后台管理解决方案

## 📋 目录 - [项目概述](#项目概述) - [技术架构](#技术架构) - [功能特性](#功能特性) - [项目结构](#项目结构) - [核心模块](#核心模块) - [技术栈详解](#技术栈详解) - [环境要求](#环境要求) - [快速开始](#快速开始) - [部署指南](#部署指南) - [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) 许可证开源。