CentOS 7实战：RuoYi-Vue前后端分离项目全栈部署指南

在当今企业级应用开发中，前后端分离架构已成为主流选择。RuoYi-Vue作为基于Spring Boot和Vue.js的权限管理系统，其优雅的代码结构和丰富的功能模块深受开发者喜爱。但对于刚接触Linux环境部署的Java开发者来说，从代码到线上服务的跨越往往充满挑战。本文将带您完成从零开始的完整部署旅程，特别针对CentOS 7环境下的Tomcat 8部署场景，深入解析每个环节的技术细节与常见陷阱。

1. 环境准备与基础配置

部署RuoYi-Vue需要先搭建稳定的基础运行环境。我们选择CentOS 7作为操作系统，这是目前企业服务器中最稳定的Linux发行版之一。在开始前，请确保您的虚拟机或云服务器已分配至少2核CPU、4GB内存及20GB磁盘空间，这对保证后续编译和运行效率至关重要。

必备组件清单 ：

• JDK 1.8（推荐Oracle JDK或OpenJDK）
• MySQL 5.7（兼容性最佳版本）
• Redis 4.0+（用于会话管理和缓存）
• Nginx 1.18+（前端服务和反向代理）
• Tomcat 8.5+（Servlet 3.1规范支持）

配置环境时最容易忽视的是系统防火墙设置。CentOS 7默认启用firewalld，需要放行关键端口：

sudo firewall-cmd --permanent --add-port=80/tcp   # Nginx
sudo firewall-cmd --permanent --add-port=8080/tcp # Tomcat
sudo firewall-cmd --permanent --add-port=3306/tcp # MySQL
sudo firewall-cmd --permanent --add-port=6379/tcp # Redis
sudo firewall-cmd --reload

提示：生产环境建议配置SELinux为permissive模式，避免权限问题导致服务异常。可通过 sudo setenforce 0 临时生效，或修改 /etc/selinux/config 文件永久生效。

2. 后端工程改造与War包生成

RuoYi-Vue默认采用前后端分离架构，后端需要转换为War包部署形式。使用IntelliJ IDEA打开项目后，重点修改以下核心配置：

关键改造步骤 ：

1. 在ruoyi-admin模块的pom.xml中，将 <packaging> 标签值从jar改为war
2. 添加Tomcat依赖作用域（避免与容器冲突）：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-tomcat</artifactId>
    <scope>provided</scope>
</dependency>

配置文件调整需特别注意路径转换。Linux环境下路径分隔符与Windows不同，建议使用绝对路径：

# application.yml示例片段
profile: 
  # Windows示例：D:/ruoyi/uploadPath
  # Linux修正为：
  uploadPath: /home/ruoyi/uploadPath

logging:
  file:
    path: /var/log/ruoyi

数据库连接配置需要与准备的MySQL实例匹配。除了修改application-druid.yml中的账号密码外，还需确认数据库字符集：

CREATE DATABASE `ry-vue` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

打包时推荐使用Maven命令确保环境一致性：

mvn clean package -DskipTests

生成的ruoyi-admin.war文件通常位于target目录下，大小约50-60MB为正常范围。如果体积异常小，可能是依赖未正确打包。

3. Tomcat深度配置与优化

将War包部署到Tomcat并非简单复制即可，需要针对生产环境进行多项优化配置。上传war包到webapps目录后，先不要立即启动，建议先进行以下调整：

server.xml关键配置 ：

<Connector 
    port="8080" 
    protocol="HTTP/1.1"
    connectionTimeout="20000"
    redirectPort="8443"
    maxThreads="200"
    minSpareThreads="20"
    acceptCount="100"
    URIEncoding="UTF-8"
    useBodyEncodingForURI="true"
/>

针对RuoYi特有的Context配置陷阱，正确的做法是：

1. 删除webapps/ROOT目录下所有文件
2. 在conf/Catalina/localhost目录下创建ROOT.xml：

<Context 
    docBase="/usr/local/tomcat/webapps/ruoyi-admin"
    reloadable="false"
    sessionCookiePath="/"
/>

这种配置方式比直接修改server.xml更优雅，也便于后续维护。启动Tomcat后，通过以下命令观察启动状态：

tail -f ../logs/catalina.out | grep -E 'ERROR|WARN|Exception'

正常启动应能看到Spring Boot的banner和初始化完成的日志。常见启动问题包括：

• 数据库连接失败（检查账号密码和网络连通性）
• Redis连接超时（确认Redis服务状态和防火墙设置）
• 文件权限不足（确保上传目录有写权限）

4. 前端工程构建与Nginx高级配置

前端部署的核心在于正确的静态资源构建和Nginx路由配置。使用VSCode打开ruoyi-ui项目后，建议先清理npm缓存：

npm cache clean --force
rm -rf node_modules
npm install --registry=https://registry.npmmirror.com

构建生产环境包时，添加--modern参数可生成现代浏览器优化版本：

npm run build:prod --modern

生成的dist目录结构应包含：

dist/
├── static/
│   ├── css/
│   ├── js/
│   └── fonts/
└── index.html

Nginx配置需要特别注意前后端路由的协调。以下是经过生产验证的配置模板：

server {
    listen       80;
    server_name  your-domain.com;
    
    # 前端静态资源
    location / {
        root   /home/ruoyi/projects/ruoyi-ui;
        try_files $uri $uri/ /index.html;
        index  index.html;
        
        # 缓存控制
        location ~* \.(js|css|png|jpg|jpeg|gif|ico)$ {
            expires 1y;
            add_header Cache-Control "public, no-transform";
        }
    }
    
    # 后端API代理
    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_connect_timeout 60s;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
    
    # 避免favicon.ico干扰
    location = /favicon.ico {
        log_not_found off;
        access_log off;
    }
}

配置完成后，使用以下命令验证配置并平滑重启：

sudo nginx -t  # 测试配置
sudo nginx -s reload  # 热加载

5. 全链路测试与故障排查

系统部署完成后，需要进行端到端的验证测试。以下是关键检查点清单：

1. 基础服务连通性 ：

   • MySQL： telnet 127.0.0.1 3306
   • Redis： redis-cli ping 应返回"PONG"
   • Tomcat：访问 http://server-ip:8080 应看到Tomcat默认页

2. 后端功能验证 ：

   curl -X POST "http://localhost:8080/login" \
   -H "Content-Type: application/json" \
   -d '{"username":"admin","password":"admin123"}'
   

   正常应返回包含token的JSON响应

3. 前端路由测试 ：

   • 直接访问 /user 等子路由不应出现404
   • 刷新页面应保持当前路由状态
   • 验证码图片应正常显示（检查Nginx代理配置）

常见问题解决方案 ：

问题现象	可能原因	解决方案
验证码不显示	跨域问题或路径错误	检查Nginx的/prod-api/代理配置
登录后跳转404	前端路由未正确处理	确保所有非API请求回退到index.html
静态资源加载失败	路径大小写不匹配	Linux严格区分大小写，检查引用路径
上传文件失败	目录权限不足	对上传目录执行 chmod -R 755 /path

对于顽固的404问题，建议按以下步骤排查：

1. 检查浏览器开发者工具中的Network请求
2. 确认请求是否到达正确的服务（Nginx或Tomcat）
3. 查看对应服务的访问日志（Nginx在/var/log/nginx/access.log）
4. 检查Tomcat的catalina.out是否有异常堆栈

在多次部署实践中发现，90%的部署问题源于路径配置错误或权限不足。建议采用以下目录结构规范：

/home/ruoyi/
├── projects/
│   ├── ruoyi-ui/    # 前端静态资源
│   └── uploadPath/  # 文件上传目录
├── logs/            # 应用日志
└── backups/         # 配置备份

通过以上系统化的部署方法和深度优化的配置方案，即使是Linux新手也能顺利完成RuoYi-Vue项目的全栈部署。记得在每次重大配置变更前备份相关文件，这将为可能的回滚操作提供保障。