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

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

---

目录

1. 环境准备与版本要求

2. 下载源码并导入 IDEA

3. 数据库准备与 SQL 导入

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

5. 启动 Nacos 服务

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

7. 启动 RuoYi 微服务各模块

8. 启动前端（ruoyi-ui）项目

9. 常见问题与排查建议

---

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.Driver
    url: jdbc:mysql://localhost:3306/ry-cloud?useUnicode=true&characterEncoding=utf8&serverTimezone=GMT%2B8
    username: root
    password: 123456

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

7. 启动 RuoYi 微服务各模块

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

GatewayApplication - Bootstrap.yaml

# Tomcat
server:
  port: 8080

# Spring
spring:
  application:
    # 应用名称
    name: ruoyi-gateway
  profiles:
    # 环境配置
    active: dev
  cloud:
    nacos:
      discovery:
        # 服务注册地址
        server-addr: localhost:8848
        username: nacos
        password: nacos
      config:
        # 配置中心地址
        server-addr: localhost:8848
        username: nacos
        password: nacos
        # 配置文件格式
        file-extension: yml
        # 共享配置
        shared-configs:
          - application-${spring.profiles.active}.${spring.cloud.nacos.config.file-extension}
    sentinel:
      # 取消控制台懒加载
      eager: true
      transport:
        # 控制台地址
        dashboard: 127.0.0.1:8718
      # nacos配置持久化
      datasource:
        ds1:
          nacos:
            server-addr: localhost:8848
            dataId: sentinel-ruoyi-gateway
            groupId: DEFAULT_GROUP
            data-type: json
            rule-type: gw-flow

AuthApplicaiton - Bootstrap.yaml

# Tomcat
server: 
  port: 9200

# Spring
spring: 
  application:
    # 应用名称
    name: ruoyi-auth
  profiles:
    # 环境配置
    active: dev
  cloud:
    nacos:
      discovery:
        # 服务注册地址
        server-addr: 127.0.0.1:8848
        username: nacos
        password: nacos
      config:
        # 配置中心地址
        server-addr: 127.0.0.1:8848
        username: nacos
        password: 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-system
  profiles:
    # 环境配置
    active: dev
  cloud:
    nacos:
      discovery:
        # 服务注册地址
        server-addr: 127.0.0.1:8848
        username: nacos
        password: nacos
      config:
        # 配置中心地址
        server-addr: 127.0.0.1:8848
        username: nacos
        password: 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 是能打开的。

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

可能原因总结

1. Nacos 启动慢/未就绪：微服务启动早于 Nacos，注册失败。

2. 端口监听或网络隔离：Nacos 只监听 127.0.0.1，外部/容器内访问不到。

3. 数据库未初始化/配置错：Nacos 持久化没连上 MySQL，实际并未"健康"启动。

4. 防火墙/网络权限：端口被阻塞，外部机器/容器不能访问。

5. 客户端配置写成 localhost：只适用于本机测试，跨主机或Docker环境务必用真实 IP。

6. 多套 Nacos 实例混用：配置文件、注册中心混乱，导致服务互相注册不上。

7. 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

MySQL 连接失败 / 数据库不存在

• 报错：
  java.sql.SQLSyntaxErrorException: Unknown database 'ry-cloud'

• 解决：

  • 手动创建数据库（见上文）

  • 必须导入官方SQL

  • 数据库参数严格对齐，端口/字符集都别写错

多套Nacos/多套配置文件混用导致诡异Bug

• 表现：

  • 日志一堆奇怪报错、服务注册不上

• 解决：

  • 本地开发只保留一份Nacos和配置文件，别多头操作

  • 推荐本地用源码解压版，测试环境用docker，但不要混着来

  • 配置路径、内容一定统一、明确