# magic-admin
**Repository Path**: hardy-fan/magic-admin
## Basic Information
- **Project Name**: magic-admin
- **Description**: No description available
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-08-01
- **Last Updated**: 2025-09-24
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
> 演示地址：http://14.103.184.174/index
>
> 前端地址：https://github.com/makemyownlife/magic-admin-ui
>
> 演示账号请关注公众号：勇哥Java实战，回复：magic 即可获取。
> 
# 1 项目背景
从职业生涯伊始，我一直是微服务架构的坚定拥趸，这很大程度上源于长期深耕互联网行业，习惯了高并发、分布式架构下的开发模式。
然而，去年在优化某航空公司核心用户中心系统时，我的技术认知受到了不小的冲击。
因为航空公司用户中心是一个典型的单体应用——尽管业务量不小，但稳定的业务模型和有限的扩展需求，使得单体架构反而比微服务更高效、更经济。
事实上，单体应用在 IT 领域始终占据着不可替代的生态位。甚至可以说，在大多数业务场景下，单体架构不仅完全够用，甚至可能是更优解。
它的价值主要体现在：**开发效率高、运维复杂度低**，尤其适合业务边界清晰、迭代节奏可控的中小型系统。
因此，我想自己写一个单体开发框架，但考虑到从零开始，会花费较长的时间，最终决定在成熟的单体开发框架上定制开发。
在知乎、Github 上搜索【快速开发框架】 ，很多的话题都绕不开若依 RuoYi 。开源世界 RuoYi 单体框架有三个不同的项目，分别是：**ruoyi-vue** 、**ruoyi-vue-plus** 、**ruoyi-vue-pro** 。
这三个项目源码，我都仔细研读过了，功能对比细节如下表 ：
| **评估维度** | **RuoYi-Vue** | **RuoYi-Vue-Plus** | **RuoYi-Vue-Pro** |
| ------------ | ----------------- | -------------------- | -------------------------- |
| **核心优势** | 极简开箱即用 | 多租户/功能增强 | 全生态功能预制 |
| **二次开发** | ⭐⭐⭐⭐⭐（源码简洁） | ⭐⭐⭐☆（需理解模块化） | ⭐⭐（需深度裁剪） |
| **成本效益** | 人力/时间成本最低 | 中等投入高回报 | (中等偏上)需评估功能利用率 |
> 有兴趣的同学可以参看对比文章 ，https://mp.weixin.qq.com/s/J_FUQHB3Ji35Uk1e40yHWg
最终，我选择基于 RuoYi-Vue-Pro 进行定制开发 ，原因很简单：基础功能丰富，且 UI 界面也符合我的口味。
项目的名称：magic-admin , 保留了 RuoYi-Vue-Pro 的基础功能 ，同时在**客户端管理**、**代码组织结构**、 **多租户管理**这三个层面做了定制。
# 2 设计概览
后端单体开发平台基于开源项目 ruoyi-vue-pro 重构 。
- 后端采用 Spring Boot、MySQL + MyBatis Plus、Redis + Redisson
- 消息队列可使用 Event、Redis、RabbitMQ、Kafka、RocketMQ 等
- 权限认证使用 Spring Security & Token & Redis，支持多终端、多种用户的认证系统
- 支持加载动态权限菜单，按钮级别权限控制，Redis 缓存提升性能
模块设计图如下：
**1、基础模块**
| 功能 | 描述 |
| ---------- | ------------------------------------------------------------ |
| 用户管理 | 用户是系统操作者，该功能主要完成系统用户配置 |
| 角色管理 | 角色菜单权限分配、设置角色按机构进行数据范围权限划分 |
| 菜单管理 | 配置系统菜单、操作权限、按钮权限标识等，本地缓存提供性能 |
| 部门管理 | 配置系统组织机构（公司、部门、小组），树结构展现支持数据权限 |
| 岗位管理 | 配置系统用户所属担任职务 |
| 客户端管理 | 配置系统客户端信息 |
| 字典管理 | 对系统中经常使用的一些较为固定的数据进行维护 |
| 操作日志 | 系统正常操作日志记录和查询 |
| 登录日志 | 系统登录日志记录查询，包含登录异常 |
| 通知公告 | 系统通知公告信息发布维护 |
| 地区管理 | 展示省份、城市、区镇等城市信息，支持 IP 对应城市 |
**2、基础设施**
| 描述 | |
| -------- | ------------------------------------------------------------ |
| 代码生成 | 前后端代码的生成（Java、Vue、SQL、单元测试），支持 CRUD 下载 |
| 系统接口 | 基于 Swagger 自动生成相关的 RESTful API 接口文档 |
| 表单构建 | 拖动表单元素生成相应的 HTML 代码，支持导出 JSON、Vue 文件 |
| 配置管理 | 对系统动态配置常用参数，支持 SpringBoot 加载 |
| 定时任务 | 在线（添加、修改、删除)任务调度包含执行结果日志 |
| 文件服务 | 支持将文件存储到 S3（MinIO、阿里云、腾讯云、七牛云）、本地、FTP、数据库等 |
| 消息队列 | 基于 Redis 实现消息队列，Stream 提供集群消费，Pub/Sub 提供广播消费 |
| 服务保障 | 基于 Redis 实现分布式锁、幂等、限流功能，满足高并发场景 |
界面截图见下图：
# 3 定制功能
**1、删除多租户功能**
多租户功能是指**一套系统可以同时服务多个不同的租户（客户或组织），并且每个租户的数据和配置相互隔离**，彼此不可见。
| 方式 | 说明 | 优缺点 |
| ------------------------------------ | -------------------------------------------- | ------------------------------------ |
| **独立数据库** | 每个租户使用单独的数据库 | ✅ 隔离性好，安全性高
❌ 运维成本高 |
| **共享数据库，独立Schema** | 同一数据库，不同租户使用不同表结构（Schema） | ✅ 资源利用率高
❌ 需数据库支持 |
| **共享数据库，共享表（租户ID字段）** | 所有租户数据存同一表，用 `tenant_id` 区分 | ✅ 成本最低
❌ 需严格代码控制 |
ruoyi-vue-pro 是采用了第三种方式来实现的，每张表需要添加 tenant_id 字段 ，我认为不同的业务形态对于多租户功能的需求是不一样，采用一刀切的使用 `tenant_id` 区分可能会导致系统的复杂度更高 , 出现 BUG 的风险系数高，所以我删除了多租户功能，保持和 ruoyi-vue (若依版本) 一致。
**2、客户端管理**
后台系统不仅仅可以支持后台登录，也应该可以支持 APP 或者 小程序等其他终端登录。
不同终端在发送请求时，都需要再请求头中传输客户端 Key , 不同终端可配置独立的 **Token 有效期、权限策略**。
**3、Token 管理**
下图是 ruoyi-vue-pro 的 Token 记录表 即：数据库是 Token 的存储容器 。
虽然每次查询 accessToken 都会先从 Redis 先查询一次 ，但假如在同一时刻有大量 Token 失效，那么数据库就会成为瓶颈，可能会有缓存雪崩的风险。
我的做法是所有的 Token 都通过 Redis 来存储，同时每个客户端都有独立的 namespace ，见下图：
**4、包层级结构**
相比 ruoyi-vue-pro ， 我更加倾向于简洁的包层级结构。
如图，包结构分为 controller 、domain、mapper 、 service 四个核心包，同时 domain 根据领域分为五个子包：
- dataobject : 数据实体对象 ，可以简单的理解，一个对象映射一张表
- enums：枚举对象，比如错误码
- vo: 前端请求/响应对象
- convert ：通过 service 将 dataobject 对象转换成 VO 对象
- dto：内置服务调用对象
同时，我也修改了代码生成逻辑，生成的目录也完全按照上面的标准。
# 4 框架设计规划
框架设计的原则还是要简洁和易于维护，未来会在如下两个层面持续优化：
1、客户端管理优化（加密增强）
2、添加流程引擎模块（企业级工作流支持）
# 5 启动服务端
本地电脑上项目运行环境依赖组件以及版本信息如下：
- IntelliJ IDEA 版本 2019 +
- Git 代码版本管理工具
- JDK 8 +
- Maven（如果 IntelliJ IDEA 2021 版本及以上，内置了 Maven 组件）
## 01 克隆项目
打开 Github 项目地址， 复制对应的 SSH 或 HTTP 克隆地址。
打开 IntelliJ IDEA，菜单栏顶部找到 Git -> Clone 选项。
点击 Clone 后，URL 文本框填写项目的 HTTP 或 SSH 地址，比如 HTTP 的地址：`git@github.com:makemyownlife/magic-admin.git`，Directory 填写项目存储在本地的目录地址。
等待克隆及 Maven 初始化即可。
拉下来后，可在项目根目录执行 `mvn clean install` 测试是否具备运行环境。
## 02 初始化 MySQL
项目当前支持 MySQL 5.7 + ，首先需要创建一个名字为 `magic-admin` 数据库 。
然后分别导入 magic_admin.sql ，quartz.sql 这两个文件。
- **magic_admin.sql**：用于创建或初始化 MagicAdmin 后台管理系统所需的数据库结构和初始数据 。
- **quartz.sql** : Quartz 调度框架的数据库脚本，用于在数据库中创建 Quartz 所需的表结构，以便支持持久化任务调度 。
## 03 项目启动
项目依赖 JDK 1.8 + ，因此理论上兼容性非常强。
配置文件分为 生产 prod 、本地开发 local 两个环境文件，在本地运行，需要修改本地环境文件。
**1、修改 MySQL 数据库信息：**
**2、修改 Redis 数据库信息：**
**个人本地环境，一般笔者并不会开启密码，建议生产环境开启。**
启动 MagicAdminApplication.java 即可。
# 6 启动 admin UI
前端 UI 需要在本机安装 NodeJs ，可参考：
> https://www.runoob.com/nodejs/nodejs-install-setup.html
>
> https://blog.csdn.net/weixin_45565886/article/details/141828707
----
打开 Githu 项目地址：https://github.com/makemyownlife/magic-admin-ui 复制对应的 SSH 或 HTTP 克隆地址。
通过 git clone 命令克隆到本地自定义目录，然后执行如下命令：
```bash
# 安装 pnpm，提升依赖的安装速度
npm config set registry https://registry.npmjs.org
npm install -g pnpm
# 安装依赖
pnpm install
# 启动服务
npm run dev
```
启动完成后，浏览器会自动打开 http://localhost:80 ，可以看到前端界面。
> 默认账号密码：admin/magic123456