# snail

**Repository Path**: baseme/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**: 46
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Snail —— 蜗牛快速开发平台

[![JDK](https://img.shields.io/badge/JDK-17-orange)](https://www.oracle.com/java/)
[![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)
[![Spring Cloud Alibaba](https://img.shields.io/badge/Spring%20Cloud%20Alibaba-2025.0.0.0-blueviolet)](https://github.com/alibaba/spring-cloud-alibaba)
[![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/)
[![Vue](https://img.shields.io/badge/Vue-3.x-4FC08D)](https://vuejs.org/)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

**Snail** 是一款企业级快速开发平台，基于若依 RuoYi-Cloud 二次开发，集成 AI 智能运维机器人、Flowable 工作流引擎、多租户、数据权限等企业级能力。项目代号"蜗牛"，寓意稳扎稳打、持续迭代。

> **架构演进：v7.x 全面升级** — Spring Boot 3.5 + Spring Cloud 2025，JDK 17，双模式架构（单体/微服务），api/biz/model 三层拆分，新增 MQTT 设备接入（EMQX）。

---

## 目录

- [核心功能](#核心功能)
- [技术栈](#技术栈)
- [系统架构](#系统架构)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [模块导航](#模块导航)
- [启动脚本](#启动脚本)
- [文档索引](#文档索引)
- [版本历史](#版本历史)

---

## 核心功能

| 功能域 | 功能点 |
|--------|--------|
| **用户权限** | 用户管理、RBAC 角色管理、菜单权限（动态路由）、部门管理（树）、岗位管理、字典管理、参数配置 |
| **系统安全** | JWT 认证（jjwt 0.12）、验证码（Kaptcha）、XSS 过滤、IP 黑名单、在线用户监控、注解式鉴权（Spring Security） |
| **工作流引擎** | Flowable 7.2 引擎、BPMN 设计器、流程部署/发起/审批/驳回/委派/转办、流程图高亮跟踪、已办/待办/抄送 |
| **AI 运维机器人** | 自然语言交互、StateGraph 多 Agent 工作流编排、LLM 意图识别、5 个领域 Agent（闲聊/咨询/诊断/操作/统计）、RedisSaver 会话持久化、Nacos 提示词热更新 |
| **MCP 工具集** | 向量知识库检索（Milvus）、ES 日志查询、Flowable 流程操作、自然语言转 SQL 统计 |
| **定时任务** | XXL-Job 3.2 调度中心、`@JobTask` 注解自动注册、在线 CRON 管理、执行日志、失败告警 |
| **多租户** | 表字段隔离（tenant_id 过滤）+ 独立数据库隔离双模式 |
| **数据权限** | 全部/自定义/本部门/本部门及以下/仅本人 五级数据权限（MyBatis 拦截器自动拼接） |
| **文件管理** | 上传/下载/删除/预览，本地 / MinIO / FastDFS 三种存储策略热切换，文件类型/大小限制配置 |
| **操作审计** | `@Log` 注解 AOP 切面，请求参数/响应结果/执行耗时自动记录，异步持久化 |
| **消息队列** | RabbitMQ / Kafka 双实现，消息发送/消费抽象，幂等去重（Redis SET NX）+ 重试 + 死信队列，MQ 日志异步落库 |
| **MQTT 接入** | Spring Integration + Paho v5 对接 EMQX，单连接聚合订阅 + topic 路由 + 多客户端负载均衡，EMQX JWT+ACL 鉴权（用户/设备双身份） |
| **设备管理** | 设备注册（BCrypt 密钥）/MQTT 鉴权（失败锁定）/遥测上报/指令下发（QoS1 确认）/上下线检测（遗嘱/WebHook） |
| **分布式锁** | Redis SET NX + Lua 脚本安全释放，自旋等待 + TTL 线程锁标识（snail-common-lock） |
| **Excel 工具** | EasyExcel + `@Excel` 注解驱动导入导出 |
| **序列号生成** | Redis 预生成 + 远程批量分配，支持年月日/时间戳/随机数等规则 |
| **分布式事务** | Seata AT 模式集成 |
| **API 文档** | Knife4j + SpringDoc OpenAPI，多服务 API 聚合 |
| **第三方集成** | 第三方对接渠道管理、外部 API 代理与转发、签名/加密/解密 |

---

## 技术栈

### 后端

| 技术 | 版本 | 说明 |
|------|------|------|
| JDK | 17 | 运行环境 |
| Spring Boot | 3.5.5 | 基础框架 |
| Spring Cloud | 2025.0.0 | 微服务治理 |
| Spring Cloud Alibaba | 2025.0.0.0 | 微服务组件（Nacos / Sentinel / Seata） |
| Spring AI | 1.1.2 | AI 应用框架 |
| Spring AI Alibaba | 1.1.2.0 | 阿里云 AI（通义千问/DashScope） |
| Nacos | 3.x | 注册中心 + 配置中心 |
| Spring Cloud Gateway | WebFlux Netty | API 网关 |
| EMQX | 5.x | MQTT Broker（设备接入，WebSocket 8083） |
| MySQL + mysql-connector-j | 9.2.0 | 关系型数据库 |
| MyBatis-Plus | 3.5.5 | ORM 框架 |
| Druid | 1.2.27 | 数据库连接池 |
| Dynamic-Datasource | 4.3.1 | 多数据源 |
| PageHelper | 1.4.2 | 分页插件 |
| Redis / Lettuce | — | 缓存（含 Caffeine 双级缓存） |
| Redisson | — | 分布式锁（snail-common-lock） |
| RabbitMQ / Kafka | — | 消息队列双实现 |
| Seata | — | 分布式事务 |
| Flowable | 7.2.0 | 工作流引擎 |
| XXL-Job | 3.2.0 | 分布式定时任务 |
| Elasticsearch | 8.x | 日志搜索引擎 |
| Milvus | — | 向量数据库 |
| MinIO / FastDFS | — | 分布式文件存储 |
| Knife4j + SpringDoc | 4.5.0 / 2.6.0 | API 文档 |
| jjwt | 0.12.6 | JWT 令牌 |
| FastJSON2 / Hutool | 2.0.54 / 5.8.32 | JSON / 工具库 |
| EasyExcel | 4.0.3 | Excel 处理 |
| MapStruct | 1.5.5 | 对象映射 |
| Kaptcha | 2.3.3 | 验证码生成 |

### 前端

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5.34 | 核心框架（主力前端） |
| Vite | 8.0.12 | 构建工具 |
| TypeScript | 6.0.2 | 语言 |
| Element Plus | 2.14.1 | UI 组件库（暗色主题） |
| Tailwind CSS | 4.3.0 | CSS 框架 |
| Axios | 1.16.1 | HTTP 客户端 |
| Vue Router | 4.6.4 | 路由（后端动态菜单驱动） |
| mqtt.js | 5.10.0 | MQTT 客户端（设备实时遥测，WebSocket 直连 EMQX） |
| bpmn-js | 7.5.0 | 流程设计器 |
| wangeditor | 4.7.15 | 富文本编辑器 |
| Vue 2 + Ant Design Vue | — | 旧版管理端（snail-web/snail-web） |
| Uni-App | — | 移动端（snail-web/snail-app） |

---

## 系统架构

### 部署模式

项目支持**双模式部署**：同一套业务代码（snail-modules），通过不同的启动模块（snail-monolith 单体聚合 / snail-services 微服务拆分）与接口实现方式（本地直连 / Feign 远程）实现两种运行模式。

```mermaid
graph TB
    subgraph "前端"
        web["Vue 3 管理端 :8001<br/>Vue 2 管理端<br/>Uni-App 移动端"]
    end

    subgraph "微服务模式"
        gw["snail-gateway :8080<br/>Spring Cloud Gateway"]
        auth["snail-auth :9200<br/>认证中心"]
        sys["snail-system :9201<br/>系统管理"]
        file["snail-file :9204<br/>文件服务"]
        wf["snail-workflow :9205<br/>工作流"]
        job["snail-job :9206<br/>定时任务"]
        tp["snail-thirdparty :9207<br/>第三方集成"]
        demo["snail-demo :9900<br/>OA 演示"]
        device["snail-device :9910<br/>设备管理"]
        gw --> auth
        gw --> sys
        gw --> file
        gw --> wf
        gw --> job
        gw --> tp
        gw --> demo
        gw --> device
        auth -->|"Feign RPC"| sys
        auth -->|"Feign RPC"| tp
    end

    subgraph "单体模式"
        mono["snail-monolith<br/>单一 JVM :8080<br/>聚合所有模块"]
    end

    subgraph "基础设施"
        infra["MySQL :3306<br/>Redis :6379<br/>Nacos :8848<br/>EMQX :1883/8083<br/>Elasticsearch<br/>RabbitMQ / Kafka<br/>MinIO<br/>Milvus"]
    end

    device -->|"MQTT"| infra

    subgraph "AI 服务"
        oamr["snail-ai-oamr :9210<br/>运维机器人"]
        mcp["snail-ai-mcp-*<br/>4 个 MCP 工具"]
    end

    web --> mono
    web --> gw
    mono --> infra
    gw --> infra
    oamr --> infra
    mcp --> infra
```

### 模块依赖层次

```mermaid
graph TB
    subgraph "部署层"
        svc["snail-services<br/>微服务 x 9"]
        mono["snail-monolith<br/>单体 fat jar"]
    end

    subgraph "启动模块"
        svc-app["9 个启动应用<br/>直接依赖 biz 模块"]
        mono-app["SnailMonolithApplication<br/>聚合所有 biz 模块"]
    end

    subgraph "业务层 snail-modules"
        biz["9 个业务模块<br/>api / biz / model"]
    end

    subgraph "基础设施层 snail-common"
        common["17 个子模块<br/>核心 / 安全 / 缓存 / 数据源 / MQTT / ..."]
    end

    svc-app --> biz
    mono-app --> biz
    biz --> common
```

---

## 项目结构

```
snail/
├── snail-common/               # 公共基础设施（17 个子模块）
│   ├── snail-common-core/       #   核心：R 响应体/常量/异常/工具类/注解
│   ├── snail-common-security/   #   安全：注解鉴权/Token 管理/防重复提交
│   ├── snail-common-redis/      #   缓存：FastJson2 序列化 + 全数据结构封装
│   ├── snail-common-datasource/ #   数据源：Druid + @Master/@Slave + 自动填充
│   ├── snail-common-datascope/  #   数据权限：五级行级 SQL 过滤
│   ├── snail-common-tenant/     #   多租户：表/库隔离双模式
│   ├── snail-common-log/        #   操作日志：@Log AOP 采集
│   ├── snail-common-excel/      #   Excel：@Excel 注解驱动
│   ├── snail-common-lock/       #   分布式锁：SET NX + Lua 安全释放
│   ├── snail-common-mq/         #   消息队列：抽象核心（幂等/重试/日志）
│   ├── snail-common-mq-kafka/   #   Kafka 实现
│   ├── snail-common-mq-rabbitmq/#  RabbitMQ 实现（含死信队列）
│   ├── snail-common-mqtt/       #   MQTT：订阅路由/发布网关/EMQX 鉴权
│   ├── snail-common-job/        #   定时任务：XXL-Job @JobTask 自动注册
│   ├── snail-common-sequence/   #   序列号：Redis 预生成 + 批量补充
│   ├── snail-common-interface/  #   接口适配：统一接口契约
│   └── snail-common-cloud/      #   微服务装配：启动注解/Feign 拦截器/MP 插件
│
├── snail-modules/              # 业务模块（api/biz/model 三层，9 个）
│   ├── snail-modules-auth/     #   认证授权（登录/注册/Token/验证码）
│   ├── snail-modules-system/   #   系统管理（用户/角色/菜单/部门/字典等 + Feign 契约）
│   ├── snail-modules-file/     #   文件服务（Local/MinIO/FastDFS 三存储）
│   ├── snail-modules-workflow/ #   工作流（Flowable 引擎/公共模板模式）
│   ├── snail-modules-job/      #   定时任务（XXL-Job 调度中心 admin）
│   ├── snail-modules-thirdparty/#  第三方集成（高德地图/阿里云短信）
│   ├── snail-modules-gateway/  #   网关配置（验证码/CORS/XSS/白名单）
│   ├── snail-modules-demo/     #   OA 演示示例（工作流/MQ/Excel/定时任务）
│   └── snail-modules-device/   #   设备管理（MQTT 接入/鉴权/遥测/指令）
│
├── snail-monolith/             # 单体模式启动入口（聚合所有 biz + MVC 网关 + Local 实现）
├── snail-services/             # 微服务模式启动入口（9 个启动应用）
│   ├── snail-gateway/          #   API 网关 :8080
│   ├── snail-auth/             #   认证中心 :9200
│   ├── snail-system/           #   系统管理 :9201
│   ├── snail-file/             #   文件服务 :9204
│   ├── snail-workflow/         #   工作流 :9205
│   ├── snail-job/              #   定时任务 :9206
│   ├── snail-thirdparty/       #   第三方集成 :9207
│   ├── snail-demo/             #   OA 演示 :9900
│   ├── snail-device/           #   设备管理 :9910
│   └── sql/                    #   数据库初始化脚本
│
├── snail-ai/                   # AI 服务
│   ├── snail-ai-oamr/          #   AI 运维机器人（StateGraph 多 Agent）
│   ├── snail-ai-mcp-vector/    #   MCP 向量检索（Milvus 知识库）
│   ├── snail-ai-mcp-log/       #   MCP 日志查询（Elasticsearch）
│   ├── snail-ai-mcp-business/  #   MCP 业务操作（Flowable 流程）
│   └── snail-ai-mcp-statistic/ #   MCP 数据统计（NL2SQL）
│
├── snail-dependencies/         # Maven BOM 统一版本管理
├── snail-web/                  # 前端项目
│   ├── snail-web-vue3/         #   Vue 3 + TypeScript + Element Plus（主力，:8001）
│   ├── snail-web/              #   Vue 2 + Ant Design Vue（旧版）
│   └── snail-app/              #   Uni-App 移动端
├── bat/                        # Windows 启动脚本
│   ├── start-all.bat           #   一键启动所有微服务
│   ├── start-gateway.bat       #   单独启动网关
│   ├── start-auth.bat          #   单独启动认证中心
│   ├── start-system.bat        #   单独启动系统管理
│   ├── start-file.bat          #   单独启动文件服务
│   ├── start-workflow.bat      #   单独启动工作流
│   ├── start-job.bat           #   单独启动定时任务
│   ├── start-thirdparty.bat    #   单独启动第三方集成
│   ├── start-demo.bat          #   单独启动 OA 演示
│   └── mvn-clean-install.bat   #   Maven 全量构建
├── docs/                       # 项目文档
│   ├── Snail项目文档索引.md     #   文档总索引（目录导航）
│   ├── 技术设计文档.md
│   ├── 项目启动说明文档.md
│   ├── 后端开发规范.md
│   ├── 前端开发规范.md
│   ├── 更新记录/                #   版本功能更新记录
│   └── sql/                    #   数据库初始化脚本
├── pom.xml                     # Maven 根 POM
├── CLAUDE.md                   # Claude Code 开发规范
└── LICENSE                     # MIT 开源许可证
```

---

## 快速开始

### 前置条件

| 组件 | 版本 | 端口 | 说明 |
|------|------|------|------|
| JDK | 17+ | — | 运行环境 |
| MySQL | 8.0+ | 3306 | 关系型数据库 |
| Redis | 6.x+ | 6379 | 缓存 / 分布式锁 |
| Nacos | 3.x | 8848 | 注册中心 + 配置中心（命名空间 `snail`） |
| Maven | 3.8+ | — | 构建工具 |
| Node.js | 18+ | — | 前端构建 |

### 数据库初始化

执行 `snail-services/sql/` 下的脚本（按顺序）：

| 脚本 | 说明 |
|------|------|
| `snail-config.sql` | Nacos 配置库 + 业务库 DDL/DML |
| `snail-cloud.sql` | 微服务相关表 |
| `snail-job.sql` | XXL-Job 调度中心表 |
| `snail-workflow.sql` | Flowable 工作流引擎表 |
| `snail-oa.sql` | OA 演示数据 |
| `spring_ai_oamr.sql` | AI 运维机器人会话/提示词表 |

### 方式一：微服务模式（完整部署）

```bash
# 1. 构建项目
cd snail
mvn clean install -DskipTests

# 2. 启动网关（依赖 Nacos 已启动）
mvn spring-boot:run -pl snail-services/snail-gateway

# 3. 依次启动核心服务
mvn spring-boot:run -pl snail-services/snail-auth      # :9200
mvn spring-boot:run -pl snail-services/snail-system     # :9201
mvn spring-boot:run -pl snail-services/snail-file       # :9204
mvn spring-boot:run -pl snail-services/snail-workflow   # :9205
mvn spring-boot:run -pl snail-services/snail-job        # :9206
mvn spring-boot:run -pl snail-services/snail-thirdparty # :9207
mvn spring-boot:run -pl snail-services/snail-demo       # :9900
mvn spring-boot:run -pl snail-services/snail-device     # :9910（设备管理，需 EMQX）

# 4. 启动前端（Vue 3，推荐）
cd snail-web/snail-web-vue3
pnpm install
pnpm dev
# 开发服务器: http://localhost:8001 -> 代理到网关 :8080
# 默认 VITE_SERVER_MODE=microservices（微服务模式）

# 或启动 Vue 2 管理端（旧版）
cd snail-web/snail-web
npm install
npm run serve
```

**Windows 快捷启动：** 也可使用 `bat/start-all.bat` 一键按序启动所有服务。

### 方式二：单体模式（轻量快速）

```bash
# 1. 修改配置
# 编辑 snail-monolith/src/main/resources/application-dev.yml
#   数据源 / Redis / Nacos 连接地址

# 2. 构建单体包
cd snail
mvn clean package -DskipTests -pl snail-monolith -am

# 3. 启动
java -jar snail-monolith/target/snail-monolith.jar

# 4. 启动前端（Vue 3，推荐）
cd snail-web/snail-web-vue3
pnpm install
# 修改 .env.development：VITE_SERVER_MODE=monolith（单体模式，API 不带服务前缀）
pnpm dev
```

### 系统访问

| 入口 | 地址 | 默认账号 |
|------|------|----------|
| 管理端 | `http://localhost:8001` | admin / admin123 |
| 网关 | `http://localhost:8080` | — |
| API 文档 | `http://localhost:8080/doc.html` | — |
| XXL-Job Admin | `http://localhost:9206/xxl-job-admin` | admin / 123456 |
| 认证服务（直连） | `http://localhost:9200` | — |
| 系统服务（直连） | `http://localhost:9201` | — |
| EMQX Dashboard | `http://localhost:18083` | admin / public |
| 设备服务（直连） | `http://localhost:9910` | — |

---

## 模块导航

| 模块 | 说明 | 文档 |
|------|------|------|
| **snail-common** | 公共基础设施（17 个子模块，含 MQTT/cloud） | [README](snail-common/README.md) |
| **snail-modules** | 业务模块（9 个业务域，含设备管理） | [README](snail-modules/README.md) |
| **snail-monolith** | 单体模式启动入口（聚合 biz + MVC 网关 + Local 实现） | [README](snail-monolith/README.md) |
| **snail-services** | 微服务模式启动入口（9 个服务，含 device） | [README](snail-services/README.md) |
| **snail-ai** | AI 运维机器人 + 4 个 MCP 工具 | [README](snail-ai/README.md) |
| **snail-web/snail-web-vue3** | Vue 3 管理端（主力前端，MQTT 实时/流程设计） | [README](snail-web/snail-web-vue3/README.md) |
| **snail-web/snail-web** | Vue 2 管理端（旧版） | [README](snail-web/snail-web/README.md) |
| **snail-web/snail-app** | Uni-App 移动端 | [README](snail-web/snail-app/README.md) |

---

## 启动脚本

`bat/` 目录下提供了 Windows 批处理启动脚本：

| 脚本 | 功能 |
|------|------|
| `start-all.bat` | 一键启动全部微服务（按依赖顺序：gateway -> auth -> system -> file -> workflow -> job -> thirdparty -> demo） |
| `start-gateway.bat` ~ `start-demo.bat` | 单独启动单个服务 |
| `mvn-clean-install.bat` | 全量 Maven 构建（clean install） |

> **提示：** 首次启动前需确保 Nacos 已运行在 `localhost:8848`，且 `snail-config.sql` 中的配置已导入 Nacos。

---

## 文档索引

项目全部文档已整合至 **[docs/Snail项目文档索引.md](docs/Snail项目文档索引.md)**，提供统一的目录导航，点击条目可跳转到对应文档：

| 章节 | 内容 |
|------|------|
| [一、项目总览](docs/Snail项目文档索引.md#一项目总览) | 项目简介、技术设计文档、项目启动说明 |
| [二、开发规范](docs/Snail项目文档索引.md#二开发规范) | 后端开发规范、前端开发规范 |
| [三、更新记录](docs/Snail项目文档索引.md#三更新记录) | MQTT 设备功能更新记录、通知公告优化记录 |
| [四、后端模块文档](docs/Snail项目文档索引.md#四后端模块文档) | snail-common（17 子模块）、snail-modules（9 业务模块）、snail-services、snail-monolith、snail-ai |
| [五、前端模块文档](docs/Snail项目文档索引.md#五前端模块文档) | snail-web-vue3、snail-web（含组件文档）、snail-app |
| [六、数据库脚本](docs/Snail项目文档索引.md#六数据库脚本) | docs/sql 下 6 个 SQL 初始化脚本 |

> 详细文档一览（各模块 README 等），请点击上方索引文件查看。

---

## 版本历史

| 版本 | 日期 | 里程碑 |
|:---|:---|:---|
| 7.x | 2026-08 | 新增 MQTT 设备接入（EMQX）：snail-common-mqtt + snail-modules-device + snail-device 服务（:9910）；snail-starters 整合至各模块；全模块文档更新（common 17 / modules 9 / services 9） |
| 7.0.0 | 2026-07 | 双模式架构重构：api/biz/model 三层拆分、前端服务名路由适配 |
| 6.x | 2026-06 | 基础架构升级：JDK 17、Spring Boot 3.x、Spring Cloud 2024+ |
| 3.x | — | RuoYi-Cloud 基线版本 |