学习笔记若依单体 源码分析

环境搭建与项目复刻指南

📍 本章把前面所有模块串起来，回答一个问题：拿到一份 RuoYi-Vue-springboot3 源码，如何一步步把它跑起来，甚至造出你自己的后台？ 前半段是「照抄可用」的部署手册，后半段是「知其所以然」的复刻要点。

1. 技术栈前置清单

复刻该项目，本机必须具备以下环境：

组件 版本建议 用途
JDK 17（必须，>主要依赖 jakarta.* 命名空间与新特性） 编译/运行
Maven 3.6+ 构建 6 个模块
MySQL 5.7 / 8.0 业务数据（库名 ry-vue）
Redis 5.0+（含 Lua 脚本支持） 会话/验证码/限流/字典缓存
Node.js + npm/pnpm 16+ 前端 ruoyi-ui
IDE IntelliJ IDEA（可选） 开发/调试

⚠️ 注意：本 source/ 目录只包含后端（ruoyi-admin 等 6 个 Maven 模块）。前端 ruoyi-ui（Vue3 + Vite + Element Plus）是独立仓库，需单独获取（官方 Gitee「RuoYi-Vue」/「若依 RuoYi-Vue」前端仓库，或后端对应的 ruoyi-ui 目录）。

graph LR
    subgraph 必备运行时
        JDK[JDK 17]
        MAVEN[Maven]
        MYSQL[(MySQL
库 ry-vue)]
        REDIS[(Redis)]
        NODE[Node.js
前端构建]
    end
    API[RuoYi-Vue-springboot3 后端
6 模块 → jar] --> MYSQL
    API --> REDIS
    UI[ruoyi-ui 前端
Vue3 + Vite] --> API

2. 环境变量与工具验证

1
2
3
4
5
6
# 验证三件套版本（Windows PowerShell / Git Bash）
java -version            # 应为 17.x
mvn -version             # 应为 3.6+
node -v && npm -v        # 前端需要
redis-server --version   # 记得先启动 Redis
mysql --version

若 JDK 只有 8/11，请安装 JDK17 并配置 JAVA_HOME；Spring Boot 3.x 强制 JDK 17 起步，版本不对会在编译期直接报 UnsupportedClassVersionError。

3. 数据库初始化（后端第一步）

3.1 建库并导入两份 SQL

1
2
# 用 MySQL 客户端执行（也可在 Navicat/DataGrip 中执行）
mysql -uroot -p
1
2
3
4
5
6
7
-- 1. 建业务库
CREATE DATABASE IF NOT EXISTS `ry-vue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
USE `ry-vue`;
-- 2. 导入业务数据（含用户/菜单/角色/字典等种子数据）
source /path/to/source/RuoYi-Vue-springboot3/sql/ry_20260417.sql;
-- 3. 导入 Quartz 调度器所需表（qrtz_* 系列）
source /path/to/source/RuoYi-Vue-springboot3/sql/quartz.sql;

ry_20260417.sql 一次性建好全部表并灌入初始数据（含 sys_user 的 admin 账号、菜单、角色、部门、字典）。
quartz.sql 建 Quartz 的表结构（qrtz_job_details、qrtz_triggers 等），供 06 章 的 SysJobServiceImpl.init() 全量重建任务用。

4. 后端配置修改（三处关键）

4.1 数据源：ruoyi-admin/src/main/resources/application-druid.yml

1
2
3
4
5
6
7
8
9
druid:
  # 主库
  master:
    url: jdbc:mysql://localhost:3306/ry-vue?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8
    username: root          # ← 改成本机账号
    password: password      # ← 改成本机密码
  # 从库开关（读写分离示例，默认关闭）
  slave:
    enabled: false

4.2 服务/令牌：ruoyi-admin/src/main/resources/application.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
server:
  port: 8080                # 后端端口，前端代理会打到这

spring:
  redis:
    host: localhost         # 若无本机 Redis，指到远程
    port: 6379
    database: 0
    password:               # 有密码则填

# token 配置（生产务必改 secret！）
token:
  header: Authorization
  secret: abcdefghijklmnopqrstuvwxyz   # ← 篡改密钥，用于 JWT 签名
  expireTime: 30            # 会话 30 分钟滑动过期

ruoyi:
  name: 若依系统
  profile: ./uploadPath     # 文件上传根目录
  captchaType: math         # 验证码类型：math 数学 / char 字符

🔒 安全红线：生产部署必须把 token.secret 换成随机长字符串，否则任何人可用已知密钥伪造 JWT（HS512 对称签名）。

4.3 安全锁定策略（application.yml）

1
2
3
4
user:
  password:
    maxRetryCount: 5    # 连续错误 5 次
    lockTime: 10        # 锁定 10 分钟（[02 章](../ruoyi-spb3-02-module-framework-security/) 密码计数）

5. 启动 Redis 与后端

5.1 启动 Redis

1
2
redis-server --daemonize yes           # 后台启动
redis-cli ping                         # 返回 PONG 即就绪

5.2 编译打包后端

1
2
3
cd source/RuoYi-Vue-springboot3
mvn clean package -DskipTests
# 产物：ruoyi-admin/target/ruoyi-admin.jar

六个模块会按依赖顺序自动构建：common → system → framework → quartz → generator → admin（admin 打 fat jar）。

5.3 运行

1
2
3
4
5
6
7
8
# 方式一：直接 java -jar
java -jar ruoyi-admin/target/ruoyi-admin.jar

# 方式二：用仓库自带脚本（Linux/macOS）
./ry.sh start      # ./ry.sh stop / restart / status

# 方式三：Windows 脚本
# bin/run.bat  或  ry.bat

启动成功标志（控制台 ASCII 大图）：

1
(♥◠‿◠)ﾉﾞ  若依启动成功   ლ(´ڡ`ლ)ﾞ

验证接口：

1
2
curl http://localhost:8080/   # 返回欢迎语
curl http://localhost:8080/captchaImage   # 返回 {captchaEnabled, uuid, img}

6. 前端 ruoyi-ui 启动

前端独立于本 source，从 RuoYi 官方仓库获取 ruoyi-ui 目录后：

1
2
3
4
5
6
7
cd ruoyi-ui
npm install              # 或 pnpm install
# 配置代理指向后端（.env.development / vite.config.js）
VITE_APP_BASE_API = '/dev-api'
# vite.config.js 中 proxy '/dev-api' → http://localhost:8080

npm run dev              # 开发模式，默认 http://localhost:80

默认登录：admin / admin123。

sequenceDiagram
    participant B as 浏览器
前端:80
    participant V as Vite 代理
/dev-api
    participant A as 后端:8080
    B->>V: 请求 /dev-api/xxx
    V->>A: 转发 /xxx
    A-->>B: JSON {code,msg,data}

7. 复刻核心要点（从 0 到可继续开发的你自己的后台）

如果不想机械抄，而是基于这套源码重建你自己的管理系统，把这几件事想清楚即完成 70%：

  1. 保留分层骨架：common ↔(domain/utils/annotation) ← system(business) + framework(auth/aop) ← admin(controllers)。新增业务只改 system 与 admin，framework/common 基本不动。
  2. 新一张业务表：
    • 建表 + 在 system/domain 建实体（继承 BaseEntity）；
    • 建 mapper 接口 + XML；
    • 建 service 接口 + 实现（复用 @DataScope 权限、AjaxResult、分页 startPage）；
    • 在 admin 建 SysXxxController（继承 BaseController，用 @Log、@PreAuthorize）。
  3. 前端添加菜单页面：DB 插入一条 sys_menu，buildMenus 自动生成路由 → 权限串（perms）自动进 LoginUser.permissions → @ss.hasPermi 即时生效。无需改前端代码。
  4. 复用基础设施：登录态（JWT+Redis）、操作日志（@Log）、数据权限（@DataScope）、限流（@RateLimiter）、防重复（@RepeatSubmit）、代码生成（导入表即可生成 CRUD）。
  5. 安全强化：改默认 admin 密码、改 token.secret、按需收紧 @Anonymous 与匿名端点。

8. 常见启动失败排查

症状 大概率原因 处理
连接 MySQL 失败 库没建/密码错/库名不符 核对 application-druid.yml 与 ry-vue 库
KEYS 慢/阻塞 Redis 数据量大不适用 keys(*) 见 01章思考题
登录提示密码错但明明对 Redis 没起/会话键过期 redis-cli ping 确认，重启 Redis
前端跨域/404 代理未配 / 端口不符 核对 vite.config.js proxy → :8080
验证码一直不过 Redis 未启动（答案存不进） 启动 Redis
JAR 启动即退 + 端口占用 :8080 被占 换 server.port

9. 总结：一图串起整个项目如何协作

graph TB
    subgraph 数据层
        MYSQL[(MySQL ry-vue)]
        REDIS[(Redis)]
    end
    subgraph 后端
        C[Controller admin] --> S[ServiceImpl system]
        S --> MAP[Mapper+XML]
        MAP --> MYSQL
        C --> AOP[framework 切面
@Log/@DataScope/@RateLimiter]
        AOP --> REDIS
        SEC[Security/JWT] --> REDIS
    end
    subgraph 前端
        UI[Vue3 页面]
    end
    UI -->|HTTP JSON| C
    JOB[Quartz] --> S
    GEN[代码生成器] -->|生成| C
  • 请求来 → JwtAuthenticationTokenFilter 还原用户 → 路由到 Controller → Service 掺入数据权限 → Mapper 查库 → AjaxResult 返回。
  • 增删改查 → @Log 记操作日志（异步）、@DataScope 注入行级权限、@RateLimiter 门限。
  • 定时与生成 → Quartz 动态任务（invokeTarget 反射）、代码生成器把新表一键变页面。

至此，从「启动类如何发现各模块」到「如何跑通登录认证、如何写业务、如何部署上线」，你已有一条完整闭环。回到 00-overview.md 复习整体，或进入 appendix-references.md 看参考资料与源码速查。

交叉引用