FastAPI Web Admin

基于 FastAPI + Vue3 的现代化企业级后台管理系统

一个开箱即用的前后端分离管理平台，内置完整的 RBAC 权限系统和动态路由机制

🌈 项目介绍

FastAPI Web Admin 是一个面向企业级应用的现代化后台管理系统脚手架，采用前后端完全分离的架构设计。

核心特性：

🚀 开箱即用，快速搭建企业后台系统
🔐 完整的 RBAC 权限管理体系
🎯 动态路由注册，配置即可分配权限
🎨 支持主题切换和暗黑模式
📦 Docker 一键部署
⚡ 异步高性能架构
🛠️ 开发者友好，专注业务逻辑

📋 技术栈

环境要求

技术	版本	说明
Python	≤ 3.13	后端运行环境
Node.js	18.15.0	前端构建环境
MySQL	8.0.23	主数据库
Redis	6.0.9	缓存和任务队列

后端技术栈

技术	版本	用途
FastAPI	0.111.0	异步 Web 框架
SQLAlchemy	2.0.3	异步 ORM
Pydantic	2.7.3	数据验证
Alembic	1.13.1	数据库迁移
Celery	5.2.7	异步任务队列
Redis	5.0.4	缓存和消息队列
Loguru	0.6.0	日志系统
python-jose	3.3.0	JWT 认证

前端技术栈

技术	版本	用途
Vue	3.5.8	渐进式框架
Vite	5.4.8	构建工具
TypeScript	4.9.4	类型系统
Element Plus	2.7.4	UI 组件库
Pinia	2.0.28	状态管理
Vue Router	4.1.6	路由管理
Axios	1.2.1	HTTP 客户端
Monaco Editor	0.34.1	代码编辑器

🏗️ 系统架构

整体架构图

┌─────────────────────────────────────────────────────────────┐
│                         用户层                               │
│                    (浏览器 / 移动端)                         │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                      前端层 (Vue 3)                          │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  路由    │  │  状态    │  │  组件    │  │  指令    │   │
│  │ Router   │  │  Pinia   │  │ Element  │  │ 权限控制 │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP/HTTPS
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                   API 网关层 (FastAPI)                       │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  认证    │  │  限流    │  │  日志    │  │  异常    │   │
│  │ 中间件   │  │ 中间件   │  │ 中间件   │  │  处理    │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                    业务逻辑层 (Services)                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  用户    │  │  角色    │  │  菜单    │  │  权限    │   │
│  │ 服务     │  │ 服务     │  │ 服务     │  │  服务    │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │
                         ▼
┌─────────────────────────────────────────────────────────────┐
│                  数据访问层 (SQLAlchemy)                     │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Models  │  │ Schemas  │  │  会话    │  │  事务    │   │
│  │  定义    │  │  验证    │  │  管理    │  │  管理    │   │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘   │
└────────────────────────┬────────────────────────────────────┘
                         │
         ┌───────────────┴───────────────┬──────────────┐
         ▼                               ▼              ▼
┌──────────────────┐          ┌──────────────┐  ┌─────────────┐
│   MySQL 8.0      │          │  Redis 6.0   │  │   Celery    │
│   主数据库       │          │  缓存/队列   │  │  任务队列   │
└──────────────────┘          └──────────────┘  └─────────────┘

后端分层架构

backend/
├── app/
│   ├── apis/              # API 路由层 - 处理 HTTP 请求
│   │   ├── v1/            # API 版本控制
│   │   ├── deps.py        # 依赖注入
│   │   └── router.py      # 路由注册
│   │
│   ├── services/          # 业务逻辑层 - 核心业务处理
│   │   ├── user.py        # 用户服务
│   │   ├── role.py        # 角色服务
│   │   ├── menu.py        # 菜单服务
│   │   └── auth.py        # 认证服务
│   │
│   ├── models/            # 数据模型层 - ORM 模型定义
│   │   ├── user.py        # 用户模型
│   │   ├── role.py        # 角色模型
│   │   └── base.py        # 基础模型
│   │
│   ├── schemas/           # 数据验证层 - Pydantic 模型
│   │   ├── user.py        # 用户 Schema
│   │   ├── role.py        # 角色 Schema
│   │   └── response.py    # 响应 Schema
│   │
│   ├── db/                # 数据库配置
│   │   ├── session.py     # 会话管理
│   │   └── base.py        # 基础配置
│   │
│   ├── corelibs/          # 核心库
│   │   ├── redis.py       # Redis 连接池
│   │   ├── security.py    # 安全工具
│   │   └── logger.py      # 日志配置
│   │
│   ├── utils/             # 工具函数
│   │   ├── common.py      # 通用工具
│   │   └── validators.py  # 验证器
│   │
│   ├── exceptions/        # 异常处理
│   │   ├── handlers.py    # 异常处理器
│   │   └── errors.py      # 自定义异常
│   │
│   └── init/              # 初始化模块
│       └── init_data.py   # 初始数据
│
├── celery_worker/         # Celery 任务
│   ├── tasks/             # 任务定义
│   ├── scheduler/         # 定时任务
│   └── worker.py          # Worker 配置
│
├── tests/                 # 测试文件
│   ├── unit/              # 单元测试
│   └── integration/       # 集成测试
│
├── alembic/               # 数据库迁移
│   └── versions/          # 迁移版本
│
├── config.py              # 配置文件
├── main.py                # 应用入口
└── cli.py                 # CLI 工具

前端目录架构

frontend/src/
├── api/                   # API 接口封装
│   ├── user.ts            # 用户接口
│   ├── role.ts            # 角色接口
│   └── request.ts         # 请求封装
│
├── components/            # 公共组件
│   ├── Table/             # 表格组件
│   ├── Form/              # 表单组件
│   └── Dialog/            # 对话框组件
│
├── layout/                # 布局组件
│   ├── Header/            # 头部
│   ├── Sidebar/           # 侧边栏
│   └── Main/              # 主体
│
├── views/                 # 页面视图
│   ├── system/            # 系统管理
│   │   ├── user/          # 用户管理
│   │   ├── role/          # 角色管理
│   │   └── menu/          # 菜单管理
│   └── dashboard/         # 仪表盘
│
├── router/                # 路由配置
│   ├── index.ts           # 路由入口
│   ├── routes.ts          # 路由定义
│   └── guards.ts          # 路由守卫
│
├── stores/                # Pinia 状态管理
│   ├── user.ts            # 用户状态
│   ├── permission.ts      # 权限状态
│   └── app.ts             # 应用状态
│
├── directive/             # 自定义指令
│   └── permission.ts      # 权限指令 v-permission
│
├── utils/                 # 工具函数
│   ├── auth.ts            # 认证工具
│   ├── storage.ts         # 存储工具
│   └── validate.ts        # 验证工具
│
├── types/                 # TypeScript 类型
│   ├── user.d.ts          # 用户类型
│   └── api.d.ts           # API 类型
│
├── theme/                 # 主题配置
│   ├── light.scss         # 亮色主题
│   └── dark.scss          # 暗色主题
│
├── App.vue                # 根组件
└── main.ts                # 应用入口

✨ 核心特性

后端核心功能

1. 异步高性能架构

FastAPI 异步框架，支持高并发请求
SQLAlchemy 2.0 异步 ORM，提升数据库操作性能
Redis 异步连接池，优化缓存访问

2. 完善的中间件系统

认证中间件：JWT Token 验证
日志中间件：请求/响应日志记录，trace_id 追踪
限流中间件：API 访问频率控制
异常中间件：统一异常捕获和响应

3. 分层架构设计

APIs 层：处理 HTTP 请求，参数验证
Services 层：业务逻辑处理，事务管理
Models 层：数据模型定义，数据库映射
Schemas 层：数据验证，序列化/反序列化

4. 任务队列系统

Celery 异步任务处理
Celery Beat 定时任务调度
数据库持久化任务状态

5. 数据库管理

Alembic 数据库迁移
一键初始化脚本
自动生成迁移文件

前端核心功能

1. 动态路由系统

后端配置菜单，前端自动注册路由
支持多级嵌套路由
路由懒加载，优化首屏性能

2. 权限控制体系

路由级权限：根据角色动态生成菜单
按钮级权限：v-permission 指令控制
接口级权限：后端 API 权限验证

3. 主题系统

亮色/暗色主题切换
自定义主题配置
主题持久化存储

4. 状态管理

Pinia 状态管理
持久化插件支持
模块化状态设计

5. 开发体验

TypeScript 类型支持
Monaco Editor 代码编辑
热更新开发环境

🚀 快速开始

方式一：Docker 部署（推荐）

1. 克隆项目

git clone https://github.com/rebort-hub/fastapiwebadmin.git
cd fastapiwebadmin

2. 配置环境变量

# 复制环境变量文件
cp .env.example .env

# 编辑 .env 文件，配置数据库密码等信息

3. 启动服务

# 一键启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

4. 访问系统

前端地址：http://localhost
后端 API：http://localhost:8100
API 文档：http://localhost:8100/docs

默认账号：admin / admin123456

方式二：本地开发部署

后端部署

1. 环境准备

# 确保已安装 Python 3.13、MySQL 8.0、Redis 6.0
python --version
mysql --version
redis-server --version

2. 创建数据库

CREATE DATABASE fastapiwebadmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

3. 配置环境

cd backend

# 复制配置文件
cp .env.example .env

# 编辑 .env 文件，修改数据库连接信息
# MYSQL_DATABASE_URI=mysql+asyncmy://用户名:密码@localhost:3306/fastapiwebadmin
# REDIS_URI=redis://localhost:6379/4

4. 安装依赖

# 使用国内镜像源加速
pip install -r requirements -i https://mirrors.aliyun.com/pypi/simple

5. 初始化数据库

# 一键初始化（推荐）
python cli.py init-db

# 或手动使用 Alembic
alembic upgrade head
python cli.py init-data

6. 启动后端服务

# 开发模式
python main.py

# 生产模式
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8100

7. 启动 Celery（可选）

# Windows 启动 Worker（单线程）
celery -A celery_worker.worker.celery worker --pool=solo -l INFO

# Linux 启动 Worker（多线程）
celery -A celery_worker.worker.celery worker --loglevel=INFO -c 10 -P solo -n fastapiwebadmin-celery-worker

# 启动定时任务调度器
celery -A celery_worker.worker.celery beat -S celery_worker.scheduler.schedulers:DatabaseScheduler -l INFO

# 启动心跳监控
celery -A celery_worker.worker.celery beat -l INFO

前端部署

1. 环境准备

# 确保已安装 Node.js 18.15.0
node -v  # v18.15.0

2. 安装依赖管理工具

# 安装 cnpm（使用淘宝镜像）
npm install -g cnpm --registry=https://registry.npm.taobao.org

# 或安装 yarn
npm install -g yarn

3. 安装项目依赖

cd frontend

# 使用 cnpm
cnpm install

# 或使用 yarn
yarn install

4. 启动开发服务器

# 使用 cnpm
cnpm run dev

# 或使用 yarn
yarn dev

访问：http://localhost:5173

5. 生产构建

# 使用 cnpm
cnpm run build

# 或使用 yarn
yarn build

# 构建产物在 dist/ 目录

🗄️ 数据库管理

Alembic 迁移命令

# 初始化数据库（包含迁移和初始数据）
python cli.py init-db

# 生成迁移文件
alembic revision --autogenerate -m "描述信息"

# 执行迁移
alembic upgrade head

# 回滚迁移
alembic downgrade -1

# 查看迁移历史
alembic history

# 查看当前版本
alembic current

数据库脚本

如果需要手动导入数据库：

# 导入初始化脚本
mysql -u root -p fastapiwebadmin < backend/script/db_init.sql

📸 系统截图

登录页

首页

路由菜单管理

接口管理

个人中心

主题切换

🔧 开发指南

后端开发

添加新的 API 接口

在 app/models/ 创建数据模型
在 app/schemas/ 创建 Pydantic Schema
在 app/services/ 实现业务逻辑
在 app/apis/v1/ 创建路由处理器

示例：创建用户管理接口

# app/models/user.py
from app.db.base import Base
from sqlalchemy import Column, String, Integer

class User(Base):
    __tablename__ = "users"
    id = Column(Integer, primary_key=True)
    username = Column(String(50), unique=True)
    email = Column(String(100))

# app/schemas/user.py
from pydantic import BaseModel

class UserCreate(BaseModel):
    username: str
    email: str

class UserResponse(BaseModel):
    id: int
    username: str
    email: str

# app/services/user.py
from app.models.user import User
from app.schemas.user import UserCreate

class UserService:
    async def create_user(self, user_data: UserCreate):
        # 业务逻辑
        pass

# app/apis/v1/user.py
from fastapi import APIRouter, Depends
from app.services.user import UserService

router = APIRouter()

@router.post("/users", response_model=UserResponse)
async def create_user(user: UserCreate):
    service = UserService()
    return await service.create_user(user)

前端开发

添加新页面

在 src/views/ 创建页面组件
在 src/router/routes.ts 配置路由
在 src/api/ 创建接口调用
在后台菜单管理中配置菜单

示例：创建用户列表页面

// src/api/user.ts
import request from './request'

export const getUserList = (params: any) => {
  return request.get('/api/v1/users', { params })
}

// src/views/system/user/index.vue
<template>
  <div class="user-container">
    <el-table :data="userList">
      <el-table-column prop="username" label="用户名" />
      <el-table-column prop="email" label="邮箱" />
    </el-table>
  </div>
</template>

<script setup lang="ts">
import { ref, onMounted } from 'vue'
import { getUserList } from '@/api/user'

const userList = ref([])

onMounted(async () => {
  const res = await getUserList({})
  userList.value = res.data
})
</script>

// src/router/routes.ts
{
  path: '/system/user',
  name: 'SystemUser',
  component: () => import('@/views/system/user/index.vue'),
  meta: { title: '用户管理', permission: 'system:user:list' }
}

权限控制

<!-- 按钮级权限控制 -->
<el-button v-permission="'user:create'">新增用户</el-button>
<el-button v-permission="'user:edit'">编辑</el-button>
<el-button v-permission="'user:delete'">删除</el-button>

🧪 测试

后端测试

cd backend

# 运行所有测试
pytest

# 运行单个测试文件
pytest tests/test_user.py

# 生成覆盖率报告
pytest --cov=app --cov-report=html

# 查看覆盖率报告
open htmlcov/index.html

前端测试

cd frontend

# 运行单元测试
npm run test

# 运行 E2E 测试
npm run test:e2e

📦 部署

生产环境部署

使用 Docker Compose（推荐）

# 生产环境配置
docker-compose -f docker-compose.prod.yml up -d

# 查看日志
docker-compose logs -f backend

# 重启服务
docker-compose restart backend

手动部署

后端部署：

# 使用 Gunicorn + Uvicorn
gunicorn main:app \
  -w 4 \
  -k uvicorn.workers.UvicornWorker \
  -b 0.0.0.0:8100 \
  --access-logfile logs/access.log \
  --error-logfile logs/error.log

前端部署：

# 构建
npm run build

# 使用 Nginx 部署
# 将 dist/ 目录内容复制到 Nginx 静态目录
cp -r dist/* /usr/share/nginx/html/

Nginx 配置示例：

server {
    listen 80;
    server_name your-domain.com;

    # 前端静态文件
    location / {
        root /usr/share/nginx/html;
        try_files $uri $uri/ /index.html;
    }

    # 后端 API 代理
    location /api {
        proxy_pass http://localhost:8100;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

🛠️ 常见问题

后端问题

Q: 数据库连接失败？

A: 检查 .env 文件中的数据库配置，确保 MySQL 服务已启动。

Q: Redis 连接失败？

A: 确保 Redis 服务已启动，检查 REDIS_URI 配置。

Q: Celery 任务不执行？

A: 确保 Celery Worker 和 Beat 都已启动，检查 Redis 连接。

前端问题

Q: 启动报错 "Cannot find module"？

A: 删除 node_modules 和 package-lock.json，重新安装依赖。

Q: 接口请求 404？

A: 检查 src/config/ 中的 API 地址配置。

Q: 路由权限不生效？

A: 确保后台已配置菜单权限，并分配给对应角色。

🤝 贡献指南

欢迎贡献代码！请遵循以下步骤：

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
提交 Pull Request

代码规范

后端：

遵循 PEP 8 规范
使用类型注解
编写单元测试

前端：

遵循 Vue 3 风格指南
使用 TypeScript
组件命名使用 PascalCase

📄 开源协议

本项目采用 MIT 协议开源。

🔗 相关链接

GitHub: https://github.com/rebort-hub/fastapiwebadmin
FastAPI 文档: https://fastapi.tiangolo.com/
Vue 3 文档: https://vuejs.org/
Element Plus 文档: https://element-plus.org/

💬 交流群

微信群

QQ 群

欢迎加入交流群，一起学习进步！

💌 支持作者

如果这个项目对你有帮助，请在 GitHub 上给个 ⭐ Star 支持一下！

你的支持是我持续更新的动力 🚀

Made with ❤️ by Rebort

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
backend		backend
frontend		frontend
static/img		static/img
README.md		README.md
docker-compose.yml		docker-compose.yml

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

FastAPI Web Admin

🌈 项目介绍

📋 技术栈

环境要求

后端技术栈

前端技术栈

🏗️ 系统架构

整体架构图

后端分层架构

前端目录架构

✨ 核心特性

后端核心功能

1. 异步高性能架构

2. 完善的中间件系统

3. 分层架构设计

4. 任务队列系统

5. 数据库管理

前端核心功能

1. 动态路由系统

2. 权限控制体系

3. 主题系统

4. 状态管理

5. 开发体验

🚀 快速开始

方式一：Docker 部署（推荐）

1. 克隆项目

2. 配置环境变量

3. 启动服务

4. 访问系统

方式二：本地开发部署

后端部署

1. 环境准备

2. 创建数据库

3. 配置环境

4. 安装依赖

5. 初始化数据库

6. 启动后端服务

7. 启动 Celery（可选）

前端部署

1. 环境准备

2. 安装依赖管理工具

3. 安装项目依赖

4. 启动开发服务器

5. 生产构建

🗄️ 数据库管理

Alembic 迁移命令

数据库脚本

📸 系统截图

登录页

首页

路由菜单管理

接口管理

个人中心

主题切换

🔧 开发指南

后端开发

添加新的 API 接口

示例：创建用户管理接口

前端开发

添加新页面

示例：创建用户列表页面

权限控制

🧪 测试

后端测试

前端测试

📦 部署

生产环境部署

使用 Docker Compose（推荐）

手动部署

🛠️ 常见问题

后端问题

前端问题

🤝 贡献指南

代码规范

📄 开源协议