# snail

**Repository Path**: WilliamWangmy/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**: 90
- **Forks**: 41
- **Created**: 2023-08-01
- **Last Updated**: 2026-07-13

## Categories & Tags

**Categories**: backend

**Tags**: SpringAIAlibaba, MCP丨Skill, SpringCloud丨微服务, 多租户丨动态权限, flowable

## 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-2.7.5-brightgreen)](https://spring.io/projects/spring-boot)
[![Spring Cloud](https://img.shields.io/badge/Spring%20Cloud-2021.0.5-blue)](https://spring.io/projects/spring-cloud)
[![Nacos](https://img.shields.io/badge/Nacos-2.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-2.x%20/%203.x-4FC08D)](https://vuejs.org/)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

**Snail** 是一款企业级快速开发平台，支持**单体**和**微服务**两种部署模式，一套代码双模运行。集成 AI 智能运维、Flowable 工作流引擎、多租户、数据权限等能力。项目代号"蜗牛"，寓意稳扎稳打、持续迭代。

---

## 📋 目录

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

---

## 🚀 核心功能

| 功能域 | 功能点 |
|--------|--------|
| **用户权限** | 用户管理、RBAC 角色管理、菜单权限、部门管理（树）、岗位管理、字典管理 |
| **系统安全** | JWT 认证、验证码、XSS 过滤、IP 黑名单、在线用户监控、注解式鉴权 |
| **工作流引擎** | Flowable 引擎、BPMN 设计、流程部署、发起/审批/驳回/委派/转办、流程图高亮跟踪 |
| **AI 运维** | 自然语言交互、系统诊断、业务咨询、StateGraph 多 Agent 编排 |
| **MCP 工具** | 向量知识库检索、ES 日志查询、Flowable 流程操作、自然语言转 SQL 统计 |
| **定时任务** | XXL-Job 调度中心、`@JobTask` 自动注册、在线 CRON 管理、执行日志 |
| **多租户** | 表字段隔离 / 独立数据库隔离双模式 |
| **数据权限** | 全部/自定义/本部门/本部门及以下/仅本人 五级数据权限 |
| **文件管理** | 上传/下载/删除，Local / MinIO / FastDFS 三种存储热切换 |
| **操作审计** | AOP 注解式日志自动采集、异步持久化 |
| **消息队列** | RabbitMQ / Kafka 双实现、消息记录持久化 + 重试 |
| **分布式锁** | Redis SET NX + Lua 脚本安全释放 |
| **Excel 工具** | EasyExcel + 注解驱动导入导出 |
| **序列号** | Redis 预生成 + 远程批量分配 |
| **API 文档** | SpringDoc + OpenAPI 自动聚合 |

---

## 🛠 技术栈

| 技术 | 说明 |
|------|------|
| JDK 17 | 运行环境 |
| Spring Boot 2.7.5 | 基础框架 |
| Spring Cloud 2021.0.5 | 微服务治理 |
| Spring Cloud Alibaba 2021.0.6.0 | 微服务组件（Nacos / Sentinel） |
| Spring AI 1.1.2 | AI 应用框架 |
| Nacos 2.x | 注册中心 + 配置中心 |
| MySQL 8.0+ | 关系型数据库 |
| MyBatis-Plus 3.5.x | ORM 框架 |
| Druid + Dynamic-DS | 多数据源连接池 |
| Redis / Lettuce | 缓存 / 分布式锁 |
| RabbitMQ / Kafka | 消息队列双实现 |
| Flowable 7.2.0 | 工作流引擎 |
| XXL-Job | 分布式定时任务 |
| Elasticsearch 8.x | 日志搜索引擎 |
| Milvus | 向量数据库 |
| FastDFS / MinIO | 分布式文件存储 |
| Kaptcha | 验证码生成 |
| EasyExcel 3.x | Excel 处理 |
| Vue 2 / Vue 3 / Uni-App | 多端前端 |

---

## 🏗 系统架构

### 双模式架构

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

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

    subgraph "微服务模式"
        gw["snail-gateway :8080<br/>Spring Cloud Gateway"]
        auth["snail-auth :9200<br/>认证中心"]
        sys["snail-system :9300<br/>系统管理"]
        file["snail-file :9400<br/>文件服务"]
        job["snail-job :9500<br/>定时任务"]
        wf["snail-workflow :9600<br/>工作流引擎"]
        tp["snail-thirdparty :9700<br/>第三方集成"]
        demo["snail-demo :9100<br/>示例演示"]
        gw --> auth
        gw --> sys
        gw --> file
        gw --> wf
        gw --> demo
        auth -->|"Feign"| sys
        auth -->|"Feign"| tp
    end

    subgraph "基础设施"
        infra["MySQL / Redis / Nacos / ES / RabbitMQ / MinIO"]
    end

    web --> mono
    web --> gw
    mono --> infra
    auth --> infra
    sys --> infra
    file --> infra
    job --> infra
    wf --> infra
    tp --> infra
```

### 模块依赖层次

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

    subgraph "Starter 适配层"
        cloud["cloud-starter × 2<br/>Feign + Reactive"]
        boot["boot-starter × 8<br/>Servlet MVC"]
    end

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

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

    svc --> cloud
    mono --> boot
    cloud --> biz
    boot --> biz
    biz --> common
```

---

## 📁 项目结构

```
snail/
├── snail-common/               # 公共基础设施（15 个子模块）
│   ├── snail-common-core/      #   核心：响应体/常量/异常/工具类
│   ├── snail-common-security/  #   安全：JWT/鉴权/拦截器
│   ├── snail-common-redis/     #   缓存：Redis 全数据结构封装
│   ├── snail-common-datasource/#   数据源：Druid + Dynamic-DS
│   ├── snail-common-datascope/ #   数据权限：五级行级过滤
│   ├── snail-common-tenant/    #   多租户：表/库隔离双模式
│   ├── snail-common-log/       #   操作日志：AOP 注解采集
│   ├── snail-common-excel/     #   Excel：注解导入导出
│   ├── snail-common-lock/      #   分布式锁：Redis SET NX
│   ├── snail-common-mq/        #   消息队列：抽象核心
│   ├── snail-common-mq-kafka/  #   Kafka 实现
│   ├── snail-common-mq-rabbitmq/#  RabbitMQ 实现
│   ├── snail-common-job/       #   定时任务：XXL-Job 封装
│   ├── snail-common-sequence/  #   序列号：分布式 ID 生成
│   └── snail-common-interface/ #   接口适配：统一接口契约
│
├── snail-modules/              # 业务模块（api/biz/model 三层）
│   ├── snail-modules-system/   #   系统管理（api+biz+model）
│   ├── snail-modules-auth/     #   认证授权（biz+model）
│   ├── snail-modules-file/     #   文件服务（biz+model）
│   ├── snail-modules-workflow/ #   工作流引擎（api+biz+common+model）
│   ├── snail-modules-job/      #   定时任务（biz+model）
│   ├── snail-modules-thirdparty/#  第三方集成（api+biz+model）
│   ├── snail-modules-gateway/  #   网关配置（biz）
│   └── snail-modules-demo/     #   示例演示（biz+model）
│
├── snail-starters/             # 场景化自动装配
│   ├── snail-*-boot-starter/   #   单体 Starter × 8（Servlet MVC）
│   └── snail-*-cloud-starter/  #   微服务 Starter × 2（Feign + Reactive）
│
├── snail-monolith/             # 单体启动入口
├── snail-services/             # 微服务启动入口（8 个服务 + SQL）
├── snail-ai/                   # AI 服务
│   ├── snail-ai-oamr/          #   AI 运维机器人
│   └── snail-ai-mcp-*/         #   MCP 工具（向量/日志/业务/统计）
├── snail-dependencies/         # Maven 依赖版本管理
├── snail-web/                  # 前端项目
│   ├── snail-web/              #   Vue 2 管理端
│   └── snail-app/              #   Uni-App 移动端
└── docs/                       # 项目文档
```

---

## 🔧 快速开始

### 前置条件

| 组件 | 版本 | 端口 |
|------|------|------|
| JDK | 17+ | — |
| MySQL | 8.0+ | 3306 |
| Redis | 6.x+ | 6379 |
| Nacos | 2.x | 8848 |
| Maven | 3.8+ | — |
| Node.js | 16+ | — |

### 方式一：单体模式（推荐快速启动）

```bash
# 1. 初始化数据库
# 执行 snail-services/sql/ 下的脚本：
#   snail-config.sql / snail-job.sql / snail-oa.sql / snail-workflow.sql

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

# 3. 启动后端
cd snail-monolith
mvn clean package -DskipTests
java -jar target/snail-monolith.jar

# 4. 启动前端（Vue 2 管理端）
cd snail-web/snail-web
npm install
npm run serve -- --mode monolith
# 开发服务器: http://localhost:8000 → 代理到 :8080
```

### 方式二：微服务模式

```bash
# 1-2. 同上（初始化数据库 + 配置 Nacos）

# 3. 启动网关
cd snail-services/snail-gateway
mvn spring-boot:run

# 4. 依次启动核心服务
# snail-auth (:9200) → snail-system (:9300) → 其他服务

# 5. 启动前端
cd snail-web/snail-web
npm install
npm run serve
# 开发服务器: http://localhost:8000 → 代理到网关 :8080
```

### 系统访问

| 入口 | 地址 | 默认账号 |
|------|------|----------|
| 管理端 | `http://localhost:8000` | admin / admin123 |
| 网关 | `http://localhost:8080` | — |
| 认证服务 | `http://localhost:9200` | — |
| 系统服务 | `http://localhost:9300` | — |
| XXL-Job Admin | `http://localhost:8080/xxl-job-admin`（单体） | admin / 123456 |

---

## 📦 模块导航

| 模块 | 说明 | 文档 |
|------|------|------|
| **snail-common** | 公共基础设施（15 个子模块） | [README](snail-common/README.md) |
| **snail-modules** | 业务模块（8 个业务域） | [README](snail-modules/README.md) |
| **snail-starters** | 场景化自动装配（10 个 Starter） | [README](snail-starters/README.md) |
| **snail-monolith** | 单体模式启动入口 | [README](snail-monolith/README.md) |
| **snail-services** | 微服务模式启动入口（8 个服务） | [README](snail-services/README.md) |
| **snail-ai** | AI 运维 + MCP 工具 | [README](snail-ai/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) |

---

## 版本历史

| 版本 | 日期 | 里程碑 |
|:---|:---|:---|
| 7.0.0 | 2026-07 | 双模式架构重构：api/biz/model 三层拆分、boot/cloud Starter 机制、前端服务名路由适配 |
| 6.x | 2026-06 | 基础架构升级，jdk17、SpringBoot3.X等等 |
| 3.x | — | RuoYi-Cloud 基线版本 |