如何10分钟跑通RuoYi-FastAPI:从克隆项目到登录后台的完整新手入门教程
如何10分钟跑通RuoYi-FastAPI:从克隆项目到登录后台的完整新手入门教程
想快速上手 Python 后台开发框架?RuoYi-FastAPI 是一个基于 Vue/React + FastAPI 的前后端分离中后台管理框架(若依的 FastAPI 版本),内置用户、角色、菜单、定时任务、代码生成等 22 项常用功能,开箱即用。本文带你从克隆项目到成功登录后台,全程只需 10 分钟,无需任何框架经验也能跟着走。
一、环境准备:先确认这 4 个条件
开始之前,请确保本机已安装以下环境(版本要求来自项目徽章,见 README.md):
| 依赖 | 最低版本 | 用途 |
|---|---|---|
| Python | ≥ 3.10 | 运行 FastAPI 后端 |
| Node.js | 22.22.2+ / 24.15.0+ | 运行前端工程 |
| MySQL | ≥ 5.7 | 主数据库 |
| Redis | ≥ 6.2 | 缓存与令牌存储 |
💡 小技巧:如果暂时不想手动装数据库和 Redis,可以直接用文章最后提到的 Docker Compose 一键部署,跳过所有本地环境准备。
二、克隆 RuoYi-FastAPI 仓库
打开终端,执行一条命令克隆项目(整个流程中唯一的完整命令):
git clone https://gitcode.com/insistence2022/RuoYi-FastAPI.git
cd RuoYi-FastAPI
项目结构很清晰,记住三个目录就够用了:
ruoyi-fastapi-backend/:共用的 FastAPI 后端ruoyi-fastapi-frontend/:前端工程,含vue2、vue3、react三套 Web + 移动端ruoyi-fastapi-test/:端到端测试
下文我们以 Vue3 Web 前端 为主线演示。
三、后端快速启动:改配置、导库、3 步跑起来
1. 安装 Python 依赖
进入后端目录安装依赖(MySQL 用户):
cd ruoyi-fastapi-backend
pip3 install -r requirements.txt
如果使用 PostgreSQL 数据库,则安装 requirements-pg.txt 中的依赖。另外,只有需要 AI 插件时才执行 ruoyi plugin install-deps ai,新手可以跳过这一步。
2. 配置数据库与 Redis
打开 .env.dev 文件,只需核对/修改三处:
# MySQL 连接(把用户名密码改成你本机的)
"db_username": "root"
"db_password": "mysqlroot"
"db_database": "ruoyi-fastapi"
# Redis 连接
REDIS_HOST = '127.0.0.1'
REDIS_PORT = 6379
3. 导入初始化 SQL
先在 MySQL 中新建数据库 ruoyi-fastapi(库名可自定义,与上面配置一致即可),然后导入初始化脚本 ruoyi-fastapi.sql——里面包含全部表结构和默认账号数据,用 Navicat、DBeaver 等工具右键执行即可。
4. 启动后端服务
项目自带统一 CLI 入口(说明文档见 cli_usage.md),运行:
ruoyi app run --env=dev
看到服务监听 9099 端口即表示后端启动成功。
四、前端一键启动:pnpm 3 条命令
另开一个终端,进入 Vue3 Web 工程并安装依赖:
cd ruoyi-fastapi-frontend/vue3/web
npm install -g pnpm@11.28.6
pnpm install
⚠️ 国内网络下载慢时,推荐使用镜像源:
pnpm install --registry=https://registry.npmmirror.com
然后启动开发服务:
pnpm run dev
前端默认使用 80 端口,并把 /dev-api 请求代理到后端 9099(代理配置见 vite.config.js),前后端无需任何手动联通操作。
五、登录后台:输入 admin 完成跑通
浏览器访问 http://localhost:80,你会看到 RuoYi-FastAPI 的登录页,输入默认账号密码:
- 账号:
admin - 密码:
admin123
登录成功后即可看到工作台、用户管理、菜单管理、定时任务、代码生成等完整菜单。🎉 恭喜,你已经跑通了 RuoYi-FastAPI!
六、新手常见问题速查
| 问题 | 原因与解决 |
|---|---|
| 浏览器打开空白或 404 | 确认前端已 pnpm run dev,且访问的是 80 端口 |
| 后端启动报数据库连接失败 | 核对 .env.dev 中 MySQL 账号密码;确认已执行初始化 SQL |
pnpm install 很慢 |
使用 npmmirror 镜像源重新安装 |
| 80 端口被占用 | 修改 vite 配置中的 port,同时保持前端代理指向 9099 |
访问不存在的页面时,前端会展示友好的 404 提示页:
七、进阶选项:Docker Compose 一键部署
如果不想手动装 Python 环境和数据库,仓库根目录提供了完整的 Compose 编排(docker-compose.my.yml 为 MySQL 版,docker-compose.pg.yml 为 PostgreSQL 版),一条命令拉起全部服务:
docker compose --env-file docker.env -f docker-compose.my.yml up -d --build
通过 docker.env 中的 FRONTEND_FRAMEWORK=vue3 可切换构建的 Web 前端框架。注意默认未做数据持久化配置,演示环境建议自行配置卷挂载。
八、跑通之后,下一步玩什么?
- 代码生成:配置数据库表,一键生成前后端代码(Python、SQL、Vue、JS、React),这是若依系列的招牌能力
- 插件系统:支持插件安装、启停、升级,AI 管理功能就是一个示例插件
- 统一认证中心:基于 OAuth 2.0 / OIDC 的 SSO 能力,接入文档见 unified_authentication_developer_guide.md
- 切换前端框架:同一后端可同时驱动 Vue2、Vue3、React 三套 Web 工程,按需选择即可
10 分钟,一个完整的中后台管理底座已经在你的电脑上运行了。接下来,试着用「代码生成」功能给自己建一张业务表吧。

