5分钟搭建企业级中后台:FastapiAdmin本地环境搭建与运行新手教程
5分钟搭建企业级中后台:FastapiAdmin本地环境搭建与运行新手教程
FastapiAdmin 是一款完全开源、免费使用的快速开发平台,后端基于 FastAPI + SQLAlchemy,前端基于 Vue3 + TypeScript + Vite + Pinia + Element Plus,帮你在 5 分钟内搭建并跑通一个企业级中后台系统。本教程面向新手,手把手带你完成本地环境搭建与项目运行,从零到成功登录只需四步。
一、认识 FastapiAdmin:一套开箱即用的全栈中后台
在动手之前,先花 30 秒了解你将要搭建的是什么。FastapiAdmin 是一个"开箱即用"的中后台解决方案:用户、角色、菜单、部门、字典、日志等系统管理功能全部内置,还附带代码生成器、定时任务、AI 对话、文件存储等扩展模块,Web 端和移动端(H5/小程序)共用一套后端。
它的核心卖点可以用一句话概括:前端负责界面,后端负责业务,克隆仓库、配好数据库,几分钟就能看到一个完整的管理后台跑起来。
二、环境准备:4 个必备组件一次装好
开始搭建前,请确认你的电脑上已经安装好以下工具。这是本地运行 FastapiAdmin 的硬性要求:
| 组件 | 版本要求 | 用途 |
|---|---|---|
| Python | ≥ 3.12 | 后端运行环境 |
| uv | 最新版(推荐) | 后端依赖管理 |
| Node.js | ≥ 20.0 | 前端运行环境 |
| pnpm | ≥ 9.0 | 前端依赖管理 |
| MySQL | 8.0+(或 PostgreSQL 14+ / SQLite) | 业务数据库 |
| Redis | 6.x / 7.x | 缓存与会话 |
💡 小贴士:如果 Node.js 版本不符,可以用 nvm 快速切换:nvm install 20。数据库需要提前在 MySQL 中建一个空库(如 fastapiadmin),首次启动时后端会自动建表并写入基础数据。
三、第一步:克隆项目代码
打开终端,执行以下命令克隆仓库:
git clone https://gitcode.com/fastapiadmin/FastapiAdmin
克隆完成后,进入项目目录。整个工程是一个 Monorepo,目录结构非常清晰:
FastapiAdmin/
├─ backend/ # FastAPI 后端(Pydantic 2.0 + SQLAlchemy + Alembic)
├─ frontend/
│ ├─ web/ # Vue3 Web 前端(Element Plus + TypeScript)
│ ├─ app/ # UniApp 移动端(H5 + 小程序 + App)
│ └─ docs/ # VitePress 文档网站
├─ docker/ # Docker Compose 一键部署
└─ deploy.sh # 一键部署脚本
四、第二步:配置后端环境变量并启动服务
后端的环境配置采用 .env 文件管理,只需修改两个关键配置。
1. 复制示例配置文件
cd FastapiAdmin/backend
cp env/.env.example env/.env.dev
2. 编辑 env/.env.dev,重点填写这两处
- 数据库配置:
DATABASE_TYPE(mysql / postgres / sqlite)、DATABASE_HOST、DATABASE_PORT、DATABASE_USER、DATABASE_PASSWORD、DATABASE_NAME - Redis 配置:
REDIS_HOST、REDIS_PORT、REDIS_PASSWORD
完整配置项说明可参考 .env.example 中的逐项注释。开发阶段其他配置(端口、密钥等)保持默认即可。
3. 安装依赖并启动
cd backend
uv sync
uv run main.py run --env=dev
没有 uv 也没关系,可用传统方式:
python -m venv .venv && pip install -r requirements.txt && python main.py run --env=dev(详见 backend/README.md)。
看到服务启动成功(默认端口 8001)后,可以先在浏览器打开 http://127.0.0.1:8001/docs,能看到 Swagger 接口文档,说明后端已跑通 ✅。
五、第三步:启动前端并登录验证
另开一个终端,进入前端目录启动开发服务器:
cd FastapiAdmin/frontend/web
cp .env.development.example .env.development
pnpm install
pnpm run dev
其中 .env.development 里的 VITE_API_BASE_URL 默认指向 http://127.0.0.1:8001,正好对接刚才启动的后端,一般无需改动。
启动成功后,浏览器访问 http://127.0.0.1:5173,你会看到 FastapiAdmin 的登录页:
使用初始化自带的账号 admin / 123456 登录(角色选择"管理员"),即可进入系统。
六、看到成果:你的中后台已经跑起来了
登录成功后,首先映入眼帘的是内置的仪表盘工作台,统计数据、图表、待办事项一应俱全:
左侧菜单里还藏着不少开箱即用的功能,比如代码生成器——选中一张数据库表,就能一键生成前后端全套 CRUD 代码,是快速开发业务模块的利器:
除此之外,系统管理(用户/角色/菜单/部门/字典)、监控管理(在线用户/服务器/缓存)、日志管理、定时任务、AI 对话等模块都已就绪,可以直接在界面里体验。
七、常见问题速查表
搭建过程中如果遇到问题,先对照下表自查,90% 的情况都能解决:
| 问题现象 | 原因与解决 |
|---|---|
| 后端启动报数据库连接失败 | 空库还没创建,或 .env.dev 中连接信息填错;确认 MySQL 已启动且库名、账号、密码一致 |
| 前端页面打不开或接口报错 | 后端服务未启动,或 VITE_API_BASE_URL 指向的后端地址(默认 http://127.0.0.1:8001)不对 |
| 报 Node.js 版本不符 | 用 nvm 安装对应版本:nvm install 20 |
| 忘记执行数据库迁移表 | 不需要——后端首次启动会自动建表并初始化基础数据 |
uv sync 下载依赖慢 |
使用国内 PyPI 镜像源 |
八、写在最后
到这里,你已经完成了 FastapiAdmin 的本地环境搭建:克隆仓库 → 配置后端 .env.dev → 启动后端 → 启动前端 → 登录成功,整个过程熟练后真的只要 5 分钟。
后续可以继续深入:
- 修改 backend/app/config/setting.py 中的
ENABLED_MODULES,按需裁剪功能模块 - 参考 frontend/docs/src/guide/start.md 了解移动端与文档站的启动方式
- 使用 docker/ 目录下的 Compose 配置进行 Docker 一键部署
祝搭建顺利,欢迎在开源社区交流使用心得!



