若依微服务版（RuoYi-Cloud）快速上手

前言

若依（RuoYi）是国内使用最广泛的开源后台管理框架之一，基于 Spring Boot 构建，开箱即用，省去大量重复的基础建设工作。

若依有多个版本，其中 RuoYi-Cloud 是微服务版本，基于 Spring Cloud + Spring Cloud Alibaba 构建，适合有一定规模、需要多服务独立部署的项目。本文将帮你理解它的整体架构和核心模块。

---

一、若依微服务版的技术栈

层次	技术
服务注册与发现	Nacos
配置中心	Nacos Config
网关	Spring Cloud Gateway
负载均衡	Spring Cloud LoadBalancer
远程调用	OpenFeign
熔断降级	Sentinel
权限认证	Spring Security + JWT
缓存	Redis
数据库	MySQL + MyBatis Plus
日志链路追踪	SkyWalking（可选）
容器化	Docker + Docker Compose

---

二、整体架构

若依微服务的请求流转过程如下：

客户端（浏览器/App）
        ↓
  Gateway 网关（统一入口，鉴权、路由、限流）
        ↓
  Auth 认证服务（登录、Token 签发与验证）
        ↓
  各业务微服务（System、Monitor、Job 等）
        ↓
  MySQL / Redis / Nacos

所有外部请求都必须经过网关，网关负责：

• 路由转发（把 /system/** 的请求转发到 system 服务）
• Token 验证（未登录直接拦截）
• 限流（防止恶意刷接口）

---

三、核心模块解析

1. ruoyi-gateway（网关模块）

整个系统的统一入口，基于 Spring Cloud Gateway 实现。

核心配置在 bootstrap.yml 中定义路由规则：

spring:
  cloud:
    gateway:
      routes:
        - id: ruoyi-system
          uri: lb://ruoyi-system        # lb:// 表示负载均衡，从 Nacos 发现服务
          predicates:
            - Path=/system/**           # 匹配路径
          filters:
            - StripPrefix=1             # 去掉路径前缀

网关还内置了一个 Token 过滤器，每个请求到来时，先验证 JWT Token 是否有效，无效则直接返回 401，不会让请求打到后端服务。

2. ruoyi-auth（认证模块）

负责用户登录和 Token 管理，流程如下：

用户提交账号密码
      ↓
Auth 服务校验（查 MySQL，比对密码）
      ↓
生成 JWT Token + 用户信息存入 Redis
      ↓
返回 Token 给客户端
      ↓
客户端后续请求携带 Token → 网关验证 → 从 Redis 取用户信息

Token 存在 Redis 中而不只是依靠 JWT 自验证，是为了能主动让 Token 失效（比如用户被封号、强制下线）。

3. ruoyi-system（系统模块）

最核心的业务模块，包含：

• 用户管理：增删改查用户，分配角色
• 角色管理：定义角色，绑定菜单权限
• 菜单管理：树形菜单结构，控制前端页面可见性
• 部门管理：组织架构树
• 字典管理：维护系统中的枚举值（如性别、状态等）
• 操作日志：记录谁在什么时间做了什么操作

这套 RBAC（基于角色的权限控制）模型是若依的核心设计：用户 → 角色 → 菜单/权限。

4. ruoyi-modules（业务模块目录）

这是你自己业务代码的归宿。若依提供了 ruoyi-modules 目录作为扩展入口，你可以在这里新建自己的微服务模块，比如：

ruoyi-modules/
  ├── ruoyi-system/      # 框架自带
  ├── ruoyi-job/         # 定时任务（自带）
  ├── ruoyi-file/        # 文件服务（自带）
  └── your-business/     # 你自己的业务模块 ← 在这里扩展

5. ruoyi-common（公共模块）

存放各个微服务都会用到的公共代码：

• ruoyi-common-core：基础工具类、统一返回结果、全局异常处理
• ruoyi-common-redis：Redis 操作封装
• ruoyi-common-security：权限注解、Token 解析工具
• ruoyi-common-swagger：接口文档配置

通过 Maven 依赖引入，各服务直接复用，避免重复造轮子。

---

四、Nacos：注册中心 + 配置中心

Nacos 在若依微服务中承担双重职责：

作为注册中心： 每个微服务启动时向 Nacos 注册自己的地址，其他服务通过 Nacos 发现它，实现服务间通信，不需要硬编码 IP。

作为配置中心： 把数据库地址、Redis 配置、各种开关等配置统一存在 Nacos，修改后不需要重启服务即可生效。

# bootstrap.yml 中指定配置中心地址
spring:
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        file-extension: yml
      discovery:
        server-addr: 127.0.0.1:8848

---

五、如何新增一个业务模块

以新增一个"设备管理"模块为例，步骤如下：

1. 在 ruoyi-modules 下新建 Maven 模块 ruoyi-device
2. 引入公共依赖 ：在 pom.xml 中引入 ruoyi-common-core、ruoyi-common-security 等
3. 写业务代码：Controller、Service、Mapper，和普通 Spring Boot 项目一样
4. 在 Nacos 中添加配置：数据库、Redis 等配置
5. 在 Gateway 中添加路由规则 ：将 /device/** 路由到新服务
6. 在 System 模块中添加菜单和权限：让前端能看到新模块的入口

整个过程的核心是：业务代码你来写，基础设施若依已经搭好了。

---

六、本地快速启动

若依提供了 Docker Compose 文件，可以一键启动基础设施：

# 克隆项目
git clone https://gitee.com/y_project/RuoYi-Cloud.git

# 启动基础设施（MySQL、Redis、Nacos）
cd docker
docker-compose up -d

# 按顺序启动各服务
# 1. 先启动 Gateway 和 Auth
# 2. 再启动 System 等业务服务

启动顺序很重要：必须先有 Nacos（注册中心），其他服务才能注册上去。

---

七、常见踩坑点

问题	原因	解决
服务启动找不到配置	Nacos 中没有对应的配置文件	在 Nacos 控制台手动创建配置
接口返回 401	Token 未携带或已过期	检查请求头 Authorization: Bearer xxx
服务间调用失败	Feign 接口定义与实际接口不匹配	对齐路径、参数类型
网关路由不生效	路由配置写错或未刷新	检查 Gateway 配置，必要时重启

---

总结

若依微服务版的核心价值在于：把微服务架构中最繁琐的基础设施（鉴权、网关、注册中心、配置中心、日志）都搭好了，开发者只需要专注在业务逻辑上。

对于中小团队来说，直接基于若依二次开发，能节省大量时间。代价是需要花时间理解它的架构设计，避免在不理解原理的情况下盲目修改导致问题。