做后台管理系统开发的朋友对若伊框架应该都不陌生。这套基于Spring Boot的快速开发平台在中小型项目和企业内部系统里出镜率极高前一段时间我连续帮两个团队处理过部署问题一个直接用Tomcat一个上了Nginx做前置代理踩了不少坑也把整套链路摸清了。今天专门聊聊若伊框架的部署重点就是两个方向单Tomcat怎么搞TomcatNginx怎么搞各自的配置要点、常见报错、选型逻辑一次讲透。先交代一下背景我这里说的若伊框架以最常见的RuoYi-Vue单体版本为例技术栈是Spring Boot 2.x Vue MySQL Redis。部署环境我默认是Linux服务器Windows上思路完全一样命令换成对应的脚本就行。适合谁看刚接触若伊框架、不知道怎么把项目从开发环境搬到服务器的同学以及正在纠结要不要上Nginx、或者已经上了Nginx但遇到404/502问题的朋友。这篇文章不是教科书就是我实战过程的一次完整复盘。1. 部署前先搞懂若伊框架到底该用什么方式跑起来1.1 若伊框架的技术底座与两种部署形态若伊框架的核心是Spring Boot而Spring Boot自带内嵌Tomcat。这意味着一个打包好的Jar包直接java -jar就能跑根本不需要额外装Tomcat。那为什么市面上还会大量存在“把war包丢进外置Tomcat”的部署方式因为很多公司的运维体系是围绕Tomcat建的统一的应用目录、统一的启动脚本、统一的端口管理甚至日志收集、监控报警都基于Tomcat的目录结构。在这种情况下让开发把项目打成war包塞进既有Tomcat里是运维成本最低的选择。所以你会看到两种主流部署形态Jar包方式nohup java -jar ruoyi-admin.jar --server.port8080 适合个人学习、Docker容器、纯内网小规模部署。War包方式把Spring Boot项目的打包方式改成war放到Tomcat的webapps目录由外置Tomcat启动适合既有运维体系、需要多应用共存的场景。而TomcatNginx的组合本质上是在war包方式之上再加一层前置服务负责静态资源托管、反向代理、负载均衡、HTTPS终结。本文的核心脉络就是先把war包方式的Tomcat部署讲清楚再叠加Nginx讲生产环境的完整架构。1.2 选Tomcat还是直接Java -jar场景决定方案很多刚接触若伊框架的人会问Spring Boot都内嵌Tomcat了为什么还要单独装一个我的回答是单独装Tomcat不是为了“多此一举”而是为了“可控”。直接Java -jar虽然简单但应用进程和前端的静态资源全部挤在一个端口上上传文件路径、静态资源路径、接口路径全混在一起线上出了问题不好定位。举一个很实际的例子若伊框架的前端是Vue打包后的dist目录如果直接扔进Jar包里访问Tomcat要同时处理接口请求和静态文件读取。一旦访问量上来IO会成为瓶颈。而引入Nginx之后静态资源交给Nginx处理Tomcat专心跑Java接口两边各司其职这就是生产环境推荐TomcatNginx的根本原因。所以我的建议很直接个人学习、测试环境用Java -jar跑最快公司服务器、正式项目优先考虑Tomcatwar包再在前面挂Nginx。2. 环境准备从零装好JDK、Maven、Tomcat与Nginx2.1 JDK版本与Maven构建环境若伊框架RuoYi-Vue对应的是Spring Boot 2.x官方要求JDK 1.8实际用JDK 8或JDK 11都能跑。但这里有个隐藏雷区Tomcat的版本兼容性。Tomcat 9及以下用的是javax.servlet命名空间Tomcat 10开始换成了jakarta.servlet。而若伊框架老版本里的Servlet依赖通通是javax所以如果装了Tomcat 10war包部署后大概率直接启动失败报各种NoClassDefFoundError。结论部署若伊框架老老实实用Tomcat 8.5或9.0。环境变量方面Linux下建议把Java和Tomcat的路径写进/etc/profileexport JAVA_HOME/usr/local/jdk1.8.0_202 export CATALINA_HOME/usr/local/tomcat9 export PATH$JAVA_HOME/bin:$CATALINA_HOME/bin:$PATHMaven版本建议3.6以上。构建前检查一下settings.xml把中央仓库换成阿里云镜像否则拉Spring Boot依赖的时候那个速度会让人怀疑人生。mirror idaliyunmaven/id mirrorOf*/mirrorOf urlhttps://maven.aliyun.com/repository/public/url /mirror2.2 Tomcat安装及配置教程从下载到启动Tomcat的安装本身不复杂难的是理解它的目录结构。下载地址是tomcat.apache.org注意选择Core里的tar.gz或zip包Windows直接解压Linux解压到指定的/usr/local/tomcat9目录即可。启动关闭的命令/usr/local/tomcat9/bin/startup.sh /usr/local/tomcat9/bin/shutdown.shWindows对应的是startup.bat和shutdown.bat。启动后怎么判断是否成功先看日志tail -f /usr/local/tomcat9/logs/catalina.out出现Server startup in [xxx] milliseconds基本就稳了再访问http://localhost:8080能看到Tomcat默认首页说明安装成功。2.3 Nginx下载与安装Windows和Linux两条路线Nginx的高频玩法是反向代理和静态资源托管。Windows下直接到nginx.org下载Windows版zip解压后结构很简洁nginx.exe双击就运行默认监听80端口。Linux下推荐用系统包管理器比如AlmaLinux 9dnf install -y nginx systemctl enable nginx --now装完先不急着配置用nginx -t测试配置语法通过后再systemctl reload nginx重载。这里要特别强调Nginx的配置文件在/etc/nginx/conf.d/下强烈建议为若伊框架单独建一个配置文件比如ruoyi.conf不要全部堆在nginx.conf里否则后期维护非常痛苦。我见过太多人把所有server块全写进主配置文件改一个站点要重启整个Nginx风险极高。3. 若伊框架打包实操从源码到可部署产物3.1 源码结构解析与打包命令若伊框架的源码结构很清晰核心模块包括ruoyi-admin后台管理入口、ruoyi-framework框架核心、ruoyi-system系统管理模块、ruoyi-common公共模块、ruoyi-quartz定时任务、ruoyi-generator代码生成。打包时通常只关注顶层父工程和ruoyi-admin模块因为admin是最后的启动入口。命令行进入项目根目录mvn clean package -Dmaven.test.skiptrue构建完成后ruoyi-admin/target目录下会生成可部署产物。默认情况下若伊框架是Jar包如果要部署到外置Tomcat必须做两件事第一在ruoyi-admin/pom.xml里把打包方式从jar改成warpackagingwar/packaging第二修改启动类RuoYiApplication.java让它继承SpringBootServletInitializer并重写configure方法SpringBootApplication public class RuoYiApplication extends SpringBootServletInitializer { Override protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) { return builder.sources(RuoYiApplication.class); } }这两个改动缺一不可。我自己第一次改的时候只改了pom.xml结果启动类还是原来的写法war包虽然在Tomcat里解压了但应用始终没有起来日志里也没有任何明显报错最后排查半天才反应过来是启动类没有适配Servlet容器环境。3.2 数据库初始化与Redis配置若伊框架部署前必须初始化数据库。源码的sql目录下有两个文件一个是以ry_开头的系统表初始化脚本比如ry_2021xxxx.sql另一个是quartz.sql负责定时任务所需的表。用命令行导入MySQLmysql -u root -p create database ry default character set utf8mb4; use ry; source /path/to/sql/ry_2021xxxx.sql; source /path/to/sql/quartz.sql;数据库编码强烈建议统一utf8mb4不只是因为表情符号更关键的是中文排序和存储兼容性。等数据库建好再打开ruoyi-admin/src/main/resources/application-druid.yml确认连接串url: jdbc:mysql://localhost:3306/ry?useUnicodetruecharacterEncodingutf8 username: root password: your_passwordRedis的配置在application.yml里redis: host: localhost port: 6379 password:这里有个部署新手必踩的坑Tomcat起来了前端页面也打开了但验证码出不来点登录一直转圈。十有八九是Redis没启动或者密码不对。若伊框架的验证码、会话缓存全都要用RedisRedis挂了系统就瘫痪。3.3 修改application.yml中的关键参数打包前还有一个容易被忽略的配置项文件上传路径。若伊框架上传的头像、图片等文件默认存放位置是当前项目目录下的profile文件夹。开发环境无所谓生产环境如果直接跑重启或升级war包时上传文件很可能丢失。所以一定要改成服务器上的绝对路径ruoyi: profile: /data/ruoyi/upload另外启动端口server.port在war包部署到外置Tomcat的环境下会失效因为对外端口由Tomcat决定。很多人改完application.yml里的8081端口发现Tomcat还是8080还以为没生效其实是理解错了war包部署模式下内嵌容器的配置被外置Tomcat覆盖了这个逻辑要提前搞清楚。4. Tomcat部署若伊框架的完整过程4.1 war包部署步骤打包成功后ruoyi-admin/target/ruoyi-admin.war就是我们要的产物。把它拷贝到Tomcat的webapps目录下启动Tomcat后它会自动解压出一个同名目录。这一步的默认访问路径是http://服务器IP:8080/ruoyi-admin/注意路径里必须带应用上下文名称ruoyi-admin。如果你希望直接通过根路径访问也就是http://服务器IP:8080/直达登录页有几种做法把war包重命名为ROOT.war再放入webapps这是最省事的方式。修改server.xml里的Host配置添加Context指定docBase为解压后的目录。实际项目里我一般会把war包改成ROOT.war这样路径最短Nginx反向代理配置也简单很多。4.2 JVM内存与Tomcat启动参数调优默认Tomcat的JVM参数非常保守启动内存只有256M左右。若伊框架包含定时任务、代码生成、接口服务跑一段时间后就可能内存不足严重的直接OOM崩溃。部署时建议调整JVM参数。Linux下在Tomcat的bin目录新建一个setenv.sh文件export JAVA_OPTS-Xms1024m -Xmx2048m -XX:MetaspaceSize256m -XX:MaxMetaspaceSize512mTomcat启动时如果检测到setenv.sh会自动读取里面的JAVA_OPTS无需修改启动脚本。这个参数怎么定建议根据服务器内存来4G内存的机器-Xms和-Xmx可以设2048M8G内存的机器设4096M。JVM参数设置过大反而会造成浪费太小又扛不住并发这个度要结合你实际部署的服务器配置来调。4.3 启动日志与访问验证部署后的验证流程很重要。启动Tomcat后不要急着打开浏览器先看日志tail -f /usr/local/tomcat9/logs/catalina.out看到Deployment of web application archive [webapps/ROOT.war] has finished说明war包部署完成。然后访问http://localhost:8080/页面能出现若伊框架的登录页再用默认账号admin / admin123登录。如果登录时验证码能出来、密码也对但一直卡在登录请求上那就检查Redis连接。如果页面能打开但样式错乱或者接口404那就是打包时前端静态资源没打进war包或者Nginx路径配置有问题这一块放到后面单独说。5. TomcatNginx组合部署生产环境的标配5.1 为什么生产环境要引入NginxTomcat单独能跑但离“生产可用”还差几步第一HTTPS证书的配置在Tomcat里虽然能做但证书续期、多域名管理都比较笨重Nginx处理证书要灵活得多第二若伊框架的前端是静态资源由Nginx直接返回要比Tomcat处理快得多第三一旦未来需要扩容Nginx可以轻松配置多台Tomcat做负载均衡而Tomcat本身做负载均衡要引入额外组件。所以我的建议是单机测试用Tomcat正式环境必须上Nginx。这不是炫技而是让每个组件做自己最擅长的事。5.2 Nginx详细配置教程server与location的规划一份可以套用的Nginx配置放在/etc/nginx/conf.d/ruoyi.confserver { listen 80; server_name yourdomain.com; # 前端静态资源 location / { root /data/ruoyi/dist; index index.html; 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; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } # 上传文件访问 location /profile/ { proxy_pass http://127.0.0.1:8080/profile/; } }逐行解释一下location /匹配前端页面请求root指向Vue打包后的目录try_files这一行很关键它保证Vue Router在history模式下刷新非首页路径不会出现404。location /prod-api/是若伊框架默认的接口前缀前端所有Ajax请求都带这个前缀这里通过proxy_pass转发到Tomcat且末尾的/会把/prod-api/前缀替换掉后端Controller直接按/路径接收请求不用改路由。这里有个细节非常容易出错proxy_pass http://127.0.0.1:8080/;末尾的斜杠和proxy_pass http://127.0.0.1:8080;不带斜杠效果完全不一样。带斜杠表示把/prod-api/xxx转发成/xxx不带斜杠会保留完整路径。项目里一定要根据你后端实际的路由来决定否则就是404和接口地址对不上的问题。5.3 静态资源与接口分离后的路径问题引入Nginx后常见的路径问题有三个。第一个是前端请求接口的baseURL。Vue项目里环境变量文件.env.production中会配置VUE_APP_BASE_API /prod-api这个前缀必须和Nginx里location /prod-api/对应上否则前端请求发出去根本到不了后端。第二个是上传文件的访问路径。若伊框架上传图片后前端访问路径通常是/profile/upload/xxx.jpg所以Nginx里需要额外加一条location /profile/转发到Tomcat。如果连这层图片访问都想省掉Tomcat的IO可以直接用alias指向本地磁盘目录location /profile/ { alias /data/ruoyi/upload/; }这样图片由Nginx直接返回文件不再经过Java进程性能最好。第三个是跨域。如果开发环境是localhost:8080前端直连后端生产环境通过Nginx同域部署跨域问题通常自动消失。但如果你用了独立域名做API服务比如api.yourdomain.com那就需要在Nginx或后端单独配CORS这个要提前设计好。6. 常见问题与排查技巧实录6.1 Tomcat启动出现异常的处理部署中最常见的问题是Tomcat版本不兼容。Tomcat 10的用户会发现war包无法启动日志里报java.lang.NoClassDefFoundError: javax/servlet/...这就是因为Spring Boot 2.x若伊框架用的是javax命名空间Tomcat 10换成了jakarta彻底不兼容。解决办法很简单降级到Tomcat 9。第二个常见问题是端口被占用。Linux下先查端口netstat -tlnp | grep 8080 lsof -i:8080找到占用进程后要么kill要么修改Tomcat的server.xml里Connector的port。Windows下用netstat -ano | findstr 8080查PID再到任务管理器里结束进程。6.2 中文乱码、数据库连接失败与端口占用中文乱码分两类。第一类是Tomcat日志乱码Windows下尤为普遍。打开conf/logging.properties把java.util.logging.ConsoleHandler.encoding改成UTF-8再重启Tomcat。第二类是数据库中文乱码通常有两种原因一种是连接串没加characterEncodingutf8另一种是数据库表本身就是latin1编码。解决方式是把库表和连接串都统一成utf8mb4。数据库连接失败是另一个高频问题。报错一般类似Access denied for user rootlocalhost或Communications link failure。前者是账号密码或权限问题后者是连接地址不对或者MySQL服务没启动。建议先用命令行工具在服务器本机试一下mysql -u root -p能连上数据库再看应用配置连不上就先去解决MySQL本身的问题。这个方法能帮你快速缩小排查范围。6.3 反向代理后的404与502排查NginxTomcat部署后浏览器打开页面正常但一调接口就404这基本是proxy_pass路径拼接的问题。想快速验证可以用curl模拟curl http://127.0.0.1:8080/system/user/list如果后端直接访问正常而通过Nginx访问404那一定是proxy_pass末尾的斜杠问题。记住一个口诀location带前缀、proxy_pass带斜杠去掉前缀不带斜杠保留前缀。502 Bad Gateway则是反向代理中最常见的错误。502表示Nginx能连到上游但上游没响应通常原因包括Tomcat没启动、Tomcat启动失败、Tomcat端口写错。排查顺序是先看Tomcat进程是否存在再curl后端端口是否通最后看Nginx配置文件里的地址和端口是否和Tomcat一致。6.4 关于Tomcat与Nginx配合的面试考点顺带说一句很多读者是在准备面试时搜到这篇博文的。围绕Tomcat和Nginx面试官喜欢问的无非是反向代理和正向代理的区别。Nginx负载均衡的几种策略轮询、权重、ip_hash、fair。Tomcat的默认端口为什么是8080Connector运行模式有哪些。Nginx如何处理高并发为什么能比Tomcat抗压。这些问题的答案网上都有但真正能讲出细节的人不多。我建议你在本地完整部署一遍TomcatNginx环境亲手配置一次反向代理感受一下proxy_pass两种写法导致的路径差异。面试时能把这个细节讲清楚比背一百道八股文都管用。7. 部署方案对比与影响范围分析7.1 三种部署方式的成本与适用场景最后用一张表格梳理一下几种部署方式的差异部署方式上手难度启动速度静态资源性能多实例扩展HTTPS支持适用场景Java -jar 直接跑最低快一般需自行处理需自行配置学习、测试、Docker单Tomcat部署war包较低中一般较难配置麻烦小规模内网系统TomcatNginx中等中好方便灵活正式生产环境从成本角度看单Tomcat的维护成本最低但对将来扩展不友好TomcatNginx前期多了一层配置但换来的是更清晰的架构、更灵活的静态资源处理、更平滑的扩容能力。如果项目上线后有明确的用户增长预期我建议从一开始就上Nginx省得后面再改架构。7.2 对运维和开发的影响范围部署方案的选型直接影响的不只是服务器还有前后端团队的协作方式。上了Nginx之后前端发布只需要把新的dist目录替换到Nginx的root路径整个发布过程可以不重启Tomcat后端发布则只需要替换war包配合Tomcat的优雅停机能做到很短的窗口期。这对发布流程的改善非常明显。另外上传文件的存储位置如果规划到Nginx的alias目录备份、迁移、磁盘扩容都会变得简单。记录访问日志时Nginx的access.log可以单独记录静态资源请求和接口请求做安全审计、访问分析时数据也更干净。所以别小看一个Nginx它对整个项目的影响范围比想象中大得多。如果以后再遇到部署问题我个人的建议是先理清架构再动手配置最后用日志验证。Java -jar适合跑通流程Tomcat适合传统运维NginxTomcat适合正式生产。没有绝对的正确答案只有最适合当前环境的选择。