RuoYi-Cloud 微服务本地部署详细流程实录（IDEA + 本地 Windows 环境）

本文以 RuoYi-Cloud 3.x 版本为例，开发工具用的是 IntelliJ IDEA，数据库为 MySQL 8.x，注册中心选用本地 Nacos 2.2.3，Redis 为 3.x/5.x 均可。亲测全流程可用，细节与官方文档略有不同，避免新手踩坑。

0.官方教程写法

微服务官方文档：https://doc.ruoyi.vip/ruoyi-cloud/

Gitee 仓库源码：https://gitee.com/y_project/RuoYi-Cloud

1. 环境准备

建议软件及版本（亲测可用）：

组件	推荐版本（最低）	我的实际版本	检查命令
JDK	1.8+（推荐17）	openjdk 17.0.16 Temurin	`java -version`
MySQL	5.7+（推荐8.x）	MySQL 8.0.42	`mysql -V`
Redis	3.0+	Redis 3.0.504（本地Win）	`redis-server --version`
Maven	3.0+	Apache Maven 3.9.10	`mvn -v`
Node.js	12+	v16.20.2	`node -v`
Nacos	2.2.3（重点！）	2.2.3（本地包）	启动后网页端口 `8848`

2. 下载源码并导入 IDEA

访问 RuoYi-Cloud Gitee 仓库
下载最新源码，解压到本地工作目录。
打开 IntelliJ IDEA，File -> Open 选择项目根目录。
第一次导入会自动加载 Maven 依赖，视网速情况可能较慢。
不需要 Eclipse，IDEA 完全兼容 RuoYi-Cloud。

3. 数据库准备与 SQL 导入

用 Navicat/DBeaver/DataGrip 等工具新建数据库：

ry-cloud （主业务库，必须）
ry-config （Nacos 配置/注册中心专用库，必须）

CREATE DATABASE ry-cloud DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
CREATE DATABASE ry-config DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

导入 SQL 脚本（解压源码后 /sql 目录里可找到）：

ry-cloud 导入：ry_2021xxxx.sql（必须），如需定时任务再导入 quartz.sql（可选）
ry-config 导入：ry_config_2021xxxx.sql（必须）

⚠️ 数据库表没导好，后续 Nacos 注册、微服务启动会一堆报错！

如果不知道怎么使用Navicat导入SQL文件，请参考:Navicat 导入 SQL 文件_navicat导入sql文件-CSDN博客

4. Nacos 配置：持久化&本地启动&关键参数

建议用 Nacos 2.2.3，本地解压目录结构如下（重点检查 bin、conf 文件夹是否齐全）：

持久化配置

编辑 nacos/conf/application.properties，添加/修改如下内容（必须，不配不行）：

# 指定MySQL持久化
spring.datasource.platform=mysql
db.num=1
db.url.0=jdbc:mysql://127.0.0.1:3306/ry-config?characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true&useUnicode=true&useSSL=false&serverTimezone=UTC
db.user.0=root
db.password.0=123456# 推荐token配置，防止鉴权403
nacos.core.auth.plugin.nacos.token.secret.key=VGhpc0lzTXlDdXN0b21TZWNyZXRLZXkwMTIzNDU2Nzg=

⚠️ 一定用你本地的数据库用户名和密码！

启动脚本参数

打开 nacos/bin/startup.cmd，检查并确保如下参数设置：

set MODE="standalone"
set FUNCTION_MODE="all"
set SERVER=nacos-server

5. 启动 Nacos 服务

推荐方式：本地 Windows 下双击 startup.cmd，或命令行运行：

startup.cmd -m standalone

等待命令行提示 Nacos 启动成功。
访问 http://localhost:8848/nacos/
默认账号密码：nacos / nacos

6. 检查并修改 Nacos 配置中心

进入 Nacos 后台 - 配置管理

路径：http://localhost:8848/nacos/index.html#/configurationManagement
必须存在下列配置文件：
- application-dev.yml
- ruoyi-gateway-dev.yml
- ruoyi-auth-dev.yml
- ruoyi-system-dev.yml
- ruoyi-monitor-dev.yml
- ruoyi-gen-dev.yml
- ruoyi-job-dev.yml
- ruoyi-file-dev.yml
- sentinel-ruoyi-gateway

修改微服务 yml 的数据库配置！

例如 ruoyi-system-dev.yml 中：

datasource:master:driver-class-name: com.mysql.cj.jdbc.Driverurl: jdbc:mysql://localhost:3306/ry-cloud?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8username: rootpassword: 123456

⚠️ 密码、端口、数据库名一定和你本地一致！否则服务启动会报错。修改后一定记得点击“发布”或“保存”。

7. 启动 RuoYi 微服务各模块

修改GatewayApplication、SystemApplication、AuthApplicaiton配置文件：

GatewayApplication - Bootstrap.yaml

# Tomcat
server:port: 8080# Spring
spring:application:# 应用名称name: ruoyi-gatewayprofiles:# 环境配置active: devcloud:nacos:discovery:# 服务注册地址server-addr: localhost:8848username: nacospassword: nacosconfig:# 配置中心地址server-addr: localhost:8848username: nacospassword: nacos# 配置文件格式file-extension: yml# 共享配置shared-configs:- application-${spring.profiles.active}.${spring.cloud.nacos.config.file-extension}sentinel:# 取消控制台懒加载eager: truetransport:# 控制台地址dashboard: 127.0.0.1:8718# nacos配置持久化datasource:ds1:nacos:server-addr: localhost:8848dataId: sentinel-ruoyi-gatewaygroupId: DEFAULT_GROUPdata-type: jsonrule-type: gw-flow

AuthApplicaiton - Bootstrap.yaml

# Tomcat
server: port: 9200# Spring
spring: application:# 应用名称name: ruoyi-authprofiles:# 环境配置active: devcloud:nacos:discovery:# 服务注册地址server-addr: 127.0.0.1:8848username: nacospassword: nacosconfig:# 配置中心地址server-addr: 127.0.0.1:8848username: nacospassword: nacos# 配置文件格式file-extension: yml# 共享配置shared-configs:- application-${spring.profiles.active}.${spring.cloud.nacos.config.file-extension}

SystemApplication - Bootstrap.yaml

# Tomcat
server:port: 9201# Spring
spring: application:# 应用名称name: ruoyi-systemprofiles:# 环境配置active: devcloud:nacos:discovery:# 服务注册地址server-addr: 127.0.0.1:8848username: nacospassword: nacosconfig:# 配置中心地址server-addr: 127.0.0.1:8848username: nacospassword: nacos# 配置文件格式file-extension: yml# 共享配置shared-configs:- application-${spring.profiles.active}.${spring.cloud.nacos.config.file-extension}

在 IDEA 的右侧服务面板，依次启动：
1. RuoYiGatewayApplication（网关，必须）
2. RuoYiAuthApplication（认证，必须）
3. RuoYiSystemApplication（系统，必须）
其它服务（如 gen、job、file、monitor）按需启动。
启动日志出现类似 “Started RuoYiGatewayApplication in XX seconds” 即为成功。

若服务注册到 Nacos，Nacos 后台“服务管理”里能看到对应服务。

8. 启动前端（ruoyi-ui）

进入 ruoyi-ui 目录，首次安装依赖：
```
npm install
```
开发环境启动前端：
在 IDEA/VSCode 里，打开 package.json，直接点击 dev 脚本旁的“运行”按钮；
或终端命令：
```
npm run dev
```

默认访问 http://localhost:80/ 或 8080 端口（看控制台打印）。

初始账号密码：
用户名：admin
密码：123456

9. 常见问题与实战踩坑总结（重点关注Nacos注册异常）

❗【重中之重】Nacos客户端无法注册/连接不上（Client not connected, current status:STARTING）

典型现象

启动 gateway 或 system 服务时，控制台反复出现：
```
com.alibaba.nacos.api.exception.NacosException: Client not connected, current status:STARTING
```
com.alibaba.nacos.api.exception.NacosException: Client not connected, current status:STARTING
但你直接访问 http://localhost:8848/nacos 是能打开的。

服务死活注册不上，项目启动失败或服务断连。

可能原因总结

Nacos 启动慢/未就绪：微服务启动早于 Nacos，注册失败。
端口监听或网络隔离：Nacos 只监听 127.0.0.1，外部/容器内访问不到。
数据库未初始化/配置错：Nacos 持久化没连上 MySQL，实际并未“健康”启动。
防火墙/网络权限：端口被阻塞，外部机器/容器不能访问。
客户端配置写成 localhost：只适用于本机测试，跨主机或Docker环境务必用真实 IP。
多套 Nacos 实例混用：配置文件、注册中心混乱，导致服务互相注册不上。
Nacos 版本兼容性/官方 bug：有些版本（如 2.0.3/2.0.4）兼容性较差。

实战终极解决办法

🚩 我的亲测建议：

务必用 Nacos 2.2.3 官方本地包（不要用低版本/来路不明的Docker镜像）

配置文件只保留一套，application.properties 必须写对持久化和 token 参数（见上文配置节）

一定保证数据库已初始化，并且Nacos已成功连上MySQL

启动前先访问：http://localhost:8848/nacos/v1/console/health/readiness，确认状态为OK

各服务连接Nacos时，nacos.server-addr 推荐直接写本机IP，如 192.168.1.x:8848，别写localhost

遇到“STARTING”不要只盯业务服务，先排查Nacos服务端

本地/测试环境不要用多套Nacos，否则配置、注册容易混乱

Docker用户务必端口映射 -p 8848:8848，配置文件挂载用 -v

其他常见易踩坑

JAVA_HOME/JDK版本不对导致Nacos无法启动

报错：
Please set the JAVA_HOME variable in your environment, We need java(x64)! jdk8 or later is better!
解决：
- JAVA_HOME 必须指向 JDK（不要指向 JRE）
- 设置后重开命令行窗口，echo %JAVA_HOME% 检查
- java -version 必须能查到JDK