若伊框架生产部署实战：Tomcat+Nginx整合方案与踩坑指南

1. 部署前的方案选型什么时候该用纯 Tomcat什么时候必须上 Nginx接触过若伊框架RuoYi的朋友都知道这个基于 Spring Boot 的后台管理系统开发起来确实快代码结构清晰前端 Vue 后端 Boot 分工明确。但到了部署环节好多人就卡住了特别是第一次搞生产环境的人光看到“tomcat / tomcatnginx”两种模式就开始懵到底有什么区别我该选哪种先说结论这两种部署方式对应的场景非常清晰。若伊框架本身是前后端分离架构后端打包出来是一个 Spring Boot 可执行 jar 包也可以打成传统 war 包丢进 Tomcat 的 webapps 目录跑。但生产环境里头很少有人真拿一个裸 Tomcat 直接对公网提供服务。原因很简单Tomcat 擅长的是跑 Java 应用处理静态资源、并发连接、请求转发这些活儿它干得不算差但跟 Nginx 比起来效率和灵活性都差一截。Nginx 处理静态文件的性能极强内存占用小抗并发能力强还能做反向代理、负载均衡、SSL 证书终结这些都是生产环境刚需。所以方案选型其实就一句话开发环境和内网小规模使用纯 Tomcat 足够了部署简单、排查方便。面向公网、用户量稍大、需要 HTTPS 或者多节点扩展的场景直接上 Tomcat Nginx让 Nginx 在前面挡流量、分发请求、托管前端静态文件Tomcat 在后面专心跑接口。这两种方案我都实打实部署过下面把每一步都拆开讲包括踩过的坑。2. 环境准备与打包构建先把若伊应用变成能部署的形态2.1 环境清单JDK、Maven、Tomcat、Nginx 版本怎么选部署若伊框架第一步不是急着装 Tomcat而是把基础环境捋清楚。我这边实测的版本组合给大家做个参考JDK若伊框架基于 Spring Boot 2.xJDK 1.8 和 JDK 11 都能跑。我生产环境用的是 JDK 11因为 Spring Boot 2.7 对 JDK 11 的支持更完善垃圾回收器选择也更多。如果你还在用 JDK 8也没问题但不建议再往下降。Maven3.6 以上版本都行主要用来打包。如果本地没配私服注意把阿里云镜像配好不然拉依赖能把你等哭。Tomcat我用的是 Tomcat 9.0.x对应 Servlet 4.0 规范和 Spring Boot 2.x 搭配非常顺。Tomcat 8.5 也可以但不推荐再用 Tomcat 7 了JDK 版本和规范都太老。Nginx1.20 以上版本即可稳定版用 1.24.x 或 1.26.x 都行。操作系统建议 CentOS 7.9 以上或者直接用 Rocky Linux、AlmaLinux 这些别再用老旧的 CentOS 6 死磕。注意JDK 版本和 Tomcat 版本必须兼容。比如 Tomcat 9 需要 JDK 8 以上Tomcat 10 对应的是 Jakarta EE 规范若伊框架毕竟还依赖 javax.* 命名空间直接上 Tomcat 10 会报 ClassNotFoundException这一点务必记住。2.2 后端打包区分 jar 包和 war 包的关键操作若伊框架的代码结构里ruoyi-admin 是启动模块打包的动作基本都在这个模块上完成。默认情况下若伊的 pom.xml 配置的是 jar 包方式配合内置 Tomcat 直接java -jar就能启动。但如果要走外置 Tomcat 部署需要先把打包方式改成 war。具体操作分三步第一步修改 ruoyi-admin 的 pom.xml把packagingjar/packaging改成packagingwar/packaging。第二步在 ruoyi-admin 的启动类RuoYiApplication上继承SpringBootServletInitializer并重写configure方法。核心代码如下SpringBootApplication public class RuoYiApplication extends SpringBootServletInitializer { public static void main(String[] args) { SpringApplication.run(RuoYiApplication.class, args); } Override protected SpringApplicationBuilder configure(SpringApplicationBuilder builder) { return builder.sources(RuoYiApplication.class); } }第三步在打包前检查application.yml里的端口配置。外置 Tomcat 部署时Spring Boot 内置的 server.port 配置会失效实际端口由 Tomcat 决定。如果你用 jar 包方式端口还是由server.port控制。这里有个非常容易踩的坑改成 war 包后打包命令要清理掉旧的 target 目录不然会有脏文件打进去。我习惯用mvn clean package -Dmaven.test.skiptrue跳过测试加快打包速度。打包完成后war 包会出现在ruoyi-admin/target/目录下文件名一般是ruoyi-admin.war。2.3 前端打包Vue 项目的构建与产物处理若伊框架的前端在ruoyi-ui目录下基于 Vue 2 Element UI。打包前先确认 Node.js 版本建议用 14.x 或 16.xNode 版本太高比如 18可能会导致 node-sass 编译报错。前端打包命令npm install --registryhttps://registry.npmmirror.com npm run build:prod打包完成后dist目录就是最终的前端产物。注意build:prod用的是.env.production里的配置这里最关键的是VUE_APP_BASE_API它决定了前端请求后端接口的地址。开发环境一般是/dev-api通过代理转发生产环境建议改成实际的后端访问路径比如http://your-server-ip:8080或者更优雅的做法是配成同域路径由 Nginx 做转发我在后面的 Nginx 配置里详细说。3. Tomcat 单机部署小规模场景的快速落地3.1 Tomcat 安装与目录结构速览在 Linux 上装 Tomcat最简单的方式就是下载 tar.gz 包解压即用。我一般放在/usr/local/tomcat目录下wget https://archive.apache.org/dist/tomcat/tomcat-9/v9.0.85/bin/apache-tomcat-9.0.85.tar.gz tar -zxvf apache-tomcat-9.0.85.tar.gz -C /usr/local/ mv /usr/local/apache-tomcat-9.0.85 /usr/local/tomcat9Tomcat 目录结构并不复杂但新手容易搞混bin/启动和关闭脚本startup.sh和shutdown.sh最常用。conf/核心配置文件所在server.xml配端口和虚拟主机context.xml配数据源。webapps/存放 war 包的位置Tomcat 启动时会自动解压部署。logs/日志目录catalina.out 是主日志排查问题第一眼看这里。3.2 纯 Tomcat 部署若伊后端的两种姿势用外置 Tomcat 部署 war 包非常简单把打包好的ruoyi-admin.war丢到webapps/目录下然后启动 Tomcat 即可cp ruoyi-admin.war /usr/local/tomcat9/webapps/ /usr/local/tomcat9/bin/startup.sh第一次启动时Tomcat 会解压 war 包生成ruoyi-admin目录。启动过程可以用tail -f /usr/local/tomcat9/logs/catalina.out实时观察日志看到Started RuoYiApplication字样就说明启动成功了。如果你不想用外置 Tomcat直接用 jar 包方式部署其实也能算“Tomcat单机部署”的一种变体因为 Spring Boot 内置了 Tomcat。命令更简单nohup java -jar ruoyi-admin.jar --server.port8080 ruoyi.log 21 这两种方式各有优劣。war 包的优点是可以利用 Tomcat 的成熟管理能力比如通过 manager 应用热部署、统一管理多个应用。jar 包方式的优点是部署简单一条命令搞定而且日志管理更方便。我个人建议如果纯粹单机部署直接用 jar 包反而更省事。3.3 前端静态文件的托管方案纯 Tomcat 部署模式下前端 dist 目录里的静态文件怎么处理最直接的做法是把dist目录里的内容复制到 Tomcat 的webapps/ROOT/目录下这样访问http://ip:8080/就能看到前端页面rm -rf /usr/local/tomcat9/webapps/ROOT/* cp -r dist/* /usr/local/tomcat9/webapps/ROOT/但这种方式的弊端非常明显前端静态资源和后端接口混在一个 Tomcat 实例里前端代码更新要动 Tomcat接口出问题排查日志时还要在一堆静态资源访问日志里翻找长期维护起来比较痛苦。所以我只在演示环境或极小的内网项目里这么干过真正上线基本都走 Nginx 方案。重要提示纯 Tomcat 部署方式下接口地址和前端页面如果不在同一个端口就会出现跨域问题。解决办法是若伊框架里配置跨域过滤器或者把前端请求路径和后端地址保持一致也就是前端部署到 Nginx、后端接口也通过 Nginx 转发这就是下面章节要讲的整合部署方案。3.4 Tomcat 乱码问题与内存参数调优第一次用 Tomcat 部署若伊几乎必踩乱码的坑。现象是前端页面上看到的中文全是乱码还有控制台日志也乱码。这个问题的根因有三个文件编码、Tomcat URI 编码、数据库连接编码。第一个找到conf/server.xml在Connector节点上加URIEncodingUTF-8Connector port8080 protocolHTTP/1.1 connectionTimeout20000 redirectPort8443 URIEncodingUTF-8 /第二个检查conf/logging.properties确保java.util.logging.ConsoleHandler.encoding UTF-8这样控制台日志就不会乱码。第三个数据库连接串里加编码参数url: jdbc:mysql://localhost:3306/ry-vue?useUnicodetruecharacterEncodingutf8useSSLfalseserverTimezoneAsia/Shanghai另外JVM 内存参数建议在bin/setenv.sh中配置没有就新建JAVA_OPTS-Xms512m -Xmx1024m -XX:MetaspaceSize256m -XX:MaxMetaspaceSize512m这个配置根据服务器内存大小调整。我之前在一台 2G 内存的机器上部署初始堆 512m 最大 1G跑若伊框架加几个并发任务完全够用。如果机器内存 4G 以上-Xmx可以放大到 2G给 JVM 留足余量。4. Nginx Tomcat 整合部署生产环境的标配玩法4.1 Nginx 安装与基础配置Nginx 的安装各发行版有差异CentOS/RHEL 系用 yum 最省事yum install -y nginx systemctl enable nginx systemctl start nginxUbuntu/Debian 系用 aptapt install -y nginx systemctl enable nginx systemctl start nginxNginx 的配置主文件在/etc/nginx/nginx.conf为了管理方便我习惯在/etc/nginx/conf.d/目录下为每个项目单独建配置文件。这样配置隔离出问题互不影响后续更新也清晰。4.2 反向代理让前后端共用一个入口Nginx 在这里承担的核心职责是反向代理。所谓反向代理可以理解为 Nginx 是前台接待员用户只需要认识 Nginx 这个人不需要知道背后真正的服务是谁。用户请求到 NginxNginx 根据请求路径把任务分发给背后的 Tomcat 或静态文件目录。若伊框架的整合部署核心思路是这样的用户访问http://your-domain/Nginx 直接返回前端静态文件即 dist 目录的内容。用户访问http://your-domain/api/xxxNginx 把请求转发给 Tomcat 的http://127.0.0.1:8080/xxx。用户访问http://your-domain/prod-api/xxx同样转发给 Tomcat这里的/prod-api是若伊前端配置的请求前缀。下面这个配置是我实际用的完整版server { listen 80; server_name your-domain.com; # 前端静态资源 location / { root /data/www/ruoyi-ui; index index.html index.htm; 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; proxy_set_header X-Forwarded-Proto $scheme; proxy_connect_timeout 60s; proxy_read_timeout 120s; } # 静态资源缓存针对图片、JS、CSS location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ { root /data/www/ruoyi-ui; expires 7d; add_header Cache-Control public, no-transform; } }这段配置里最关键的是location /prod-api/这段反向代理规则。注意proxy_pass后面那个斜杠的含义http://127.0.0.1:8080/末尾带斜杠表示把/prod-api/前缀去掉后再转发。举个例子用户请求/prod-api/loginNginx 转发给 Tomcat 的地址是http://127.0.0.1:8080/login。如果不带斜杠Nginx 会原样把整个路径传给 Tomcat也就是http://127.0.0.1:8080/prod-api/login后端若没配置对应 context-path必然 404。4.3 动静分离Nginx 处理静态Tomcat 专注接口Nginx Tomcat 整合方案最大的优势就是动静分离。前端打包出来的 JS、CSS、图片这些静态文件完全由 Nginx 处理不经过 TomcatTomcat 的线程和内存全部留给接口调用。这样做的好处非常明显静态文件响应速度大幅提升。Nginx 处理静态文件的能力比 Tomcat 强很多高并发下差距尤其明显。Tomcat 负载显著降低。Tomcat 不需要解析静态资源的 HTTP 请求线程池压力小接口响应更稳定。部署更灵活。前端代码更新时只需要替换/data/www/ruoyi-ui目录下的文件不用重启 Tomcat。后端口新增接口只需要重新部署 jar/war不用管前端。我实测过一个场景同一个若伊系统纯 Tomcat 扛 50 个并发用户时接口平均响应时间在 200ms 左右页面加载能感觉到卡顿。改成 Nginx 动静分离后同样的并发量接口响应时间掉到 80ms 以内页面加载几乎是秒开。这不是夸张静态资源不走 Java 应用服务器效果立竿见影。4.4 整合部署完整操作实录下面从零走一遍整合部署的完整流程照着做基本不会出问题。第一步准备好前后端产物。后端 jar 包在ruoyi-admin/target/ruoyi-admin.jar前端产物在ruoyi-ui/dist/。第二步创建前端静态目录并上传文件mkdir -p /data/www/ruoyi-ui cp -r dist/* /data/www/ruoyi-ui/第三步启动后端 jar 包。生产环境不用java -jar裸跑用 nohup 放后台并指定日志文件nohup java -jar /opt/ruoyi/ruoyi-admin.jar \ --spring.profiles.activeprod \ --server.port8080 \ /opt/ruoyi/logs/ruoyi.log 21 这里--spring.profiles.activeprod是启用 production 环境的配置。若伊框架里有application-prod.yml文件里面配了生产环境的数据库、Redis 等关键信息。记得先把数据库连接改对不然应用起不来。第四步创建 Nginx 配置文件vim /etc/nginx/conf.d/ruoyi.conf把上一节的那段配置写好注意server_name改成你自己的域名或 IP。第五步验证 Nginx 配置并重载nginx -t systemctl reload nginx第六步全链路验证。浏览器访问http://your-server-ip/能看到若伊登录页说明前端静态资源正常。输入默认账号 admin/admin123能登录进去说明后端接口通了。如果登录失败用curl http://127.0.0.1:8080/login直接测后端接口能快速定位问题在 Nginx 转发还是后端本身。注意若伊框架默认开启了验证码功能登录时需要验证码。如果 Nginx 转发配置有问题获取验证码的接口会失败表现为验证码图片不显示或刷新不出来。排查时先看验证码能不能出来这其实是个很灵敏的“探针接口”。4.5 HTTPS 配置Nginx 终结 SSL 证书的实践生产环境怎么能不上 HTTPS尤其是涉及登录密码的系统中。Nginx 最适合做 SSL 证书的终结者Tomcat 不需要做任何 SSL 配置证书管理全部在 Nginx 层完成。在 Nginx 配置中加入 SSL 相关参数server { listen 443 ssl; server_name your-domain.com; ssl_certificate /etc/nginx/ssl/your-domain.crt; ssl_certificate_key /etc/nginx/ssl/your-domain.key; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; ssl_session_cache shared:SSL:10m; ssl_session_timeout 10m; # 前端静态资源 location / { root /data/www/ruoyi-ui; index index.html index.htm; 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; proxy_set_header X-Forwarded-Proto $scheme; } } server { listen 80; server_name your-domain.com; return 301 https://$host$request_uri; }第二条server块的作用是把所有 HTTP 请求永久重定向到 HTTPS避免用户走明文协议。证书和私钥最好用绝对路径Nginx 对相对路径的解析容易出问题。若伊框架前端的.env.production里配置的VUE_APP_BASE_API也要对应改成https://your-domain.com/prod-api或者更简单的方式是配置成同源的/prod-api让浏览器自动带上当前的域名和协议。我推荐后一种这样证书更换或者域名调整时前端代码不用重新构建。4.6 Nginx 负载均衡单机不够时的扩展思路虽然标题是“tomcat / tomcatnginx”但很多人在部署完单机整合方案之后没过多久就碰上了新问题用户量上来了一台 Tomcat 扛不住了。这时候 Nginx 的负载均衡能力就派上用场了。最简单的配置方式用upstream定义一组后端服务器upstream ruoyi_backend { server 127.0.0.1:8080 weight5; server 127.0.0.1:8081 weight5; keepalive 32; } server { listen 80; server_name your-domain.com; location /prod-api/ { proxy_pass http://ruoyi_backend/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }这里的weight5表示两台服务器权重相等也可以按机器性能调整。keepalive 32是保持长连接的配置能减少频繁创建连接的开销。但注意部署多个后端实例时若伊框架本身的 session 是存储在 Redis 里的所以只要 Redis 配置正确多实例之间 session 不会丢失这一点若伊框架做得很省心。你要操心的反而是文件上传问题——若伊默认把上传的文件存在本地磁盘ruoyi/uploadPath多实例部署时文件会分散在各台机器上。解决思路有两个一是用 NFS 把多台机器的存储目录挂载共享二是改造若伊的文件存储方式接入 MinIO 或者阿里云 OSS 这类的对象存储。后者改动量稍大但一劳永逸。5. 高频踩坑实录乱码、404、502 排查与解决5.1 接口 404Nginx 转发路径和 Tomcat 上下文路径冲突这个问题出现的频率极高。现象是前端页面能打开接口请求也能发出去但返回 404 或者页面上的接口请求 URL 变成http://domain/prod-api/prod-api/login这种双前缀。原因基本是两个一是 Nginx 的proxy_pass末尾斜杠处理不对前面已经强调过带斜杠表示去掉前缀后转发不带斜杠则保留完整路径二是若伊前端的VUE_APP_BASE_API配置成了/prod-api且后端接口的 context-path 也设置成了/prod-api两边重复了。排查思路按照这个顺序来先用curl直接打后端接口确认后端是否正常启动接口是否能通。再通过 Nginx 的curl http://your-domain/prod-api/login测试转发结果。看 Nginx 的错误日志/var/log/nginx/error.log和后端日志/opt/ruoyi/logs/ruoyi.log对照着分析。5.2 502 Bad Gateway后端没有正常监听或连接超时Nginx 返回 502说明 Nginx 没能成功和后端建立连接。最常见的原因是后端服务根本没起或者监听的端口不对。先确认 Java 进程是否存活ps -ef | grep java netstat -tlnp | grep 8080如果端口没有监听去翻后端的启动日志/opt/ruoyi/logs/ruoyi.log看有没有报错堆栈。数据库连接失败、Redis 连接失败是启动失败的高频原因。还有一种情况是后端起来了但 Nginx 的proxy_read_timeout太短某些慢接口超时导致 502。若伊框架里有些报表类的接口执行时间可能超过 60 秒我遇到过导出大批量 Excel 时接口跑了两分多钟Nginx 默认 60 秒读超时直接掐断连接前端报 502。解决办法是把proxy_read_timeout加到 300s同时后端接口逻辑也尽量优化。5.3 前端页面白屏或刷新后 404前端页面首次打开正常但刷新某个路由页面时出现 404这是 Vue Router 的 history 模式典型问题。因为刷新页面时浏览器会真实地向服务器请求那个 URL 路径Nginx 发现没有对应的静态文件就返回了默认的 404。解决方式是 Nginx 配置try_files将不存在的路径都回退到index.htmllocation / { root /data/www/ruoyi-ui; index index.html index.htm; try_files $uri $uri/ /index.html; }这一行配置非常重要try_files会按顺序查找文件$uri是原始请求路径$uri/是目录形式都找不到时最后回退到/index.html。这样 Vue Router 接管路由后不管用户刷新哪个子页面都能正确加载入口页面并恢复路由状态。5.4 验证码出不来或登录报错验证码是若伊框架的“第一道关卡”基本上后端接口有问题最先暴露在这里。验证码接口/prod-api/captchaImage如果 404多半是 Nginx 转发规则不对如果接口返回 200 但图片显示不出来可能是 Redis 没配好导致验证码存不进去。另外若伊框架的验证码生成依赖 RedisRedis 连接失败会导致验证码接口报错。所以排查这个环节第一个检查 Nginx 转发第二个检查 Redis 连接第三个检查后端接口日志。如果只是本地测试不想用验证码可以在后端配置里把验证码开关关掉ruoyi: captchaEnabled: false但这个改法只建议开发环境用生产环境千万别这么干验证码是防止暴力破解的第一道防线。5.5 端口被占用和防火墙问题排查Linux 上部署部署若伊还经常遇到“服务起不来”的假象。一个典型的场景是java -jar启动时报端口被占用如果你前面已经启动过一个实例再启动就会冲突。排查方式lsof -i :8080发现占用进程后确认是不是自己之前启动的残留进程是就直接 kill 掉。另外云服务器上别忘了在安全组里放行 80 和 443 端口本地防火墙也检查一下firewall-cmd --add-port80/tcp --permanent firewall-cmd --add-port443/tcp --permanent firewall-cmd --reload很多新手在本地测试没问题部署到云服务器后外网访问不了十有八九是安全组和防火墙的问题。6. 部署方式的综合对比与我的最终建议把两种部署方式放到一起看差异主要体现在这几个维度对比维度纯 Tomcat 部署Tomcat Nginx 整合部署复杂度低适合快速验证中多一层配置但逻辑清晰静态资源处理Tomcat 处理效率一般Nginx 处理性能强并发能力单机受限于 Tomcat 线程Nginx 扛连接Tomcat 专注接口HTTPS 配置需要在 Tomcat 配证书Nginx 统一配置简单灵活扩展性扩展麻烦要改端口/多部署通过 upstream 轻松扩展节点适用场景开发/演示/内网小规模生产环境、面向公网、多用户访问我个人的建议非常明确学习阶段、本地测试、内网临时演示直接纯 Tomcat 或 jar 包起步快速看到效果不要被 Nginx 配置劝退。但如果你要把若伊框架正式部署到服务器哪怕用户量不大我也建议直接上 Tomcat Nginx 整合方案。原因很简单这套架构不仅解决眼前的问题还给后面留好了扩展空间——用户涨了加一台后端节点就行要上 HTTPS 改一个 Nginx 配置文件就行不用动代码、不用动 Tomcat 配置。6.1 部署脚本小抄一条命令搞定重启最后分享一个我在生产环境一直用的部署脚本简化重启流程减少手动操作的出错概率。脚本放到/opt/ruoyi/deploy.sh内容如下#!/bin/bash APP_NAMEruoyi-admin.jar APP_PATH/opt/ruoyi LOG_PATH$APP_PATH/logs/ruoyi.log # 停止旧进程 PID$(ps -ef | grep $APP_NAME | grep -v grep | awk {print $2}) if [ -n $PID ]; then echo Stopping old process: $PID kill -9 $PID sleep 2 fi # 启动新进程 cd $APP_PATH nohup java -jar $APP_PATH/$APP_NAME \ --spring.profiles.activeprod \ --server.port8080 \ $LOG_PATH 21 echo Application started, log: $LOG_PATH每次更新后端代码只需要./deploy.sh然后看日志确认启动成功。这套流程我用了两年踩过的坑基本都写在上面的章节里了。6.2 一点实在话部署若伊框架这件事说难不难说简单也不简单。难点不在技术本身而在于你对整个调用链路的理解——用户请求怎么进来、Nginx 怎么转发、Tomcat 怎么处理、Redis 和数据库在哪个环节起作用。把这些链路在脑子里盘清楚了遇到问题就能快速定位而不是对着报错日志干瞪眼。我自己第一次部署时也栽过跟头前端配好了、后端起好了结果忘了在安全组里放行端口折腾了半天才知道问题出在云厂商的防火墙策略上。所以啊部署工作一定要有全局视角从网络层到应用层逐层排查效率才会高。这套方案用熟了以后后续再做其他 Spring Boot 项目的部署基本都是同一个套路换汤不换药。若伊框架本身代码规范、文档齐全部署环节其实没有太多花活把 Tomcat 和 Nginx 这两块吃透后面路就好走多了。