RuoYi-Cloud-Plus 开发与部署指南
本文详细介绍了RuoYi-Cloud-Plus项目的初始化、开发环境搭建、代码生成器使用、Docker编排部署以及常见问题解决方案。内容涵盖从项目克隆、依赖服务配置到微服务启动的全流程，并提供了代码生成器的扩展方法和Docker化部署的最佳实践。
项目初始化与开发环境搭建
RuoYi-Cloud-Plus 是一个基于 Spring Cloud Alibaba 的微服务通用权限管理系统，提供了丰富的功能和模块化的设计。为了顺利开始开发，首先需要完成项目的初始化与开发环境的搭建。以下是一个详细的步骤指南：
1. 环境准备
在开始之前，确保你的开发环境满足以下要求：
- JDK 17+：项目基于 Java 17 开发，确保已安装并配置好环境变量。
- Maven 3.6+：用于项目的依赖管理和构建。
- Docker：用于运行依赖的服务（如 MySQL、Redis、Nacos 等）。
- IDE：推荐使用 IntelliJ IDEA 或 Eclipse 进行开发。
验证环境
运行以下命令验证 JDK 和 Maven 是否已正确安装：
java -version
mvn -version
如果未安装 Maven，可以参考 Maven 官方文档 进行安装。
2. 克隆项目
使用以下命令克隆项目到本地：
git clone https://gitcode.com/dromara/RuoYi-Cloud-Plus.git
cd RuoYi-Cloud-Plus
3. 配置依赖服务
项目依赖多个服务（如 MySQL、Redis、Nacos 等），可以通过 Docker 快速启动这些服务。项目提供了 docker-compose.yml 文件，位于 script/docker 目录下。
运行以下命令启动服务：
cd script/docker
docker-compose up -d
服务说明
- MySQL：默认端口
3306，用户名root，密码123456。 - Redis：默认端口
6379。 - Nacos：默认端口
8848，用户名nacos，密码nacos。
4. 初始化数据库
项目提供了 SQL 脚本用于初始化数据库，位于 script/sql 目录下。运行以下命令导入数据：
mysql -u root -p < script/sql/ry-cloud.sql
5. 构建项目
在项目根目录下运行以下命令构建项目：
mvn clean install
6. 启动服务
项目包含多个微服务模块，可以通过以下命令启动核心服务：
cd ruoyi-auth
mvn spring-boot:run
cd ../ruoyi-gateway
mvn spring-boot:run
7. 访问系统
启动完成后，可以通过以下地址访问系统：
- 前端地址：
http://localhost:80 - Nacos 控制台：
http://localhost:8848/nacos
8. 开发工具推荐
- Lombok：减少样板代码。
- MapStruct：简化对象映射。
- MyBatis-Plus：增强 MyBatis 功能。
9. 常见问题
- Maven 依赖下载失败：检查网络或配置镜像源。
- 服务启动失败：检查日志文件，确认依赖服务是否正常运行。
通过以上步骤，你已经完成了 RuoYi-Cloud-Plus 项目的初始化与开发环境搭建。接下来可以开始进行功能开发或二次定制。
代码生成器使用与扩展
RuoYi-Cloud-Plus 的代码生成器是一个强大的工具，能够根据数据库表结构自动生成前后端代码，显著提升开发效率。本节将详细介绍代码生成器的使用方法、核心组件以及如何扩展其功能。
代码生成器核心组件
代码生成器的核心组件主要包括以下几个类：
-
GenTable 和 GenTableColumn
这两个类分别表示数据库表和表的列信息，用于存储生成代码所需的元数据。 -
VelocityUtils
负责模板渲染，将数据库表信息转换为代码文件。支持动态生成 Java 类、XML 映射文件、前端页面等。 -
GenUtils
提供工具方法，如初始化表信息、转换字段名、生成模块名称等。 -
GenTableServiceImpl
实现代码生成的核心逻辑，包括表信息的导入、同步、代码生成等。 -
GenConfig
配置代码生成的基本参数，如作者、包名、表前缀等。
以下是一个简单的类图，展示这些组件之间的关系：
classDiagram
class GenTable {
+Long id
+String tableName
+String tableComment
+List~GenTableColumn~ columns
+GenTableColumn pkColumn
}
class GenTableColumn {
+Long id
+String columnName
+String columnComment
+String javaType
}
class VelocityUtils {
+prepareContext(GenTable genTable)
+getFileName(String template, GenTable genTable)
}
class GenUtils {
+initTable(GenTable genTable)
+initColumnField(GenTableColumn column, GenTable table)
}
class GenTableServiceImpl {
+selectGenTableById(Long id)
+updateGenTable(GenTable genTable)
+generatorCode(Long tableId)
}
class GenConfig {
+String author
+String packageName
}
GenTable "1" *-- "n" GenTableColumn
VelocityUtils --> GenTable
GenUtils --> GenTable
GenUtils --> GenTableColumn
GenTableServiceImpl --> GenTable
GenTableServiceImpl --> GenTableColumn
使用代码生成器
1. 配置代码生成参数
在 application.yml 中配置代码生成的基本参数，如作者、包名等：
gen:
author: YourName
packageName: com.yourpackage
autoRemovePre: true
tablePrefix: sys_
2. 导入表结构
通过以下步骤导入数据库表结构：
- 在数据库中创建表。
- 在代码生成器界面中点击“导入表”，选择需要生成代码的表。
3. 生成代码
导入表结构后，点击“生成代码”按钮，系统会自动生成以下文件：
- 后端代码：Controller、Service、Mapper、Entity 等。
- 前端代码：Vue 页面、API 接口等。
扩展代码生成器
1. 自定义模板
代码生成器使用 Velocity 模板引擎渲染代码文件。可以通过修改模板文件来自定义生成的代码：
- 模板文件路径：
resources/templates - 支持自定义模板类型，如新增一个
custom.vm模板。
2. 扩展字段类型映射
在 GenUtils 类中，可以通过修改 initColumnField 方法扩展字段类型映射逻辑。例如：
public static void initColumnField(GenTableColumn column, GenTable table) {
// 自定义字段类型映射
if (column.getColumnType().equals("custom_type")) {
column.setJavaType("CustomType");
}
}
3. 新增生成逻辑
在 GenTableServiceImpl 类中，可以通过扩展 generatorCode 方法新增生成逻辑。例如：
public void generatorCode(Long tableId) {
// 原有逻辑
GenTable table = baseMapper.selectGenTableById(tableId);
// 新增自定义逻辑
generateCustomFiles(table);
}
示例：生成代码流程
以下是一个生成代码的流程图：
flowchart TD
A[导入表结构] --> B[配置生成参数]
B --> C[生成后端代码]
C --> D[生成前端代码]
D --> E[下载代码包]
总结
RuoYi-Cloud-Plus 的代码生成器通过灵活的配置和扩展能力，能够满足不同项目的需求。通过自定义模板和扩展逻辑，可以进一步优化生成代码的质量和效率。
Docker 编排与一键部署
RuoYi-Cloud-Plus 提供了完整的 Docker 编排支持，通过 docker-compose.yml 文件可以一键部署所有依赖服务和微服务模块。以下是对 Docker 编排与一键部署的详细介绍。
Docker Compose 文件解析
项目的 docker-compose.yml 文件位于 script/docker 目录下，定义了所有依赖服务的容器化配置。以下是一个简化的示例：
version: '3.8'
services:
nacos:
image: nacos/nacos-server:2.0.3
container_name: ruoyi-nacos
ports:
- "8848:8848"
volumes:
- ./nacos/conf:/home/nacos/conf
environment:
- MODE=standalone
redis:
image: redis:6.2.6
container_name: ruoyi-redis
ports:
- "6379:6379"
volumes:
- ./redis/data:/data
- ./redis/conf/redis.conf:/usr/local/etc/redis/redis.conf
command: redis-server /usr/local/etc/redis/redis.conf
mysql:
image: mysql:8.0.28
container_name: ruoyi-mysql
ports:
- "3306:3306"
environment:
- MYSQL_ROOT_PASSWORD=123456
volumes:
- ./mysql/data:/var/lib/mysql
- ./mysql/conf:/etc/mysql/conf.d
关键配置说明
- Nacos：作为注册中心和配置中心，端口为
8848，数据卷挂载了配置文件目录。 - Redis：用于缓存，端口为
6379，挂载了数据目录和配置文件。 - MySQL：数据库服务，端口为
3306，挂载了数据目录和配置文件。
一键部署流程
-
启动依赖服务： 运行以下命令启动所有依赖服务：
cd script/docker docker-compose up -d -
构建微服务镜像： 每个微服务模块（如
ruoyi-gateway、ruoyi-auth等）均提供了Dockerfile，可以通过以下命令构建镜像：docker build -t ruoyi-gateway:latest ruoyi-gateway/ -
启动微服务： 使用
docker-compose启动所有微服务：docker-compose -f docker-compose-microservices.yml up -d
微服务部署示例
以下是一个微服务模块的 Dockerfile 示例（以 ruoyi-gateway 为例）：
FROM openjdk:17-jdk-slim
VOLUME /tmp
COPY target/ruoyi-gateway.jar app.jar
ENTRYPOINT ["java", "-jar", "/app.jar"]
关键点
- 基础镜像：使用
openjdk:17-jdk-slim作为基础镜像。 - 构建命令：将编译后的
jar文件复制到容器中，并通过ENTRYPOINT启动服务。
部署验证
-
检查容器状态：
docker ps确保所有容器（如
ruoyi-nacos、ruoyi-redis等）均处于运行状态。 -
访问服务：
- Nacos 控制台：
http://localhost:8848/nacos - 网关服务：
http://localhost:8080
- Nacos 控制台：
常见问题
-
端口冲突： 如果某个端口已被占用，修改
docker-compose.yml中的端口映射即可。 -
数据持久化： 所有数据卷（如 MySQL 数据、Redis 数据）均挂载到本地目录，确保数据持久化。
-
日志查看： 使用以下命令查看容器日志：
docker logs -f ruoyi-gateway
通过以上步骤，可以快速完成 RuoYi-Cloud-Plus 的 Docker 化部署。
常见问题与解决方案
在开发与部署RuoYi-Cloud-Plus项目时，可能会遇到一些常见问题。本节将针对这些问题提供详细的解决方案，帮助开发者快速定位并解决问题。
1. 登录认证失败
问题描述：用户登录时提示“授权类型不正确”或“验证码错误”。
解决方案：
- 授权类型不正确：检查登录请求中的
grant_type参数是否正确。支持的授权类型包括password、sms、email等。确保前端传递的授权类型与后端配置一致。 - 验证码错误：
- 确保验证码未过期（默认有效期为5分钟）。
- 检查验证码是否正确，区分大小写。
- 若使用Redis存储验证码，确保Redis服务正常运行。
// 示例：验证码校验逻辑
if (!captcha.equals(redisCache.getCacheObject(verifyKey))) {
throw new CaptchaException();
}
2. 网关限流异常
问题描述：请求被Sentinel拦截，返回“Too Many Requests”。
解决方案：
- 检查Sentinel的限流规则配置，确保规则符合业务需求。
- 调整限流阈值或关闭不必要的限流规则。
- 若为突发流量，可考虑增加服务实例或优化接口性能。
// 示例：Sentinel限流处理
@SentinelResource(value = "resourceName", blockHandler = "handleBlock")
public Mono<ServerResponse> handleBlock(ServerWebExchange exchange, BlockException ex) {
return ServerResponse.status(HttpStatus.TOO_MANY_REQUESTS).build();
}
3. 文件上传失败
问题描述：上传文件时提示“文件大小超过限制”或“文件名过长”。
解决方案：
- 文件大小限制：检查配置文件中的
spring.servlet.multipart.max-file-size和spring.servlet.multipart.max-request-size参数，适当调整大小限制。 - 文件名长度限制：默认文件名长度限制为100字符，可通过配置文件修改。
# 示例：文件上传配置
spring:
servlet:
multipart:
max-file-size: 10MB
max-request-size: 10MB
4. 分布式事务失败
问题描述：跨服务调用时事务未回滚。
解决方案：
- 确保Seata服务正常运行，且配置文件中
seata.enabled=true。 - 检查
@GlobalTransactional注解是否添加到分布式事务的入口方法上。 - 验证数据库是否支持Seata（如MySQL需开启XA模式）。
// 示例：分布式事务注解
@GlobalTransactional
public void distributedMethod() {
// 业务逻辑
}
5. Redis连接异常
问题描述：Redis连接超时或无法访问。
解决方案：
- 检查Redis服务是否启动，网络是否通畅。
- 验证配置文件中的
spring.redis.host和spring.redis.port是否正确。 - 若为集群模式，确保所有节点配置正确。
# 示例：Redis配置
spring:
redis:
host: 127.0.0.1
port: 6379
password: your_password
6. 服务注册失败
问题描述：服务未注册到Nacos。
解决方案：
- 检查Nacos服务是否正常运行。
- 验证配置文件中的
spring.cloud.nacos.discovery.server-addr是否正确。 - 确保服务启动时未报错，日志中无Nacos相关异常。
# 示例：Nacos配置
spring:
cloud:
nacos:
discovery:
server-addr: 127.0.0.1:8848
7. 接口文档无法访问
问题描述：Swagger或Knife4j文档页面无法打开。
解决方案：
- 检查是否添加了
springdoc-openapi-starter-webmvc-ui依赖。 - 确保配置文件中的
springdoc.api-docs.enabled=true。 - 若为生产环境，需显式启用文档（默认禁用）。
# 示例：Swagger配置
springdoc:
api-docs:
enabled: true
swagger-ui:
path: /swagger-ui.html
8. 多数据源切换失败
问题描述：动态数据源切换无效。
解决方案：
- 检查数据源配置是否正确，确保
dynamic-datasource依赖已引入。 - 验证
@DS注解是否添加到Service或Mapper层方法上。 - 确保数据源名称与配置文件中定义的一致。
// 示例：动态数据源注解
@DS("slave")
public List<User> selectUserList() {
return userMapper.selectList();
}
9. 日志收集异常
问题描述：ELK未收集到日志。
解决方案：
- 检查Logstash服务是否正常运行。
- 验证日志配置文件（如
logback-spring.xml）中的Logstash输出配置是否正确。 - 确保日志级别设置为
INFO或更低。
<!-- 示例：Logstash配置 -->
<appender name="logstash" class="net.logstash.logback.appender.LogstashTcpSocketAppender">
<destination>127.0.0.1:5000</destination>
</appender>
10. 代码生成器报错
问题描述：代码生成时提示“表不存在”或“字段类型不支持”。
解决方案：
- 检查数据库中是否存在目标表。
- 验证表名和字段名是否符合命名规范（避免使用关键字）。
- 若为Oracle或PostgreSQL，确保表名和字段名为大写。
// 示例：代码生成器配置
GenTable genTable = new GenTable();
genTable.setTableName("sys_user");
通过以上解决方案，可以快速定位并解决RuoYi-Cloud-Plus项目中的常见问题。若问题仍未解决，建议查阅项目文档或联系社区支持。
RuoYi-Cloud-Plus作为一个功能完善的微服务权限管理系统，通过本文的指南可以快速完成开发环境搭建和项目部署。代码生成器和Docker编排的支持显著提升了开发效率，而常见问题的解决方案则为项目稳定性提供了保障。掌握这些核心内容后，开发者能够更高效地进行二次开发和定制化工作。
Kimi-K2.5Kimi K2.5 是一款开源的原生多模态智能体模型，它在 Kimi-K2-Base 的基础上，通过对约 15 万亿混合视觉和文本 tokens 进行持续预训练构建而成。该模型将视觉与语言理解、高级智能体能力、即时模式与思考模式，以及对话式与智能体范式无缝融合。Python00
GLM-4.7-FlashGLM-4.7-Flash 是一款 30B-A3B MoE 模型。作为 30B 级别中的佼佼者，GLM-4.7-Flash 为追求性能与效率平衡的轻量化部署提供了全新选择。Jinja00
VLOOKVLOOK™ 是优雅好用的 Typora/Markdown 主题包和增强插件。 VLOOK™ is an elegant and practical THEME PACKAGE × ENHANCEMENT PLUGIN for Typora/Markdown.Less00
PaddleOCR-VL-1.5PaddleOCR-VL-1.5 是 PaddleOCR-VL 的新一代进阶模型，在 OmniDocBench v1.5 上实现了 94.5% 的全新 state-of-the-art 准确率。 为了严格评估模型在真实物理畸变下的鲁棒性——包括扫描伪影、倾斜、扭曲、屏幕拍摄和光照变化——我们提出了 Real5-OmniDocBench 基准测试集。实验结果表明，该增强模型在新构建的基准测试集上达到了 SOTA 性能。此外，我们通过整合印章识别和文本检测识别（text spotting）任务扩展了模型的能力，同时保持 0.9B 的超紧凑 VLM 规模，具备高效率特性。Python00
KuiklyUI基于KMP技术的高性能、全平台开发框架，具备统一代码库、极致易用性和动态灵活性。 Provide a high-performance, full-platform development framework with unified codebase, ultimate ease of use, and dynamic flexibility. 注意：本仓库为Github仓库镜像，PR或Issue请移步至Github发起，感谢支持！Kotlin07
compass-metrics-modelMetrics model project for the OSS CompassPython00
项目优选
kernel
docs
pytorch
ops-math
kernel
flutter_flutter
nop-entropy
RuoYi-Vue3
leetcode
ohos_react_native