普通部署指南（JAR 包部署）

使用传统方式部署：在服务器上直接安装 JDK、MySQL、Redis、Nginx，通过 JAR 包运行后端服务。
如需使用 Docker 容器化部署，请参考 Docker 部署指南。

一、整体流程

本地/构建机                              生产服务器
┌──────────────────┐                ┌──────────────────────┐
│ 1. 拉取代码       │                │ 3. 安装基础环境        │
│ 2. 构建后端+前端   │  ── 上传产物 ──▶ │ 4. 初始化数据库        │
│    (JAR + dist)  │                │ 5. 部署后端 (JAR)     │
└──────────────────┘                │ 6. 部署前端 (Nginx)   │
                                    └──────────────────────┘

⚠️ 不建议在生产服务器上执行构建。构建过程消耗大量 CPU 和内存，且需要安装 Maven、Node.js 等工具链，会污染生产环境。请在本地开发机或专用构建机上完成构建，仅将产物上传到服务器。

二、本地构建（开发机 / 构建机）

以下操作在本地开发机或构建机上执行，不在生产服务器上操作。

2.1 构建环境要求

软件	版本要求	用途
JDK	17 或 21	编译后端
Maven	3.8+	构建后端项目
Node.js	≥ 20.19.0	构建前端项目
pnpm	≥ 10.0.0	前端包管理器
Git	2.x	拉取代码

2.2 拉取代码

bash

mkdir -p ~/workspace && cd ~/workspace

git clone <后端仓库地址> ruoyi-office
git clone <前端仓库地址> ruoyi-office-vben

2.3 构建后端

bash

cd ~/workspace/ruoyi-office

mvn clean package -Dmaven.test.skip=true -Dskip.repackage=true -pl yudao-server -am -Pprod

# 确认产物
ls -lh yudao-server/target/yudao-server.jar

⚠️ 关键参数：
-Dskip.repackage=true：子模块跳过 repackage，由 yudao-server 统一打 Fat JAR
-pl yudao-server -am：仅构建 yudao-server 及其依赖
-Pprod：激活生产环境 Profile
首次构建需下载依赖，约 5-15 分钟。

💡 Maven 国内加速：编辑 $MAVEN_HOME/conf/settings.xml，在 <mirrors> 中添加：
xml
<mirror>
    <id>aliyun</id>
    <mirrorOf>central</mirrorOf>
    <url>https://maven.aliyun.com/repository/public</url>
</mirror>

2.4 构建前端

bash

cd ~/workspace/ruoyi-office-vben

# 1. 安装依赖
pnpm install

# 2. 构建 Monorepo 内部依赖包
pnpm -r --filter "./packages/**" --filter "./internal/**" build

# 3. 构建前端应用
cd apps/web-antd
pnpm build

构建产物位于 apps/web-antd/dist/。

💡 内存不足报 OOM？执行 export NODE_OPTIONS="--max-old-space-size=4096" 后重试。
💡 vite.config.mts 已配置生产环境 base: '/web/'，无需额外修改。

2.5 上传产物到服务器

bash

# 上传后端 JAR
scp ~/workspace/ruoyi-office/yudao-server/target/yudao-server.jar root@服务器IP:/data/app/

# 上传前端产物
scp -r ~/workspace/ruoyi-office-vben/apps/web-antd/dist/* root@服务器IP:/usr/share/nginx/html/web/

# 上传数据库 SQL（首次部署时需要）
scp ~/workspace/ruoyi-office-db/ruoyi-office-20260301.sql root@服务器IP:/data/

也可使用 FTP、rsync 或其他文件传输方式，效果相同。

三、服务器环境准备

以下所有操作均在生产服务器上执行。

3.1 服务器配置要求

项目	最低配置	推荐配置
CPU	2 核	4 核+
内存	4 GB	8 GB+
磁盘	40 GB	100 GB+
操作系统	CentOS 7+ / Ubuntu 20.04+	CentOS Stream 9 / Ubuntu 22.04

3.2 所需软件（仅运行时依赖）

软件	版本要求	用途
JDK	17 或 21	运行后端服务
MySQL	8.0+	数据库
Redis	5.0+	缓存
Nginx	1.18+	前端静态文件 & API 反代

注意：生产服务器不需要安装 Maven、Node.js、pnpm、Git 等构建工具。

3.3 端口规划

服务	端口	说明
Nginx	80	对外统一入口
yudao-server	48080	后端 API
MySQL	3306	数据库
Redis	6379	缓存

3.4 安装 JDK

bash

# CentOS / RHEL
yum install -y java-21-openjdk java-21-openjdk-devel

# Ubuntu / Debian
apt update && apt install -y openjdk-21-jdk

# 验证
java -version

JDK 17 同样可用，按服务器情况选择。

3.5 安装 MySQL

bash

# CentOS
yum install -y mysql-server
systemctl start mysqld && systemctl enable mysqld

# Ubuntu
apt install -y mysql-server
systemctl start mysql && systemctl enable mysql

# 安全初始化（设置 root 密码）
mysql_secure_installation

验证：

bash

mysql -u root -p -e "SELECT VERSION();"

3.6 安装 Redis

bash

# CentOS（需要 EPEL 源）
yum install -y epel-release && yum install -y redis
systemctl start redis && systemctl enable redis

# Ubuntu
apt install -y redis-server
systemctl start redis-server && systemctl enable redis-server

# 验证
redis-cli ping   # 返回 PONG

3.7 安装 Nginx

bash

# CentOS
yum install -y nginx
systemctl start nginx && systemctl enable nginx

# Ubuntu
apt install -y nginx
systemctl start nginx && systemctl enable nginx

# 验证
curl -I http://127.0.0.1   # 返回 200

四、初始化数据库

4.1 创建数据库

sql

CREATE DATABASE IF NOT EXISTS `ruoyi-office`
  DEFAULT CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

4.2 导入数据

bash

# 以最新的 SQL 文件为准（已在 2.5 步上传到 /data/ 目录）
mysql -u root -p ruoyi-office < /data/ruoyi-office-20260301.sql

4.3 验证

bash

mysql -u root -p -e "USE ruoyi-office; SHOW TABLES;" | head -20
# 能看到 system_users、system_role 等表即成功

五、部署后端

5.1 准备目录

bash

mkdir -p /data/app
# JAR 文件已在 2.5 步上传到 /data/app/ 目录
ls -lh /data/app/yudao-server.jar

5.2 配置说明

配置已内嵌在 JAR 的 application-prod.yaml 中，通过启动参数覆盖即可，无需解压：

配置项	环境变量	说明
MySQL 地址	`MYSQL_URL`	JDBC 连接串
MySQL 用户名	`MYSQL_USERNAME`	默认 `root`
MySQL 密码	`MYSQL_PASSWORD`	必须修改
Redis 地址	`REDIS_HOST`	默认 `127.0.0.1`
Redis 端口	`REDIS_PORT`	默认 `6379`
Redis 密码	`REDIS_PASSWORD`	无密码留空

5.3 启动服务

bash

nohup java -Xms512m -Xmx2048m \
  -DMYSQL_URL="jdbc:mysql://127.0.0.1:3306/ruoyi-office?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&nullCatalogMeansCurrent=true&rewriteBatchedStatements=true" \
  -DMYSQL_USERNAME=root \
  -DMYSQL_PASSWORD='YourPassword123!' \
  -DREDIS_HOST=127.0.0.1 \
  -DREDIS_PORT=6379 \
  -DREDIS_PASSWORD='' \
  -jar /data/app/yudao-server.jar \
  --spring.profiles.active=prod \
  > /data/app/nohup.out 2>&1 &

tail -f /data/app/nohup.out

5.4 验证

bash

# 等待 30-60 秒
curl http://127.0.0.1:48080/actuator/health
# 返回 {"status":"UP"} 即成功

5.5 使用 systemd 托管（推荐）

创建 /etc/systemd/system/yudao-server.service：

ini

[Unit]
Description=YuDao Server
After=network.target mysql.service redis.service

[Service]
Type=simple
User=root
WorkingDirectory=/data/app
Environment="MYSQL_URL=jdbc:mysql://127.0.0.1:3306/ruoyi-office?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&nullCatalogMeansCurrent=true&rewriteBatchedStatements=true"
Environment="MYSQL_USERNAME=root"
Environment="MYSQL_PASSWORD=YourPassword123!"
Environment="REDIS_HOST=127.0.0.1"
Environment="REDIS_PORT=6379"
Environment="REDIS_PASSWORD="
ExecStart=/usr/bin/java -Xms512m -Xmx2048m -jar /data/app/yudao-server.jar --spring.profiles.active=prod
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

bash

systemctl daemon-reload
systemctl enable yudao-server
systemctl start yudao-server

# 常用命令
systemctl status yudao-server    # 状态
systemctl stop yudao-server      # 停止
systemctl restart yudao-server   # 重启
journalctl -u yudao-server -f    # 日志

5.6 停止 / 重启（非 systemd）

bash

kill $(ps -ef | grep yudao-server | grep -v grep | awk '{print $2}')

六、部署前端

6.1 放置构建产物

bash

mkdir -p /usr/share/nginx/html/web
# 前端文件已在 2.5 步上传到 /usr/share/nginx/html/web/ 目录
ls -la /usr/share/nginx/html/web/index.html

Nginx 默认站点目录为 /usr/share/nginx/html，如有自定义请替换路径。

6.2 配置 Nginx

创建 /etc/nginx/conf.d/ruoyi-office.conf：

nginx

server {
    listen 80;
    server_name _;

    charset utf-8;

    # Gzip 压缩
    gzip on;
    gzip_vary on;
    gzip_min_length 1024;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/xml text/javascript
               application/json application/javascript application/xml+rss
               application/x-javascript image/svg+xml;

    # ========== 前端静态文件 ==========
    location /web {
        alias /usr/share/nginx/html/web;
        index index.html;
        try_files $uri $uri/ /web/index.html;
    }

    # 静态资源长缓存
    location ~* ^/web/(.+)\.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
        root /usr/share/nginx/html;
        expires 30d;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # ========== 后端 API 反向代理 ==========
    location /admin-api {
        proxy_pass http://127.0.0.1:48080/admin-api;
        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;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }

    # ========== 根路径跳转 ==========
    location = / {
        return 302 /web;
    }
}

⚠️ 如果系统 Nginx 默认配置文件 /etc/nginx/conf.d/default.conf 也监听了 80 端口，需删除或重命名以避免冲突。

6.3 生效配置

bash

nginx -t && nginx -s reload

6.4 验证

浏览器访问 http://服务器IP/web，出现登录页即成功。

账号	密码
admin	admin123

七、日常更新

更新流程同样遵循「本地构建 → 上传产物 → 服务器重启」的原则。

更新后端

bash

# ===== 本地/构建机 =====
cd ~/workspace/ruoyi-office && git pull origin master
mvn clean package -Dmaven.test.skip=true -Dskip.repackage=true -pl yudao-server -am -Pprod
scp yudao-server/target/yudao-server.jar root@服务器IP:/data/app/

# ===== 生产服务器 =====
systemctl stop yudao-server
systemctl start yudao-server

更新前端

bash

# ===== 本地/构建机 =====
cd ~/workspace/ruoyi-office-vben && git pull origin master
pnpm install
pnpm -r --filter "./packages/**" --filter "./internal/**" build
cd apps/web-antd && pnpm build

# 上传（先清理再上传）
ssh root@服务器IP "rm -rf /usr/share/nginx/html/web/*"
scp -r dist/* root@服务器IP:/usr/share/nginx/html/web/
# 静态文件替换即时生效，无需重启 Nginx

更新数据库

bash

# 将增量 SQL 上传到服务器后执行
mysql -u root -p ruoyi-office < 增量SQL文件.sql

八、常见问题

Q1：Maven 构建失败，提示依赖下载超时？

确认 Maven 镜像加速已配置（参考 2.3 节），清除缓存后重试：

bash

mvn clean package -U -Dmaven.test.skip=true -Dskip.repackage=true -pl yudao-server -am -Pprod

Q2：后端启动后立即退出？

bash

tail -100 /data/app/nohup.out   # 查看日志

常见原因：①数据库连接失败 ②Redis 连接失败 ③内存不足（减小 -Xmx）④端口被占用（netstat -tlnp | grep 48080）。

Q3：前端 `pnpm install` 失败？

bash

pnpm store prune && rm -rf node_modules && pnpm install
node -v   # 确认 >= 20.19.0

Q4：前端构建报 JavaScript heap out of memory？

bash

export NODE_OPTIONS="--max-old-space-size=4096"
pnpm build

Q5：访问 `/web` 返回 404？

确认文件存在：ls /usr/share/nginx/html/web/index.html
确认 Nginx 配置中 alias 路径正确
检查并重载配置：nginx -t && nginx -s reload
检查 default.conf 是否冲突

Q6：页面正常但接口报 502 / 504？

bash

curl http://127.0.0.1:48080/actuator/health   # 确认后端在运行

检查 Nginx 中 proxy_pass 地址是否指向正确的后端端口。

Q7：JAR 包超过 500MB？

确保构建命令包含 -Dskip.repackage=true，否则子模块会各自打出 Fat JAR 造成重复。

Q8：如何修改配置而不重新打包？

bash

# 方式一：启动参数覆盖
java -jar yudao-server.jar --spring.datasource.dynamic.datasource.master.password=新密码

# 方式二：环境变量
export MYSQL_PASSWORD=新密码

# 方式三：外部配置文件（与 JAR 同目录放一份 application-prod.yaml）

普通部署指南（JAR 包部署） ​

一、整体流程 ​

二、本地构建（开发机 / 构建机） ​

2.1 构建环境要求 ​

2.2 拉取代码 ​

2.3 构建后端 ​

2.4 构建前端 ​

2.5 上传产物到服务器 ​

三、服务器环境准备 ​

3.1 服务器配置要求 ​

3.2 所需软件（仅运行时依赖） ​

3.3 端口规划 ​

3.4 安装 JDK ​

3.5 安装 MySQL ​

3.6 安装 Redis ​

3.7 安装 Nginx ​

四、初始化数据库 ​

4.1 创建数据库 ​

4.2 导入数据 ​

4.3 验证 ​

五、部署后端 ​

5.1 准备目录 ​

5.2 配置说明 ​

5.3 启动服务 ​

5.4 验证 ​

5.5 使用 systemd 托管（推荐） ​

5.6 停止 / 重启（非 systemd） ​

六、部署前端 ​

6.1 放置构建产物 ​

6.2 配置 Nginx ​

6.3 生效配置 ​

6.4 验证 ​

七、日常更新 ​

更新后端 ​

更新前端 ​

更新数据库 ​

八、常见问题 ​

Q1：Maven 构建失败，提示依赖下载超时？ ​

Q2：后端启动后立即退出？ ​

Q3：前端 pnpm install 失败？ ​

Q4：前端构建报 JavaScript heap out of memory？ ​

Q5：访问 /web 返回 404？ ​

Q6：页面正常但接口报 502 / 504？ ​

Q7：JAR 包超过 500MB？ ​

Q8：如何修改配置而不重新打包？ ​

普通部署指南（JAR 包部署）

一、整体流程

二、本地构建（开发机 / 构建机）

2.1 构建环境要求

2.2 拉取代码

2.3 构建后端

2.4 构建前端

2.5 上传产物到服务器

三、服务器环境准备

3.1 服务器配置要求

3.2 所需软件（仅运行时依赖）

3.3 端口规划

3.4 安装 JDK

3.5 安装 MySQL

3.6 安装 Redis

3.7 安装 Nginx

四、初始化数据库

4.1 创建数据库

4.2 导入数据

4.3 验证

五、部署后端

5.1 准备目录

5.2 配置说明

5.3 启动服务

5.4 验证

5.5 使用 systemd 托管（推荐）

5.6 停止 / 重启（非 systemd）

六、部署前端

6.1 放置构建产物

6.2 配置 Nginx

6.3 生效配置

6.4 验证

七、日常更新

更新后端

更新前端

更新数据库

八、常见问题

Q1：Maven 构建失败，提示依赖下载超时？

Q2：后端启动后立即退出？

Q3：前端 `pnpm install` 失败？

Q4：前端构建报 JavaScript heap out of memory？

Q5：访问 `/web` 返回 404？

Q6：页面正常但接口报 502 / 504？

Q7：JAR 包超过 500MB？

Q8：如何修改配置而不重新打包？