# ruke-fast **Repository Path**: ttlp/ruke-fast ## Basic Information - **Project Name**: ruke-fast - **Description**: No description available - **Primary Language**: Java - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-10-09 - **Last Updated**: 2026-10-16 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README ## 项目简介 ruke-fast 是一套基于 Spring Boot 3、Spring Security 6.x、MyBatis-Plus、Redis、Hutool 等技术栈的企业级通用框架，提供 RBAC 权限控制（含数据权限）、多种登录方式、日志监控、安全加固等核心能力，为后续业务系统开发提供统一底座。 ### 核心特性 | 特性 | 说明 | | :------------ | :---------------------------------------- | | 多种登录方式 | 密码+图形验证码登录、邮箱验证码登录 | | RBAC 权限控制 | 用户-角色-菜单三级权限模型 | | 数据权限 | 全部/本部门/部门及子部门/本人/自定义 | | 菜单按钮树形 | 目录-菜单-按钮三级树形结构 | | 操作日志 | 注解+AOP 自动记录，异步执行 | | 登录日志 | 自动记录登录成功/失败 | | 链路追踪 | MDC 生成 Trace ID 全链路透传 | | 安全加固 | 防重放、防暴力破解、XSS 过滤、CORS 白名单 | | 多环境配置 | dev/test/prod 环境隔离 | | 容器化部署 | Dockerfile + docker-compose.yml | | 接口文档 | Smart-Doc 构建期生成 HTML | ## 技术栈 | 分类 | 技术选型 | 版本 | | :------- | :--------------------- | :--------------- | | 基础框架 | Spring Boot | 3.2.x | | 安全框架 | Spring Security | 6.2.x | | JDK | OpenJDK | 17 | | 构建工具 | Apache Maven | 3.8+ | | ORM | MyBatis-Plus | 3.5.5+ | | 数据库 | MySQL | 8.0+ | | 连接池 | Druid | 1.2.28 | | 缓存 | Redis + Lettuce | 6.x/7.x | | 分布式锁 | Redisson | 3.25.x | | JWT | JJWT | 0.12.x | | 工具库 | Hutool | 5.8.x | | 代码简化 | Lombok | 1.18.x | | 验证码 | EasyCaptcha | 1.6.x | | 邮件 | JavaMail + Spring Mail | Spring Boot 内置 | | 接口文档 | Smart-Doc | 3.1.2 | | 日志 | Logback + SLF4J | Spring Boot 内置 | | 监控 | Spring Boot Actuator | 3.2.x | ## 工程结构 ```text ruke-server/ ├── pom.xml # Maven 根父工程：模块聚合、依赖版本和插件管理 │ ├── ruke-bom/ # JAR 依赖版本统一管理，packaging=pom │ # 统一第三方依赖和项目内部模块版本 │ ├── ruke-common/ # 公共基础模块，普通 JAR │ # 通用异常、错误码、基础模型和纯 Java 公共能力 │ ├── ruke-framework/ # 技术基础设施聚合父模块，packaging=pom │ ├── ruke-framework-web/ # Spring MVC、异常处理、响应包装和 Web 配置 │ ├── ruke-framework-security/ # Spring Security、JWT、认证鉴权和安全上下文 │ ├── ruke-framework-mybatis/ # MyBatis-Plus、分页、字段填充和部门数据权限 │ ├── ruke-framework-redis/ # Redis、缓存和分布式锁 │ ├── ruke-framework-log/ # 日志注解、日志切面、请求日志和日志事件 │ ├── ruke-framework-openapi/ # Smart-Doc 接口文档生成模块 │ ├── ruke-framework-storage/ # 本地、MinIO、阿里云 OSS、腾讯云 COS 等底层对象存储适配 │ ├── ruke-framework-sms/ # 短信服务商接入和短信发送能力 │ ├── ruke-framework-mail/ # 文本、HTML、附件邮件发送能力 │ └── ruke-framework-i18n/ # 国际化消息源和多语言消息访问 │ ├── ruke-module/ # 业务模块聚合父模块，packaging=pom │ ├── ruke-module-system/ # 用户、角色、菜单、部门、岗位和权限管理 │ ├── ruke-module-config/ # 参数配置、数据字典和动态配置管理 │ ├── ruke-module-file/ # 文件元数据、业务关联、访问权限和文件管理 │ ├── ruke-module-message/ # 消息模板、发送任务、发送记录和渠道编排 │ ├── ruke-module-notice/ # 系统公告、通知发布、接收范围和已读状态管理 │ ├── ruke-module-job/ # 定时任务配置、调度执行和执行记录 │ ├── ruke-module-audit/ # 登录日志、操作日志和安全审计管理 │ └── ruke-module-online/ # 在线用户、在线会话和强制下线管理 │ └── ruke-boot/ # Spring Boot 启动与最终装配模块，packaging=jar # 启动类、环境配置及各模块的最终依赖装配 ``` ### 模块说明 | 模块 | 职责 | | :---------------------- | :----------------------------------------------------- | | ruke-bom | 通过 dependencyManagement 统一第三方依赖和内部模块版本 | | ruke-common | 通用异常、错误码、基础模型和纯 Java 公共能力 | | ruke-framework-web | Spring MVC、异常处理、响应包装和 Web 配置 | | ruke-framework-security | Spring Security、JWT、认证鉴权和安全上下文 | | ruke-framework-mybatis | MyBatis-Plus、分页、字段填充和部门数据权限 | | ruke-framework-redis | Redis、缓存和分布式锁 | | ruke-framework-log | 日志注解、日志切面、请求日志和日志事件 | | ruke-framework-openapi | Smart-Doc 接口文档生成模块 | | ruke-framework-storage | 本地、MinIO、阿里云 OSS、腾讯云 COS 等底层对象存储适配 | | ruke-framework-sms | 短信服务商接入和短信发送能力 | | ruke-framework-mail | 文本、HTML、附件邮件发送能力 | | ruke-framework-i18n | 国际化消息源配置和多语言消息访问 | | ruke-module-system | 用户、角色、菜单、部门、岗位和权限管理 | | ruke-module-config | 参数配置、数据字典和动态配置管理 | | ruke-module-file | 文件元数据、业务关联、访问权限和文件管理 | | ruke-module-message | 消息模板、发送任务、发送记录和渠道编排 | | ruke-module-notice | 系统公告、通知发布、接收范围和已读状态管理 | | ruke-module-job | 定时任务配置、调度执行和执行记录 | | ruke-module-audit | 登录日志、操作日志和安全审计管理 | | ruke-module-online | 在线用户、在线会话和强制下线管理 | | ruke-boot | Spring Boot 启动、环境配置和最终模块装配 | ## 快速开始 ### 环境要求 | 环境 | 版本 | | :---- | :------ | | JDK | 17 | | Maven | 3.8+ | | MySQL | 8.0+ | | Redis | 6.x/7.x | ### 1. 克隆项目 ```bash git clone https://gitee.com/ttlp/ruke-fast.git cd ruke-fast ``` ### 2. 初始化数据库 ```bash # 登录 MySQL mysql -u root -p # 创建数据库 CREATE DATABASE ruke_fast CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci; # 执行建表脚本 for %f in (ruke-server\sql\ddl\*.sql) do mysql -u root -p ruke_fast < %f # 执行初始化数据脚本 for %f in (ruke-server\sql\dml\*.sql) do mysql -u root -p ruke_fast < %f ``` ### 3. 修改配置 修改 `ruke-module/ruke-boot/src/main/resources/application-dev.yml`： yaml ``` spring: datasource: url: jdbc:mysql://localhost:3306/ruke_fast?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai&useSSL=false username: root password: your_password data: redis: host: localhost port: 6379 password: your_redis_password ``` ### 4. 构建项目 bash ``` mvn clean install -DskipTests ``` ### 5. 启动应用 bash ``` cd ruke-module/ruke-boot mvn spring-boot:run ``` 或 bash ``` java -jar ruke-module/ruke-boot/target/ruke-boot-1.0.0.jar --spring.profiles.active=dev ``` ### 6. 访问验证 | 地址 | 说明 | | :---------------------------------------- | :------- | | http://localhost:8080/api/actuator/health | 健康检查 | | ruke-server/docs/api/debug-all.html | Smart-Doc HTML 接口文档 | ### 默认账号 | 账号 | 密码 | 角色 | | :---- | :----- | :--------- | | admin | 123456 | 超级管理员 | | test | 123456 | 普通用户 | ## 接口规范 ### 请求方法 | 规范项 | 说明 | | :-------- | :--------------------------------------- | | 请求方法 | 仅允许 GET 和 POST | | GET 请求 | 查询类接口，参数使用 Query String | | POST 请求 | 新增/修改/删除类接口，参数使用 JSON Body | | 路径规范 | `/api/{module}/{action}` | ### 统一响应格式 json ``` { "code": 200, "msg": "操作成功", "data": {}, "timestamp": 1702800000000 } ``` ### 错误码规范 | 错误码范围 | 分类 | | :--------- | :----------- | | 200 | 成功 | | 400-499 | 客户端错误 | | 401-499 | 认证授权错误 | | 429 | 限流错误 | | 500-599 | 服务端错误 | | 600-699 | 业务错误 | | 700-719 | 安全错误 | ## 核心功能 ### 认证模块 | 功能 | 说明 | | :------------------ | :--------------------------------------------------- | | 密码+图形验证码登录 | 支持用户名/手机号/邮箱 | | 邮箱验证码登录 | 6 位数字验证码 | | JWT Token | 统一 Token 格式，含 userId/username/deptId/loginType | | Token 管理 | 主动注销、Refresh Token 刷新 | ### 授权模块 | 功能 | 说明 | | :----------- | :-------------------------------------------------- | | RBAC | 用户-角色-菜单三级权限 | | 接口权限 | `@PreAuthorize("hasAuthority('system:user:list')")` | | 数据权限 | 5 种范围：全部/本部门/部门及子部门/本人/自定义 | | 菜单按钮树形 | 一级菜单从 101 开始编号 | | 超级管理员 | 绕过所有权限校验 | ### 日志模块 | 功能 | 说明 | | :------- | :--------------------------------------------------- | | 操作日志 | `@Log` 注解 + AOP 异步记录 | | 登录日志 | 记录登录成功/失败及失败原因 | | 审计字段 | create_by/create_time/update_by/update_time 自动填充 | | 链路追踪 | MDC 生成 Trace ID | ### 安全防护 | 功能 | 说明 | | :---------- | :------------------------ | | 密码加密 | BCrypt（强度 10+） | | 防重放 | timestamp + nonce 校验 | | 防暴力破解 | 登录失败 5 次锁定 15 分钟 | | 防 XSS | 请求参数 HTML 标签转义 | | 防 SQL 注入 | MyBatis-Plus 参数化查询 | | CORS | 白名单域名控制 | | HTTPS | 生产环境强制 + HSTS | ### 扩展业务模块 | 模块 | 功能 | | :------- | :----------------------- | | 通知公告 | 增删改查、发布/撤回 | | 参数配置 | 增删改查、按 Key 查询 | | 任务调度 | 增删改查、执行/暂停/恢复 | | 在线用户 | 查看在线用户、强制下线 | | 操作审计 | 按维度统计操作日志 | | 文件管理 | 上传/下载/删除/列表 | | 消息管理 | 发送/查询/删除 | ## 配置说明 ### 环境配置 | 环境 | 配置文件 | 说明 | | :--- | :------------------- | :------- | | 开发 | application-dev.yml | 本地开发 | | 测试 | application-test.yml | 测试环境 | | 生产 | application-prod.yml | 生产环境 | ### 关键配置项 yaml ``` jwt: secret: ${JWT_SECRET:...} # JWT 签名密钥 expiration: 7200000 # Access Token 有效期（2小时） refresh-expiration: 604800000 # Refresh Token 有效期（7天） captcha: expire: 120 # 图形验证码有效期（2分钟） email: code: expire: 300 # 邮箱验证码有效期（5分钟） send-limit: 60 # 发送间隔（60秒） daily-limit: 10 # 每日发送上限 login: fail-max-count: 5 # 登录失败最大次数 lock-time: 900 # 锁定时间（15分钟） ``` ### 环境变量 | 变量名 | 说明 | | :------------- | :------------- | | MYSQL_URL | 数据库主机/IP:端口 | | MYSQL_NAME | 数据库名 | | MYSQL_USERNAME | 数据库用户名 | | MYSQL_PASSWORD | 数据库密码 | | REDIS_HOST | Redis 主机 | | REDIS_PORT | Redis 端口 | | REDIS_PASSWORD | Redis 密码 | | JWT_SECRET | JWT 签名密钥 | | MAIL_HOST | 邮件服务器 | | MAIL_USERNAME | 邮件账号 | | MAIL_PASSWORD | 邮件授权码 | ## 部署 ### Docker 部署 ```bash # 进入后端工程 cd ruke-server # 手动编译并生成可执行 JAR mvn -pl ruke-boot -am -Dmaven.test.skip=true clean package mvn -pl ruke-boot -Dmaven.test.skip=true package spring-boot:repackage # 使用预先生成的 JAR 构建镜像并创建服务 docker compose up -d --build # 查看日志 docker compose logs -f ruke-server ``` `ruke-server/Dockerfile` 只负责运行 JRE，不在 Docker 构建阶段执行 Maven。构建上下文必须包含 `ruke-boot/target/ruke-boot-*.jar`；更新代码后需重新执行两条 Maven 命令，再执行 `docker compose up -d --build ruke-server`。 ### JAR 包部署 ```bash # 构建 mvn clean package -DskipTests # 启动 nohup java -jar ruke-boot-1.0.0.jar --spring.profiles.active=prod > startup.log 2>&1 & ``` ### Nginx 配置 ```nginx server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/nginx/ssl/your-domain.crt; ssl_certificate_key /etc/nginx/ssl/your-domain.key; location /api/ { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } ``` ## 文档体系 | 序号 | 文档名称 | 说明 | | :--- | :----------------------- | :--------------------------- | | 1 | 需求规格说明书 | 项目需求分析 | | 2 | 功能全景清单 | 所有功能点清单 | | 3 | 技术方案设计文档 | 技术选型、架构设计、模块划分 | | 4 | 数据库设计文档 | 建表 SQL、初始化数据 | | 5 | 项目初始化与工程搭建文档 | Maven 多模块工程搭建 | | 6 | 模块开发文档 | 各模块开发说明 | | 7 | 接口文档 | 所有接口说明 | | 8 | 测试文档 | 测试用例与报告 | | 9 | 部署与运维文档 | 部署步骤、运维指南 | | 10 | README.md | 项目入口文档 | ## 开发规范 ### 命名规范 | 类型 | 规范 | 示例 | | :----- | :--------------------- | :------------------- | | 包名 | 全小写，点分隔 | com.ruke.common | | 类名 | 大驼峰 | UserService | | 方法名 | 小驼峰 | getUserById | | 常量 | 全大写，下划线分隔 | JWT_SECRET_KEY | | 表名 | 小写+下划线，前缀 sys_ | sys_user | | 字段名 | 小写+下划线 | user_id | ### 分层规范 | 层级 | 职责 | | :--------- | :--------------------------------- | | Controller | 参数校验、响应封装，不包含业务逻辑 | | Service | 业务逻辑、事务管理 | | Mapper | 仅数据库操作 | ### 代码规范 - 响应格式统一（code/msg/data/timestamp） - HTTP 状态码统一为 200，业务状态通过 code 区分 - 异常全局统一处理，不返回堆栈信息 - 关键逻辑有注释说明 ## 常见问题 ### 应用启动失败 | 问题 | 解决方案 | | :------------- | :------------------------- | | 端口被占用 | 修改 server.port | | 数据库连接失败 | 检查数据库服务、用户名密码 | | Redis 连接失败 | 检查 Redis 服务、host/port | | 模块找不到 | 执行 `mvn clean install` | ### 接口异常 | 问题 | 解决方案 | | :----------- | :--------------------- | | 401 未认证 | 检查 Token 是否有效 | | 403 无权限 | 检查用户角色和菜单权限 | | 500 系统异常 | 查看错误日志定位问题 | | 响应慢 | 查看慢 SQL 日志优化 | ### 获取帮助 - 执行 Smart-Doc Maven 任务生成 `ruke-server/docs/api/debug-all.html` 接口文档 - 查看 `logs/ruke-fast-error.log` 错误日志 - 联系开发团队 ## 版本历史 | 版本 | 日期 | 说明 | | :---- | :--------- | :------------------------------------------------- | | 1.0.0 | 2026-10-09 | 初始版本，包含认证、授权、日志、监控、扩展业务模块 | ## 许可证 本项目采用 MIT 许可证，详见 [LICENSE](https://license/) 文件。 ## 贡献指南 1. Fork 本项目 2. 创建特性分支（`git checkout -b feature/xxx`） 3. 提交更改（`git commit -m 'Add xxx'`） 4. 推送到分支（`git push origin feature/xxx`） 5. 提交 Pull Request ## 联系方式 | 角色 | 联系方式 | | :--------- | :------- | | 项目负责人 | - | | 技术支持 | - | | 邮箱 | - |