ruoyi-cloud

name	ruoyi-cloud
description	Use when scaffolding Java Spring Cloud microservice backends — Nacos service discovery, Sentinel rate limiting, Seata distributed transactions, Spring Boot 3 + Vue 3 admin. RuoYi-Cloud: popular Chinese Spring Cloud microservice boilerplate framework.
tags	["java","spring-cloud","microservices","rbac","nacos"]

项目地址： https://gitee.com/y_project/RuoYi-Cloud

GitHub 镜像： https://github.com/yangzongzhuan/RuoYi-Cloud

官网： http://ruoyi.vip/

文档： http://doc.ruoyi.vip/

许可证： MIT

概述

RuoYi-Cloud 主要特性：

• Spring Cloud Alibaba：Nacos（注册/配置）、Sentinel（熔断限流）、Seata（分布式事务）
• 网关：Spring Cloud Gateway + 鉴权过滤器
• 认证：JWT + Spring Security + OAuth2
• 业务模块：RBAC（菜单/角色/权限/部门/用户）、字典、参数、日志、文件、定时任务、监控
• 代码生成：单表/树表/主子表 → Mapper + Service + Controller + Vue 页面
• 前端：Vue 3 + Vite + Element Plus + Pinia
• DevOps：Docker Compose 一键部署、SkyWalking / Prometheus 集成

---

模块结构

RuoYi-Cloud
├── ruoyi-gateway        # API 网关
├── ruoyi-auth           # 认证服务
├── ruoyi-modules
│   ├── ruoyi-system     # 系统模块
│   ├── ruoyi-gen        # 代码生成
│   ├── ruoyi-job        # 定时任务
│   └── ruoyi-file       # 文件服务
├── ruoyi-api            # 远程调用 Feign 接口
├── ruoyi-common         # 公共工具
├── ruoyi-visual
│   ├── ruoyi-monitor    # Spring Boot Admin
│   └── ruoyi-visual-name # Nacos / Sentinel UI 入口
└── ruoyi-ui             # Vue 3 前端

---

环境与依赖

组件	版本
RuoYi-Cloud	3.6.8（最新，2026-04）
Spring Boot	4.0.x（主分支）/ 3.x（springboot3 分支）
Spring Cloud	2025.1.0
Spring Cloud Alibaba	2025.1.0.0
JDK	17+（Spring Boot 4 要求 17+） / 8（老分支）
Maven	3.9+（官方使用 3.11）
MySQL	5.7+ / 8.0
Redis	5.0+
Nacos	2.x
Sentinel	1.8+
Seata	1.6+（可选）
Node.js	18+

---

启动步骤

# 1. 克隆
git clone https://gitee.com/y_project/RuoYi-Cloud.git
cd RuoYi-Cloud

# 2. 数据库
mysql -u root -p < sql/ry_20240629.sql
mysql -u root -p < sql/ry_config_20240629.sql

# 3. Nacos：将 nacos/config 下 .yml 推送到 Nacos
#    或直接通过控制台导入 ZIP

# 4. 启动基础设施
docker compose -f docker/docker-compose.yml up -d  # 含 mysql/redis/nacos

# 5. 启动后端
mvn clean install -DskipTests
# 顺序：ruoyi-gateway → ruoyi-auth → ruoyi-modules-system → 其它

# 6. 前端
cd ruoyi-ui
npm install --registry=https://registry.npmmirror.com
npm run dev   # http://localhost:80

默认账号：admin / admin123。

---

配置中心（Nacos）

每个微服务启动时从 Nacos 拉取：

ruoyi-gateway-dev.yml
ruoyi-auth-dev.yml
ruoyi-system-dev.yml
application-dev.yml         # 公共
sentinel-ruoyi-gateway.json # Sentinel 限流规则

切换环境：spring.profiles.active=dev|test|prod。

---

网关与认证

请求流程：

Client → Gateway
  ├─ 路由匹配（lb://ruoyi-system）
  ├─ AuthFilter：从 Header 取 token，调 redis 校验
  ├─ Sentinel：限流 / 熔断
  └─ 转发到目标服务（带 user_key/user_id）

# ruoyi-gateway-dev.yml
spring:
  cloud:
    gateway:
      routes:
        - id: ruoyi-system
          uri: lb://ruoyi-system
          predicates:
            - Path=/system/**
          filters:
            - StripPrefix=1

获取 token：

curl -X POST http://localhost:8080/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin123","code":"x","uuid":"x"}'

---

RBAC 权限

• 数据库：sys_user / sys_role / sys_menu / sys_dept / sys_role_menu / sys_user_role
• Spring Security：@RequiresPermissions("system:user:list")
• 前端：根据返回菜单/按钮动态渲染

@PreAuthorize("@ss.hasPermi('system:user:edit')")
@PutMapping
public AjaxResult edit(@RequestBody SysUser user) { ... }

---

Feign 远程调用

@FeignClient(value = "ruoyi-system", contextId = "remoteUserService")
public interface RemoteUserService {
    @GetMapping("/user/info/{username}")
    R<LoginUser> getUserInfo(@PathVariable("username") String username);
}

---

Sentinel 限流

@SentinelResource(value = "listUser",
    blockHandler = "listUserBlock",
    fallback     = "listUserFallback")
public AjaxResult list() { ... }

控制台 localhost:8718 配置规则，热更新到 Nacos。

---

Seata 分布式事务

@GlobalTransactional(rollbackFor = Exception.class)
public void createOrder(...) {
    orderService.save(...);
    accountService.deduct(...);
    inventoryService.reduce(...);
}

需启动 Seata Server + 在每个微服务接入 io.seata:seata-spring-boot-starter。

---

代码生成

1. 设计表（添加 t_ 前缀业务表）
2. 系统工具 → 代码生成 → 选表 → 编辑信息（生成路径/作者/包名/前端目录）
3. 下载 zip 或同步到 Maven 工程

生成内容：Entity / Mapper.xml / Mapper / Service / ServiceImpl / Controller + Vue 页面 + SQL（菜单 + 权限）。

---

定时任务（Quartz）

后台「系统监控 → 定时任务」 → 添加：

• Bean 名：ryTask
• 方法：ryParams('test')
• Cron：0 0/5 * * * ?

@Component("ryTask")
public class RyTask {
    public void ryParams(String params) { /* ... */ }
}

---

日志与监控

• 操作日志、登录日志：@Log(title = "...", businessType = ...)
• Spring Boot Admin：http://localhost:9100/
• SkyWalking 集成：-javaagent:skywalking-agent.jar
• Prometheus / Micrometer

---

Docker 部署

cd docker
sh deploy.sh save       # 构建并保存镜像
sh deploy.sh base       # mysql/redis/nacos
sh deploy.sh server     # 业务服务
sh deploy.sh web        # 前端

---

升级与定制

1. 保留扩展点：新建模块 ruoyi-modules-mybiz，不要直接改 system
2. 统一基础包名：com.ruoyi 替换为公司域名（IDE 重构）
3. 按需删除模块：不需要 Seata 可移除依赖
4. 多租户：基于 MyBatis Plus 拦截器或 ShardingSphere 改造

---

性能与最佳实践

1. 网关连接池：调整 Reactor Netty 与下游 Feign
2. Redis 缓存权限：@CacheEvict 在权限变更时清空
3. Nacos 双注册中心 + 配置版本灰度
4. 慢 SQL：MyBatis Plus + p6spy；EXPLAIN 调优
5. 链路追踪：SkyWalking + 全链路日志 traceId

---

AI 使用建议

推荐工作流

1. 启动基础设施：Nacos + MySQL + Redis → Docker Compose 一键启动
2. 导入配置：将 Nacos 配置导入到 Nacos 控制台（SQL 或 ZIP 导入）
3. 启动微服务：按顺序启动 gateway → auth → system → gen → job → file
4. 新增业务模块：ruoyi-modules/ 下新建模块 → 注册到 Nacos → 网关配置路由
5. 代码生成：设计表 → 代码生成工具 → 一键生成 Entity/Mapper/Service/Controller + Vue 页面

关键模式与常见陷阱

• 启动顺序：必须先启 Nacos，再启 Gateway → Auth → 业务模块，否则服务发现失败
• Nacos 命名空间：确保所有微服务的 namespace 与 group 一致，否则无法发现
• Token 过期：Redis 中 token TTL 与 JWT 过期时间要保持一致；时间不同步会导致 401
• 分布式事务：Seata tx-service-group 必须与 Nacos 配置一致，否则不回滚
• 新建模块隔离：新建业务模块 ruoyi-modules-mybiz，不要直接修改 system 模块，方便升级
• 性能优化：网关连接池调优 + Redis 缓存权限 + SkyWalking 全链路追踪

如何选择正确方案

场景	推荐方案
Java 微服务后台	RuoYi-Cloud
.NET 微服务后台	Admin.NET（单体/插件式）
简单单体应用	RuoYi（单体版）
前端定制	RuoYi-Cloud 自带 Vue3 前端，也可替换为 React/Angular

---

常见问题

问题	解决
启动慢/服务发现不到	检查 Nacos 命名空间与 group 一致
鉴权失败 401	Redis 中 token 过期；时间不同步
前端 401 反复	检查 axios 拦截器与刷新机制
分布式事务不回滚	Seata tx-service-group 与配置中心一致
性能问题	网关 + 业务服务横向扩容；启用本地缓存

---

相关技能

• RuoYi-Cloud 是 Java 生态的独立技能。如需 .NET 生态的类似框架，可参考 Admin.NET 后端（Furion + SqlSugar），它在架构思想上与 RuoYi 类似但技术栈不同。

---

参考资源

• 文档：http://doc.ruoyi.vip/
• 仓库：https://gitee.com/y_project/RuoYi-Cloud
• 中文教程（znlgis）：https://znlgis.github.io/others/tutorial/ruoyi-cloud/