★ FEATURED ARTICLE 简介若依框架是一套全面开源的快速开发平台前端采用Vue和Element UI后端基于Spring Boot、Security、Redis与Jwt。这份部署文档面向需要在Linux或Windows环境中独立完成若依前后端分离项目上线的开发者覆盖从代码打包、代理配置到服务启动的完整流程。文档重点讲解两大典型场景一是Linux加Nginx部署涉及后台Jar包生成、前端Dist构建、Redis与Nginx安装配置以及Nohup后台启动二是Windows加Tomcat部署包括POM改War、Webapps目录整理、Service配置和刷新404问题的修复。同时针对调用第三方API时的跨域困境提供后端CORS、前端Proxy及Nginx反向代理三种应对思路。资源为一份Docx文档压缩包约223KB结构紧凑可直接按步骤操作。已有7764人学习浏览适合具备Spring Boot和Vue基础、希望快速落地若依项目的初中级开发者尤其能避免菜单空白、打包后失效等常见坑。1. 部署若依前后端分离先定 LinuxNginx 还是 WindowsTomcat接手若依RuoYi前后端分离项目部署我遇到最多的问题不是代码写不出来而是环境方案没定清楚就盲目开跑。若依作为一套全部开源、个人和企业都能免费使用的快速开发平台前端用 Vue Element UI后端用 Spring Boot Spring Security Redis Jwt这套组合在真实项目里出现频率极高。但很多开发者在自己的 Windows 开发机上跑得通一上服务器就各种 404、空白页、菜单打不开本质上是没分清两套部署路径Linux 服务器上用 Nginx 做反向代理和 Windows 服务器上用 Tomcat 直接扛。这两套方案从打包方式到配置项完全不同我建议接到部署任务先回答一个问题手头服务器装的是 Linux 还是 Windows没有 Nginx 的话后端接口怎么暴露方案定死后面每一步才有意义。2. 打包后台 jar 和前端 dist装环境之前最容易翻车的两步2.1 后台打包IDEA Terminal 里的 mvn clean package若依后端打包几乎没有第二种选择就是 Maven 打 jar 包。我一般在 IDEA 自带的 Terminal 窗口里执行mvn clean package -DskipTests执行完去项目根目录下的target文件夹里找*.jar文件那个就是后端产物。-DskipTests的意思是跳过单元测试因为我遇到过测试类里连不上测试库导致打包中断的情况既然目标只是部署先跳过去再说。这里有个细节容易被忽略target目录里通常会有两个 jar一个原始 jar带-original后缀或用.original结尾一个是 Spring Boot 可执行 jar。部署要认准不带original的那个否则启动就会报「没有主清单属性」。判断也很简单可执行 jar 一般有 60MB 以上原始 jar 通常只有几百 KB。复制到服务器之前我习惯先本地java -jar跑一遍看端口能不能起这一步能在开发机上暴露数据库配置和 Redis 连接问题省得到服务器上再排查。2.2 前端打包npm run build:prod 与 dist 目录若依前端的打包命令基本固定在ruoyi-ui目录也就是前端工程根目录下执行npm run build:prod --report--report参数会在打包完成后生成一份依赖分析报告report.html主要用来定位打包体积过大问题不需要报告的时候去掉也不影响 dist 生成。打包完成会多出一个dist目录里面是index.html、static目录和一堆编译后的 js/css。整个dist目录就是前端静态资源的全部内容后续复制到服务器上动的就是这一个文件夹。前端打包对 Node.js 版本有要求若依这类 Vue 2 项目建议 Node 14 或 16 LTS太新的 Node 版本可能在node-sass编译阶段直接报错。如果npm run build:prod报 Python 或 binding 相关错误常见做法是删掉node_modules和package-lock.json换 Node 版本后重新npm install这比单修依赖快得多。另外打包前要看一眼vue.config.js里的publicPath这个配置直接决定了 dist 里index.html引用静态资源时前缀对不对后面第三章还会专门讲它的坑。2.3 环境变量检查清单复制部署包前先过一遍打包动作本身不难难的是打包前把运行参数对清楚。我一般先在本地确认几件事后端application.yml里的数据库地址、账号、密码有没有指向正式库。若依默认配置里带了本地 MySQL 连接信息和 Redis 密码项如果服务器上 Redis 没配密码而代码里写死了密码启动时会一直报连接超时。前端.env.production里的VUE_APP_BASE_API也很重要它决定了生产环境请求后端接口用的路径前缀Linux Nginx 方案里通常保持/prod-apiWindows Tomcat 方案里要改成实际部署的上下文路径。有一回我帮一个项目团队排查问题前端都部署上去了登录时报「网络异常」最后发现就是.env.production里把VUE_APP_BASE_API写成了开发环境的http://localhost:8080浏览器访问服务器的页面请求却打回开发者本机自然必挂无疑。这类问题不在第 2 章爆发就一定在第 6 章验证时爆发建议打包前花五分钟把这张环境清单过一遍。3. Linux Nginx 部署Redis、Nginx 配置与后台启停3.1 安装 Redis 并确认缓存连通若依后端的登录验证码、用户 token 都依赖 Redis服务器上没跑 Redis 的话后端服务能启动但登录会一直卡在验证码错误。Linux 下装 Redis 我通常直接走系统源:yum install -y redis systemctl enable redis systemctl start redisUbuntu 系对应把yum换成apt-get install -y redis-server。装好后下一步不是急着启动后端而是先确认 Redis 能存能取。用redis-cli敲一个 ping还做不到的检查bind和protected-mode若依后端和 Redis 在同一台机器上时redis.conf里保持默认只监听127.0.0.1即可后端连接地址填127.0.0.1:6379就行如果 Redis 在其他机器bind要改成内网 IPprotected-mode要设 no否则代码里连接 Redis 会被拒。3.2 安装 Nginx 并修改 conf/nginx.confNginx 在若依这套架构里承担两件事托管前端 dist 静态文件以及把/prod-api/开头的接口请求反向代理到后端 jar 进程。CentOS 上安装yum install -y nginx nginx装完以后修改conf/nginx.conf这是整套部署的核心配置server { listen 80; server_name _; # 前端静态资源 location / { root /home/ruoyi/dist; index index.html; try_files $uri $uri/ /index.html; } # 后端接口反向代理 location /prod-api/ { proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header REMOTE-HOST $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_pass http://127.0.0.1:8080/prod-api/; } }location /里的 root 指向你上传 dist 的绝对路径try_files这行是配给 Vue 路由用的刷新页面时让它回退到index.html。location /prod-api/这一段把前端请求转发到后端 8080 端口注意proxy_pass结尾带着/prod-api/这样前端/prod-api/login经过代理后完整映射到后端接口路径后端不需要额外处理前缀。若后端 jar 改了端口或部署路径只需同步改proxy_pass这一个位置。改完用nginx -t验证语法再nginx -s reload重载这一步别省。3.3 启动 jar 包保活日志重定向别写错后端 jar 的启动命令就是那经典的一行nohup java -jar ruoyi-admin.jar msg.log 21 nohup让它忽略挂断信号让它在后台运行 msg.log 21把标准输出和错误输出都写进当前目录下的msg.log。这样做的直接好处是关掉终端窗口服务不会被杀一旦启动失败还能打开 msg.log 看真实报错。如果是帮别人维护的机器我会再加一层ulimit -n 65535提高文件句柄上限避免高并发下出现 too many open files。启动后等十秒左右先看进程还在不在ps -ef | grep java tail -f msg.log日志里看到Started RuoYiApplication这类字样说明后端已起来。再确认 8080 端口在监听ss -lntp | grep 8080。全套起来后浏览器输入服务器 IP 就能看到若依登录页默认账号admin/admin123进入系统。这里提一下很多人踩过的坑后期在系统里改了菜单或调整了前端代码后重新打包部署发现登录正常但菜单打不开多半是vue.config.js的配置被改动了。若依默认生成的配置里publicPath可能是类似./的写法部署阶段要按实际情况调整把/之前的.去掉再重新打包上传 dist。这行配置改动虽小影响的是打包后 index.html 里所有静态资源的前缀拼接前缀错了浏览器就找不到 js/css表现就是菜单点击无响应或页面空白。另外jar 启动失败时日志里最常出现的几个原因8080端口被占用改端口或先杀掉占用进程redis.clients.jedis.exceptions.JedisConnectionException连不上 Redis回 3.1 检查MySQL 连接串写错导致Communications link failure。msg.log 是整套若依部署里最直接的黑匣子任何页面异常都要先回来翻它。4. Windows Tomcat 部署war 包、service.xml 与刷新 4044.1 修改 pom.xml从 jar 切换到 war没有 Nginx、需要在 Windows 上用 Tomcat 跑时后端打包方式要换。打开后端根目录的pom.xml找到打包类型配置:groupIdcom.ruoyi/groupId artifactIdruoyi-admin/artifactId versionxxx/version packagingwar/packaging关键就是packaging从jar改成war。改完后同样在 Terminal 里执行mvn clean package -DskipTests这次target目录里生成的是ruoyi-admin.war。打包出的 war 复制到 Tomcat 的webapps目录下重命名为prod-api这样 war 解压后访问路径就是http://ip:端口/prod-api与前端请求的后端前缀保持一致。这一步懒得起别名也行但后面改service.xml和前端代理时都要在路径上多绕一层我建议还是按prod-api命名。4.2 复制 dist 到 webapps 并改 service.xml前端部分把dist整个目录复制到 Tomcat 的webapps目录下可以和prod-api并列放着。为了让 Tomcat 启动时直接把项目根路径映射到 dist 内容需要打开 Tomcatconf目录下的service.xml文档里写成 service.xml实际上 Tomcat 安装目录里真实文件是server.xml这两个名字我都见过被混用以conf/server.xml为准。在Host节点内部加上Context path/ docBaseD:/apache-tomcat/webapps/dist reloadabletrue crossContexttrue/ContextdocBase可以填 dist 的绝对路径也可以填相对于 webapps 的路径。path/表示访问根路径时直接加载 dist。这一步不加的话登录页能打开但登录之后画面就空白了——因为本地开发时访问路径是ip:端口/router这一类带路由的地址Tomcat 默认的 Context 映射不处理这种前端路由回退加了这个 Context 等于给前端路由修了一条直达通道。server.xml里还要检查 Tomcat 自身的启动端口默认8080如果和平时的后端端口撞了调Connector port8080那一行的端口值。改完server.xml必须重启 Tomcat 才生效只重启应用没用。4.3 Tomcat 方案刷新 404新建 WEB-INF/web.xml 兜底Tomcat 下部署若依还有一个高频问题登录进系统后正常操作没问题但鼠标点到刷新浏览器按钮十有八九会跳到 404。原因很简单Vue 是单页应用路由切换都在前端内部完成刷新时浏览器按当前 URL 去请求 TomcatTomcat 找不到对应的物理文件自然返回 404。解决方案是在 dist 目录下新建WEB-INF文件夹在里面放一个web.xml把 404 错误页指回前端首页?xml version1.0 encodingUTF-8? web-app xmlnshttp://xmlns.jcp.org/xml/ns/javaee xmlns:xsihttp://www.w3.org/2001/XMLSchema-instance xsi:schemaLocationhttp://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd version3.1 metadata-completetrue display-nameRouter for Tomcat/display-name error-page error-code404/error-code location/index.html/location /error-page /web-app这段配置的逻辑是所有 404 响应统一重定向到index.html由前端路由自己接管 URL 判断。version3.1对应 Tomcat 8.5/9如果你的 Tomcat 版本较老把 web-app 版本降到 3.0 也一样能用。新建完这个文件重启 Tomcat再刷新页面就不会 404 了。整体走完这套 Windows Tomcat 方案访问关系是浏览器请求 Tomcat8080端口根路径/由 Context 映射加载 dist 内容/prod-api下的接口请求走到解压后的 war 应用里。没有 Nginx 承担静态托管和代理Tomcat 一个人把两件事都干了。5. 跨域与排查第三方 API 无法调用时的三处配置5.1 先定位跨域发生在哪一层若依项目里被问到最多的跨域问题是前端页面需要调用第三方开放 API比如地图服务这类外部接口。浏览器控制台报熟悉的No Access-Control-Allow-Origin header is present往往先要分清是后端接口跨域还是第三方 API 跨域。如果是若依前后端之间跨域开发时靠 devServer 代理部署后靠 Nginx 同源转发通常不会暴露而直接在前端代码里axios.get打第三方 API只要第三方没给你开 CORS 头浏览器直接拦截这就是另一套思路了。解决办法有三个层级按项目实际情况选一个最省事的是让后端转发即前端请求自家后端接口后端用 HTTP 客户端去请求第三方 API浏览器全程只和同源后端通信其次是在 Nginx 上做一个专门的转发 location相当于半个网关最后才是依赖第三方主动开放 CORS 头这个多数情况下指望不上。5.2 后端 CORS 配置与 Nginx 转发如果后端要直接承接跨域请求在 Spring Boot 里加一个全局 CORS 配置类Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/**) .allowedOriginPatterns(*) .allowedMethods(GET, POST, PUT, DELETE, OPTIONS) .allowedHeaders(*) .maxAge(3600); } }allowedOriginPatterns比allowedOrigins更宽松允许带凭证的跨域请求生产环境建议缩到具体的域名而不是直接*。这个方法只对若依后端接口生效不会影响第三方 API。对于第三方 API我一般优先在 Nginx 上加转发配置location /third-api/ { proxy_pass https://外部API域名/; proxy_set_header Host 外部API域名; }这样前端代码里把请求地址从https://外部域名/xxx改成/third-api/xxx请求到了自家服务器后由 Nginx 转发浏览器和第三方之间不再直接通信跨域问题从根上消失。前端.env.production里把VUE_APP_BASE_API对应的公共接口前缀设置好即可。5.3 部署避坑菜单打不开、空白页、内存不足记录几条真实项目中重复出现的问题每一条都是「现象 → 原因 → 解决」的结构现象一登录页正常登录后菜单点了没反应。原因出在vue.config.js的publicPath配置不当打包后的 JS/CSS 资源路径带前缀浏览器加载不到资源但页面骨架还在。解决方法是把publicPath调整成部署环境可访问的路径重新打包上传 dist并清一下浏览器缓存或换无痕窗口验证。现象二Windows Tomcat 部署登录成功但跳转后空白页。原因是 Tomcat 没有把根路径映射到 dist前端路由地址在 Tomcat 上找不到对应应用如 4.2 所说在server.xml的Host下加Context配置即可。有人会试图改成 hash 路由来绕但我建议还是修服务器配置保持 history 路由的 URL 干净。现象三页面刷新 404。常见于 Linux 的 Nginx 方案里漏了try_files以及 Tomcat 方案里漏了WEB-INF/web.xml的 404 错误页兜底。这两处都是为了把「文件不存在」交给前端路由处理本质是同一件事。现象四jar 启动几秒后进程消失msg.log 提示内存不足或端口冲突。内存不足时给 JVM 显式设置堆大小例如java -Xms256m -Xmx512m -jar端口冲突时换端口或者netstat -lntp找出占用进程。现象五登录页验证码图片加载不出来。后端日志里能看到连不上 Redis 的异常验证码是存 Redis 的Redis 起不来或者 Spring 配置的连接信息对着空地址时验证码功能就报废。常见做法是redis-cli ping先自证 Redis 存活再看后端application.yml里 Redis 密码是否与服务器一致。6. 验证跑通登录、接口与缓存三件事逐一确认部署完成不是页面能打开就算完我每次部署若依至少走一遍完整验证链路。第一步浏览器输入服务器 IP或 Tomcat 方案下IP:端口能看到若依登录页且验证码图片正常加载第二步用admin / admin123登录系统正常进入首页左侧菜单按权限动态渲染第三步随便点开一个菜单比如用户管理页面列表有数据且操作按钮响应正常。这三步看着基础但任何一个环节断裂后面交到使用者手上就是事故。推荐再往后端加一层接口验证。打开浏览器开发者工具的 Network 面板看登录接口/prod-api/login返回的 JSON 里是否带token字段用curl直接打接口也行curl http://127.0.0.1:8080/prod-api/login -X POST -H Content-Type: application/json -d {username:admin,password:admin123}返回码 200 且响应里出现token字段说明后端逻辑和数据库连接都通了。另一件事是验证 Redis 缓存真的在工作登录一个账号后在服务器上用redis-cli执行keys *能看到若依缓存的 token 或验证码相关 key没有的话多半是后端 Redis 配置没生效或连错了库。Linux 方案下还要顺带验证静态资源是否由 Nginx 正常托管在浏览器里直接访问http://IP/static/js/xxx.js这类路径能下载文件说明 root 配置正确访问一个不存在的路由路径能回退到前端首页而不是 Nginx 404说明try_files生效。之后我再遇到菜单打不开或页面空白这类问题第一反应就是带着这几个验证步骤倒查先curl接口再tail日志再看 Nginx 转发方向问题基本都能定位到某一层。这套验证习惯已经帮我在部署若依时少走了很多弯路希望也能帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
