第二章. 用法入门：本地环境搭建与项目启动

本章学习路径

我们将严格按照生产环境的准备步骤，分阶段完成项目启动：

2.1. 必备环境与源码获取

在上一章中，我们已经从理论上全面分析了 RuoYi-Vue-Plus 5.x 在架构设计、技术选型和功能完备性上的巨大优势。但“纸上得来终觉浅”，要想真正驾驭这套框架，我们必须在本地亲手将它运行起来。本节我们将完成实战的第一步：明确环境需求，并从官方仓库获取最新的前后端源码。

2.1.1. 官方文档导览

在开始任何操作之前，我们首先要学会查阅官方文档，它是我们学习过程中最权威、最及时的“老师”。

打开文档后，我们会看到 RVP (集群版) 和 RVC (微服务版) 的入口。本课程我们聚焦于 RuoYi-Vue-Plus（集群版）。在文档站点的“框架介绍”中，我们可以找到所有相关的源码仓库地址；在“快速开始” -> “项目初始化”中，则详细列出了项目运行所需的必备环境。

2.1.2. 核心技术栈与环境清单

RVP 5.x 是基于 Spring Boot 3.x 构建的，这对我们的本地开发环境提出了明确要求。在开始前，请确保您的电脑中安装了以下核心软件：

• Java Development Kit (JDK)：必须使用 JDK 17 或 JDK 21。（禁止 使用 Oracle JDK，推荐使用 OpenJDK 或 GraalVM Community JDK）。
• Maven：推荐 3.6 或更高版本。
• 数据库 (Database)：推荐 MySQL 8.0（最低 5.7）。
• 缓存 (Cache)：Redis（任意稳定版本）。
• 对象存储 (OSS)：Minio（推荐，后续章节使用）。
• Node.js：Node.js 18 或更高版本。（注意：plus-ui 前端项目要求 Node.js 18+，16 或更低版本在安装依赖时可能会失败）。
• IDE：IntelliJ IDEA 2022.x 或更高版本（注意：官方文档不推荐 2023 版，因其 Bug 较多）。

2.1.3. 克隆后端仓库（RuoYi-Vue-Plus）

RVP 5.x 采用了前后端分离的开发模式，其后端代码托管在 Dromara 组织的 Gitee 仓库中。

我们打开本地终端（例如 Git Bash），进入您存放代码的目录，执行 git clone 命令下载后端代码：

1
2

# 1. 克隆后端仓库
git clone https://gitee.com/dromara/RuoYi-Vue-Plus.git

2.1.4. 克隆前端仓库（plus-ui）

RVP 5.x 的统一前端 plus-ui 托管在另一个 Gitee 仓库中，它同时适配集群版和微服务版。

我们在 相同 的目录下，执行 git clone 命令下载前端代码：

1
2

# 2. 克隆前端仓库
git clone https://gitee.com/JavaLionLi/plus-ui.git

下载完成后，您的代码目录结构应如下所示：

1
2
3

课程代码/
├── RuoYi-Vue-Plus/   # 后端项目
└── plus-ui/          # 前端项目

2.1.5. 切换 dev 开发分支

这是一个非常关键的步骤。默认情况下，我们 clone 下来的可能是 5.x（稳定版）或 ts（前端）分支。为了跟上最新的功能迭代和课程进度，我们 必须 将前后端项目统一切换到 dev (开发) 分支。

1
2
3
4
5
6
7

# 3. 切换后端到 dev 分支
cd RuoYi-Vue-Plus
git checkout dev

# 4. 切换前端到 dev 分支
cd ../plus-ui
git checkout dev

2.1.6 本节小结

我们完成了项目实战的第一步：

• 明确了 RVP 5.x 必需的核心环境（JDK 17+, Node.js 18+, MySQL 8, Redis）。
• 从 Gitee 官方仓库分别克隆了后端 RuoYi-Vue-Plus 和前端 plus-ui 的代码。
• （关键操作） 将前后端项目统一切换到了 dev 开发分支。

2.2. 后端项目配置

在上一节中，我们已经成功将 RuoYi-Vue-Plus（后端）和 plus-ui（前端）的 dev 分支代码克隆到了本地。现在，我们的“原材料”已经备齐，接下来需要对“加工厂”（IDEA）和“配方”（配置文件）进行精细调整，以确保后端服务能够顺利启动。本节我们将完成后端项目的 JDK 版本统一、Maven 环境激活以及核心 yml 文件的配置。

2.2.1. 在 IDEA 中配置 JDK 17/21

首先，我们使用 IntelliJ IDEA 打开刚刚下载的 RuoYi-Vue-Plus 后端项目目录。

1. 统一 pom.xml 的 JDK 版本

RVP 5.x 必须使用 JDK 17 或 21。我们需要确保项目的 pom.xml 文件中声明的 Java 版本与我们环境中安装的版本一致。

打开项目根目录下的 pom.xml 文件：

1
2
3
4
5
6
7
8
9
10
11
12

<!-- 文件路径: RuoYi-Vue-Plus/pom.xml -->

<properties>
    <!-- 
      确保这里的版本号与你希望使用的 JDK 版本一致。
      如果你安装的是 JDK 17，就保持 17。
      如果你希望使用 JDK 21，就改为 21。
      本课程我们统一使用 17。
    -->
    <java.version>17</java.version> 
    <!-- ... 其他属性 ... -->
</properties>

修改完毕后，IDEA 会提示 Maven 项目需要刷新。点击右上角的 Maven 图标（或弹出的提示）Reload All Maven Projects，让 IDEA 重新加载依赖。

2. 统一 IDEA 项目结构 (Project Structure) 的 JDK 版本

仅仅修改 pom.xml 是不够的，我们还必须告诉 IDEA 本身使用哪个 JDK 来编译这个项目。

1. 点击菜单栏 File -> Project Structure...（快捷键 Ctrl+Alt+Shift+S）。
2. 在弹出的窗口中，选择 Project 选项卡。
3. 确保 SDK 下拉框中选择的是 17 (Corretto, OpenJDK, or others) 版本。
4. 确保 Language level（语言级别）也设置为 17。

2.2.2. 激活 Maven dev Profile

RVP 5.x 为不同环境（开发、生产）提供了不同的配置文件（application-dev.yml, application-prod.yml）。我们需要告诉 Maven 我们当前处于开发环境，应该激活 dev 配置。

1. 点击 IDEA 右侧的 Maven 侧边栏。
2. 展开 Profiles（环境配置）选项。
3. 确保只有 dev 选项被 勾选。

这个操作会告诉 Spring Boot 在启动时去加载 application-dev.yml 的配置。

2.2.3. 修改 application-dev.yml

万事俱备，我们现在来配置项目连接本地服务（MySQL 和 Redis）的“钥匙”。

打开 ruoyi-admin 模块下的开发配置文件：
文件路径：RuoYi-Vue-Plus/ruoyi-admin/src/main/resources/application-dev.yml

1. 配置数据源 (Datasource)

找到 datasource 部分，框架默认的配置如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 文件路径: ruoyi-admin/src/main/resources/application-dev.yml

# 数据源配置
spring:
  datasource:
    dynamic:
      # ...
      datasource:
        # 主数据源
        master:
          # 默认连接的是本地 3306 端口的 ruoyi-vue 数据库
          # 确保你的数据库名、账号、密码与此一致
          # 我们将在 2.3 节中创建这个 'ruoyi-vue' 数据库
          url: jdbc:mysql://localhost:3306/ruoyi-vue? # ...
          username: root  # 你的 MySQL 用户名
          password: root  # 你的 MySQL 密码
          # ...

请确保 username 和 password 与您本地 MySQL 服务的账号密码一致。本课程中我们统一使用 root/root。

2. 配置 Redis

找到 redis 部分，这是本地启动 最容易出错 的地方。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 文件路径: ruoyi-admin/src/main/resources/application-dev.yml

  # Redis 配置
  data:
    redis:
      # Redis 数据库索引（默认为 0）
      database: 0
      # Redis 服务器地址
      host: localhost
      # Redis 服务器端口
      port: 6379
      # Redis 服务器连接密码（默认为空）
      # 如果你的本地 Redis 没有设置密码，必须将下面这行注释掉！
      # password: ruoyi123  <-- 默认配置，如果本地没密码请注释
      # ...

3. 配置 Redis Key 前缀（推荐）

在 redis 配置的下方，找到 redis-key-prefix。

1
2
3
4
5
6
7
8

# 文件路径: ruoyi-admin/src/main/resources/application-dev.yml

# redisson 配置
redisson:
  # redis key前缀
  keyPrefix: ry-vue
  # 线程池数量
  threads: 4

这是一个 强烈推荐 的最佳实践。设置前缀（如 ruoyi-vue）后，所有存入 Redis 的 Key 都会自动带上 ruoyi-vue: 的开头。这可以有效避免你的 RVP 项目与其他项目（如果它们也用了 Redis 0 号库）发生 Key 冲突，导致数据被覆盖或错乱。

2.2.4 本节小结

我们完成了后端项目的核心配置工作：

• 统一了 JDK 版本：确保了 pom.xml 和 IDEA Project Structure 均指向 JDK 17。
• 激活了开发环境：通过 Maven Profile 锁定了 dev 环境，确保加载 application-dev.yml。
• 配置了数据源：检查了 application-dev.yml 中的 MySQL 账号密码。
• 配置了 Redis：注释了默认的 Redis 密码（本地无密码），并添加了 redis-key-prefix 以防止冲突。

思考检验：

如果在 application-dev.yml 中忘记配置 redis-key-prefix，并且你本地还运行着一个 RuoYi 4.x 的项目（它也连接了 Redis 0 号库），可能会发生什么问题？

2.3. 数据库初始化

在上一节中，我们已经完成了后端项目的 application-dev.yml 配置文件修改，确保了 IDEA 可以正确连接到本地的 MySQL 和 Redis 服务。然而，正如配置所示，我们的后端服务依赖一个名为 ruoyi-vue 的数据库，而这个数据库目前还是空的。本节，我们将使用数据库管理工具（Navicat）来创建这个数据库，并导入 RVP 5.x 所需的全部核心表结构。

2.3.1. 在 Navicat 中创建 ruoyi-vue 数据库

首先，打开您的 Navicat 数据库管理工具（或其他等效工具，如 DBeaver），并连接到本地的 MySQL 8.0 服务。

1. 在连接列表上右键，选择“新建数据库”。

2. 在弹出的窗口中，填入以下两个关键信息：

   • 数据库名：ry-vue（必须与 application-dev.yml 中的配置一致）
   • 字符集：utf8mb4
   • 排序规则：utf8mb4_general_ci使用 utf8mb4 字符集是为了确保能正确存储 Emoji 表情和一些特殊字符，这是现代 Web 应用的标准配置。

3. 点击“确定”，一个新的空数据库 ruoyi-vue 就创建好了。

2.3.2. 找到 RVP 5.x 的 SQL 脚本

RVP 5.x 已经为我们准备好了所有需要的 SQL 脚本。我们回到 RuoYi-Vue-Plus 后端项目的根目录：

脚本路径：RuoYi-Vue-Plus/script/sql/

打开这个 sql 文件夹，您会看到 mysql、oracle、postgresql 等子目录。我们进入 mysql 目录。

文件路径：RuoYi-Vue-Plus/script/sql/

在这里，您会看到几个关键文件（文件名中的日期版本号可能会变化）：

• ry_2023xxxx.sql：（核心） 这是 RVP 5.x 的 系统主表，包含了用户、角色、菜单、租户等所有核心功能表。
• ry_flowable_2023xxxx.sql：（扩展） 这是 Flowable 工作流引擎所需的表结构。
• ry_snailjob_2023xxxx.sql：（扩展） 这是 SnailJob 任务调度中心所需的表结构。
• update/ 目录：这个目录存放的是版本升级脚本。例如，如果您是从 5.0 版本升级到 5.2 版本，才需要按顺序执行 update 目录下的脚本。对于我们 dev 分支的全新安装，请忽略 update 目录。

2.3.3. 导入三个核心 SQL 脚本

由于我们的 dev 分支默认集成了工作流和任务调度模块，因此我们 必须 导入上述三个 SQL 文件，才能保证服务完整启动。

1. 在 Navicat 中，双击打开 ruoyi-vue 数据库（确保它是激活状态）。
2. 右键点击 ruoyi-vue 数据库，选择“运行 SQL 文件…”。
3. 点击“…”按钮，选择我们找到的第一个脚本：ry_2023xxxx.sql（系统主表）。
4. 点击“开始”按钮，执行脚本。
5. 执行成功后，关闭窗口。重复此步骤，继续导入第二个脚本 ry_flowable_2023xxxx.sql（工作流表）。
6. 再次成功后，继续重复此步骤，导入第三个脚本 ry_snailjob_2023xxxx.sql（调度中心表）。

2.3.4. 验证数据表

当三个脚本全部执行完毕后，右键点击 ruoyi-vue 数据库并选择“刷新”。

此时，您应该能看到数据库中出现了大量的表，它们大致可以分为三类：

• sys_... / gen_... `：RVP 5.x 的系统核心表。
• flw_...：Flowable 工作流的表。
• sj_...：SnailJob 调度中心的表。

2.3.5 本节小结

我们完成了后端服务启动前最关键的数据库准备工作：

• 创建了数据库：在 Navicat 中创建了名为 ruoyi-vue 的数据库，并指定了 utf8mb4 字符集。
• 定位了 SQL 脚本：在 script/sql/mysql/ 目录下找到了三个核心脚本。
• 导入了全部数据：按顺序导入了 系统主表、工作流表 和 调度中心表。

2.4. 启动后端四大服务

在上一节中，我们已经完成了 ruoyi-vue 数据库的创建和初始化，所有的数据表都已准备就绪。我们距离成功启动后端服务只差“点火”这最后一步了。RVP 5.x 作为一个功能完备的分布式框架，其后端并不仅仅是一个服务，而是由“主服务 + 扩展服务”组成的集群。本节，我们将依次启动 ruoyi-admin（主服务）、ruoyi-monitor（监控中心）和 ruoyi-snailjob-server（调度中心）。

2.4.1. 启动 ruoyi-admin 主服务

ruoyi-admin 模块是整个 RVP 5.x 的核心，它聚合了所有的 common 插件和 modules 业务模块，是真正的“主应用”。

1. 在 IDEA 的项目浏览器中，找到 ruoyi-admin 模块。
2. 展开 src/main/java/com/ruoyi 目录。
3. 找到 RuoYiApplication.java 这个文件，这就是 Spring Boot 的启动类。
4. 右键点击 RuoYiApplication，选择 Debug 'RuoYiApplication'。

2.4.2. 解决 shorten command line 启动错误（可选）

当您第一次启动时，有小概率 会遇到一个常见的 Windows 启动错误，控制台会提示 Command line is too long... 或 找不到或无法加载主类。

• 痛点是什么：这是因为 RVP 5.x 聚合了大量的模块和 JAR 包，导致最终的 classpath 启动命令字符串超过了 Windows 默认的 255 个字符长度限制。
• 如何解决：我们必须告诉 IDEA“缩短”这个启动命令。

1. 点击 IDEA 右上角的启动配置下拉框（在“运行”按钮左侧），选择 Edit Configurations...。
2. 在弹出的窗口中，找到 RuoYiApplication 的配置。
3. 在配置界面的底部，找到 Modify options（修改选项），点击它。
4. 在弹出的菜单中，选择 shorten command line（缩短命令行）。
5. 一个新的选项会出现在配置中，将其值从 none 修改为 JAR manifest
6. 点击 Apply 和 OK 保存。

再次启动服务：完成上述配置后，再次点击“Debug”按钮启动 RuoYiApplication。

这一次，您将在控制台看到 Spring Boot 的日志滚动，最后出现 Started RuoYiApplication in ... seconds 的提示。

验证：打开浏览器，访问 http://localhost:8080（ruoyi-admin 的默认端口，在 application-dev.yml 中定义）。如果您能看到一个 JSON 提示（例如 {"msg":"操作成功","code":200,"data":...} 或欢迎页面），说明您的后端主服务已成功启动！

2.4.3. 启动 ruoyi-monitor 监控中心

ruoyi-admin 启动成功后，我们接着启动扩展模块。首先是服务监控中心。

1. 在项目浏览器中，找到 ruoyi-extend -> ruoyi-monitor 模块。
2. 展开 src/main/java/com/ruoyi/monitor 目录。
3. 找到 MonitorAdminApplication.java 启动类。
4. （重要） 像 2.4.2 节一样，同样为这个启动类配置 shorten command line。
5. 右键 Debug 启动。

该服务默认运行在 9090 端口（在 ruoyi-monitor/src/main/resources/application.yml 中定义）。

2.4.4. 启动 ruoyi-snailjob-server 调度中心

最后，我们启动任务调度中心的服务端。

1. 在项目浏览器中，找到 ruoyi-extend -> ruoyi-snailjob-server 模块。
2. 展开 src/main/java/com/ruoyi/snailjob 目录。
3. 找到 SnailJobServerApplication.java 启动类。
4. （重要） 同样为这个启动类配置 shorten command line。
5. 右键 Debug 启动。

该服务默认运行在 8800 端口（在 ruoyi-snailjob-server/src/main/resources/application.yml 中定义）。

启动成功后，我们可以打开 ruoyi-monitor（监控中心）的控制台，看到 ruoyi-admin (8080) 和 ruoyi-snailjob-server (8800) 都已经成功注册上来，显示为 UP 状态。

2.4.5 本节小结

我们成功启动了 RVP 5.x 的所有后端服务：

• RuoYiApplication (8080 端口)：核心主服务，提供业务 API。
• MonitorAdminApplication (9090 端口)：监控中心，用于监视集群服务状态。
• SnailJobServerApplication (8800 端口)：调度中心，用于管理定时任务。
• 关键技巧：我们掌握了解决 Windows shorten command line 启动错误的“三步配置法”（Edit Configurations -> shorten command line -> JAR manifest）。

2.5. 启动前端服务 (plus-ui)

在上一节中，我们已经成功启动了后端的全部三个核心服务：ruoyi-admin（主服务，8080 端口）、ruoyi-monitor（监控中心，9090 端口）和 ruoyi-snailjob-server（调度中心，8800 端口）。至此，我们的“大脑”和“神经中枢”都已开始工作。

但要真正与系统交互，我们还需要启动它的“面孔”——plus-ui 前端项目。本节我们将完成前端项目的环境配置、依赖安装和启动。

2.5.1. 在 IDEA (或 VSCode) 中打开项目

首先，我们需要使用一个专门的前端开发工具来打开 plus-ui 目录。我们 强烈推荐 使用 Visual Studio Code (VSCode)，因为它对 Vue 3 和 TypeScript 的支持更为出色。

1. 打开 VSCode。
2. 点击菜单栏 File -> Open Folder...。
3. 选择我们之前克隆的 plus-ui 目录。

2.5.2. （关键） 检查并切换 Node.js 版本

这是启动前端 最重要、也最容易失败 的一步。在 VSCode 中，打开集成终端（`Ctrl + ``），输入以下命令：

1

node -v

如果显示的 不是 v18.x.x 或 v20.x.x，您必须切换版本。推荐使用 nvm（Node Version Manager）来管理多版本：

1
2
3
4
5
6
7
8
9

# 1. (如果您安装了 nvm) 列出所有已安装版本
nvm list

# 2. 切换到 18 版本（或更高）
nvm use 18

# 3. 再次确认版本
node -v
# 确保输出为 v18.x.x

2.5.3. 安装项目依赖

在 Node.js 版本（18+）正确的前提下，我们在终端中执行以下命令，安装项目 package.json 中声明的所有依赖：

1
2
3

# 使用 npm (Node Package Manager) 安装依赖
# 这个过程会下载几百兆的文件，请耐心等待
pnpm install

2.5.4. 启动前端开发服务

依赖安装完成后，node_modules 目录已经创建。现在，我们执行 package.json 中 scripts 定义的 dev 命令，来启动 Vite 开发服务器：

1
2

# (对应视频中的 'mpn run d' 指令)
pnpm run dev

启动成功后，您会在终端看到类似以下的提示：

1
2
3
4
5

VITE v5.x.x  ready in 1.23s

➜  Local:   http://localhost:5173/
➜  Network: use --host to expose
➜  press h + enter to show help

2.5.5 本节小结

我们完成了前端项目的启动工作，重点在于环境的配置：

• 检查了 Node.js 版本：这是最关键的步骤，必须使用 Node.js 18 或更高版本。
• 安装了依赖：通过 npm install 下载了所有前端库。
• 启动了开发服：通过 npm run dev 成功在 5173 端口启动了 Vite。

2.6. 最终联调验证

在上一节中，我们已经按照 plus-ui 项目的要求，正确配置了 Node.js 18+ 环境，并通过 npm install 和 npm run dev 成功在 5173 端口启动了前端开发服务。至此，我们本地的 RVP 5.x 环境已经“万事俱备”：后端三大服务（主应用、监控、调度）和前端服务均已启动。

本节，我们将进行启动流程的最后一步：通过浏览器逐一访问所有服务，验证我们的整个系统是否已经正确联通并处于可用状态。

2.6.1. 访问并登录前端界面

我们的第一站是前端 UI 界面。

1. 打开浏览器，在地址栏输入 Vite 开发服务器的地址：http://localhost:5173。
2. 您应该能看到 RVP 5.x 现代化的登录界面。
3. 根据我们 ry_vue_5.X.sql 脚本中的默认数据，输入超级管理员的账号和密码：
   • 用户名：admin
   • 密码：admin123

如果一切顺利，系统会提示“欢迎登录”，并成功进入后台管理系统的主界面。此时，您可以点击“系统管理”、“租户管理”等菜单，确认页面可以正常加载数据。这证明 plus-ui (5173 端口) 与 ruoyi-admin (8080 端口) 之间的 API 通信已经成功建立。

2.6.2. 验证 Admin 监控中心

接下来，我们检查 ruoyi-monitor 服务是否正常。

1. 在后台管理界面中，找到并点击菜单：系统监控 -> Admin 监控。

2. 系统会打开一个新的浏览器标签页，访问监控中心。您也可以直接访问 http://localhost:9090。根据我们之前查阅的 ruoyi-monitor-admin/src/main/resources/application.yml 文件，其端口为 9090，上下文路径为 /。

3. 浏览器会弹出一个登录框，要求输入账号密码。这在 application.yml 中配置，根据视频演示，我们输入：

   • 用户名：ruoyi
   • 密码：123456

4. 登录成功后，您会进入 Spring Boot Admin 的监控界面。在“Applications”（应用）列表中，您应该能看到至少有两个服务实例显示为 UP（在线）：

   • ruoyi-admin (8080)
   • ruoyi-monitor-admin (9090)

2.6.3. 验证 SnailJob 调度中心

最后，我们来验证 ruoyi-snailjob-server。

1. 回到 RVP 5.x 的后台管理界面，点击菜单：系统监控 -> 任务调度中心。

2. 系统会打开一个新的标签页，访问 SnailJob 的管理后台。您也可以直接访问 http://localhost:8800/snail-job。根据 ruoyi-snailjob-server/src/main/resources/application.yml，其端口为 8800，上下文路径为 /snail-job。

3. 在 SnailJob 的登录页面，输入默认的账号密码（根据视频演示）：

   • 用户名：admin
   • 密码：admin

4. 登录成功后，您会进入 SnailJob 的“概览”仪表盘。点击左侧菜单的“在线机器”，您应该能看到 ruoyi-group 分组下，我们启动的 ruoyi-admin (8080) 服务已经作为执行器成功注册了上来。

2.6.4 本节小结

我们完成了本地环境的最终验证，确认了所有服务均已正常启动并联通：

• plus-ui (5173)：前端界面访问正常。
• ruoyi-admin (8080)：通过前端 admin/admin123 登录成功，API 接口正常。
• ruoyi-monitor (9090)：通过 ruoyi/123456 登录成功，能看到已注册的服务列表。
• ruoyi-snailjob-server (8800)：通过 admin/admin 登录成功，能看到已注册的 ruoyi-admin 执行器。

速查清单：