文章目录RuoYi-Cloud微服务技术解析从网关鉴权到Nacos、Sentinel与Seata工程实践一、引言若依微服务解决的不是“拆服务”这么简单二、版本演进与选型先决定是否真的需要微服务2.1 官方后端分支怎么选2.2 从单体迁移时先画边界三、架构全景每个模块在请求路径中的位置3.1 Nacos 为什么同时承担注册和配置3.2 ruoyi-api 与 ruoyi-common 的边界四、核心机制一次登录和一次业务请求如何完成4.1 登录不是纯 JWT而是 JWT Redis 会话4.2 网关如何防止伪造内部身份4.3 数据权限如何落到 SQL4.4 Sentinel 与 Seata 各自解决什么五、工程实践从源码启动到生产部署5.1 本地启动顺序5.2 新增业务服务的最小步骤5.3 示例配置为什么不能直接用于生产六、横向对比与常见误区若依不是免设计的业务平台6.1 RuoYi-Cloud、单体版与社区增强版6.2 五个高频误区七、总结把脚手架变成可长期维护的系统RuoYi-Cloud微服务技术解析从网关鉴权到Nacos、Sentinel与Seata工程实践一、引言若依微服务解决的不是“拆服务”这么简单在 Java 后台管理系统中RuoYi-Cloud若依微服务版的价值不只是提供用户、角色、菜单和代码生成器而是把一套可运行的微服务基础设施组合成统一工程前端请求经过 Spring Cloud Gateway服务通过 Nacos 注册与读取配置OpenFeign 完成内部调用Redis 保存登录态Sentinel负责流量控制Seata作为可选模块处理分布式事务。截至 2026 年 8 月官方 RuoYi-Cloud 版本为3.6.8。master主分支已经升级到 Spring Boot4.0.6、Spring Cloud2025.1.1、Spring Cloud Alibaba2025.1.0.0要求 JDK 17 及以上官方同时维护 Spring Boot 3 和 Spring Boot 2 分支为存量项目保留迁移空间。这篇文章不只列组件名称而是沿着一个请求的真实路径解释服务如何发现、登录态如何创建与校验、用户身份如何跨服务传递、数据权限如何落到 SQL以及实际部署时哪些默认配置不能直接搬到生产环境。亲爱的朋友们创作不容易若对您有帮助的话请点赞收藏加关注哦您的关注是我持续创作的动力谢谢大家有问题请私信或联系邮箱jasonai.fngmail.com二、版本演进与选型先决定是否真的需要微服务若依官方主要提供三个不同形态传统前后端一体版 RuoYi、前后端分离单体版 RuoYi-Vue以及分布式版 RuoYi-Cloud。它们共享用户、角色、菜单、部门、字典、日志和代码生成等后台能力但运行复杂度并不相同。项目形态后端形态主要依赖更适合的团队RuoYi单体、服务端页面Spring Boot、Thymeleaf维护传统管理系统前后端不分离RuoYi-Vue前后端分离单体Spring Boot、Spring Security、Vue业务边界尚未稳定的中小项目RuoYi-Cloud多进程微服务Spring Cloud、Spring Cloud Alibaba、Redis、Nacos确实需要独立发布、横向扩容或团队分工的系统RuoYi-Cloud-Plus社区重写的增强版本Sa-Token、MyBatis-Plus、Dubbo 等接受不同开发模型并需要更多集成能力的团队“未来可能变大”不是采用微服务的充分理由。RuoYi-Cloud 的最小完整环境至少包含数据库、Redis、Nacos、网关、认证服务和系统服务加入代码生成、定时任务、文件服务和监控后进程数、配置项、日志来源与故障点都会增加。如果一个团队不能持续维护配置中心、链路日志、凭证轮换和服务级告警RuoYi-Vue 单体版通常更稳妥。2.1 官方后端分支怎么选分支基础版本JDK / Nacos选择建议masterSpring Boot 4.xJDK 17、Nacos 3.x新项目且依赖已验证兼容时采用springboot3Spring Boot 3.xJDK 17、Nacos 3.x需要 Jakarta 体系同时希望第三方依赖更成熟springboot2Spring Boot 2.xJDK 8、Nacos 2.x仅用于无法升级 JDK 的存量系统前端则可在 Vue 2、Vue 3 JavaScript 和 Vue 3 TypeScript 版本之间选择。多人长期协作的新项目更适合 Vue 3 TypeScript迁移既有 Vue 2 页面时可以先维持接口契约不变再逐步替换前端。2.2 从单体迁移时先画边界若依自带的system、gen、job、file是基础功能模块不等于每张业务表都应拆成一个服务。实际拆分应以业务所有权和一致性边界为依据例如订单服务拥有订单表库存服务拥有库存表跨服务只通过 API 或事件通信禁止多个服务直接读写同一业务表。否则只是把单体代码分成多个进程却保留共享数据库耦合。三、架构全景每个模块在请求路径中的位置官方工程采用 Maven 聚合项目。核心目录可归为入口服务、业务服务、远程接口契约和公共组件四类。模块默认端口核心职责是否建议独立扩容ruoyi-gateway8080动态路由、全局鉴权、验证码过滤、Sentinel 网关限流是所有外部流量入口ruoyi-auth9200登录、退出、注册、刷新会话是登录高峰可单独扩容ruoyi-system9201用户、角色、菜单、部门、字典、参数和日志视后台访问量决定ruoyi-gen9202数据库表解析与前后端代码生成通常限制在开发或内网环境ruoyi-job9203Quartz 定时任务及执行日志需要重点处理重复执行问题ruoyi-file9300本地文件、FastDFS 或 MinIO 接入无状态化后再横向扩容ruoyi-monitor9100Spring Boot Admin 服务监控管理面不应暴露到公网ruoyi-api-system无OpenFeign 接口、DTO、降级工厂作为编译期契约被其他服务依赖ruoyi-common-*无安全、Redis、日志、数据权限、多数据源、Seata、接口文档公共库变更会影响多个服务┌─────────────────────────────────────────────────────────────┐ │ 浏览器 / 移动端 / 第三方系统 │ └──────────────────────────┬──────────────────────────────────┘ ▼ Nginx / 负载均衡器 │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ ruoyi-gateway │ │ 路由匹配 · 验证码 · JWT解析 · Redis会话校验 · Sentinel限流 │ └───────┬────────────┬────────────┬──────────────┬─────────────┘ ▼ ▼ ▼ ▼ ruoyi-auth ruoyi-system ruoyi-gen 业务服务 │ ▲ │ │ │ OpenFeign │ └──────┬───────┘ └────────────┘ │ ┌──────────┴──────────┐ ▼ ▼ 独立业务数据库 文件/对象存储 Nacos服务注册 配置发布 Redis登录态 缓存 Sentinel限流/熔断规则 Seata可选的跨库事务协调3.1 Nacos 为什么同时承担注册和配置每个服务的bootstrap.yml只保留少量引导信息应用名、端口、当前环境以及 Nacos 地址。启动时服务读取公共配置application-{profile}.yml再读取自身配置{application-name}-{profile}.yml。以网关为例它会加载公共 OpenFeign 配置和专属路由、Redis、白名单配置同时把实例注册为ruoyi-gateway。这种方式减少了镜像中的环境差异但也让 Nacos 成为关键依赖。生产环境需要独立命名空间、鉴权、持久化、高可用与配置审计不能继续使用仓库示例中的默认口令或单机模式。敏感密码最好来自 Secret 管理系统再通过环境变量或工作负载身份注入不应明文保存在普通 Nacos 配置中。3.2ruoyi-api与ruoyi-common的边界ruoyi-api-system定义RemoteUserService、RemoteLogService、DTO 和回退工厂表达跨服务契约ruoyi-common-*则封装横跨多个服务的技术能力。业务开发时应控制公共模块规模稳定的协议模型可以共享业务规则不应塞入common-core否则任何小改动都需要重新构建和发布大量服务。四、核心机制一次登录和一次业务请求如何完成4.1 登录不是纯 JWT而是 JWT Redis 会话前端向/auth/login发起请求。网关根据 Nacos 中的路由配置将请求转给ruoyi-auth登录白名单使其跳过令牌校验但验证码过滤器仍可在路由前验证请求。POST /auth/login │ ▼ Gateway验证码校验、去掉 /auth 前缀 │ ▼ ruoyi-authSysLoginService.login() │ OpenFeign 内部来源标记 ▼ ruoyi-system查询用户、角色和权限 │ ▼ ruoyi-auth校验状态、密码和黑名单 │ ├── 生成随机 UUID 作为 userKey ├── Redis 保存完整 LoginUser会话键为 login_tokens:{userKey} └── JWT 写入 userKey、userId、username │ ▼ 返回 access_token 与 expires_in这是一种有状态的混合设计。JWT 让网关快速读取用户标识Redis 决定会话是否仍然有效并保存完整权限信息。它带来三项能力退出登录可立即删除 Redis 会话、管理员可以主动将用户踢下线、权限与登录信息可以集中刷新。代价是 Redis 故障会影响所有受保护请求因此需要主从或集群、高可用监控以及合理的超时策略。4.2 网关如何防止伪造内部身份AuthFilter从请求头读取 Bearer Token解析 JWT 后检查 Redis 中是否存在对应会话再提取userKey、userId和username写入下游请求头。它还会删除外部请求携带的内部来源头防止客户端直接伪装成服务间调用。下游服务的HeaderInterceptor把这些头写入SecurityContextHolder。后者使用TransmittableThreadLocal保存当前线程身份业务代码再通过SecurityUtils或权限注解读取。请求结束必须清理线程变量异步线程池也要注意上下文传播和复用污染。安全层校验对象典型实现不能替代什么网关登录态用户是否已登录、会话是否存在JWT 解析 Redis 键检查不能代替接口级权限接口权限用户是否有某个菜单或按钮权限RequiresPermissions/PreAuthorizeAspect不能代替数据行过滤内部接口调用是否来自可信服务InnerAuth 内部来源头不能只信任可伪造的公网请求头数据权限用户能看到哪些部门或本人数据DataScope SQL 条件不能代替数据库账号隔离生产部署还应在网关之后增加网络层约束业务服务只接受来自网关或服务网络的流量内部调用使用 mTLS 或服务身份。仅靠一个字符串请求头证明“内部调用”在网关被绕过或服务端口暴露时是不够的。4.3 数据权限如何落到 SQL若依把功能权限和数据权限分开。DataScopeAspect在标注了DataScope的查询方法执行前根据当前用户角色生成部门、自定义部门、部门及子部门或仅本人等过滤条件并放入查询对象的params.dataScope。Mapper XML 再把该片段拼入 SQL。这种方式对传统后台列表很直接但有三个约束查询参数必须符合切面预期Mapper 必须正确引用数据权限片段新增查询若漏加注解可能返回过多数据。工程上应为每类角色编写集成测试验证“全量、部门、子部门、本人、无权限”五类边界而不能只测试管理员账号。4.4 Sentinel 与 Seata 各自解决什么Sentinel 位于流量与依赖稳定性层。官方网关配置从 Nacos 读取规则可按ruoyi-auth、ruoyi-system等路由资源限制 QPS公共 OpenFeign 配置也支持 Sentinel 降级。当系统服务变慢时认证服务的RemoteUserFallbackFactory可以返回可控错误避免线程不断堆积。Seata则是可选公共模块项目提供ruoyi-common-seata和初始化 SQL但不会自动让所有调用具备事务一致性。业务服务必须引入依赖、配置事务组并在明确的全局事务边界使用相应注解。对高并发核心链路应先考虑本地事务加消息最终一致性只有业务确实要求强一致且能接受锁、回滚日志和协调器成本时再采用 Seata AT 等模式。五、工程实践从源码启动到生产部署5.1 本地启动顺序官方仓库提供 Docker Compose 和各服务镜像目录但示例主要用于体验与开发。一个稳定的本地启动顺序如下顺序组件检查点1MySQL导入ry、Nacos 配置、Quartz按需导入 Seata SQL2Redis确认可写、密码与连接地址一致3Nacos导入ry_config确认服务发现与配置列表可用4ruoyi-system用户与权限数据能够查询5ruoyi-authOpenFeign 能发现并调用系统服务6ruoyi-gateway路由、白名单和 Sentinel 规则加载成功7其他模块按需启动 gen、job、file、monitor 与业务服务8前端/NginxAPI 前缀指向网关不直连内部服务常用构建命令为mvn clean package-DskipTests跳过测试只适合首次验证构建。正式流水线应至少执行单元测试、权限集成测试、数据库迁移检查、依赖漏洞扫描和镜像扫描。若所有环境都长期使用-DskipTests代码生成带来的速度优势会被回归风险抵消。5.2 新增业务服务的最小步骤在ruoyi-modules下建立独立 Maven 模块并声明唯一的spring.application.name。引入 Nacos Discovery、Nacos Config、Web、安全与所需数据访问模块。创建bootstrap.yml只放引导配置业务配置发布到独立 Nacos Data ID。在网关配置中增加lb://服务名路由和明确的 Path 前缀。将跨服务 DTO 与 Feign 契约放入对应ruoyi-api-*模块并提供超时与降级行为。建立独立数据库账号和表所有权避免直接访问其他服务数据库。补齐权限标识、数据范围测试、接口文档、日志脱敏、指标和告警。一个简化的引导配置如下spring:application:name:ruoyi-orderprofiles:active:devcloud:nacos:discovery:server-addr:${NACOS_ADDR:127.0.0.1:8848}config:server-addr:${NACOS_ADDR:127.0.0.1:8848}config:import:-nacos:application-${spring.profiles.active}.yml-nacos:${spring.application.name}-${spring.profiles.active}.yml5.3 示例配置为什么不能直接用于生产官方 Compose 使用 Nacos 单机模式并在示例中出现数据库、Nacos、监控与 Druid 的演示口令服务配置大量使用localhostMySQL 容器还采用 5.7。它们的目的是降低本地体验门槛不是生产基线。开发示例生产改造Nacos standalone三节点或托管高可用启用鉴权、TLS、命名空间和审计明文固定密码Secret 管理、定期轮换、不同服务独立账号所有 Actuator 端点暴露仅开放必要端点并限制管理网络访问服务端口映射到宿主机内部服务仅在私有网络暴露对外只开放网关本地文件上传目录对象存储或共享存储校验类型、大小并做恶意文件扫描单个 RedisSentinel/Cluster 或云托管并验证会话故障恢复日志只落本机集中采集、Trace ID、脱敏和保留策略六、横向对比与常见误区若依不是免设计的业务平台6.1 RuoYi-Cloud、单体版与社区增强版维度RuoYi-Vue官方 RuoYi-CloudRuoYi-Cloud-Plus运行复杂度低一个后端进程中高多服务与中间件高集成组件更多默认鉴权思路Spring Security JWT网关、JWT、Redis 登录态与权限切面Sa-Token 为主数据访问MyBatisMyBatis、PageHelper、动态数据源MyBatis-Plus 等增强工具服务调用进程内方法调用OpenFeignOpenFeign / Dubbo 等适用重点快速交付、维护简单官方微服务结构、学习资料多需要更多现成功能并接受社区实现差异主要代价难以独立扩容单个模块分布式运维和一致性成本升级面更大团队需掌握更多组件选择时不要只比较功能数量。官方 RuoYi-Cloud 结构相对克制便于理解 Spring Cloud Alibaba 的基本调用链Plus 版本功能更多但不是官方项目的原地升级包包结构、认证、ORM 和扩展方式都有差异迁移前必须做代码级评估。6.2 五个高频误区误区实际问题修正方式“用了 JWT 就完全无状态”登录状态和完整用户信息仍依赖 Redis为 Redis 做容量、可用性和过期策略设计“经过网关就绝对安全”内部服务若可直连请求头可能被伪造网络隔离、mTLS、服务身份与入口校验并用“引入 Seata 就有分布式事务”仍需事务边界、协调器、回滚日志和异常测试先确定一致性模型再选择 AT/TCC/消息方案“代码生成后无需测试”生成器只解决重复 CRUD无法证明业务规则正确保留单测、接口测试、权限和迁移测试“每个模块都应该拆服务”过细拆分增加调用延迟与发布协调围绕业务所有权和独立变化频率划分边界若依最适合作为可读、可改的工程起点而不是不可触碰的产品内核。上线前应删除不使用的模块与演示账号收紧公共依赖建立数据库迁移工具并用压测验证网关、Redis、Nacos和热点接口的容量。框架提供的是基础结构可靠性仍来自团队自己的测试、监控与操作规范。七、总结把脚手架变成可长期维护的系统维度核心结论版本选择新项目评估 Boot 4 主分支依赖兼容性优先时选择 Boot 3Boot 2 仅留给存量系统架构定位网关、认证、系统服务、业务服务和公共契约分层清晰但不替代业务边界设计登录机制JWT 携带基本声明Redis 保存真实会话兼顾快速解析与主动失效能力权限体系登录态、接口权限、内部调用和数据范围是四个不同层次必须分别验证中间件Nacos、Redis 是关键依赖Sentinel负责稳定性Seata按一致性需求选用生产化更换示例口令、隔离管理面、收窄服务端口、建立可观测性和自动化测试RuoYi-Cloud 的优势是用一套相对直白的源码展示完整微服务后台如何运转请求如何进入、服务如何发现、身份如何传播、权限如何落到查询、失败如何降级。它的局限也来自同一点默认实现为了通用和易上手保留了许多简化配置无法直接回答每个组织的安全、容量与一致性问题。真正可靠的落地路径是先用单体确认业务边界再按独立发布和扩容需求拆分把官方模块当作参考实现把生产安全、数据所有权、故障恢复与测试体系当作自己的责任。这样若依才不会只是“能启动的后台”而会成为可持续演进的工程底座。参考资料RuoYi-Cloud 官方仓库与版本说明 — GiteeRuoYi-Cloud GitHub 镜像仓库RuoYi 官方文档RuoYi-Cloud 根 POM当前框架版本网关 AuthFilter 源码TokenServiceJWT 与 Redis 会话实现DataScopeAspect数据权限实现Spring Cloud Alibaba 官方项目页Nacos 官方文档Sentinel 官方文档Seata 官方文档