RuoYi-Vue 本地部署指南：从克隆到跑通权限管理后台

RuoYi-Vue 本地部署指南：从克隆到跑通权限管理后台

【免费下载链接】RuoYi-Vue:tada: (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue & Element 的前后端分离权限管理系统，同时提供了 Vue3 的版本项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue

假设你要给团队搭一个内部后台：要有登录、用户管理、角色权限，还要能在线改代码生成 CRUD 页面，但又不想从零写这些基础功能。RuoYi-Vue（若依）就是干这个的：一套基于 SpringBoot + Spring Security + JWT 的后端，配一套 Vue 前端，把登录认证、菜单权限、代码生成这些"每个后台都绕不开"的功能全部做完了。你跟着这篇做完，本地会有一个可以登录、可以分配权限的权限管理后台，后面开发业务功能时只写自己的表和业务代码即可。

快速开始：从克隆到跑通

这一节解决"环境怎么配、命令怎么敲、怎么确认启动成功"的问题。

环境要求

获取项目与构建

克隆仓库到本地：

git clone https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue cd RuoYi-Vue

先建库再导数据。sql/目录下的ry_20260417.sql是系统主数据表，quartz.sql是定时任务表，两个都要导入，缺了后者定时任务模块会报错：

CREATE DATABASE `ry-vue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; USE `ry-vue`; SOURCE sql/ry_20260417.sql; SOURCE sql/quartz.sql;

注意：application-druid.yml 里默认库名就是ry-vue，建库时保持一致可以少走一步改配置的弯路。

确认 MySQL 和 Redis 都起来了，构建后端：

mvn clean install -Dmaven.test.skip=true

看到BUILD SUCCESS即构建成功。然后启动服务，Windows 双击 ry.bat，Linux/Mac 用：

cd ruoyi-admin/target sh ry.sh start

启动成功的验证标志：终端日志出现 Spring Boot 启动完成信息（Tomcat started on port 8080），接着浏览器访问前端页面（前端仓库另起，见 README.md 的版本分支表），用admin / admin123能登录进系统首页，就算跑通了。

核心能力拆解

这一节挑三个最影响日常开发效率的功能，说明怎么用、代码在哪。

登录认证：JWT 无状态登录

系统登录走 JWT（JSON Web Token，一种服务端签发的令牌，客户端每次请求带上它，服务端验签就知道你是谁，不用每次查会话表）。认证逻辑集中在 ruoyi-framework/src/main/java/com/ruoyi/framework/security/，其中 TokenService.java 负责生成、刷新、校验令牌。

1. 打开登录页，输入admin / admin123和图形验证码（默认是数学运算题，类型在 application.yml 的captchaType: math配置）；
2. 登录成功后请求头会带Authorization，后续接口靠它识别身份；
3. 令牌有效期在 application.yml 的token.expireTime（默认 30 分钟）配置，过期会静默续期。

权限管理：细到按钮的 RBAC

权限模型是 RBAC（Role-Based Access Control，基于角色的访问控制：用户挂角色，角色挂菜单/按钮权限）。相关代码在 ruoyi-system/src/main/java/com/ruoyi/system/service/impl/SysRoleServiceImpl.java，前端页面在独立的 ruoyi-ui 仓库的views/system/下。

1. 用 admin 登录后进入「系统管理 → 部门管理」，搭好公司/部门树；
2. 「角色管理」里新建角色，勾选它能看到的菜单和按钮（比如只给"查看"不给"删除"）；
3. 「用户管理」里新建测试账号并分配该角色，另开浏览器登录它，只能看到和角色匹配的菜单——看到按钮消失了，说明权限生效。

代码生成：一张表变一套 CRUD

ruoyi-generator/ 是代码生成模块，能把一张数据库表变成后端 Controller/Service/Mapper 加前端页面，省掉重复的增删改查。核心逻辑在 GenTableServiceImpl.java，模板用 Velocity 渲染（VelocityInitializer.java）。

1. 把你的业务表导入 MySQL，登录后台进入「系统工具 → 代码生成」，点「导入」选表；
2. 在生成配置里调整字段类型、是否查询条件、表单控件，然后「预览」；
3. 点「下载」得到 zip，解压后按提示把 java 代码、vue 页面、sql 各自放入对应位置并执行 sql，重启即可在菜单里看到新模块。

进阶配置：按需修改

这一节覆盖两个几乎人人都要改的配置：服务端口和数据源。

改后端端口

端口被占用是最常见的启动失败原因，直接改配置最干净。编辑 ruoyi-admin/src/main/resources/application.yml：

server: port: 9090 # 原来是 8080

改完重启（sh ry.sh restart），浏览器访问http://localhost:9090/captchaImage能返回验证码图片 JSON，说明端口已切换。注意前端项目里代理的后端地址也要同步改，否则前后端对不上。

换数据库地址与账号

数据源配置在 ruoyi-admin/src/main/resources/application-druid.yml，最小改动就是 master 这三行：

master: url: jdbc:mysql://192.168.1.100:3306/ry-vue?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8 username: root password: 你的密码

Redis 地址在 application.yml 的spring.data.redis段，默认localhost:6379无密码，远程部署时记得改。改完重启，用 admin 登录能看到用户列表数据，说明数据源切换成功。

常见问题排查

现象 → 原因 → 解决：

1. 启动报Access denied for user或Unknown database→ 数据库没建库导数据，或账号密码与 application-druid.yml 不一致 → 按「快速开始」一节建ry-vue库并导入两个 sql，确认用户名密码一致。
2. 启动卡在 Redis 连接超时报错→ 本机 Redis 没启动或端口不是 6379 → 启动 Redis 服务；远程 Redis 则改 application.yml 中host和password。
3. 登录一直提示验证码错误→ 验证码存 Redis，Redis 挂了或captchaType配成了char而你按数字算 → 确认 Redis 存活；查看 application.yml 里captchaType是math（数学题）还是char（字符）。
4. 改完端口或数据源不生效→ 改了配置文件但没重启，或改错了文件（application.yml与application-druid.yml分工不同）→ 重启服务；数据源相关确认改的是 druid 那个文件。
5. 上传头像/附件报路径不存在→ application.yml 里ruoyi.profile默认是D:/ruoyi/uploadPath，Linux 上没有这个目录 → 改成实际存在的路径，如/home/ruoyi/uploadPath并提前创建。

小结

到这里，你已经在本地跑起来一套带登录认证、角色权限、代码生成的管理后台：数据库和 Redis 配好了，端口、数据源、上传路径这几个高频配置点也知道了在哪里改。下一步可以看看 ruoyi-quartz/ 里的定时任务模块怎么在线配置 cron 任务，或者照着代码生成流程把你自己的第一张业务表变成可操作的页面。更多功能列表和版本分支说明见 README.md，环境细节可参考 doc/若依环境使用手册.docx。有踩坑经验欢迎在评论区聊聊。

【免费下载链接】RuoYi-Vue:tada: (RuoYi)官方仓库 基于SpringBoot，Spring Security，JWT，Vue & Element 的前后端分离权限管理系统，同时提供了 Vue3 的版本项目地址: https://gitcode.com/GitHub_Trending/ru/RuoYi-Vue