你想了解若依（RuoYi）框架部署过程中的常见问题及解决方案，我会按「环境配置、前后端部署、运行异常、数据 / 权限问题」四大高频场景，梳理每个问题的现象、原因和可直接落地的解决方法，覆盖前后端分离版（Spring Boot + Vue）的核心部署痛点：

若依最新源码下载：

https://gitee.com/ruoyieleadmin/ruoyi-ele-admin

一、环境配置类问题（部署前最易踩坑）

问题 1：JDK 版本不兼容导致后端启动失败

• 现象：启动 ruoyi-admin.jar 时报 UnsupportedClassVersionError，或日志提示 “JDK 版本低于 1.8/17”。
• 原因：若依不同版本对 JDK 要求不同（3.x 用 JDK8，4.x + 推荐 JDK17），环境 JDK 版本不匹配。
• 解决方案：
  1. 查看若依版本对应的 JDK 要求（官网 README 或 pom.xml）；
  2. 安装对应 JDK 并配置环境变量：

• # 示例：配置JDK17环境变量（Linux）
  export JAVA_HOME=/usr/local/jdk-17.0.8
  export PATH=$JAVA_HOME/bin:$PATH
  # 验证
  java -version

  启动 jar 包时指定 JDK 路径：/usr/local/jdk-17.0.8/bin/java -jar ruoyi-admin.jar。

问题 2：Redis 未启动 / 配置错误导致后端初始化失败

• 现象：启动日志报错 Could not connect to Redis 或 Redis connection timeout。
• 原因：Redis 服务未启动、端口 / 密码配置错误、防火墙拦截。
• 解决方案：
  1. 检查 Redis 是否启动：systemctl status redis（Linux）/ 查看 Redis 服务（Windows）；
  2. 核对 application.yml 中 Redis 配置：

     yaml

     spring:
       redis:
         host: 127.0.0.1 # 改为实际Redis地址
         port: 6379
         password: 123456 # 无密码则注释
         timeout: 5000
     

  3. 开放 Redis 端口（Linux）：firewall-cmd --add-port=6379/tcp --permanent && firewall-cmd --reload；
  4. 测试 Redis 连接：redis-cli -h 127.0.0.1 -p 6379 -a 123456。

问题 3：前端打包后访问空白 / 样式错乱

• 现象：Vue 前端 npm run build 打包后，Nginx 部署访问页面空白，控制台报 404（js/css 文件找不到）。
• 原因：前端打包路径配置错误、Nginx 反向代理配置不当。
• 解决方案：
  1. 修改前端 .env.production 配置（解决路径问题）：

     js

     # 若依前端根目录/.env.production
     VUE_APP_BASE_API = '/prod-api' // 后端接口代理前缀
     VUE_APP_PUBLIC_PATH = '/' // 打包根路径，若部署在子目录则改为'/ruoyi/'
     

  2. 重新打包：npm run build:prod；
  3. 修正 Nginx 配置（解决静态资源加载）：

     nginx

     server {
         listen 80;
         server_name ruoyi.example.com;
         # 前端静态文件路径
         root /usr/local/ruoyi/dist;
         index index.html;
         # 解决Vue路由刷新404
         location / {
             try_files $uri $uri/ /index.html;
         }
         # 反向代理后端接口
         location /prod-api/ {
             proxy_pass http://127.0.0.1:8080/; # 后端地址
             proxy_set_header Host $host;
             proxy_set_header X-Real-IP $remote_addr;
         }
     }

问题 4：后端 jar 包启动后端口被占用

• 现象：启动日志报错 Address already in use，提示 8080/9090 端口被占用。
• 原因：端口被其他程序占用，或若依多实例启动冲突。
• 解决方案：
  1. 查找占用端口的进程：

     bash

     运行

     # Linux
     netstat -tlnp | grep 8080
     # Windows
     netstat -ano | findstr "8080"
     

  2. 杀死占用进程（Linux）：kill -9 进程ID（Windows：任务管理器结束进程）；
  3. 临时修改启动端口：java -jar ruoyi-admin.jar --server.port=8081；
  4. 永久修改：修改 application.yml 中 server.port 配置。

问题 5：Docker 部署后容器启动即退出

• 现象：docker run 启动若依容器后，docker ps -a 显示容器状态为 Exited。
• 原因：Dockerfile 未配置前台运行、容器内依赖缺失、日志权限不足。
• 解决方案：
  1. 确保 Dockerfile 中启动命令为前台运行（关键）：

     dockerfile

     # 错误示例（后台运行会导致容器退出）
     # java -jar ruoyi-admin.jar &
     # 正确示例
     CMD ["java", "-jar", "ruoyi-admin.jar"]
     

  2. 查看容器日志定位问题：docker logs 容器ID；
  3. 启动容器时挂载日志目录并赋予权限：

     bash

     运行

     docker run -d -p 8080:8080 \
     -v /data/ruoyi/logs:/usr/local/ruoyi/logs \
     --name ruoyi-admin \
     ruoyi-image:v1.0
     

问题 6：登录后提示 “token 无效 / 过期”，无法访问接口

• 现象：前端登录成功，但访问菜单 / 接口时提示 “token 失效”，后端日志报 JWT signature does not match locally computed signature。
• 原因：JWT 密钥不一致、token 过期时间配置过短、前端请求头未携带 token。
• 解决方案：
  1. 核对前后端 JWT 密钥（若依 application.yml）：

     yaml

     ruoyi:
       jwt:
         secret: abcdefghijklmnopqrstuvwxyz # 前后端需一致，前端在utils/auth.js中
         expireTime: 7200 # token过期时间（秒），建议改长（如86400）
     

  2. 检查前端请求头是否携带 token（若依已封装，需确保 request.js 中配置正确）：

     js

     // 前端src/utils/request.js
     headers: {
         'Authorization': 'Bearer ' + getToken(),
         'Content-Type': 'application/json'
     }
     

  3. 清理前端缓存（LocalStorage），重新登录。

问题 7：导出 Excel/DBF 文件提示 “文件不存在 / 下载失败”

• 现象：点击导出按钮后，前端提示下载失败，后端日志报 FileNotFoundException。
• 原因：若依临时文件目录权限不足、磁盘空间不足。
• 解决方案：
  1. 检查若依临时目录配置（application.yml）：

     yaml

     ruoyi:
       profile: /data/ruoyi/uploadPath # 确保该目录存在且有读写权限
     

  2. 赋予目录权限（Linux）：chmod -R 777 /data/ruoyi/uploadPath；
  3. 检查磁盘空间：df -h（Linux），清理磁盘释放空间。

问题 8：数据库连接失败 / 表不存在

• 现象：后端启动报错 Access denied for user 'root'@'localhost' 或 Table 'ruoyi.sys_user' doesn't exist。
• 原因：数据库账号密码错误、未执行若依初始化 SQL 脚本、数据库驱动不兼容。
• 解决方案：
  1. 核对数据库配置（application.yml）：

     yaml

     spring:
       datasource:
         url: jdbc:mysql://127.0.0.1:3306/ruoyi?useUnicode=true&characterEncoding=utf8&useSSL=false
         username: root
         password: 123456
         driver-class-name: com.mysql.cj.jdbc.Driver # MySQL8.0+用这个，5.x用com.mysql.jdbc.Driver
     

  2. 执行若依根目录下的 sql/ruoyi.sql 初始化脚本；
  3. 测试数据库连接：mysql -uroot -p123456 -h127.0.0.1 ruoyi。

问题 9：菜单 / 按钮权限不生效

• 现象：登录后看不到配置的菜单，或点击按钮提示 “没有权限”。
• 原因：权限数据未刷新、Redis 缓存未清理、注解配置错误。
• 解决方案：
  1. 清理 Redis 缓存（删除权限相关 key）：

     bash

     运行

     redis-cli
     keys *menu* # 查看权限缓存key
     del sys_menu_cache # 删除菜单缓存
     

  2. 核对角色 - 菜单 - 权限关联数据（数据库 sys_role_menu 表）；
  3. 检查接口上的 @PreAuthorize 注解是否与权限标识一致：

     java

     运行

     // 注解权限标识需与sys_menu表中的perms字段一致
     @PreAuthorize("@ss.hasPermi('system:user:list')")
     

总结

1. 若依部署核心坑点集中在环境匹配（JDK/Redis/ 数据库）、路径配置（前端打包 / Nginx）、权限缓存（JWT/Redis） 三大类；
2. 排查问题优先看日志：后端日志（logs/ruoyi.log）、前端控制台日志、Nginx 日志（/var/log/nginx/）；
3. 通用排查步骤：先验证基础环境（JDK/Redis/ 数据库）→ 核对配置文件 → 检查权限 / 路径 → 查看日志定位具体错误。

若依最新源码下载：

https://gitee.com/ruoyieleadmin/ruoyi-ele-admin