# snail **Repository Path**: lvhaiyan/snail ## Basic Information - **Project Name**: snail - **Description**: Snail管理后台，基于 若依/RuoYi-Cloud 为基础版本进行迭代孵化Snail平台。支持SpringAI、SpringAIAlibaba、多租户、分布式锁、消息队列（Kafka、RabbitMQ）、流程审批（flowable）、数据权限、分布式锁等多功能场景，达到开箱即用 - **Primary Language**: Java - **License**: MIT - **Default Branch**: master - **Homepage**: https://gitee.com/WilliamWangmy/snail - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 48 - **Created**: 2026-06-28 - **Last Updated**: 2026-06-28 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Snail — 蜗牛微服务系统 [![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.5-brightgreen)](https://spring.io/projects/spring-boot) [![Spring Cloud](https://img.shields.io/badge/Spring%20Cloud-2025.0.0-blue)](https://spring.io/projects/spring-cloud) [![Vue](https://img.shields.io/badge/Vue-3.5.34-4FC08D)](https://vuejs.org/) [![JDK](https://img.shields.io/badge/JDK-17-orange)](https://www.oracle.com/java/) [![License](https://img.shields.io/badge/License-MIT-green)](LICENSE) [![Nacos](https://img.shields.io/badge/Nacos-3.x-blueviolet)](https://nacos.io/) [![Flowable](https://img.shields.io/badge/Flowable-7.2.0-red)](https://www.flowable.com/) **Snail** 是一款基于 **RuoYi-Cloud** 二次开发的快速开发平台，集成 AI 智能运维机器人、Flowable 工作流引擎、多租户等企业级能力。后端采用 Spring Cloud 微服务架构，前端基于 Vue 3 + TypeScript + Element Plus，致力于为团队提供开箱即用的现代化开发体验。 > 项目代号"蜗牛"，寓意稳扎稳打、持续迭代。 --- ## 📋 目录 - [核心功能](#-核心功能) - [技术栈](#-技术栈) - [系统架构](#-系统架构) - [项目结构](#-项目结构) - [系统截图](#-系统截图) - [快速开始](#-快速开始) - [模块说明](#-模块说明) - [公共支撑](#-公共支撑) - [贡献指南](#-贡献指南) - [许可证](#-许可证) --- ## 🚀 核心功能 | 功能域 | 功能点 | |--------|--------| | **用户权限** | 用户管理、角色管理（RBAC）、菜单权限、部门管理（树结构）、岗位管理、字典管理 | | **系统安全** | JWT 认证、验证码、XSS 过滤、SQL 注入过滤、IP 黑名单、在线用户监控 | | **工作流引擎** | BPMN 设计器、流程部署、发起/审批/驳回/流转、流程图高亮跟踪、待办/已办/我发起的 | | **AI 运维机器人** | 自然语言交互、系统诊断、业务咨询、数据统计、业务操作执行、StateGraph 状态图工作流 | | **MCP 工具** | 向量知识库检索、ES 日志查询、Flowable 流程操作、自然语言转 SQL 统计 | | **定时任务** | XXL-Job 调度中心、`@JobTask` 自动注册、在线 CRON 管理、执行日志查询 | | **多租户** | 表字段隔离 + 独立数据库隔离双模式 | | **数据权限** | 全部/本部门/本部门及以下/仅本人/自定义 五级数据权限 | | **文件管理** | 上传/下载/预览/删除，支持本地/MinIO/FastDFS 三种存储热切换 | | **操作审计** | 操作日志、登录日志 AOP 自动记录 | | **消息队列** | RabbitMQ / Kafka 双实现，消息记录持久化 + 重试 | | **API 文档** | Knife4j + SpringDoc 聚合所有微服务 API | | **第三方集成** | 外部 API 代理转发、签名/加密/解密 | --- ## 🛠 技术栈 ### 前端 | 技术 | 版本 | 说明 | |------|------|------| | Vue | ^3.5.34 | 核心框架 | | TypeScript | ~6.0.2 | 开发语言 | | Vite | ^8.0.12 | 构建工具 | | Element Plus | ^2.14.1 | UI 组件库 | | Tailwind CSS | ^4.3.0 | CSS 框架 | | Axios | ^1.16.1 | HTTP 客户端 | | vue-router | ^4.6.4 | 路由 | 另有 Vue 2 + Ant Design Vue（`snail-web`）及 Uni-App 移动端（`snail-app`）版本。 ### 后端 | 技术 | 版本 | 说明 | |------|------|------| | JDK | 17 | 运行环境 | | Spring Boot | 3.5.5 | 基础框架 | | Spring Cloud | 2025.0.0 | 微服务 | | Spring Cloud Alibaba | 2025.0.0.0 | 微服务组件 | | Spring AI | 1.1.2 | AI 框架 | | Nacos | 3.x | 注册中心 / 配置中心 | | Spring Cloud Gateway | — | API 网关（WebFlux Netty） | | MySQL / mysql-connector-j | 9.2.0 | 数据库 | | MyBatis-Plus | 3.5.5 | ORM | | Druid | 1.2.27 | 数据库连接池 | | Redis / Caffeine | — | 双级缓存 | | Redisson | — | 分布式锁 | | RabbitMQ / Kafka | — | 消息队列（双实现） | | Flowable | 7.2.0 | 工作流引擎 | | XXL-Job | 3.2.0 | 分布式定时任务 | | Elasticsearch | 8.x | 搜索引擎 | | Milvus | — | 向量数据库 | | MinIO / FastDFS | — | 对象存储 | | Seata | — | 分布式事务 | | Knife4j / SpringDoc | 4.5.0 / 2.6.0 | API 文档 | | EasyExcel | 3.3.4 | Excel 处理 | --- ## 🏗 系统架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ 用户层 │ │ Vue 3 SPA (8001) │ Vue 2 管理端 │ Uni-App 移动端 │ └──────────────────────┬──────────────────────────────────────┘ │ HTTP / WebSocket ┌──────────────────────▼──────────────────────────────────────┐ │ API 网关 (8080) │ │ Spring Cloud Gateway — 鉴权 / 限流 / XSS / IP黑名单 │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ MCP 协议网关 — Spring AI MCP 工具调用路由 │ │ │ └──────────────────────────────────────────────────────┘ │ └──────┬────────────────────────────────────────────────┬─────┘ │ │ ┌──────▼──────────┐ ┌───────────────────────────────┐ │ │ 认证中心 (9200) │ │ 业务微服务集群 │ │ │ snail-auth │ │ ┌──────────────────────┐ │ │ │ JWT 签发/刷新 │ │ │ snail-modules-system │ │ │ └──────────────────┘ │ │ 系统管理 (9201) │ │ │ │ ├──────────────────────┤ │ │ ┌──────────────────┐ │ │ snail-modules- │ │ │ │ AI 运维机器人 │ │ │ workflow (9205) │◄──┘ │ │ snail-ai-oamr │◄─┼──┤ ├────────────────────┤ │ │ StateGraph 工作流│ │ │ snail-modules-file │ │ │ 9210 │ │ │ 文件管理 (9204) │ │ └──────┬───────────┘ │ ├──────────────────────┤ │ │ │ │ snail-modules-job │ │ ┌──────▼───────────┐ │ │ 定时任务 (9206) │ │ │ MCP 工具层 │ │ ├──────────────────────┤ │ │ snail-ai-mcp-* │ │ │ snail-modules-third │ │ │ 向量/日志/业务/统计│ │ │ 第三方集成 (9207) │ │ └──────────────────┘ │ └──────────────────────┘ │ └──────────────────────────────────┘ │ ┌──────────────────────────────┴──────────────────────────────┐ │ 基础设施 │ │ MySQL │ Redis │ Nacos │ ES │ Milvus │ RabbitMQ │ │ MinIO │ Seata │ XXL-Job │ Kafka │ Flowable │ └─────────────────────────────────────────────────────────────┘ ``` **数据流向：** 1. 用户通过前端 SPA 访问 → API 网关统一入口 2. 网关进行 JWT 鉴权、验证码校验、XSS 过滤、限流 3. 认证通过后路由至具体微服务 4. 微服务间通过 Feign 同步调用，用户上下文自动传递 5. AI 机器人通过 StateGraph 工作流引擎编排多 Agent 协作 6. MCP 工具层为 AI 提供向量检索、日志查询、业务操作、数据统计等工具 --- ## 📁 项目结构 ``` snail ├── snail-gateway/ # API 网关（8080） ├── snail-auth/ # 认证授权中心（9200） ├── snail-common/ # 公共模块 │ ├── snail-common-core/ # 核心模块 │ ├── snail-common-cloud/ # 微服务组合注解 │ ├── snail-common-redis/ # 缓存模块 │ ├── snail-common-security/ # 安全模块 │ ├── snail-common-datasource/ # 多数据源 │ ├── snail-common-datascope/ # 数据权限 │ ├── snail-common-tenant/ # 多租户 │ ├── snail-common-log/ # 操作日志 │ ├── snail-common-lock/ # 分布式锁 │ ├── snail-common-excel/ # Excel 处理 │ ├── snail-common-sequence/ # 序列号生成 │ ├── snail-common-mq/ # 消息队列抽象 │ ├── snail-common-mq-rabbitmq/ # RabbitMQ 实现 │ ├── snail-common-mq-kafka/ # Kafka 实现 │ ├── snail-common-seata/ # 分布式事务 │ ├── snail-common-swagger/ # API 文档 │ └── snail-common-job/ # 定时任务 ├── snail-modules/ # 业务微服务 │ ├── snail-modules-system/ # 系统管理（9201） │ ├── snail-modules-system-api/ # 系统管理接口 │ ├── snail-modules-file/ # 文件管理（9204） │ ├── snail-modules-workflow/ # 工作流引擎（9205） │ ├── snail-modules-workflow-api/ # 工作流接口 │ ├── snail-modules-job-admin/ # 定时任务（9206） │ ├── snail-modules-job-api/ # 定时任务接口 │ ├── snail-modules-thirdparty/ # 第三方集成（9207） │ └── snail-modules-thirdparty-api/ # 第三方集成接口 ├── snail-ai/ # AI 服务 │ ├── snail-ai-oamr/ # AI 运维机器人（9210） │ ├── snail-ai-mcp-vector/ # MCP 向量检索 │ ├── snail-ai-mcp-log/ # MCP 日志查询 │ ├── snail-ai-mcp-business/ # MCP 业务操作 │ └── snail-ai-mcp-statistic/ # MCP 数据统计 ├── snail-demo/ # OA 演示 │ ├── snail-api-oa/ # OA 接口 │ └── snail-biz-oa/ # OA 业务 ├── snail-dependencies/ # 依赖版本管理 ├── snail-web/ # 前端 │ ├── snail-web-vue3/ # Vue 3 主力前端 │ └── snail-web/ # Vue 2 管理端 ├── sql/ # 数据库脚本 └── docs/ # 项目文档 ``` --- ## 🖼 系统截图 > vue3迁移完成后补上相关截图，vue2系统截图请切换分支查看 --- ## 🔧 快速开始 ### 前置条件 | 组件 | 版本要求 | 端口 | |------|----------|------| | JDK | 17+ | — | | MySQL | 8.0+ | 3306 | | Redis | 6.x+ | 6379 | | Nacos | 3.x | 8848 | | Node.js | 18+ | — | | Maven | 3.8+ | — | ### 启动基础设施 启动 MySQL、Redis、Nacos 三个基础服务，确保对应端口可用。 ### 初始化数据库 执行 `sql/` 目录下的初始化脚本： ```bash # 按顺序执行 source sql/snail-cloud.sql # 公共库（用户/角色/菜单等） source sql/snail-config.sql # Nacos 配置库 source sql/snail-job.sql # XXL-Job 调度库 source sql/snail-workflow.sql # Flowable 工作流库 source sql/snail-oa.sql # OA 演示数据 ``` ### 配置 Nacos 1. 在 Nacos 中创建命名空间 `snail` 2. 配置分组设为 `snail` 3. 发布 `application-dev.yml` 等各服务配置文件 ### 启动后端服务 ```bash # 完整构建 mvn clean package -DskipTests # 最低启动顺序（需依次启动） # 1. Nacos（已启动） # 2. snail-gateway → 端口 8080 # 3. snail-auth → 端口 9200 # 4. snail-modules-system → 端口 9201 ``` ### 启动前端 ```bash cd snail-web/snail-web-vue3 npm install npm run dev # 开发服务器默认运行在 http://localhost:8001 # 已配置代理 /api → 后端 8080 ``` ### 环境变量 | 变量名 | 说明 | 默认值 | |--------|------|--------| | `DASHSCOPE_API_KEY` | AI 模块必需（通义千问 API Key） | — | | `NACOS_HOST` | Nacos 地址 | `192.168.1.2:8848` | --- ## 📦 模块说明 各模块的详细文档请参阅对应 README： | 模块 | 端口 | README | |------|------|--------| | **snail-gateway** | 8080 | [README](snail-gateway/README.md) | | **snail-auth** | 9200 | [README](snail-auth/README.md) | | **snail-common** | — | [README](snail-common/README.md) | | **snail-modules** | 9201+ | [README](snail-modules/README.md) | | **snail-demo** | — | [README](snail-demo/README.md) | | **snail-web-vue3** | 8001 | [README](snail-web/snail-web-vue3/README.md) | | **snail-web** | — | [README](snail-web/snail-web/README.md) | | **snail-app** | — | [README](snail-web/snail-app/README.md) | --- ## 🧩 公共支撑 | 能力 | 模块 | 说明 | |------|------|------| | **统一响应体** | `snail-common-core` | `R` 泛型包装，统一 code/msg/data 格式 | | **缓存服务** | `snail-common-redis` | Redis + Caffeine 双级缓存 | | **安全上下文** | `snail-common-security` | Feign 调用自动传递 Token/用户信息 | | **多数据源** | `snail-common-datasource` | `@Master` / `@Slave` 注解动态切换 | | **数据权限** | `snail-common-datascope` | `@DataScope` 注解 + MyBatis 拦截器，五级权限 | | **多租户** | `snail-common-tenant` | 表字段隔离 / 独立数据库隔离双模式 | | **操作日志** | `snail-common-log` | `@Log` 注解 AOP 自动记录 | | **分布式锁** | `snail-common-lock` | `@Lock` 声明式锁，Redisson 实现 | | **Excel** | `snail-common-excel` | `@Excel` 注解驱动，EasyExcel 实现 | | **消息队列** | `snail-common-mq` | 消息发送/消费抽象 + 持久化重试 | | **序列号** | `snail-common-sequence` | 分布式 ID 生成器 | | **API 文档** | `snail-common-swagger` | Knife4j + SpringDoc API 聚合 | --- ## 🤝 贡献指南 欢迎通过 Issue 和 Pull Request 贡献代码。 1. Fork 本仓库 2. 创建特性分支：`git checkout -b feat/amazing-feature` 3. 提交变更：`git commit -m 'feat: add amazing feature'` 4. 推送分支：`git push origin feat/amazing-feature` 5. 提交 Pull Request 请确保代码风格一致、测试通过，并遵循项目的提交信息规范。 --- ## 📄 许可证 [MIT License](LICENSE) © 2020 若依 Snail 基于 [RuoYi-Cloud](https://gitee.com/y_project/RuoYi-Cloud) 二次开发，感谢若依团队的开源贡献。