梦幻西游管理后台 - 后端项目
基于 Spring Boot 3.2 + MyBatis-Plus + Spring Security + MinIO + Knife4j 的游戏管理后台系统。
技术栈
- 后端框架: Spring Boot 3.2.0
- ORM 框架: MyBatis-Plus 3.5.5
- 安全框架: Spring Security + JWT
- 数据库: MySQL 8.0 + Flyway 版本管理
- 对象存储: MinIO (兼容 S3)
- API 文档: Knife4j 4.4.0
- 连接池: Druid 1.2.20
- 工具库: Hutool 5.8.24
- 缓存: Redis 7
- 构建工具: Maven
功能模块
系统模块
- ✅ 用户认证（登录、注册、Token 刷新）
- ✅ 用户管理（增删改查）
- ✅ 角色管理（增删改查、权限分配）
- ✅ 权限管理（树形结构）
- ✅ RBAC 权限控制
业务模块
- ✅ 文件管理（上传、下载、去重）
- ✅ 邀请码系统
- ✅ 服务器管理
- ✅ 账号管理
- ✅ 角色管理（含图片、关键词）
项目结构
mhxy-tools/
├── src/main/java/com/mhxy/
│ ├── common/ # 通用模块
│ │ ├── config/ # 配置类
│ │ │ ├── MyBatisPlusConfig.java
│ │ │ ├── SecurityConfig.java
│ │ │ └── CustomMetaObjectHandler.java
│ │ ├── constant/ # 常量
│ │ │ └── BusinessConstant.java
│ │ ├── dto/ # 通用 DTO
│ │ │ └── PageDTO.java
│ │ ├── entity/ # 通用实体
│ │ │ └── BaseEntity.java
│ │ ├── exception/ # 异常处理
│ │ │ ├── BusinessException.java
│ │ │ └── GlobalExceptionHandler.java
│ │ ├── result/ # 统一响应
│ │ │ └── Result.java
│ │ ├── security/ # 安全相关
│ │ │ └── JwtAuthenticationFilter.java
│ │ ├── util/ # 工具类
│ │ │ └── JwtUtil.java
│ │ └── vo/ # 通用 VO
│ │ └── PageVO.java
│ ├── common/ # 系统模块
│ │ ├── controller/
│ │ │ ├── AuthController.java
│ │ │ ├── SysUserController.java
│ │ │ ├── SysRoleController.java
│ │ │ └── SysPermissionController.java
│ │ ├── mapper/
│ │ │ ├── SysUserMapper.java
│ │ │ ├── SysRoleMapper.java
│ │ │ ├── SysPermissionMapper.java
│ │ │ ├── SysUserRoleMapper.java
│ │ │ └── SysRolePermissionMapper.java
│ │ ├── model/
│ │ │ ├── dto/
│ │ │ ├── entity/
│ │ │ │ ├── SysUser.java
│ │ │ │ ├── SysRole.java
│ │ │ │ ├── SysPermission.java
│ │ │ │ ├── SysUserRole.java
│ │ │ │ └── SysRolePermission.java
│ │ │ └── vo/
│ │ ├── service/
│ │ │ ├── AuthService.java
│ │ │ ├── SysUserService.java
│ │ │ └── SysRoleService.java
│ │ └── service/impl/
│ │ ├── AuthServiceImpl.java
│ │ ├── SysUserServiceImpl.java
│ │ └── SysRoleServiceImpl.java
│ └── business/ # 业务模块
│ ├── controller/
│ │ └── FileController.java
│ ├── mapper/
│ │ └── FileHashReferenceMapper.java
│ ├── model/
│ │ ├── entity/
│ │ │ └── FileHashReference.java
│ │ └── vo/
│ ├── service/
│ │ ├── FileService.java
│ │ └── FileServiceImpl.java
│ └── service/impl/
│ └── FileServiceImpl.java
├── src/main/resources/
│ ├── application.yml # 主配置文件
│ ├── mapper/ # MyBatis XML 映射文件
│ └── db/migration/ # Flyway 数据库迁移脚本
│ └── V1.0.0__init_schema.sql
├── sql/ # 数据库脚本
│ └── mhxy-mgr.sql
├── Dockerfile # Docker 构建文件
├── docker-compose.yml # Docker Compose 配置
├── .dockerignore # Docker 忽略文件
├── .gitignore # Git 忽略文件
└── pom.xml # Maven 配置文件
快速开始
前置要求
- JDK 17+
- Maven 3.6+
- Docker (可选，用于容器化部署)
本地开发
1. 克隆项目
git clone <repository-url>
cd mhxy-tools
2. 配置数据库
创建 MySQL 数据库：
CREATE DATABASE mhxy-mgr CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
3. 启动 MySQL
# 使用 docker-compose 启动（包含 MySQL、MinIO、Redis）
docker-compose up -d mysql
# 或手动启动
mysql -u root -p < sql/mhxy-mgr.sql
4. 修改配置
编辑 src/main/resources/application.yml，修改数据库密码等配置：
spring:
datasource:
url: jdbc:mysql://localhost:3306/mhxy-mgr?...
username: root
password: your_password # 修改为你的数据库密码
redis:
host: localhost
port: 6379
minio:
access-key: minioadmin
secret-key: minioadmin
bucket-name: mhxy-files
5. 启动应用
# 使用 Maven 启动
mvn clean install
mvn spring-boot:run
# 或使用 IDE 直接运行 MhxyToolsApplication
6. 访问 API 文档
打开浏览器访问：http://localhost:8080/doc.html
默认管理员账号：
- 用户名：admin
- 密码：admin123
Docker 部署
一键启动所有服务
# 启动所有服务（MySQL、MinIO、Redis、应用）
docker-compose up -d
# 查看日志
docker-compose logs -f app
# 停止所有服务
docker-compose down
# 停止并删除数据卷
docker-compose down -v
访问服务
- 应用: http://localhost:8080
- API 文档: http://localhost:8080/doc.html
- MinIO 控制台: http://localhost:9001
- 用户名：minioadmin
- 密码：minioadmin
- MinIO API: http://localhost:9000
- Druid 监控: http://localhost:8080/druid/index.html
- 用户名：admin
- 密码：admin
- MySQL: localhost:3306
- 数据库：mhxy-mgr
- 用户名：root
- 密码：root
API 接口
认证接口
POST /api/auth/login # 用户登录
POST /api/auth/register # 用户注册
POST /api/auth/refresh # 刷新 Token
系统管理接口
# 用户管理
GET /api/system/users # 获取用户列表
GET /api/system/users/current # 获取当前用户信息
GET /api/system/users/{id} # 获取用户详情
POST /api/system/users # 创建用户
PUT /api/system/users/{id} # 更新用户
DELETE /api/system/users/{id} # 删除用户
PUT /api/system/users/{id}/reset-password # 重置密码
PUT /api/system/users/{id}/roles # 分配角色
# 角色管理
GET /api/system/roles # 获取角色列表
GET /api/system/roles/{id} # 获取角色详情
POST /api/system/roles # 创建角色
PUT /api/system/roles/{id} # 更新角色
DELETE /api/system/roles/{id} # 删除角色
PUT /api/system/roles/{id}/permissions # 分配权限
# 权限管理
GET /api/system/permissions # 获取权限列表
GET /api/system/permissions/tree # 获取权限树
GET /api/system/permissions/menus # 获取用户菜单树
POST /api/system/permissions # 创建权限
PUT /api/system/permissions/{id} # 更新权限
DELETE /api/system/permissions/{id} # 删除权限
业务接口
# 文件管理
POST /api/business/files/upload # 上传文件
POST /api/business/files/upload/batch # 批量上传文件
GET /api/business/files/download/{fileHash} # 下载文件
DELETE /api/business/files/{fileHash} # 删除文件
GET /api/business/files/{fileHash} # 获取文件信息
GET /api/business/files/preview/{fileHash} # 生成预签名 URL
核心功能说明
1. 文件去重
系统使用 SHA-256 Hash 进行文件去重，上传相同文件时会自动复用已有文件，节省存储空间。
去重流程：
- 计算文件 Hash
- 查询数据库是否已存在
- 如果存在，引用计数 +1；如果不存在，上传到 MinIO 并插入记录
2. 权限控制
使用 SpringSecurity + JWT 实现认证授权：
- Access Token：有效期 2 小时
- Refresh Token：有效期 7 天
- 权限注解：
@PreAuthorize("hasAuthority('user:create')")
3. 数据权限隔离
通过 MyBatis-Plus 的逻辑删除和 deleted 字段实现数据隔离。
4. API 文档
使用 Knife4j 提供 Swagger UI，访问：http://localhost:8080/doc.html
开发指南
添加新接口
- 在对应的 Controller 中添加方法
- 使用
@Operation注解添加 API 文档说明 - 使用
@PreAuthorize添加权限控制 - 返回
Result<T>格式的响应
添加新模块
- 创建 Mapper 接口（继承 BaseMapper）
- 创建 Entity 实体类（继承 BaseEntity）
- 创建 DTO（入参）和 VO（出参）
- 创建 Service 接口和实现类
- 创建 Controller 处理 HTTP 请求
数据库迁移
使用 Flyway 管理数据库版本：
- 在
src/main/resources/db/migration/创建新的迁移脚本 - 文件名格式：
V{version}__{description}.sql - 启动应用时自动执行迁移
常见问题
1. 连接数据库失败
检查 application.yml 中的数据库配置是否正确，确保 MySQL 服务已启动。
2. MinIO 连接失败
确保 MinIO 服务已启动，可以访问 http://localhost:9001 检查。
3. Flyway 迁移失败
删除 flyway_schema_history 表后重新启动应用。
许可证
本项目仅供学习和参考使用。
联系方式
如有问题，请提交 Issue。