5分钟搭建企业级中后台:FastapiAdmin本地环境搭建与运行新手教程

原创2026-10-17 19:15:171,327 阅读
文章标签:后端前端认证鉴权代码生成AI 应用低代码

5分钟搭建企业级中后台:FastapiAdmin本地环境搭建与运行新手教程

FastapiAdmin 是一款完全开源、免费使用的快速开发平台,后端基于 FastAPI + SQLAlchemy,前端基于 Vue3 + TypeScript + Vite + Pinia + Element Plus,帮你在 5 分钟内搭建并跑通一个企业级中后台系统。本教程面向新手,手把手带你完成本地环境搭建与项目运行,从零到成功登录只需四步。

一、认识 FastapiAdmin:一套开箱即用的全栈中后台

在动手之前,先花 30 秒了解你将要搭建的是什么。FastapiAdmin 是一个"开箱即用"的中后台解决方案:用户、角色、菜单、部门、字典、日志等系统管理功能全部内置,还附带代码生成器、定时任务、AI 对话、文件存储等扩展模块,Web 端和移动端(H5/小程序)共用一套后端。

FastapiAdmin 开源快速开发平台官方介绍页

它的核心卖点可以用一句话概括:前端负责界面,后端负责业务,克隆仓库、配好数据库,几分钟就能看到一个完整的管理后台跑起来。

二、环境准备: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 的登录页:

FastapiAdmin 中后台系统登录页面效果

使用初始化自带的账号 admin / 123456 登录(角色选择"管理员"),即可进入系统。

六、看到成果:你的中后台已经跑起来了

登录成功后,首先映入眼帘的是内置的仪表盘工作台,统计数据、图表、待办事项一应俱全:

FastapiAdmin 本地运行后的仪表盘工作台

左侧菜单里还藏着不少开箱即用的功能,比如代码生成器——选中一张数据库表,就能一键生成前后端全套 CRUD 代码,是快速开发业务模块的利器:

FastapiAdmin 代码生成器选表生成前后端代码

除此之外,系统管理(用户/角色/菜单/部门/字典)、监控管理(在线用户/服务器/缓存)、日志管理、定时任务、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 分钟。

后续可以继续深入:

祝搭建顺利,欢迎在开源社区交流使用心得!

登录后查看全文
FastapiAdmin