如何10分钟跑通RuoYi-FastAPI:从克隆项目到登录后台的完整新手入门教程

原创2026-10-30 23:32:161,951 阅读
文章标签:后端前端认证鉴权单点登录代码生成任务调度插件系统移动开发企业应用

如何10分钟跑通RuoYi-FastAPI:从克隆项目到登录后台的完整新手入门教程

想快速上手 Python 后台开发框架?RuoYi-FastAPI 是一个基于 Vue/React + FastAPI 的前后端分离中后台管理框架(若依的 FastAPI 版本),内置用户、角色、菜单、定时任务、代码生成等 22 项常用功能,开箱即用。本文带你从克隆项目到成功登录后台,全程只需 10 分钟,无需任何框架经验也能跟着走。

RuoYi-FastAPI 前端登录页背景图

一、环境准备:先确认这 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 提示页:

RuoYi-FastAPI 前端 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 分钟,一个完整的中后台管理底座已经在你的电脑上运行了。接下来,试着用「代码生成」功能给自己建一张业务表吧。

登录后查看全文
RuoYi-FastAPI