mars-admin 不是单一后台前端项目，而是一套完整的前后端分离管理平台，包含：

Spring Boot 3 后端 Vue 3 管理后台 uni-app 移动端 WebSocket 实时消息 代码生成器 Flowable 审批工作流 RBAC 权限、系统配置、文件存储、监控能力 当前仓库适合作为企业后台、内部系统或二开业务底座。

• 系统管理：用户、角色、菜单、部门、岗位、字典、参数配置
• 权限控制：基于 Sa-Token 的 RBAC 权限模型
• 系统监控：在线用户、定时任务、缓存监控、服务监控、API 访问统计、Druid 监控
• 日志审计：登录日志、操作日志
• 消息中心：系统通知、私聊、群聊、未读统计、WebSocket 实时推送
• 文件管理：本地 / MinIO / 阿里云 OSS 可切换
• 安全能力：验证码、登录限制、RSA/AES 加密链路
• 代码生成：导表、生成前后端 CRUD、支持生成到项目或下载代码包
• 工作流：流程分类、部署、设计器、待办审批、抄送我、流程实例
• 多端接入：后台管理端、PC 前台接口、App / 小程序接口

mars-admin
├── mars-common              # 公共基础模块
│   ├── entity               # 基础实体类
│   ├── exception            # 全局异常处理
│   ├── result               # 统一响应封装
│   └── util                 # 工具类
│
├── mars-infra               # 基础设施层
│   ├── mars-db              # 数据库配置
│   ├── mars-redis           # Redis 配置
│   ├── mars-oss             # 文件存储（本地/MinIO/阿里云OSS）
│   ├── mars-sms             # 短信服务（阿里云/腾讯云）
│   ├── mars-pay             # 支付服务（微信/支付宝）
│   ├── mars-push            # 推送服务（极光/友盟/个推）
│   ├── mars-social          # 社交登录（微信/支付宝/苹果）
│   ├── mars-wechat          # 微信公众号/小程序
│   ├── mars-websocket       # WebSocket 支持
│   └── mars-crypto          # 加密解密
│
├── mars-core                # 业务核心层
│   ├── mars-system          # 系统管理
│   │   ├── entity           # 系统实体（用户、角色、菜单等）
│   │   ├── mapper           # MyBatis Mapper
│   │   ├── service          # 服务层
│   │   ├── annotation       # 自定义注解
│   │   └── aspect           # AOP 切面
│   ├── mars-auth            # 认证授权
│   │   ├── strategy         # 登录策略（密码/短信/社交/小程序）
│   │   └── enums            # 枚举定义
│   ├── mars-file            # 文件管理
│   ├── mars-gen             # 代码生成
│   └── mars-message         # 消息中心（公告/聊天/群聊）
├── mars-flowable            # 审批工作流模块
│
├── mars-api                 # 接口层
│   ├── mars-admin-api       # 后台管理接口
│   │   └── controller
│   │       ├── auth         # 认证接口
│   │       ├── system       # 系统管理接口
│   │       ├── monitor      # 系统监控接口
│   │       ├── message      # 消息接口
│   │       ├── file         # 文件接口
│   │       └── gen          # 代码生成接口
│   ├── mars-app-api         # APP 接口
│   └── mars-web-api         # 网页端接口
│
├── mars-job                 # 定时任务模块
│   ├── entity               # 任务实体
│   ├── service              # 任务服务
│   └── util                 # Quartz 工具类
│
├── mars-starter             # 启动入口
│   └── resources
│       ├── application.yml
│       ├── application-dev.yml
│       └── application-prod.yml
│
├── mars-ui                  # 后台管理前端
│   ├── src
│   │   ├── api              # API 接口定义
│   │   ├── components       # 公共组件
│   │   ├── layout           # 布局组件
│   │   ├── router           # 路由配置
│   │   ├── stores           # Pinia 状态管理
│   │   ├── utils            # 工具函数
│   │   └── views            # 页面组件
│   │       ├── dashboard    # 控制台
│   │       ├── system       # 系统管理
│   │       ├── monitor      # 系统监控
│   │       ├── log          # 日志管理
│   │       ├── message      # 消息中心
│   │       ├── org          # 组织管理
│   │       └── tool         # 系统工具
│   └── package.json
│
├── mars-uniapp              # 移动端小程序
│   ├── pages
│   │   ├── login            # 登录页
│   │   ├── index            # 首页
│   │   ├── chat             # 私聊
│   │   ├── group-chat       # 群聊
│   │   ├── contacts         # 联系人
│   │   ├── group            # 群组管理
│   │   └── profile          # 个人中心
│   └── utils                # 工具类
│
└── sql                      # 数据库脚本
    └── mars-system.sql

• 用户管理 - 用户的增删改查、角色分配、状态管理、用户黑名单
• 角色管理 - 角色的权限配置、菜单分配、数据权限
• 菜单管理 - 菜单的增删改查、权限标识配置
• 部门管理 - 组织架构管理、树形结构展示
• 岗位管理 - 岗位的增删改查
• 字典管理 - 数据字典维护、字典项管理
• 系统配置 - 系统参数的动态配置（分组管理）

• 在线用户 - 当前在线用户查看、强制下线
• 定时任务 - Quartz 任务调度、执行日志
• 服务监控 - 服务器 CPU、内存、JVM 信息
• 缓存监控 - Redis 缓存信息、键值管理

• 登录日志 - 用户登录记录、登录地点
• 操作日志 - 用户操作记录、AOP 切面自动记录

• 系统公告 - 公告发布、已读未读状态
• 即时通讯 - WebSocket 实时消息
• 私聊 - 一对一聊天
• 群聊 - 群组创建、成员管理、群消息

• 文件上传 - 支持本地/MinIO/阿里云OSS
• 文件管理 - 文件列表、预览、下载、删除

• 代码生成器 - 根据数据库表生成前后端代码

• 验证码 - 图片验证码、滑块验证码、短信验证码
• 接口加密 - RSA 非对称加密传输
• 登录安全 - 登录失败限制、账号锁定
• 权限控制 - 基于 RBAC 的细粒度权限控制
• 多种登录方式 - 密码登录、短信登录、社交登录、小程序登录

• 文件存储 - 本地存储 / MinIO / 阿里云 OSS
• 短信服务 - 控制台 / 阿里云 / 腾讯云
• 支付服务 - 微信支付 / 支付宝
• 推送服务 - 控制台 / 极光 / 友盟 / 个推
• 社交登录 - 微信公众号 / 微信小程序 / 支付宝 / 苹果

• JDK 17+
• Maven 3.8+
• MySQL 8.0+
• Redis 7.0+
• Node.js 18+

1. 克隆项目

git clone https://gitee.com/Marsfactory/mars-admin.git
cd mars-admin

2. 初始化数据库

-- 创建数据库
CREATE DATABASE mars-system DEFAULT CHARACTER SET utf8mb4;

-- 导入 SQL
mysql -u root -p mars-system < sql/mars-system.sql
mysql -u root -p mars-system < sql/mars-flowable.sql
mysql -u root -p mars-system < sql/mars-flowable-indexes.sql

3. 修改配置

修改 mars-starter/src/main/resources/application-dev.yml 中的数据库和 Redis 配置：

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/mars-system
    username: root
    password: your_password
  data:
    redis:
      host: localhost
      port: 6379
      password: 
      database: 10

4. 启动项目

mvn clean install
cd mars-starter
mvn spring-boot:run

后端默认运行在 http://localhost:8080

cd mars-ui
npm install
npm run dev

前端默认运行在 http://localhost:3000

cd mars-uniapp
npm install

当前仓库的 mars-uniapp 未单独提供 npm run dev 脚本，使用 HBuilderX 打开 mars-uniapp 目录后启动：

1. 在 HBuilderX 中选择“运行”
2. 选择“运行到小程序模拟器”
3. 选择“微信开发者工具”

如需 H5 调试，也可以在 HBuilderX 中选择“运行到浏览器”。

支持自行注册账号体验

系统支持多种文件存储方式，通过系统配置动态切换：

• 本地存储 - 默认方式，文件存储在服务器本地
• MinIO - 分布式对象存储
• 阿里云 OSS - 阿里云对象存储服务

• 控制台输出 - 开发测试使用，验证码打印到控制台
• 阿里云短信 - 阿里云短信服务
• 腾讯云短信 - 腾讯云短信服务

• 微信支付 - 微信支付 API v3
• 支付宝 - 支付宝开放平台

• 控制台输出 - 开发测试使用
• 极光推送 - JPush
• 友盟推送 - UMeng Push
• 个推 - GeTui

• 微信公众号 - 微信公众平台网页授权
• 微信小程序 - 微信小程序登录
• 支付宝 - 支付宝账号登录
• 苹果登录 - Sign in with Apple

这一节不是产品介绍，而是基于当前仓库代码结构整理出的二开视角说明，重点帮助你快速定位真实入口、核心链路和改造边界。

mars-admin 不是单一后台前端项目，而是一个包含：

• Spring Boot 3 后端平台
• Vue 3 + Naive UI 管理后台
• uni-app 小程序端
• WebSocket 实时消息
• 代码生成器
• 配置中心 + RBAC + 文件存储 + 可插拔基础设施

的多模块一体化项目。

它更像一个“后台开发底座”，不是只靠几个页面拼起来的演示项目。二开时建议把它理解成三层：

1. 平台底座层：认证、权限、菜单、日志、配置、监控、文件、消息、定时任务
2. 业务承载层：mars-biz 中的具体业务表模块，以及后续新增业务模块
3. 多端接入层：mars-admin-api、mars-web-api、mars-app-api、mars-ui、mars-uniapp

• mars-common：统一返回、基础实体、异常处理、工具类
• mars-infra/mars-db：MyBatis-Plus、分页、数据权限拦截器
• mars-infra/mars-redis：Redis 支撑
• mars-infra/mars-websocket：WebSocket 握手与容器配置
• mars-infra/mars-crypto：请求解密、响应加密
• mars-infra/mars-oss / mars-sms / mars-pay / mars-push / mars-wechat / mars-social / mars-mail：可插拔能力模块

• mars-core/mars-system：平台核心，包含用户、角色、菜单、部门、岗位、字典、配置、日志、监控等
• mars-core/mars-auth：登录策略工厂，统一处理密码/短信/社交/小程序登录
• mars-core/mars-file：文件上传、分组、预览、下载
• mars-core/mars-message：通知、私聊、群聊
• mars-core/mars-gen：导表、生成代码、回滚代码
• mars-core/mars-biz：业务模块承载层，适合放你自己的业务

• mars-api/mars-admin-api：后台管理接口
• mars-api/mars-web-api：PC 前台接口，目前主要是认证入口
• mars-api/mars-app-api：App/小程序接口，目前也以认证相关为主
• mars-starter：Spring Boot 启动入口与静态资源承载

启动类在：

• mars-starter/src/main/java/com/mars/MarsAdminApplication.java

后台所有 @RestController 会自动添加 /api 前缀，避免和前端路由冲突，见：

• mars-api/mars-admin-api/src/main/java/com/mars/admin/config/ApiPrefixConfig.java

因此：

• 后端控制器写 @RequestMapping("/sys/user")
• 实际访问路径是 /api/sys/user

前端 mars-ui 通过 Vite 代理 /api 到本地 8080，构建产物会直接输出到：

• mars-starter/src/main/resources/static

这说明当前默认部署方式是“Spring Boot 直接托管前端静态资源”。

mars-ui 的核心不是单个页面，而是下面几条主线：

• src/main.ts：初始化 Vue、Pinia、Naive UI，并预加载加密配置和站点配置
• src/router/index.ts：静态路由 + 基于后端菜单的动态路由
• src/stores/user.ts：token、用户、角色、权限、菜单
• src/stores/site.ts：站点配置、水印、禁调试等公开配置
• src/stores/message.ts：消息通知、未读数、WebSocket 初始化
• src/utils/request.ts：Axios 二次封装、统一错误处理、响应解密
• src/utils/websocket.ts：消息 WebSocket 管理

也就是说，这个后台本质上是“配置驱动 + 权限驱动”的管理台，而不是页面硬编码。

后台登录控制器在：

• mars-api/mars-admin-api/src/main/java/com/mars/admin/controller/auth/AdminAuthController.java

PC 前台登录在：

• mars-api/mars-web-api/src/main/java/com/mars/web/controller/WebAuthController.java

登录不会直接在 Controller 里写死，而是走：

• mars-core/mars-auth/src/main/java/com/mars/auth/LoginStrategyFactory.java

默认管理端登录使用：

• ClientType.ADMIN
• LoginType.PASSWORD

密码登录核心实现见：

• mars-core/mars-auth/src/main/java/com/mars/auth/strategy/PasswordLoginStrategy.java

其中已经包含：

• 图形验证码 / 短信验证码校验
• 登录失败次数限制
• Redis 锁定
• 用户状态校验
• 用户类型校验
• Sa-Token 登录
• 登录日志记录

Sa-Token 拦截器配置在：

• mars-core/mars-system/src/main/java/com/mars/system/config/SaTokenConfig.java

角色/权限读取实现见：

• mars-core/mars-system/src/main/java/com/mars/system/config/StpInterfaceImpl.java

它会优先把权限和角色缓存在 Sa-Session 中，避免每次请求都查库。

项目已打通一套可配置的加密链路：

• 请求体解密：mars-infra/mars-crypto/.../DecryptRequestBodyAdvice.java
• 响应体加密：mars-infra/mars-crypto/.../EncryptResponseBodyAdvice.java
• 前端密码加密：mars-ui/src/utils/crypto.ts
• 前端响应解密：mars-ui/src/utils/request.ts

目前支持：

• 密码字段自动 RSA 加密
• 响应数据按配置进行 AES 加密
• 支持“全局加密”或“仅加密带 @EncryptResponse 注解的方法”

这是二开时最关键的链路之一。

用户登录成功后，前端会调用 /api/auth/info，后端一次性返回：

• 当前用户信息
• 角色列表
• 权限标识列表
• 菜单树

菜单装配逻辑在：

• mars-core/mars-system/src/main/java/com/mars/system/service/impl/SysMenuServiceImpl.java

前端在：

• mars-ui/src/stores/user.ts
• mars-ui/src/router/index.ts

中读取菜单并动态注册路由。

这里有两个硬约束：

1. 菜单 type = 2 才会被识别为页面路由
2. 菜单的 component 字段必须能映射到 mars-ui/src/views/**/*.vue

例如：

• 菜单组件写 system/user/index
• 前端就必须存在 mars-ui/src/views/system/user/index.vue

如果数据库菜单存在、权限也有，但前端页面文件不存在，动态路由会跳过该页面。

项目中很多功能不是写死在 application.yml，而是放在数据库配置分组里，通过 SystemConfigHelper 动态读取：

• 站点名称、描述、Logo、水印
• 登录方式、验证码、记住我、单点登录
• 注册开关、审核策略、默认角色
• 密码复杂度
• 文件上传限制
• 短信、邮件、支付、推送、微信配置
• 接口加密配置
• 前端禁调试开关
• Sa-Token 安全配置

核心文件：

• mars-core/mars-system/src/main/java/com/mars/system/helper/SystemConfigHelper.java
• mars-api/mars-admin-api/src/main/java/com/mars/admin/controller/system/SysConfigGroupController.java
• mars-ui/src/views/system/config/index.vue

所以二开时，优先判断某个能力是否已经可以“配置化”，不要急着硬改代码。

文件模块不是占位，已经打通：

• 文件上传、预览、下载、删除
• 文件分组
• 存储策略切换

核心文件：

• mars-core/mars-file/src/main/java/com/mars/file/service/impl/SysFileServiceImpl.java
• mars-core/mars-system/src/main/java/com/mars/system/storage/FileStorageFactory.java

支持：

• 本地存储
• MinIO
• 阿里云 OSS
• 腾讯云 COS
• RustFS

消息模块也不是假页面，已经包含：

• 系统通知
• 私聊
• 群聊
• WebSocket 实时推送
• 未读数同步

核心文件：

• mars-api/mars-admin-api/src/main/java/com/mars/admin/controller/message/SysNoticeController.java
• mars-api/mars-admin-api/src/main/java/com/mars/admin/controller/message/SysChatController.java
• mars-api/mars-admin-api/src/main/java/com/mars/admin/controller/message/ChatGroupController.java
• mars-api/mars-admin-api/src/main/java/com/mars/admin/websocket/MessageWebSocketHandler.java

代码生成器当前是可用状态，不只是示意页面。它支持：

• 读取数据库表结构
• 导入生成配置
• 预览代码
• 下载 ZIP
• 直接生成到项目
• 预览将生成/将删除的文件
• 回滚已生成代码

核心文件：

• mars-core/mars-gen/src/main/java/com/mars/gen/service/impl/GenTableServiceImpl.java

如果后续要批量扩业务表，优先考虑以 mars-gen 为基础进行生成，再按实际业务修整。

目前仓库中的“平台模块”完成度较高，而“业务模块”是半模板、半实装状态。

已确认的业务示例：

• student：前后端已存在，属于典型生成器业务模块
• 前端页面：mars-ui/src/views/system/student/index.vue
• 前端 API：mars-ui/src/api/student.ts
• 后端接口：mars-core/mars-biz/src/main/java/com/mars/biz/controller/StudentController.java

另外还存在一个需要注意的现象：

• customer 前端页面和 API 已存在
• 但当前仓库中未找到对应的后端 CustomerController

这说明仓库内可能存在“前后端未完全对齐”的模块，正式二开前建议先做一轮基线盘点。

当前项目同时存在：

• 平台风格：/sys/**
• 业务表风格：/system/**

对应权限码也有两种风格：

• sys:user:list
• system:student:list

后续扩业务时，建议尽快统一命名规范，否则时间一长会变得难维护。

例如 student 控制器位于 mars-biz，但代码包名仍使用了 com.mars.system.* 风格。项目能运行，但会增加理解成本。

后台二开最常见的问题不是代码写错，而是：

• 数据库菜单路径
• 权限标识
• 前端页面路径
• 后端接口权限码

没有同时对齐。

如果新增一个模块，至少要同步检查：

• 菜单表 path / component / permission
• 前端 views 路径
• 页面按钮权限判断
• Controller 上的 @SaCheckPermission

如果你要改的是：

• 用户、角色、菜单、字典、配置、监控、日志、消息、文件

优先改：

• mars-core/mars-system
• mars-api/mars-admin-api
• mars-ui/src/views/system|monitor|log|message

如果你要新增自己的业务表、业务页面、导入导出、审批前表单等，建议优先放：

• mars-core/mars-biz

前端配套放：

• mars-ui/src/views/...
• mars-ui/src/api/...

如果你要做：

• PC 前台业务
• 小程序业务
• App 业务

则需要继续补充：

• mars-api/mars-web-api
• mars-api/mars-app-api
• mars-uniapp

当前这两层接口已具备认证基础，但业务接口数量还不多。

推荐先判断模块属于“平台能力”还是“业务模块”：

• 如果属于用户、角色、菜单、字典、配置、日志、监控等平台能力，放在 mars-core/mars-system
• 如果属于你自己的业务表与业务流程，优先放在 mars-core/mars-biz

典型新增步骤：

1. 创建实体类、Mapper、Service、Controller
2. 在前端 mars-ui/src/api 中补接口文件
3. 在前端 mars-ui/src/views 中补页面
4. 在菜单表中配置 path / component / permission
5. 给按钮和接口补齐权限标识
6. 如需导入导出，优先复用已有 EasyExcel 模式

如果是标准 CRUD 表，建议优先使用代码生成器导入数据库表，再在生成结果基础上进行人工调整。

使用 @Log 注解自动记录操作日志：

@Log(title = "用户管理", businessType = BusinessType.INSERT)
@PostMapping
public Result<Void> add(@RequestBody SysUser user) {
    // ...
}

使用 Sa-Token 注解进行权限控制：

@SaCheckPermission("sys:user:add")
@PostMapping
public Result<Void> add(@RequestBody SysUser user) {
    // ...
}

说明：

• 平台模块当前多使用 sys:*
• 生成器产出的业务模块多使用 system:*

二开时建议团队统一一套权限命名规范。

在 mars-core/mars-auth/strategy 下创建新的登录策略类，实现 LoginStrategy 接口：

@Component
public class CustomLoginStrategy implements LoginStrategy {
    @Override
    public LoginResult login(LoginRequest request) {
        // 自定义登录逻辑
    }
}

• 重构项目结构为分层架构（common/infra/core/api）
• 新增 mars-uniapp 移动端小程序（聊天办公）
• 新增群聊功能（群组创建、成员管理、群消息）
• 新增多种登录策略（密码/短信/社交/小程序）
• 新增社交登录（微信/支付宝/苹果）
• 新增代码生成器模块
• 新增文件存储策略工厂（本地/MinIO/OSS）
• 新增推送服务策略工厂（极光/友盟/个推）
• 新增短信服务策略工厂（阿里云/腾讯云）
• 新增支付服务策略工厂（微信/支付宝）
• 完善系统配置分组管理
• 优化登录页面（三种样式）
• 新增滑块验证码（弹窗拼图模式）

• 完成字典管理和系统配置功能
• 实现部门和岗位管理
• 新增即时通讯功能（WebSocket）
• 优化前端界面和交互体验

• 搭建项目基础框架
• 集成 Sa-Token 实现认证授权
• 完成前后端基础架构搭建
• 实现基础权限管理（用户、角色、菜单）

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

本项目基于 MIT License 开源。