# snail

**Repository Path**: jf_linux/snail

## Basic Information

- **Project Name**: snail
- **Description**: Snail(蜗牛)是基于若依(RuoYi-Cloud)基础框架重构升级的企业级快速开发平台,包含系统管理、AI 智能助手(多智能体编排、A2A 远程智能体、MCP 工具接入、知识库 RAG)、Flowable 工作流引擎、多租户、数据权限、操作审计、定时任务、消息队列、文件管理、MQTT 设备接入等模块,前端 Vue 3 重构,全栈文档齐备,开箱即用,MIT 开源。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://gitee.com/WilliamWangmy/snail
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 45
- **Created**: 2026-09-09
- **Last Updated**: 2026-09-09

## 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/)
[![Spring AI](https://img.shields.io/badge/Spring%20AI-Alibaba-1.1.2-blue)](https://github.com/alibaba/spring-ai-alibaba)
[![Vue](https://img.shields.io/badge/Vue-3.x-4FC08D)](https://vuejs.org/)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

**Snail（蜗牛）** 是一款企业级快速开发平台，采用 **单体 / 微服务双模式架构**（一套业务代码，两种部署方式），集成 **AI 智能助手（多智能体 + A2A + MCP）**、Flowable 工作流、多租户、数据权限、消息队列、MQTT 设备接入等企业级能力。项目代号"蜗牛"，寓意稳扎稳打、持续迭代。

> **v7.x 架构**：Spring Boot 3.5 + Spring Cloud 2025 + JDK 17，`api/biz/model` 三层拆分，单体（snail-monolith）与微服务（snail-services）双模式运行。

---

## 目录

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

---

## 核心功能

| 功能域 | 功能点 |
|--------|--------|
| **用户权限** | 用户/角色/菜单（动态路由）/部门（树）/岗位/字典/参数管理，注解式权限校验（`@RequiresPermissions` / `@RequiresRoles`） |
| **系统安全** | 自研 Token 鉴权（JWT + Redis，滑动续期）、Kaptcha 验证码、XSS 过滤、IP 黑名单、在线用户监控、防重复提交（`@RepeatSubmit`） |
| **工作流引擎** | Flowable 7.2 引擎、流程部署/发起/审批/驳回/委派/转办/撤回、待办/已办、审批记录、流程图高亮、业务公共模板模式（`WorkflowBasic*`） |
| **AI 智能助手** | Spring AI Alibaba **StateGraph 多智能体编排**（监督者决策 + 闲聊/咨询/A2A 远程业务子智能体）、ReAct 工具调用、RedisSaver 多轮记忆、Nacos 提示词热更新、多模态图片上传 |
| **A2A 远程智能体** | 通过 A2A 协议 + Nacos 服务发现调用远端业务 Agent（演示：自然语言新增请假申请），登录态安全透传 |
| **MCP 工具服务** | MCP Server 标准工具服务：知识库语义检索（Milvus RAG）、通用工具（时间/时区/天气），经网关 MCP Gateway 聚合供智能助手调用 |
| **定时任务** | XXL-Job 调度中心 + 执行器封装（`@XxlJob` 标准心跳注册），在线 CRON 管理、执行日志、失败邮件告警 |
| **多租户** | 表字段隔离（MyBatis-Plus 拦截器）+ 独立数据库隔离双模式 |
| **数据权限** | 全部/自定义/本部门/本部门及以下/仅本人 五级数据权限（MyBatis 拦截器 SQL 级过滤） |
| **文件管理** | 统一上传/查询/下载/删除，本地 / MinIO / FastDFS 三种存储后端切换 |
| **操作审计** | `@Log` 注解 AOP 切面，操作日志异步落库（敏感字段自动过滤） |
| **消息队列** | RabbitMQ / Kafka 双实现 + 抽象层：幂等去重（Redis）、消费重试、死信队列、MQ 生产/消费日志 |
| **MQTT 接入** | Spring Integration + Paho v5 对接 EMQX：单连接聚合订阅 + topic 路由、发布负载均衡（QoS0/QoS1）、EMQX JWT+ACL 鉴权 |
| **设备管理** | 设备注册（BCrypt）、MQTT 鉴权（失败锁定）、遥测上报入库、指令下发（QoS1 确认 + 超时状态机）、上下线检测（遗嘱/WebHook） |
| **分布式锁** | Redis SET NX + Lua 原子释放、自旋等待、TTL 线程锁标识（TransmittableThreadLocal） |
| **Excel 工具** | EasyExcel + `@Excel` 注解驱动导入导出、单元格合并、下拉校验、枚举转换器 |
| **序列号生成** | Redis 预生成 + 远程批量分配，支持前缀/日期/补齐规则 |
| **API 文档** | Knife4j + SpringDoc OpenAPI，网关聚合多服务文档 |
| **第三方集成** | 高德地图（IP 定位/行政区/地理编码）+ 阿里云短信 |

---

## 技术栈

### 后端

| 技术 | 版本 | 说明 |
|------|------|------|
| JDK | 17 | 运行环境 |
| Spring Boot | 3.5.5 | 基础框架 |
| Spring Cloud | 2025.0.0 | 微服务治理 |
| Spring Cloud Alibaba | 2025.0.0.0 | Nacos / Sentinel |
| Spring AI / Spring AI Alibaba | 1.1.2 | AI 应用框架（DashScope、Agent、MCP、A2A） |
| Nacos | 3.x | 注册中心 + 配置中心（动态提示词） |
| Spring Cloud Gateway | WebFlux Netty | API 网关（HTTP + MCP Gateway） |
| EMQX | 5.x | MQTT Broker（WebSocket 8083） |
| MySQL + mysql-connector-j | — | 关系型数据库 |
| MyBatis-Plus | 3.5.5 | ORM 框架 |
| Druid + Dynamic-Datasource | — | 连接池 + 多数据源 |
| Redis | — | 缓存 / Token / 分布式锁 / 序列号 |
| RabbitMQ / Kafka | — | 消息队列双实现 |
| Flowable | 7.2.0 | 工作流引擎 |
| XXL-Job | 3.2.0 | 分布式定时任务（调度中心 + 执行器） |
| Milvus | — | 向量数据库（知识库 RAG） |
| MinIO / FastDFS | — | 文件存储 |
| Knife4j + SpringDoc | — | API 文档 |
| jjwt | 0.12.x | JWT 令牌 |
| EasyExcel | — | Excel 处理 |
| MapStruct | — | 对象映射 |
| Kaptcha | — | 验证码 |

### 前端

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5.x | 核心框架（主力前端） |
| Vite / TypeScript | — | 构建 / 语言 |
| Element Plus | — | UI 组件库 |
| Axios / Vue Router | — | HTTP / 路由（后端动态菜单驱动） |
| mqtt.js | — | MQTT 客户端（设备实时遥测，WebSocket 直连 EMQX） |
| bpmn-js | — | 流程设计器 |
| Vue 2 + Ant Design Vue | — | 旧版管理端 |
| Uni-App | — | 移动端 |

---

## 系统架构

### 双模式部署

同一套业务代码（snail-modules），通过不同启动模块与接口实现方式支持两种运行模式，业务代码零改动：

| 模式 | 启动模块 | 接口实现 | 适用 |
|------|---------|---------|------|
| **单体** | `snail-monolith`（单 JVM :8080） | boot-starter 本地直连（`@Primary`） | 轻量部署、二次开发调试 |
| **微服务** | `snail-services`（9 个独立服务） | cloud-starter + Feign 远程调用 | 分布式生产部署 |

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

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

    subgraph "单体模式"
        mono["snail-monolith :8080<br/>聚合全部业务模块"]
    end

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

    subgraph "AI 服务"
        oamr["snail-ai-oamr :9210<br/>智能助手（监督者 + 子智能体）"]
        mcpv["snail-ai-mcp-vector :9211<br/>知识库检索 MCP"]
        mcpb["snail-ai-mcp-business :9212<br/>通用工具 MCP"]
    end

    web --> mono
    web --> gw
    mono --> infra
    gw --> infra
    device -->|"MQTT"| infra
    oamr -->|"A2A/Nacos"| demo
    oamr -->|"MCP Gateway"| gw
    mcpv --> infra
    mcpb --> infra
```

### 模块分层

```mermaid
graph TB
    subgraph "部署层"
        svc["snail-services<br/>微服务 x 9"]
        mono["snail-monolith<br/>单体"]
    end
    subgraph "业务层 snail-modules"
        biz["9 个业务域<br/>api / biz / model 三层"]
    end
    subgraph "AI 层 snail-ai"
        ai["oamr / mcp-vector / mcp-business"]
    end
    subgraph "基础设施层 snail-common"
        common["18 个子模块<br/>core / security / mq / mqtt / agent / ..."]
    end
    svc --> biz
    mono --> biz
    ai --> common
    biz --> common
```

---

## 项目结构

```
snail/
├── snail-common/               # 公共基础设施（18 个子模块）
│   ├── snail-common-core/       #   核心：R 响应体/常量/异常/工具/脱敏
│   ├── snail-common-security/   #   安全：自研 Token/注解鉴权/防重复提交
│   ├── snail-common-redis/      #   缓存：Redis 操作封装（FastJson2 序列化）
│   ├── snail-common-datasource/ #   数据源：Druid 动态数据源 + 字段自动填充
│   ├── 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/@XxlJob）
│   ├── snail-common-sequence/   #   序列号：Redis 预生成 + 批量分配
│   ├── snail-common-interface/  #   接口适配：单体/微服务统一契约
│   ├── snail-common-cloud/      #   微服务装配：@SnailCloudApplication + MP 插件
│   └── snail-common-agent/      #   Agent 装配：技能/监控/A2A 登录态
│
├── 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 调度中心）
│   ├── snail-modules-thirdparty#   第三方集成（高德地图/阿里云短信）
│   ├── snail-modules-gateway/  #   网关公共逻辑（验证码/白名单/CORS/XSS）
│   ├── snail-modules-demo/     #   OA 演示（工作流/MQ/Excel/A2A 智能体）
│   └── snail-modules-device/   #   设备管理（MQTT 接入/鉴权/遥测/指令）
│
├── snail-monolith/             # 单体模式启动入口
├── snail-services/             # 微服务模式启动入口（9 个服务）
├── snail-ai/                   # AI 服务
│   ├── snail-ai-oamr/          #   AI 智能助手（StateGraph 多智能体，:9210）
│   ├── snail-ai-mcp-vector/    #   知识库检索 MCP（Milvus RAG，:9211）
│   └── snail-ai-mcp-business/  #   通用工具 MCP（时间/天气等，:9212）
├── snail-dependencies/         # Maven BOM 统一版本管理
├── snail-web/                  # 前端（snail-web-vue3 / snail-web / snail-app）
├── bat/                        # Windows 启动脚本
├── docs/                       # 项目文档 + docs/sql 初始化脚本 + docs/snail Nacos 配置模板
├── pom.xml                     # Maven 根 POM
└── LICENSE                     # MIT 开源许可证
```

---

## 快速开始

### 前置条件

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

> AI / 设备等扩展能力按需安装：DashScope API Key（AI 模块）、Milvus（知识库）、EMQX（MQTT）、RabbitMQ/Kafka（MQ）。

### 数据库初始化

初始化脚本位于 **`docs/sql/`**（按需执行对应脚本）：

| 脚本 | 说明 |
|------|------|
| `snail-config.sql` | Nacos 配置库 + 初始化配置 |
| `snail-cloud.sql` | 系统管理基础数据（库 `snail-cloud`） |
| `snail-job.sql` | XXL-Job 调度中心表（库 `snail-job`） |
| `snail-workflow.sql` | Flowable 工作流引擎表（库 `snail-workflow`） |
| `snail-oa.sql` | OA 演示数据（库 `snail-oa`） |
| `spring_ai_oamr.sql` | AI 智能助手表（库 `spring_ai_oamr`） |

### 发布 Nacos 配置

每个服务的配置存于 Nacos 配置中心，仓库 `docs/snail/` 提供各服务 `*-dev.yml` 模板（含 `application-dev.yml` 公共配置），按服务名 `{service-name}-dev.yml` 发布，并修改数据源/中间件地址。

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

```bash
# 1. 构建项目（根目录）
mvn clean install -DskipTests

# 2. 启动网关（依赖 Nacos、Redis）
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
```

**Windows 快捷启动：** 使用 `bat/start-all.bat` 一键按序启动。

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

```bash
# 1. 修改 snail-monolith 的数据源/Redis/Nacos 配置
# 2. 构建并启动
mvn clean package -DskipTests -pl snail-monolith -am
java -jar snail-monolith/target/snail-monolith.jar

# 3. 前端设置单体模式后启动
#    .env.development: VITE_SERVER_MODE=monolith
```

### AI 智能助手（可选）

```bash
# 1. 配置 DASHSCOPE_API_KEY 环境变量
# 2. 启动 MCP 工具服务（知识库检索需 Milvus + docs-path 文档目录）
mvn spring-boot:run -pl snail-ai/snail-ai-mcp-vector   # :9211
mvn spring-boot:run -pl snail-ai/snail-ai-mcp-business  # :9212
# 3. 启动智能助手（依赖 Nacos、Redis、MCP Gateway）
mvn spring-boot:run -pl snail-ai/snail-ai-oamr         # :9210
```

### 系统访问

| 入口 | 地址 | 默认账号 |
|------|------|----------|
| 管理端 | `http://localhost:8001` | admin / admin123 |
| 网关 API 文档 | `http://localhost:8080/doc.html` | — |
| XXL-Job 调度中心 | `http://localhost:9206/snail-job-admin` | admin / 123456 |
| EMQX Dashboard | `http://localhost:18083` | admin / public |

---

## 模块导航

| 模块 | 说明 | 文档 |
|------|------|------|
| **snail-common** | 公共基础设施（18 个子模块，含 MQTT/agent） | [README](snail-common/README.md) |
| **snail-modules** | 业务模块（9 个业务域，api/biz/model） | [README](snail-modules/README.md) |
| **snail-monolith** | 单体模式启动入口 | [README](snail-monolith/README.md) |
| **snail-services** | 微服务模式启动入口（9 个服务 + Nacos 配置映射） | [README](snail-services/README.md) |
| **snail-ai** | AI 智能助手 + MCP 工具服务 | [README](snail-ai/README.md) |
| **snail-web/snail-web-vue3** | Vue 3 管理端（主力） | [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-*.bat` | 单独启动单个服务（gateway/auth/system/file/workflow/job/thirdparty/demo） |
| `mvn-clean-install.bat` | 全量 Maven 构建 |

> device、AI 等服务未包含在批处理脚本中，需手动启动（`mvn spring-boot:run`）。

---

## 文档索引

项目全部文档已整合至 **[docs/Snail项目文档索引.md](docs/Snail项目文档索引.md)**，提供统一的目录导航：

| 章节 | 内容 |
|------|------|
| [一、项目总览](docs/Snail项目文档索引.md#一项目总览) | 项目简介、技术设计文档、启动说明 |
| [二、开发规范](docs/Snail项目文档索引.md#二开发规范) | 后端 / 前端开发规范 |
| [三、更新记录](docs/Snail项目文档索引.md#三更新记录) | 版本更新记录 |
| [四、后端模块文档](docs/Snail项目文档索引.md#四后端模块文档) | snail-common（18 子模块）、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 个初始化脚本 |

---

## 版本历史

| 版本 | 日期 | 里程碑 |
|:---|:---|:---|
| 7.x | 2026-09 | README 全面核对修正（删除未实现项：Seata/ES/Caffeine 等），模块数对齐（common 18）、AI 模块对齐（3 服务 + A2A/MCP Gateway） |
| 7.x | 2026-08 | 新增 MQTT 设备接入（EMQX）、全模块文档重构、AI 智能助手多智能体改造 |
| 7.0.0 | 2026-07 | 双模式架构重构：api/biz/model 三层拆分 |
| 6.x | 2026-06 | 基础架构升级：JDK 17、Spring Boot 3.x |
| 3.x | — | RuoYi-Cloud 基线版本 |

---

## 开源协议

[MIT](LICENSE)

Snail 基于 RuoYi-Cloud 二次开发，感谢若依社区与 Spring AI Alibaba 开源社区。