开始使用 RuoYi-FastAPI
RuoYi-FastAPI 是一套前后端分离的管理系统开发框架。两个仓库使用相同的 FastAPI 后端、数据模型和权限体系，区别主要集中在 Web 管理端：一个使用 Vue 3，另一个使用 Vue 2。
本章帮助你完成三个决定：选择哪个仓库、准备哪些本地服务，以及先启动 Web 管理端、移动端还是完整全栈环境。
第一次使用
新项目优先选择 Vue 3。只有在团队已有大量 Vue 2、Element UI 或 Vuex 代码需要继续复用时，再选择 Vue 2。
项目组成
| 目录 | 作用 | 是否共用 |
|---|---|---|
ruoyi-fastapi-backend | FastAPI 接口、认证权限、数据访问、任务和插件运行时 | 是 |
ruoyi-fastapi-frontend | Web 管理端 | 否，分为 Vue 3 / Vue 2 |
ruoyi-fastapi-app | 基于 uni-app 的移动端 | 随仓库使用对应 Vue 版本 |
docker-compose.my.yml | MySQL 环境的容器化部署编排 | 基本一致 |
docker-compose.pg.yml | PostgreSQL 环境的容器化部署编排 | 基本一致 |
两个 Web 管理端都通过 /dev-api 访问本地后端，开发代理默认转发到 http://127.0.0.1:9099。
选择前端版本
Vue 3
Vue 3 管理端使用 Vue 3、Element Plus、Vite 和 Pinia，适合新项目、现代构建链以及需要持续演进的业务系统。精确依赖版本以仓库当前 package.json 为准。
Vue 2
Vue 2 管理端使用 Vue 2、Element UI、Vue CLI 和 Vuex，适合已有 Vue 2 组件资产或仍需延续旧构建链的项目。精确依赖版本以仓库当前 package.json 为准。
选择第一次启动目标
| 当前任务 | 推荐入口 | 完成标准 |
|---|---|---|
| 先运行 Web 管理端 | Vue 3 Web或Vue 2 Web | 登录后菜单、接口代理和权限正常 |
| 先运行 H5、微信小程序或 App | 移动端快速开始 | 目标设备能访问后端并完成登录 |
| 使用完整容器环境体验 | MySQL Compose或PostgreSQL Compose | 前端、后端、数据库和 Redis 同时可用 |
| 开始二次开发 | 第一个业务闭环 | 表、接口、权限、页面和最小测试闭环 |
第一次启动路径
按以下顺序进行，可以把环境问题和代码问题分开排查：
- 准备开发环境，确认 Python、Node.js、数据库、Redis 和端口可用。
- 初始化并启动共用后端，先让
ruoyi app doctor检查配置。 - 启动 Vue 3 管理端、Vue 2 管理端或对应移动端。
- 打开目标客户端，使用本地初始化账号登录。
- 验证菜单或页面导航、权限、接口地址和数据库读写是否正常。
- 按第一个业务闭环完成表、接口、权限、菜单和页面开发。
默认开发地址
| 服务 | 默认地址或端口 | 说明 |
|---|---|---|
| Web 管理端 | http://localhost:80 | 两个前端默认都使用 80 端口 |
| FastAPI 后端 | http://localhost:9099 | 前端代理的目标服务 |
| Swagger UI | http://localhost:9099/docs | .env.dev 未关闭 Swagger 时可用 |
| Redis | 127.0.0.1:6379 | 默认使用数据库编号 2 |
| MySQL | 127.0.0.1:3306 | 默认数据库名 ruoyi-fastapi |
本地账号
初始化 SQL 提供的默认管理账号为 admin，默认密码为 admin123。它只适合本地验证，部署前必须修改密码并替换 JWT 密钥。
共用能力与版本差异
认证、权限、组织机构、字典、参数、日志、文件、定时任务、数据库访问和插件生命周期由后端统一提供。前端文档只在组件写法、构建工具、状态管理和页面目录确实不同时拆分。
因此，阅读文档时可以根据页面标记判断适用范围：
- 公共能力：同时适用于 Vue 3 和 Vue 2。
- Vue 3：只适用于 Vue 3 管理端。
- Vue 2：只适用于 Vue 2 管理端。
- 版本对照：同一任务在两个前端中的差异。