快速启动文档

目标：使用 IDEA 工具，将后端项目运行起来，并启动前端页面进行体验 🛫
整个过程非常简单，预计 15-30 分钟即可完成（取决于网络下载速度）。

一、环境准备

在开始之前，请确保本机已安装以下环境：

环境	版本要求	说明
JDK	17 或 21	推荐使用 OpenJDK / GraalVM
Maven	3.8+	用于后端项目构建
Node.js	18+	用于前端项目构建
pnpm	9.x+	前端包管理器
MySQL	5.7+ / 8.0+	数据存储
Redis	5.0+	缓存
Nacos	2.x	注册中心 & 配置中心（微服务模式必需，单体模式不需要）
IDEA	2023+	推荐使用 IntelliJ IDEA

二、克隆代码

使用 IDEA 或命令行克隆项目代码：

bash

# 后端项目
git clone <你的后端仓库地址>

# 前端项目
git clone <你的前端仓库地址>

克隆完成后，使用 IDEA 打开后端项目，耐心等待 Maven 下载完相关的依赖。

💡 项目使用 Spring Cloud 相关组件，依赖较多，首次下载需要一段时间。

三、初始化基础设施（必选）

3.1 初始化 MySQL

① 创建名为 ruoyi-office 的数据库，执行 sql/mysql/ 目录下的 dump-ruoyi-office-20260305.sql 加微信17156169080 获取最新sql 文件进行初始化。商业版从ruoyi-office-db/dump下获取最新日期的schema_xxx_sql和static_data_xxx.sql，先执行数据结构schema再执行静态数据sql。

sql

-- 创建数据库
CREATE DATABASE IF NOT EXISTS `ruoyi-office` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

支持多种数据库：MySQL、PostgreSQL、Oracle、SQL Server、达梦（DM）、人大金仓（KingbaseES）、OpenGauss 等，对应的 SQL 文件在 sql/ 目录下各数据库子目录中。

② 默认配置下，MySQL 启动在 3306 端口（Docker 环境为 33061），账号 root，密码 123456。如果不一致，需修改各服务的 application-local.yaml 配置文件中的数据库连接信息：

yaml

spring:
  datasource:
    dynamic:
      datasource:
        master:
          url: jdbc:mysql://127.0.0.1:3306/ruoyi-office?useSSL=false&serverTimezone=Asia/Shanghai&allowPublicKeyRetrieval=true&nullCatalogMeansCurrent=true&rewriteBatchedStatements=true
          username: root
          password: 123456

3.2 初始化 Redis

项目使用 Redis 缓存数据，请确保 Redis 服务已启动。

默认配置下，Redis 启动在 6379 端口，不设置密码。如果不一致，修改 application-local.yaml：

yaml

spring:
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      database: 0
      # password: 你的Redis密码

3.3 初始化 Nacos（微服务模式必需）

⚠️ 单体模式不需要 Nacos，可跳过本步。

项目使用 Nacos 作为注册中心和配置中心。

① 安装 Nacos（推荐 2.x 版本），单机模式启动：

bash

# Linux/Mac
sh startup.sh -m standalone

# Windows
startup.cmd -m standalone

② 访问 http://127.0.0.1:8848/nacos（默认账号密码 nacos/nacos），创建 dev 命名空间：

命名空间 ID：dev
命名空间名：dev

注意：命名空间 ID 和名称都设为 dev。

四、基础设施（可选）

以下组件可选安装，不影响项目基本启动。可在项目跑通后再按需安装。

4.1 RocketMQ

项目使用 RocketMQ 作为消息队列和事件总线。默认配置连接 127.0.0.1:9876。

如果暂时不使用消息队列功能，可以不安装，项目启动时会输出连接警告但不影响核心功能。

4.2 XXL-Job

项目使用 XXL-Job 作为定时任务调度中心。

默认配置下，本地 local 环境的定时任务是关闭的（xxl.job.enabled=false），避免控制台报错。

如需开启，修改配置：

yaml

xxl:
  job:
    enabled: true
    admin:
      addresses: http://127.0.0.1:9090/xxl-job-admin

五、启动后端项目

方式一：微服务模式（推荐生产环境）

微服务模式下，各业务模块独立启动，通过 Nacos 注册发现，由 Gateway 统一对外暴露接口。

5.1 编译项目

使用 IDEA 自带的 Maven 插件，或在项目根目录执行：

bash

mvn clean compile -Dmaven.test.skip=true

整个编译过程预计需要 1-2 分钟。

5.2 启动 Gateway 网关服务

运行 GatewayServerApplication 类，启动 API 网关。

启动完成后，访问 http://127.0.0.1:48080，返回 JSON 字符串说明成功。

服务	Application 类	端口
Gateway 网关	`GatewayServerApplication`	48080

5.3 启动 System 系统服务

运行 SystemServerApplication 类，启动系统服务（用户、角色、菜单、权限）。

启动完成后，验证：

直接访问：http://127.0.0.1:48081/admin-api/system/
通过网关：http://127.0.0.1:48080/admin-api/system/

两个地址都返回 JSON 字符串说明成功。

服务	Application 类	端口
System 系统服务	`SystemServerApplication`	48081

5.4 启动 Infra 基础设施服务

运行 InfraServerApplication 类，启动基础设施服务（文件、代码生成、配置、日志）。

启动完成后，验证：

直接访问：http://127.0.0.1:48082/admin-api/infra/
通过网关：http://127.0.0.1:48080/admin-api/infra/

服务	Application 类	端口
Infra 基础设施服务	`InfraServerApplication`	48082

5.5 启动其他业务服务（按需）

以下服务根据业务需要按需启动：

服务	Application 类	端口	说明
OA 协同办公	`OaServerApplication`	48101	协同办公
HRM 人力资源	`HrmServerApplication`	48102	人力资源
BPM 工作流	`BpmServerApplication`	48083	Flowable 工作流引擎
Report 报表	`ReportServerApplication`	48084	积木报表
Pay 支付	`PayServerApplication`	48085	支付渠道管理
MP 公众号	`MpServerApplication`	48086	微信公众号
Member 会员	`MemberServerApplication`	48087	C 端会员体系
ERP 进销存	`ErpServerApplication`	48088	采购、销售、库存
CRM 客户管理	`CrmServerApplication`	48089	线索、客户、商机
AI 大模型	`AiServerApplication`	48090	AI 对话、知识库
IoT 物联网	`IotServerApplication`	48091	设备管理
Product 商品	`ProductServerApplication`	48100	商品 SPU/SKU
Trade 交易	`TradeServerApplication`	48102	订单、售后
Statistics 统计	`StatisticsServerApplication`	48103	数据统计

⚠️ 最小可用集：只需启动 Gateway + System + Infra 三个服务，即可进入管理后台使用基础功能。

5.6 验证服务注册

启动完成后，访问 Nacos 控制台 http://127.0.0.1:8848/nacos → 服务管理 → 服务列表，确认各服务已注册（如 gateway-server、system-server、infra-server）。

方式二：单体模式（推荐开发 & 快速体验）

在项目根目录有一个 yudao-server 模块，它是项目的单体启动模式：

✅ 不依赖 Nacos 注册中心、配置中心
✅ 不使用 Feign 远程调用（都是 Spring Bean 本地调用）
✅ 只启动一个 Java 进程

单体模式的好处

后悔药：项目初期采用微服务架构，后续发现资源不足或业务量不大，可切换为单体部署
开发提速：本地启动多个微服务很麻烦，单体模式一个进程搞定所有服务
架构升级：不确定选微服务还是单体？直接选微服务项目，按需切换部署方式

如何单体启动

运行 YudaoServerApplication 类即可！默认开启 System 和 Infra 模块，其他模块参考对应的"功能开启"文档按需开启。

启动后访问 http://127.0.0.1:48080 验证。

如何打包部署

bash

# 单体模式打包（注意添加 -Dskip.repackage=true 参数）
mvn clean package -Dmaven.test.skip=true -Dskip.repackage=true -pl yudao-server -am -Pprod

# 启动 JAR
java -jar yudao-server/target/yudao-server.jar --spring.profiles.active=prod

⚠️ 关键参数说明：
-Dskip.repackage=true：让子模块跳过 spring-boot-maven-plugin 的 repackage，由 yudao-server 统一打包
-pl yudao-server -am：只构建 yudao-server 模块及其依赖

六、启动前端项目

6.1 安装依赖

在前端项目根目录执行：

bash

# 安装 pnpm（如果未安装）
npm install -g pnpm

# 安装项目依赖
pnpm install

6.2 启动开发服务器

bash

# 在前端项目根目录
cd apps/web-antd
pnpm dev

启动成功后，控制台会输出访问地址（默认 http://localhost:5173）。

6.3 访问管理后台

打开浏览器，访问 http://localhost:5173，使用以下默认账号登录：

账号	密码	说明
admin	admin123	超级管理员

💡 前端默认通过 Vite 代理将 /admin-api 请求转发到后端，无需额外配置 Nginx。

七、前端构建与部署

7.1 构建生产包

bash

# 在前端项目根目录
pnpm install

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

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

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

7.2 部署到服务器

将 dist/ 目录内容上传到 Nginx 的 web 目录：

bash

scp -r apps/web-antd/dist/* root@服务器IP:/data/nginx/html/web/

7.3 Nginx 配置

nginx

server {
    listen 80;
    server_name _;

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

    # 2. 后端 API 反向代理
    #    单体模式：直接代理到后端服务 :48080
    #    微服务模式：代理到 Gateway :48080（由 Gateway 分发到各微服务）
    location /admin-api {
        proxy_pass http://127.0.0.1:48080;
        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";
    }

    # 3. 根路径跳转到管理后台
    location = / {
        return 302 /web;
    }
}

💡 无论单体模式还是微服务模式，Nginx 配置完全一样——都是反代到 :48080。区别只在于单体模式下 :48080 是 yudao-server，微服务模式下 :48080 是 Gateway。

八、单体模式 vs 微服务模式对比

对比项	单体模式	微服务模式
依赖中间件	MySQL + Redis	MySQL + Redis + Nacos
启动进程	1 个 Java 进程	N 个 Java 进程（Gateway + 各服务）
打包命令	`mvn package -pl yudao-server -am -Dskip.repackage=true`	`mvn package`（全量构建）
Maven Profile	`-Dskip.repackage=true`（boot 模式）	默认（cloud 模式）
Nacos	❌ 不需要	✅ 必需
适用场景	开发调试、中小项目、资源有限	生产环境、大团队、高并发、独立扩缩容
服务器内存	4GB+	8GB+（推荐 16GB）
Nginx 反代	`/admin-api → :48080`	`/admin-api → Gateway :48080`

九、常见问题

Q1: IDEA 启动报 "Command line is too long"

点击 IDEA 报错中的蓝色链接，自动切换为 @argfile 方式即可解决。也可手动修改 .idea/workspace.xml，将 shortenCommandLine 设置为 ARGS_FILE。

Q2: 微服务模式下，服务在 Nacos 看不到

bash

# 检查 Nacos 连接
telnet 127.0.0.1 8848

# 检查启动日志中的 Nacos 连接信息
# 常见原因：
# 1. Nacos 地址配错
# 2. 命名空间 ID 不匹配（必须是 dev）
# 3. 网络不通

Q3: 启动时数据库连接失败

确认 MySQL 地址、端口、账号密码与 application-local.yaml 中配置一致。如果使用 Docker 运行 MySQL，注意默认端口可能是 33061 而非 3306。

Q4: 前端启动后，接口 401 未授权

确认后端服务已正常启动，且前端 Vite 代理配置正确。默认情况下，开发模式会自动代理 /admin-api 到后端。

Q5: 单体模式打包后 JAR 文件过大（超过 500MB）

确保打包时添加了 -Dskip.repackage=true 参数。该参数让各子模块跳过 spring-boot-maven-plugin 的 repackage，避免子模块各自打出 Fat JAR 导致重复打包。

正确命令：

bash

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

Q6: 微服务模式下，Gateway 报 503 Service Unavailable

目标微服务尚未启动或未在 Nacos 注册。等待目标服务启动完成（约 30 秒），然后在 Nacos 控制台确认服务已注册。

Q7: 想只启动部分服务，最小化资源占用

最小可用集（管理后台基础功能）：Gateway + System + Infra
加上 OA 和工作流：Gateway + System + Infra + BPM + OA
内存估算：每个服务约 512MB~1GB，Gateway 约 256MB

十、接口文档

项目集成了 Knife4j（Swagger）接口文档：

模式	文档地址	说明
单体模式	`http://127.0.0.1:48080/doc.html`	所有接口在同一文档
微服务模式	`http://127.0.0.1:48080/doc.html`	Gateway 聚合所有微服务的文档

十一、项目结构概览

project-root/
├── yudao-gateway/                          # API 网关（微服务模式）
├── yudao-server/                           # 单体启动入口
├── yudao-module-system/                    # 系统管理模块
│   ├── yudao-module-system-api/            #   对外接口
│   └── yudao-module-system-server/         #   业务实现（端口 48081）
├── yudao-module-infra/                     # 基础设施模块
│   ├── yudao-module-infra-api/
│   └── yudao-module-infra-server/          #   （端口 48082）
├── yudao-module-bpm/                       # 工作流模块（端口 48083）
├── yudao-module-oa/                        # OA 协同办公模块（端口 48101）
├── yudao-module-hrm/                       # 人力资源模块
├── yudao-module-crm/                       # CRM 模块（端口 48089）
├── yudao-module-erp/                       # ERP 模块（端口 48088）
├── yudao-module-pay/                       # 支付模块（端口 48085）
├── yudao-module-ai/                        # AI 大模型模块（端口 48090）
├── yudao-module-iot/                       # 物联网模块（端口 48091）
├── yudao-module-mall/                      # 商城模块（商品/交易/营销/统计）
├── yudao-module-member/                    # 会员模块（端口 48087）
├── yudao-module-report/                    # 报表模块（端口 48084）
├── yudao-module-mp/                        # 公众号模块（端口 48086）
├── yudao-framework/                        # 公共框架组件
├── sql/                                    # 数据库初始化脚本
│   ├── mysql/
│   ├── postgresql/
│   ├── oracle/
│   └── ...
└── pom.xml                                 # Maven 根配置

前端项目结构：

frontend-root/
├── apps/
│   └── web-antd/                           # 管理后台前端（Ant Design Vue）
│       ├── src/
│       │   ├── api/                        # API 接口定义
│       │   ├── views/                      # 页面组件
│       │   ├── components/                 # 公共组件
│       │   ├── router/                     # 路由配置
│       │   └── store/                      # 状态管理
│       └── vite.config.mts
├── packages/                               # 公共包
├── internal/                               # 内部工具
└── pnpm-workspace.yaml

十二、下一步

目标	参考文档
生产环境部署（单体）	快速部署指南
生产环境部署（微服务）	微服务部署指南
新增业务模块	参考已有模块结构，创建对应的 `yudao-module-xxx`
前端开发	在 `apps/web-antd/src/views/` 下新增页面

快速启动文档 ​

一、环境准备 ​

二、克隆代码 ​

三、初始化基础设施（必选） ​

3.1 初始化 MySQL ​

3.2 初始化 Redis ​

3.3 初始化 Nacos（微服务模式必需） ​

四、基础设施（可选） ​

4.1 RocketMQ ​

4.2 XXL-Job ​

五、启动后端项目 ​

方式一：微服务模式（推荐生产环境） ​

5.1 编译项目 ​

5.2 启动 Gateway 网关服务 ​

5.3 启动 System 系统服务 ​

5.4 启动 Infra 基础设施服务 ​

5.5 启动其他业务服务（按需） ​

5.6 验证服务注册 ​

方式二：单体模式（推荐开发 & 快速体验） ​

单体模式的好处 ​

如何单体启动 ​

如何打包部署 ​

六、启动前端项目 ​

6.1 安装依赖 ​

6.2 启动开发服务器 ​

6.3 访问管理后台 ​

七、前端构建与部署 ​

7.1 构建生产包 ​

7.2 部署到服务器 ​

7.3 Nginx 配置 ​

八、单体模式 vs 微服务模式对比 ​

九、常见问题 ​

Q1: IDEA 启动报 "Command line is too long" ​

Q2: 微服务模式下，服务在 Nacos 看不到 ​

Q3: 启动时数据库连接失败 ​

Q4: 前端启动后，接口 401 未授权 ​

Q5: 单体模式打包后 JAR 文件过大（超过 500MB） ​

Q6: 微服务模式下，Gateway 报 503 Service Unavailable ​

Q7: 想只启动部分服务，最小化资源占用 ​

十、接口文档 ​

十一、项目结构概览 ​

十二、下一步 ​

快速启动文档

一、环境准备

二、克隆代码

三、初始化基础设施（必选）

3.1 初始化 MySQL

3.2 初始化 Redis

3.3 初始化 Nacos（微服务模式必需）

四、基础设施（可选）

4.1 RocketMQ

4.2 XXL-Job

五、启动后端项目

方式一：微服务模式（推荐生产环境）

5.1 编译项目

5.2 启动 Gateway 网关服务

5.3 启动 System 系统服务

5.4 启动 Infra 基础设施服务

5.5 启动其他业务服务（按需）

5.6 验证服务注册

方式二：单体模式（推荐开发 & 快速体验）

单体模式的好处

如何单体启动

如何打包部署

六、启动前端项目

6.1 安装依赖

6.2 启动开发服务器

6.3 访问管理后台

七、前端构建与部署

7.1 构建生产包

7.2 部署到服务器

7.3 Nginx 配置

八、单体模式 vs 微服务模式对比

九、常见问题

Q1: IDEA 启动报 "Command line is too long"

Q2: 微服务模式下，服务在 Nacos 看不到

Q3: 启动时数据库连接失败

Q4: 前端启动后，接口 401 未授权

Q5: 单体模式打包后 JAR 文件过大（超过 500MB）

Q6: 微服务模式下，Gateway 报 503 Service Unavailable

Q7: 想只启动部分服务，最小化资源占用

十、接口文档

十一、项目结构概览

十二、下一步