RuoYi-Cloud微服务项目实战：从零到一，手把手教你用Nacos 2.x和Sentinel 1.8.5搭建企业级开发环境

原创于 2026-06-13 16:40:40 发布 · 597 阅读

5 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#RuoYi-Cloud #微服务 #Nacos #Sentinel

RuoYi-Cloud微服务实战：Nacos 2.x与Sentinel 1.8.5环境搭建全指南

第一次接触RuoYi-Cloud这类微服务框架时，面对Nacos、Sentinel、Gateway这些组件，很多开发者都会感到无从下手。本文将用最直白的语言，带你一步步完成开发环境搭建，避开那些官方文档没明说的坑。不同于简单的安装教程，我们会深入每个组件的配置逻辑，让你真正理解为什么这么配，以及遇到常见报错该如何解决。

1. 基础环境准备：避开版本兼容的坑

在开始之前，确保你的开发机满足以下基础要求。很多人卡在第一步就是因为忽略了版本匹配问题：

JDK 1.8+ （推荐JDK 11，实测RuoYi-Cloud对JDK 17存在兼容性问题）
Maven 3.6+ （配置阿里云镜像加速依赖下载）
Redis 5.0+ （持久化关闭时注意内存溢出风险）
MySQL 5.7+ （8.0版本需要调整密码加密方式）

重要提示：Windows用户请使用PowerShell代替CMD，避免路径解析问题；Mac/Linux用户注意文件权限设置。

用以下命令验证Java环境：

java -version
mvn -v
redis-cli ping

如果Redis返回 PONG 表示服务正常。MySQL需要提前创建好数据库：

CREATE DATABASE `ry-cloud` DEFAULT CHARACTER SET utf8mb4;
CREATE DATABASE `ry-config` DEFAULT CHARACTER SET utf8mb4;

2. Nacos 2.x部署实战：不只是启动那么简单

2.1 持久化配置：告别数据丢失烦恼

下载Nacos 2.0.3+版本后，修改 conf/application.properties ：

# 数据源配置（需提前创建ry-config数据库）
spring.datasource.platform=mysql
db.num=1
db.url.0=jdbc:mysql://127.0.0.1:3306/ry-config?useUnicode=true&characterEncoding=utf8&connectTimeout=1000&socketTimeout=3000&autoReconnect=true
db.user=root
db.password=your_password

启动时常见问题排查：

端口冲突 ：修改 server.port=8848 为其他端口
内存不足 ：调整 bin/startup.sh 中的JVM参数：
```
JAVA_OPT="${JAVA_OPT} -Xms512m -Xmx512m"
```
集群模式 ：单机测试时务必添加 -m standalone 参数

2.2 命名空间与配置管理

通过 http://localhost:8848/nacos 登录后（默认账号nacos/nacos），建议：

新建命名空间（如dev/test/prod）
导入RuoYi-Cloud的配置压缩包
检查关键配置项：
- ruoyi-gateway-dev.yml 中的Redis连接信息
- ruoyi-auth-dev.yml 中的JWT密钥

3. Sentinel 1.8.5深度配置：不只是Dashboard

3.1 定制化启动参数

创建 start_sentinel.bat （Windows）或 start_sentinel.sh （Linux）：

java -Dserver.port=18080 \
     -Dcsp.sentinel.dashboard.server=localhost:18080 \
     -Dproject.name=sentinel-dashboard \
     -Dsentinel.dashboard.auth.username=admin \
     -Dsentinel.dashboard.auth.password=123456 \
     -jar sentinel-dashboard-1.8.5.jar

关键参数说明：

-Dserver.servlet.session.timeout=7200 控制登录会话过期时间
-Dauth.enabled=true 必须开启否则无权限控制
-Dcsp.sentinel.api.port=8719 客户端通信端口

3.2 与RuoYi-Cloud集成技巧

修改各微服务的 bootstrap.yml ：

spring:
  cloud:
    sentinel:
      transport:
        dashboard: localhost:18080
        port: 8719
      eager: true  # 立即初始化

常见集成问题：

无监控数据 ：检查8719端口是否被占用
流控规则不生效 ：确认 spring-cloud-starter-alibaba-sentinel 版本与Sentinel兼容
鉴权失败 ：Dashboard的账号密码需与客户端配置一致

4. 项目启动与调试：那些官方没告诉你的细节

4.1 一键启动脚本编写

创建 start_all.bat 实现顺序启动：

@echo off
start "Nacos" cmd /k "cd D:\nacos\bin && startup.cmd -m standalone"
timeout /t 30
start "Sentinel" cmd /k "java -jar sentinel-dashboard-1.8.5.jar"
timeout /t 15
start "Gateway" cmd /k "cd D:\ruoyi-cloud\ruoyi-gateway && mvn spring-boot:run"
start "Auth" cmd /k "cd D:\ruoyi-cloud\ruoyi-auth && mvn spring-boot:run"
...

4.2 网关路由调试技巧

使用Postman测试时注意：

先获取token：

POST /auth/login
Content-Type: application/json

{"username":"admin","password":"admin123"}

在后续请求Header中添加：
```
Authorization: Bearer [token]
```

4.3 常见启动报错解决方案

错误现象	可能原因	解决方案
注册Nacos失败	网络隔离或防火墙	检查 `ping nacos_server_ip`
Redis连接超时	密码未配置或保护模式	修改redis.conf的 `protected-mode no`
数据库表不存在	SQL未执行或字符集问题	确认 `ry-cloud` 库中有 `sys_*` 表

5. 进阶实战：自定义微服务开发

以添加一个员工管理模块为例：

在 ry-cloud 库创建表：

CREATE TABLE `sys_employee` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `name` varchar(50) DEFAULT '',
  `dept_id` bigint DEFAULT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB;

使用RuoYi代码生成器：

导入刚创建的表
设置包路径为 com.ruoyi.system

生成后需手动修改：

// 在EmployeeController添加部门下拉框数据
@GetMapping("/deptOptions")
public List<SysDept> deptOptions() {
    return deptService.selectDeptList(new SysDept());
}

前端Vue组件对接：

// 在api/system/employee.js添加
export function listEmployee(query) {
  return request({
    url: '/system/employee/list',
    method: 'get',
    params: query
  })
}

开发过程中如果遇到页面空白，优先检查：