提示

以 RuoYi-Cloud 3.6.8 为例。

下载项目

# 后端
git clone https://gitcode.com/yangzongzhuan/RuoYi-Cloud.git

# 前端
git clone https://gitcode.com/yangzongzhuan/RuoYi-Cloud-Vue3.git

JDK-21
Node22、pnpm
Nacos
- 修改 application.properties 中 mysql 数据库使用 ry-config，确认内部两个端口不和现有应用冲突
- 修改 ruoyi-system-dev.yml 中的 mysql 数据源用户名及密码
- 进入Web后台 http://127.0.0.1:8080 (nacos/nacos)，确认配置文件加载正确

Navicat Premium 执行数据库文件

针对 RuoYi-Cloud 3.6.8，4 个 SQL 文件参考下面的对照表：

SQL 文件	是否必须执行	对应数据库	作用说明
`ry_20260417.sql`	✅ 必须执行	`ry-cloud`	核心业务库。包含系统管理、用户、权限等所有核心业务表。
`ry_config_20260818.sql`	✅ 必须执行	`ry-config`	Nacos配置库。用于持久化存储微服务的配置信息，是微服务启动的关键。
`quartz.sql`	❓ 按需执行	`ry-cloud` (通常)	定时任务表。只有当你需要使用框架自带的定时任务功能（`ruoyi-job`模块）时才需要执行。
`ry_seata_20210128.sql`	❓ 按需执行	`ry-seata`	分布式事务表。只有当你启用 Seata 分布式事务功能时才需要执行。默认是关闭的，可以跳过。

启动

后端

打开运行基础模块（启动没有先后顺序）

RuoYiGatewayApplication （网关模块必须）
RuoYiAuthApplication （认证模块必须）
RuoYiSystemApplication （系统模块必须）
RuoYiMonitorApplication （监控中心可选）
RuoYiGenApplication （代码生成可选）
RuoYiJobApplication （定时任务可选）
RuoYiFileApplication （文件服务可选）

前端

git switch typescript
git branch -vv

pnpm install
## 如果报错 可能是因为 pnpm install的时候不下载 sortablejs 这个包，补一下重新install就好了
pnpm dev

提示

用户名：admin

密码：admin123

后端项目整体

树形图

RuoYi-Cloud/
+-- pom.xml                          # 父工程：统一版本管理 + dependencyManagement
+-- ruoyi-api/                       # ★ Feign 远程接口模块（跨服务调用契约）
|   `-- ruoyi-api-system/            #   系统服务接口：RemoteUserService / RemoteLogService / RemoteFileService
+-- ruoyi-common/                    # ★ 公共能力模块（无业务，被各服务复用）
|   +-- ruoyi-common-core/           #   最底层：BaseController、常量、工具类、登录用户模型
|   +-- ruoyi-common-security/       #   安全认证：token 校验、权限注解
|   +-- ruoyi-common-datasource/     #   多数据源（Druid dynamic-datasource）
|   +-- ruoyi-common-datascope/      #   数据权限
|   +-- ruoyi-common-log/            #   操作日志注解 @Log
|   +-- ruoyi-common-redis/          #   Redis 缓存
|   +-- ruoyi-common-sensitive/      #   数据脱敏
|   +-- ruoyi-common-swagger/        #   接口文档
|   `-- ruoyi-common-seata/          #   分布式事务（依赖已建，未启用）
+-- ruoyi-auth/                      # ★ 认证授权中心（登录、发 token，9200）
+-- ruoyi-gateway/                   # ★ 网关（路由转发、token 鉴权、限流，8080）
+-- ruoyi-modules/                   # ★★ 业务模块层 —— 你的新业务写在这里
|   +-- ruoyi-system/                #   系统管理（用户/角色/菜单…，9201）
|   +-- ruoyi-gen/                   #   代码生成（9202）
|   +-- ruoyi-job/                   #   定时任务（9203）
|   `-- ruoyi-file/                  #   文件服务（9300）
`-- ruoyi-visual/
    `-- ruoyi-monitor/               # SpringBoot Admin 监控（9100）

新业务

推荐做法：新建一个业务模块 ruoyi-modules/ruoyi-xxx（业务隔离、独立部署），而不是塞进 ruoyi-system 。模块内部标准分层（参照 ruoyi-system 现有结构）：

ruoyi-modules/ruoyi-xxx/
+-- pom.xml
`-- src/main/
    +-- java/com/ruoyi/xxx/
    |   +-- RuoYiXxxApplication.java    # 启动类
    |   +-- controller/                 # 控制器（对外 REST 接口）
    |   +-- domain/                     # 实体类（对应数据库表）
    |   +-- mapper/                     # MyBatis Mapper 接口
    |   `-- service/                    # 业务接口 ISysXxxService
    |       `-- impl/                   # 业务实现 XxxServiceImpl
    `-- resources/
        +-- bootstrap.yml               # 注册到 Nacos
        `-- mapper/xxx/                 # Mapper XML（XML 与 Java 同级包结构）

如果只是加系统管理周边小功能（比如给 sys_user 加个字段），也可以直接加在 ruoyi-modules/ruoyi-system 对应包里。

跨服务调用（如 system 要调文件服务）时，把 Feign 接口放到 ruoyi-api/ 下新建的 ruoyi-api-xxx 模块（参照 ruoyi-api-system）：

ruoyi-api/ruoyi-api-xxx/src/main/java/com/ruoyi/xxx/api/
+-- RemoteXxxService.java     # @FeignClient 接口
+-- factory/                  # 降级 FallbackFactory
`-- domain/                   # 跨服务传输的 DTO

模块依赖关系

依赖方向（自上而下引用）：

模块	依赖	被谁依赖
ruoyi-common-core	无 ruoyi 内部依赖	所有模块
ruoyi-common-security	core、redis	ruoyi-auth、各业务模块
ruoyi-common-datasource/log/datascope/swagger/sensitive	core	ruoyi-modules-system 等业务模块
ruoyi-api-system	core	需要调 system 的模块（如 ruoyi-file）
ruoyi-modules-*	对应 common-* + ruoyi-api-system	网关路由转发
ruoyi-auth	common-security + api-system	被网关转发
ruoyi-gateway	只依赖 common-core/redis（不做业务）	前端入口

运行时调用链（Feign 方向）：

前端 --HTTP--> ruoyi-gateway(8080) --路由--> ruoyi-auth / ruoyi-system / ruoyi-gen / ruoyi-job / ruoyi-file
ruoyi-auth --Feign--> ruoyi-system    （登录时校验用户、存登录日志）
ruoyi-system --Feign--> ruoyi-file    （上传文件）
各服务 --注册/拉配置--> Nacos(8848)
各服务 --缓存--> Redis(6379)   --数据--> MySQL ry-cloud(3306)

要点：

网关不写业务代码，只做路由 + 鉴权；所有请求必须过网关（8080）。
服务间不直接 HTTP 调用，一律通过 ruoyi-api-* 里的 Feign 接口。
数据库连接、Redis 等配置都在 Nacos 配置中心（ruoyi-xxx-dev.yml），不在本地 yml。

新业务模块实施计划

建模块骨架：新建 ruoyi-modules/ruoyi-xxx，复制 ruoyi-system 的 pom 结构（改 artifactId、去掉不用的依赖）；在根 pom.xml 的 <modules> 和 ruoyi-modules/pom.xml 中注册。
写业务代码：controller / domain / mapper(+XML) / service / impl，mapper XML 放 resources/mapper/xxx/ 。
Nacos 配置：新增 ruoyi-xxx-dev.yml（数据源连 ry-cloud、Redis、端口），并更新 sql/ry_config_*.sql 。
网关路由 + 权限：ruoyi-gateway-dev.yml 加路由规则；菜单/按钮权限走 sys_menu 。
如需跨服务调用：新建 ruoyi-api-xxx Feign 接口模块，并在需要处引入。
验证：启动服务 > 注册到 Nacos > 通过网关 8080 访问接口 > 检查文档（swagger）。

前端项目整体

树形图

RuoYi-Cloud-Vue3/
+-- package.json                      # 依赖清单（pnpm，严格模式）
+-- vite.config.ts                    # 构建配置：@ 别名指向 src、代理 /prod-api > 网关 8080
+-- .env.development                  # VITE_APP_BASE_API=/prod-api
`-- src/                              # ★★★ 前端全部代码都在这里
    +-- main.ts                       # 入口：装配 Pinia / Router / 权限守卫
    +-- App.vue
    +-- permission.ts                 # 全局路由守卫（登录态校验 + 拉取动态路由）
    +-- settings.ts                   # 系统全局配置
    +-- api/                          # ★ API 层：每个后端接口一个 TS 文件（写业务接口在这里）
    |   +-- login.ts                  #   < 对应 ruoyi-auth（登录/登出/验证码）
    |   +-- menu.ts                   #   < 对应 ruoyi-system 的菜单接口
    |   +-- system/                   #   < 对应后端 ruoyi-system 服务（9201）
    |   |   +-- user.ts               #     用户 CRUD
    |   |   +-- role.ts / dept.ts / post.ts / menu.ts / config.ts
    |   |   +-- notice.ts / dict/ / operlog.ts / logininfor.ts
    |   +-- monitor/                  #   < 对应后端 ruoyi-job（9203）等监控类
    |   |   +-- job.ts / jobLog.ts / online.ts
    |   +-- tool/                     #   < 对应后端 ruoyi-gen 代码生成（9202）
    |       +-- gen.ts
    +-- views/                        # ★ 页面层：一个页面 = 一个目录，写页面在这里
    |   +-- index.vue / login.vue / register.vue / lock.vue
    |   +-- error/                    #   401 / 404
    |   +-- system/                   #   < 对应后端 ruoyi-system
    |   |   +-- user/                 #     用户管理
    |   |   |   +-- index.vue         #     列表页
    |   |   +-- role/ dept/ menu/ dict/ config/ post/ notice/ operlog/ logininfor/
    |   +-- monitor/                  #   < 对应后端 ruoyi-job
    |   |   +-- job/ index.vue        #     定时任务
    |   |   +-- online/
    |   +-- tool/
    |       +-- gen/                  #   < 对应后端 ruoyi-gen
    |           +-- index.vue + genInfoForm.vue + editTable.vue + importTable.vue
    +-- types/                        # ★ TS 类型层（本仓库是 TS 分支，与 api 一一对应）
    |   +-- api/
    |       +-- login.ts / menu.ts / common.ts
    |       +-- system/ ... / monitor/ ... / tool/ ...
    +-- components/                   # ★ 公共组件（跨页面复用才放这里）
    |   +-- FileUpload/ ImageUpload/ Pagination/ DictTag/ Editor/ ...
    +-- store/modules/                # ★ Pinia 状态：user / permission / dict / app / tagsView ...
    +-- router/index.ts               # 只写"公共路由"；业务路由不在这里手写（见下）
    +-- directive/                    # 自定义指令：hasPermi / hasRole / copyText
    +-- utils/                        # request.ts(axios 封装) / auth / dict / permission ...
    +-- plugins/                      # auth / cache / download / modal / tab
    +-- layout/                       # 框架布局（一般不用动）
    `-- assets/                       # 静态资源、svg 图标、样式

后-前端对应关系

后端模块	后端端口	前端 API 层	前端页面层	前端类型层
ruoyi-auth	9200	api/login.ts	views/login.vue	types/api/login.ts
ruoyi-system	9201	api/system/*	views/system/*	types/api/system/*
ruoyi-job	9203	api/monitor/job*	views/monitor/job*	types/api/monitor/*
ruoyi-gen	9202	api/tool/gen.ts	views/tool/gen/*	types/api/tool/*
ruoyi-file	9300	无独立模块（走 components/FileUpload → /common/upload）	—	—
你的新业务	新增服务	新建 `src/api/xxx/`	新建 `src/views/xxx/`	新建 `src/types/api/xxx/`

提示

注意两个"对不上"的映射：定时任务前端归在 monitor/ 下，代码生成前端归在 tool/ 下——这是若依前端的命名习惯，沿用即可。

模块依赖关系

+---------------------------- 一次请求的数据流 ----------------------------+
|                                                                         |
|  views/xxx/index.vue (页面)                                             |
|    |  调用                                                              |
|    ▼                                                                   |
|  api/xxx.ts (接口封装) --> 依赖 utils/request.ts (axios 单例)           |
|                              |  baseURL = VITE_APP_BASE_API = /prod-api |
|                              ▼                                         |
|  vite.config.ts 代理 /prod-api --> 网关 ruoyi-gateway :8080            |
|                                       |  路由转发 + token 鉴权          |
|                                       ▼                                |
|                               业务微服务 (ruoyi-system / 新服务)        |
`-------------------------------------------------------------------------+

关键依赖链（代码层面）：
main.ts --> App.vue --> router/index.ts (constantRoutes)
              |
              +-> permission.ts 路由守卫 --> store/modules/permission.ts
              |        |  generateRoutes() 从后端拉菜单
              |        |  getRouters() > api/menu.ts > 网关 > ruoyi-system
              |        |
              |        ▼
              |  动态组件: import.meta.glob('./views/**/*.vue')
              |  通过 loadView(后端菜单的 component 字段) 匹配 views 下的文件
              |
              `-> store/modules/user.ts --> api/login.ts (token 存取)

页面 views --依赖--> components / directives / utils / plugins / store
api/*.ts   --依赖--> utils/request.ts + types/api/*.ts

新业务模块

提示

（后端已有接口）前端要做的事

假设后端新增了 ruoyi-xxx 服务（如商品模块），前端只需 4 步：

写 API：新建 src/api/xxx/goods.ts ，用 request 封装接口：

import request from '@/utils/request'

export function listGoods(query: any) {
		return request({ url: '/xxx/goods/list', method: 'get', params: query })
}

写页面：新建 src/views/xxx/goods/index.vue（列表页）。
配菜单（关键）：在后端 sys_menu 表（系统管理>菜单管理）新增菜单，component 字段填 xxx/goods/index——前端守卫会按这个字
符串在 views/ 下自动找到你的页面，不需要手改 router/index.ts。
（可选）写类型：新建 src/types/api/xxx/goods.ts 定义 TS 类型；网关若没配该服务路由，需在 ruoyi-gateway 的配置文件里加路由
转发。

提示

补充：src/api 的 url 里 /xxx/goods/... 的 /xxx 是网关路由前缀，对应后端服务名，跟 vite.config.ts 的代理、后端 gateway 配
置保持一致即可。

RuoyiGenApplication

前端"代码生成"页面有两个列表，小心混淆：

界面	调用接口	查的是什么	为什么可能空
主页列表	/tool/gen/list	查 gen_table 表 = 已导入代码生成的表	从没导入过 → 天然为空
"导入"按钮弹窗	/tool/gen/db/list	查 information_schema.tables = 数据库里还没导入的表	库里没有符合条件的表 / 连不上库

核心查询逻辑（ GenTableMapper.xml 的 selectDbTableList ）：

select
	table_name, table_comment, create_time, update_time
from
	information_schema.tables
where
	table_schema = (select database())                        -- 取"当前连接库"
	AND table_name NOT LIKE 'qrtz\_%'                         -- 排除定时任务表
	AND table_name NOT LIKE 'gen\_%'                          -- 排除代码生成自身表
	AND table_name NOT IN (select table_name from gen_table)  -- 排除已导入的

导入流程：点"导入"勾选表 > /tool/gen/importTable > 读该表结构写入 gen_table + gen_table_column > 之后才出现在主页，可编辑配置、预览、生成代码。

身份认证

提示

项目版本：3.6.8 ｜认证方案：JWT（无状态）+ Redis（有状态）双重校验，网关统一鉴权

一、整体架构

闭环一：首次登录 → 签发 Token

提示

登录链路：网关放行 → auth 验参数/黑名单 → Feign 内部调用 system 取用户+权限 → 验密码 → LoginUser 存 Redis → 签发 JWT 给前端。自此前端持有 JWT，Redis 持有登录态。

闭环二：请求身份验证（含服务间调用）

提示

验证链路：网关验 JWT 签名 + 查 Redis 登录态 → 用户身份写入请求头 → 下游服务恢复当前用户 → 注解权限校验 → 服务间 Feign 调用靠内部来源头隔离。

核心特点：JWT 只负责"身份声明"，Redis 才是"登录态真身"。

JWT 可被任何人解析（仅做签名校验），真正的会话状态存在 Redis；
网关每次请求都查 Redis 确认登录是否有效；
完整用户信息（含权限集合）只存在 Redis，不放进 JWT；
外部请求永远无法冒充服务间内部调用（FROM_SOURCE 头被网关移除，内部接口 @InnerAuth 强制校验）。

二、登录流程

重要

（ruoyi-auth，9200）

前端 POST /auth/login（TokenController.login）：

入参校验（SysLoginService.login）
- 用户名 / 密码非空、长度范围校验；
IP 黑名单校验
- 查 Redis 中的黑名单列表（SYS_LOGIN_BLACKIPLIST），命中则拒绝；
远程查用户
- 通过 Feign RemoteUserService.getUserInfo(username, INNER) 调用 ruoyi-system；
- 传入 SecurityConstants.INNER 标记内部调用（走 @InnerAuth 白名单）；
状态校验
- 用户是否被删除（del_flag）、是否停用（status）；
密码校验
- passwordService.validate()（BCrypt 比对密文）；
记录登录日志，返回 LoginUser（含 sysUser、roles、permissions 权限集合）。

三、签发 Token

重要

（TokenService.createToken）

String token = IdUtils.fastUUID();          // ① 生成 UUID 作为 userKey
loginUser.setToken(token);
refreshToken(loginUser);                     // ② LoginUser 整体存入 Redis（key: login_tokens:{userKey}，30 分钟过期）
// ③ 用 JWT(HS512, secret) 封装 userKey/userId/userName 生成 access_token
rspMap.put("access_token", JwtUtils.createToken(claimsMap));
rspMap.put("expires_in", TOKEN_EXPIRE_TIME); // 返回给前端

关键点：

JWT 里只放 userKey(UUID) / userId / userName 三个字段，不存密码、不存权限；
完整的 LoginUser（含权限）存于 Redis，key 为 login_tokens:{userKey}；
签名算法 HS512，密钥 TokenConstants.SECRET。

四、请求鉴权

重要

（网关 AuthFilter，全局过滤器，order = -200）

每次请求必须经过网关，AuthFilter 做四件事：

白名单放行
- 路径匹配 IgnoreWhiteProperties（如 /auth/login、验证码接口、/code 等）直接放行；
取 token
- 从请求头 Authorization 取，裁掉 Bearer 前缀（getToken）；
双重校验
- JwtUtils.parseToken(token)：验 JWT 签名和过期（签名错 / 过期 → 401 "令牌已过期或验证不正确"）；
- redisService.hasKey(login_tokens:{userKey})：查 Redis 登录态（不存在 → 401 "登录状态已过期"）；
透传用户信息
- 把 userKey / userId / userName 写入请求头（USER_KEY、DETAILS_USER_ID、DETAILS_USERNAME）；
- 移除 FROM_SOURCE 头（防止外部伪造内部调用来源）；
- 放行到下游服务。

五、下游服务取用户

重要

（HeaderInterceptor.preHandle）

每个业务模块都注册了该拦截器，收到网关转发的请求后：

从请求头取出 userId / userName / userKey 放入 SecurityContextHolder（ThreadLocal）；
若请求带 token，再按 login_tokens:{userKey} 从 Redis 取完整 LoginUser；
校验是否快过期（AuthUtil.verifyLoginUserExpire，将过期时自动续期）；
之后业务代码通过 SecurityUtils.getUserId() / getUsername() / getLoginUser() 获取当前用户，无需再解 JWT。

六、权限校验

重要

（@RequiresPermissions + PreAuthorizeAspect）

登录时 getUserInfo 返回的 LoginUser 中携带该用户的菜单权限集合 permissions（存于 Redis）；
Controller 接口标注 @RequiresPermissions("system:user:list") 等注解；
PreAuthorizeAspect 切面从 LoginUser 的 permissions 中校验，无权限返回 403。

七、服务间内部调用

重要

（@InnerAuth）

服务间 Feign 调用由 FeignRequestInterceptor 自动带上 FROM_SOURCE = INNER 头；
内部接口（如 system 的 getUserInfo）用 @InnerAuth 注解保护，InnerAuthAspect 校验 FROM_SOURCE 头；
网关 AuthFilter 会移除外部请求伪造的 FROM_SOURCE，形成闭环——外部永远调不到内部接口。

总结

提示

登录时 auth 校验密码 → 把用户身份存 Redis + 发一个只含身份的 JWT 给前端；之后前端每次带 JWT 请求，网关验 JWT 签名 + 查 Redis 登录态 → 通过后把用户信息塞进请求头转发；下游服务从请求头恢复当前用户，用 @RequiresPermissions 做权限控制；服务间调用靠 @InnerAuth + 内部请求头隔离。

常见问题排查

现象	可能原因	排查方向
网关报"令牌已过期或验证不正确"	JWT 签名密钥不一致 / JWT 过期	检查各服务 `TokenConstants.SECRET` 是否一致；JWT 过期时间
网关报"登录状态已过期"	Redis 中 `login_tokens:` 被清空	检查 Redis 是否重启、过期时间、`login_tokens` key 是否存在
接口报 403	用户权限集合中无对应权限	检查 sys_menu 权限标识、用户角色是否分配
外部请求能调到内部接口	`FROM_SOURCE` 头未被移除 / `@InnerAuth` 缺失	确认网关 AuthFilter 顺序与移除逻辑、内部接口是否加注解
新服务登录态无效	新模块未注册 `HeaderInterceptor`	确认模块是否引入 `ruoyi-common-security` 并启用拦截器