RuoYi 前后端分离项目 Linux 部署全指南

前言：从本地开发到线上运行的 “最后一公里”

作为一款基于 SpringBoot+Vue 的快速开发框架，RuoYi（若依）凭借其完善的权限管理、代码生成器和前后端分离架构，成为企业级项目的首选。但对新手而言，将 RuoYi 从本地开发环境迁移到 Linux 服务器（IP：8.142.91.XXX）并稳定运行，常因环境配置、前后端联调问题 “卡壳”。

本文以conkl.cn项目（企业级技术社区）为例，从环境准备到问题排查，完整记录 RuoYi 前后端分离项目的 Linux 部署全流程，包含10 + 关键配置文件解读、502 错误深度分析及生产环境优化技巧，帮你避开 90% 的部署坑点。

一、环境准备：80% 的部署问题源于环境不一致

1.1 服务器基础环境要求（以conkl.cn为例）

1.2 环境安装与验证（以 Ubuntu 22.04 为例）

1.2.1 安装 Java（JDK 11）

# 1. 添加OpenJDK仓库（Ubuntu默认源含JDK11）
sudo apt update
sudo apt install openjdk-11-jdk -y# 2. 验证安装（输出类似：openjdk version "11.0.20" 2024-07-16）
java -version

1.2.2 安装 Node.js（v18 LTS，推荐 npm 而非 cnpm）

# 1. 使用nvm安装（避免系统级Node.js版本冲突）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc  # 加载nvm环境# 2. 安装Node.js v18 LTS
nvm install 18
nvm use 18  # 切换到v18# 3. 验证安装（输出v18.22.0，npm 9.6.7）
node -v
npm -v

为什么强调用 npm 而非 cnpm？
cnpm（淘宝镜像）通过软链接安装依赖，可能导致模块路径不一致（如node_modules中某些包指向临时目录），在 Linux 生产环境中易引发构建失败或运行时错误。RuoYi 前端依赖（如vue-router、element-ui）对版本一致性要求高，推荐使用官方 npm 源（可通过npm config set registry https://registry.npmjs.org/恢复）。

1.2.3 安装 Nginx

sudo apt install nginx -y
systemctl start nginx  # 启动Nginx
systemctl enable nginx # 开机自启

1.2.4 安装 MySQL 8.0

# 1. 安装MySQL服务
sudo apt install mysql-server -y# 2. 初始化安全配置（设置root密码、删除匿名用户等）
sudo mysql_secure_installation# 3. 验证服务状态（Active: active (running)）
systemctl status mysql

1.2.5 安装 Redis 7.0

# 1. 添加Redis官方仓库
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list# 2. 安装并启动Redis
sudo apt update
sudo apt install redis-server -y
systemctl start redis-server
systemctl enable redis-server

二、后端部署：SpringBoot 项目的 “三步上线法”

2.1 步骤 1：本地运行验证（避免 “部署即报错”）

2.1.1 克隆 RuoYi 后端代码（以conkl.cn为例）

# 本地开发机（Windows/Mac）操作
git clone https://gitee.com/y_project/RuoYi-Vue.git  # 官方仓库
cd RuoYi-Vue/ruoyi-admin  # 进入后端主模块

2.1.2 修改本地配置（确保本地可运行）

修改ruoyi-admin/src/main/resources/application-prod.yml，配置本地 MySQL 和 Redis：

spring:datasource:url: jdbc:mysql://localhost:3306/ruoyi?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=true&serverTimezone=GMT%2B8username: rootpassword: local_mysql_password  # 本地MySQL密码redis:host: localhost  # 本地Redis地址port: 6379

2.1.3 本地运行测试

# 本地执行（需安装Maven 3.6+）
mvn clean spring-boot:run

访问http://localhost:8080/ruoyi（默认后端端口 8080），返回{"code":404,"msg":"请求路径不存在"}说明后端启动成功（前端未部署时，直接访问后端接口会报 404）。

2.2 步骤 2：生产环境配置修改（关键！）

2.2.1 数据库配置（连接服务器 MySQL）

将application-prod.yml的spring.datasource修改为服务器 MySQL 地址（IP：8.142.91.XXX）：

spring:datasource:url: jdbc:mysql://8.142.91.XXX:3306/ruoyi?useUnicode=true&characterEncoding=utf8&zeroDateTimeBehavior=convertToNull&useSSL=false&serverTimezone=GMT%2B8username: ruoyi_user  # 生产环境专用账号（非root）password: ruoyi_mysql_2024  # 强密码（包含字母+数字+符号）

注意事项：

• 生产环境禁止使用 root 账号连接数据库，需新建专用用户（如

  ruoyi_user
  

  ）并授权：

  CREATE USER 'ruoyi_user'@'%' IDENTIFIED BY 'ruoyi_mysql_2024';
  GRANT ALL PRIVILEGES ON ruoyi.* TO 'ruoyi_user'@'%';
  FLUSH PRIVILEGES;
  

• useSSL=false：本地测试可关闭 SSL，但生产环境建议启用（需 MySQL 服务器配置 SSL 证书）。

2.2.2 Redis 配置（连接服务器 Redis）

修改application-prod.yml的spring.redis：

spring:redis:host: 8.142.91.XXX  # 服务器Redis地址（本地部署填localhost）port: 6379password: ruoyi_redis_2024  # Redis密码（需在redis.conf中设置）database: 0  # 使用0号数据库（默认）

Redis 密码设置：
编辑/etc/redis/redis.conf，取消注释并修改：

requirepass ruoyi_redis_2024  # 生产环境强密码

重启 Redis 生效：

systemctl restart redis-server

2.2.3 日志配置（避免 “无日志排查”）

RuoYi 默认日志路径为./logs（项目根目录），生产环境建议修改为固定路径（如/var/log/ruoyi），方便统一管理：

1. 在服务器创建日志目录并授权：

   sudo mkdir -p /var/log/ruoyi
   sudo chown -R $USER:$USER /var/log/ruoyi  # 授予当前用户写入权限
   

2. 修改logback-spring.xml（ruoyi-common-log模块）：

   <property name="LOG_PATH" value="/var/log/ruoyi" />  <!-- 原./logs -->
   <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender"><file>${LOG_PATH}/ruoyi.log</file>  <!-- 日志文件路径 -->
   </appender>
   

2.3 步骤 3：打包与运行（三种方式任选）

2.3.1 方式 1：Maven 打包 + nohup 后台运行（适合测试环境）

# 1. 本地打包（跳过测试）
mvn clean package -Dmaven.test.skip=true# 2. 上传jar包到服务器（使用scp或FileZilla）
scp target/ruoyi-admin-4.7.0.jar root@8.142.91.XXX:/opt/ruoyi/# 3. 服务器后台运行（日志输出到/var/log/ruoyi/ruoyi.log）
nohup java -jar /opt/ruoyi/ruoyi-admin-4.7.0.jar --spring.profiles.active=prod > /var/log/ruoyi/ruoyi.log 2>&1 &

2.3.2 方式 2：systemd 服务（推荐生产环境）

创建ruoyi.service文件（/etc/systemd/system/ruoyi.service）：

[Unit]
Description=RuoYi Backend Service
After=network.target mysql.service redis.service  # 依赖MySQL和Redis启动[Service]
Type=simple
User=root  # 运行用户（建议新建专用用户如ruoyi）
WorkingDirectory=/opt/ruoyi/  # 工作目录（存放jar包）
ExecStart=/usr/bin/java -Xms512m -Xmx1024m -jar ruoyi-admin-4.7.0.jar --spring.profiles.active=prod
Restart=always  # 崩溃自动重启
RestartSec=5  # 重启间隔5秒
StandardOutput=file:/var/log/ruoyi/ruoyi.stdout.log  # 标准输出日志
StandardError=file:/var/log/ruoyi/ruoyi.stderr.log  # 错误日志[Install]
WantedBy=multi-user.target

关键参数解释：

• -Xms512m -Xmx1024m：JVM 内存限制（根据服务器内存调整，4G 内存建议 Xmx=2G）；
• Restart=always：确保服务崩溃后自动恢复；
• After=mysql.service redis.service：保证 MySQL 和 Redis 启动后再启动 RuoYi。

2.3.3 方式 3：Docker 容器化（适合集群部署）

若服务器已安装 Docker，可通过 Dockerfile 快速部署：

# 基础镜像（Java 11）
FROM openjdk:11-jre-slim# 作者信息
LABEL maintainer="conkl.cn <admin@conkl.cn>"# 设置工作目录
WORKDIR /opt/ruoyi# 复制jar包到容器
COPY ruoyi-admin-4.7.0.jar .# 暴露8080端口（后端默认端口）
EXPOSE 8080# 启动命令
CMD ["java", "-jar", "ruoyi-admin-4.7.0.jar", "--spring.profiles.active=prod"]

构建并运行容器：

docker build -t ruoyi-backend:4.7.0 .
docker run -d --name ruoyi-backend \-p 8080:8080 \--link mysql:mysql \  # 链接MySQL容器--link redis:redis \  # 链接Redis容器ruoyi-backend:4.7.0

三、前端部署：Vue 项目的打包与 Nginx 配置

3.1 步骤 1：Vue 项目本地打包（npm 构建）

3.1.1 克隆 RuoYi 前端代码

# 本地开发机操作
git clone https://gitee.com/y_project/RuoYi-Vue.git
cd RuoYi-Vue/ruoyi-ui  # 进入前端目录

3.1.2 修改前端配置（对接生产后端）

编辑vue.config.js，设置publicPath（前端资源路径）和proxy（接口代理）：

module.exports = {publicPath: '/',  // 生产环境资源路径（若前端部署在根目录，保持'/'）devServer: {proxy: {'/prod-api': {  // 匹配所有以/prod-api开头的请求target: 'http://8.142.91.XXX:8080',  // 生产后端地址（IP:8.142.91.102，端口8080）changeOrigin: true,  // 允许跨域pathRewrite: {'^/prod-api': ''  // 重写路径（前端请求/prod-api/user → 后端/user）}}}}
};

3.1.3 npm 打包（关键！）

# 本地执行（确保Node.js版本为18.x）
npm install  # 安装依赖（必须用npm，避免cnpm软链接问题）
npm run build  # 打包生成dist目录（输出到ruoyi-ui/dist）

常见问题：

• npm install失败：检查 npm 源是否为官方源（npm config get registry），切换为https://registry.npmjs.org/；
• 打包报错ElementUI未找到：删除node_modules和package-lock.json，重新npm install。

3.2 步骤 2：上传前端资源到 Nginx

3.2.1 上传 dist 目录到服务器

# 本地开发机执行（将dist目录上传到服务器/usr/share/nginx/html/conkl）
scp -r dist/* root@8.142.91.XXX:/usr/share/nginx/html/conkl/

3.2.2 配置 Nginx（关键！防 502 错误）

创建conkl.cn.conf（/etc/nginx/conf.d/conkl.cn.conf）：

server {listen       80;server_name  conkl.cn;  # 域名（需解析到8.142.91.102）# 前端静态资源配置location / {root   /usr/share/nginx/html/conkl;  # 前端dist目录路径index  index.html index.htm;try_files $uri $uri/ /index.html;  # 解决Vue路由history模式404问题}# 后端接口反向代理location /prod-api/ {proxy_pass http://127.0.0.1:8080/;  # 代理到后端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;}# 错误日志（排查502关键）error_log  /var/log/nginx/conkl.error.log;access_log /var/log/nginx/conkl.access.log;
}

配置解读：

• try_files $uri $uri/ /index.html：Vue 使用history路由模式时，刷新页面会向服务器请求不存在的路径（如/user），此配置将所有未匹配的路径重定向到index.html，由前端路由处理；
• proxy_pass：将/prod-api/开头的请求转发到后端 8080 端口，实现前后端同域（避免跨域问题）；
• error_log：记录 Nginx 处理请求时的错误（如无法连接后端 8080 端口会报connect() failed (111: Connection refused)）。

3.2.3 验证 Nginx 配置并重启

sudo nginx -t  # 检查配置语法（输出"test is successful"）
sudo systemctl restart nginx  # 重启Nginx生效

四、联调测试与 502 错误排查

4.1 全链路测试（从域名到接口）

4.1.1 访问前端页面

打开浏览器，输入http://conkl.cn（需确保域名已解析到 8.142.91.XXX），应看到 RuoYi 登录页面（若显示空白，检查 Nginxerror_log是否有404 Not Found）。

4.1.2 测试后端接口

在登录页面输入账号密码（默认admin/123456），若提示 “登录成功”，说明前后端联调正常；若提示 “接口超时”，按以下步骤排查：

4.2 502 Bad Gateway 深度排查（最常见问题）

4.2.1 现象描述

访问前端页面正常，但提交表单时 Nginx 返回502 Bad Gateway。

4.2.2 排查步骤

步骤 1：检查 Nginx 错误日志、

tail -f /var/log/nginx/conkl.error.log  # 查看最新错误

常见错误及解决：

步骤 2：检查后端服务状态

# 查看后端进程是否运行（应看到java -jar ruoyi-admin-4.7.0.jar）
ps -ef | grep ruoyi# 查看8080端口是否监听（输出应包含:8080）
netstat -tlnp | grep 8080

步骤 3：检查后端日志（定位根本原因）

# 查看RuoYi应用日志（关键错误如数据库连接失败、Redis未连接）
tail -f /var/log/ruoyi/ruoyi.stderr.log

常见日志错误及解决：

• Cannot connect to MySQL server：检查application-prod.yml的数据库 URL、用户名、密码是否正确；
• Redis connection timed out：检查 Redis 服务是否启动，密码是否匹配；
• Permission denied: /var/log/ruoyi/ruoyi.log：授予当前用户日志目录写入权限（chmod 755 /var/log/ruoyi）。

五、生产环境优化：从 “能运行” 到 “稳定运行”

5.1 防火墙配置（防恶意攻击）

# 开放80（HTTP）、443（HTTPS）、22（SSH）端口
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 22/tcp# 仅允许内网访问8080端口（后端端口）
sudo ufw allow in on lo to any port 8080  # 本地回环接口
sudo ufw enable  # 启用防火墙

5.2 开启 HTTPS（提升安全性）

通过 Let’s Encrypt 免费证书配置 HTTPS（以conkl.cn为例）：

5.2.1 安装 Certbot（自动获取证书）

sudo apt install certbot python3-certbot-nginx -y

5.2.2 自动配置 Nginx HTTPS

sudo certbot --nginx -d conkl.cn  # 按提示输入邮箱，同意条款

Certbot 会自动修改conkl.cn.conf，添加 HTTPS 配置（监听 443 端口，自动续期证书）。

5.3 日志轮转（避免磁盘爆满）

RuoYi 的ruoyi.log和 Nginx 的conkl.access.log会持续增长，需配置logrotate自动切割：

5.3.1 创建ruoyi-logrotate.conf（/etc/logrotate.d/ruoyi）

/var/log/ruoyi/*.log {daily          # 每日切割rotate 30      # 保留30天日志compress       # 压缩旧日志missingok      # 日志不存在不报错notifempty     # 空日志不切割create 0644 root root  # 新日志文件权限
}

5.3.2 验证配置

sudo logrotate -f /etc/logrotate.d/ruoyi  # 强制切割一次

结语：部署不是终点，而是稳定运行的起点

从环境安装到前后端联调，从 502 错误排查到生产环境优化，RuoYi 的 Linux 部署是对 “细节把控” 的终极考验。本文以conkl.cn（IP：8.142.91.XXX）的真实部署过程为蓝本，覆盖了 90% 的常见问题及解决方案。

记住：部署成功后，还需通过阿里云监控（ECS 监控、日志服务）实时监控 CPU、内存、接口响应时间，定期备份数据库和前端代码，才能真正实现 “稳定运行”。

下一次部署 RuoYi 时，不妨按本文步骤操作，你会发现 —— 曾经的 “部署难题”，不过是 “按图索骥” 的常规操作。