# YunShu

**Repository Path**: ofom/YunShu

## Basic Information

- **Project Name**: YunShu
- **Description**: 云枢 (YunShu) —— 基于 SpringBoot 3 (JDK 21) + Vue 3 + Vite 的轻量级权限模板。后端以 MyBatis + Spring Security 为基座，代码极简、逻辑清晰，秉持“开箱即用”理念，去除冗余依赖。开发者仅需关注自身业务，即可快速完成功能扩展与部署，尤其适合毕设与小项目，告别从零搭建。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2025-06-06
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 云枢 YunShu

云枢 (YunShu) —— 一款开箱即用的轻量级权限管理系统模板，专为快速启动中小型项目与毕业设计而设计。

项目采用 Spring Boot 3 (JDK 21) 与 Vue 3 + Vite 构建前后端分离架构，后端以 MyBatis 为数据访问层，Spring Security 提供统一的身份认证与权限控制。

代码设计遵循"极简抽象、少即是多"的原则，仅保留最核心的公共模块，去除冗余依赖与过度封装，确保逻辑清晰、易于理解和二次开发。

开发者无需从零搭建，即可在模板基础上直接进行功能扩展、本地运行与生产打包部署，极大缩短项目启动周期。界面风格简洁现代，交互体验流畅，是技术学习、课程设计及小型业务系统的理想起点。

---

## ✨ 功能特性

- **RBAC 权限**：用户 / 角色 / 菜单三级模型，菜单按角色动态生成侧边栏路由
- **登录认证**：Spring Security + JWT，自定义认证过滤器，登录 / 登出 / 接口鉴权一体化
- **操作日志**：自定义 `@Log` 注解 + Spring AOP，标注在 Controller 方法上即自动记录增删改操作（异步落库）
- **登录日志**：登录成功 / 失败自动记录用户名、IP、归属地、浏览器
- **IP 归属地**：内置 ip2region 3.x 离线库（IPv4 + IPv6），无外部依赖
- **参数校验**：Bean Validation（`@Valid` + `@NotBlank` / `@NotNull`）+ 全局异常处理，统一返回友好提示
- **国际化**：vue-i18n 中文 / 英文切换

## 🛠 技术栈

### 后端 `yunshu-server`
| 类别 | 选型                                                |
|---|---------------------------------------------------|
| 框架 | Spring Boot 3.5.x / Java 21                       |
| 数据访问 | MyBatis（mybatis-spring-boot-starter）              |
| 安全 | Spring Security + JWT（jjwt）                       |
| 数据库 | MySQL 8 + Druid 连接池                               |
| 切面 | Spring AOP（操作日志，异步 `@Async`）                      |
| 工具 | Hutool、Commons Lang3 / Collections4、ip2region 3.x |

### 前端 `yunshu-web`
| 类别 | 选型 |
|---|---|
| 框架 | Vue 3 + Vite |
| 状态 | Pinia |
| UI | Element Plus |
| 国际化 | vue-i18n |
| 请求 | Axios |

## 📁 目录结构

```
YunShu
├── yunshu-server/                    后端服务
│   └── src/main/
│       ├── java/com/ys
│       │   ├── common/               公共模块
│       │   │   ├── annotation/       @Log 注解
│       │   │   ├── aspect/           LogAspect 操作日志切面
│       │   │   ├── config/           Security / Web 配置
│       │   │   ├── exception/        全局异常处理
│       │   │   ├── filter/           JWT 认证过滤器
│       │   │   └── utils/            IpUtil / IpRegion / JwtUtil / Result ...
│       │   └── modules/system/       业务模块（controller / service / mapper / domain）
│       │       └── 用户·角色·菜单·日志
│       └── resources/
│           ├── application.yml
│           ├── mapper/*.xml
│           └── banner.txt            启动 banner
├── yunshu-web/                       前端
│   └── src/{api,pages,components,store,router,lang}
├── db/yunshu.sql                     数据库初始化脚本
├── data/                             ip2region_v4.xdb / ip2region_v6.xdb（需自行下载）
└── README.md
```

## 🚀 快速开始

### 环境要求
JDK 21+ · Maven 3.6+ · Node.js 16+ · MySQL 8.x

### 1. 初始化数据库
创建数据库 `yunshu`，执行 `db/yunshu.sql`（含建表、索引、初始数据）。

### 2. 配置后端
修改 `yunshu-server/src/main/resources/application.yml`：
- 数据库连接（`url` / `username` / `password`）
- JWT `secret`、`expiration`（生产请务必更换密钥）

### 3. 启动后端

IDE 直接运行 YunshuServerApp

看到 `🚀 YunshuServerApp started successfully!` 即启动成功，服务端口 `12000`。

### 4. 启动前端
```bash
cd yunshu-web
npm install
npm run dev
```
浏览器访问 Vite 提示的地址（默认 `http://localhost:5173`）。

### 默认账号
| 角色 | 账号 | 密码 |
|---|---|---|
| 超级管理员 | admin | yunshu123 |
| 普通用户 | yunshu | yunshu123 |

## 📦 打包部署

```bash
# 后端：打包 jar
mvn -pl yunshu-server -am package
java -jar yunshu-server/target/*.jar

# 前端：打包 dist
cd yunshu-web && npm run build
# 将 dist/ 部署到 Nginx，或拷贝到后端 src/main/resources/static 做单体部署
```

## 📷 功能截图

![登录](yunshu-web/src/assets/images/img_1.png)
![首页](yunshu-web/src/assets/images/img_2.png)
![用户管理](yunshu-web/src/assets/images/img_3.png)
![角色管理](yunshu-web/src/assets/images/img_4.png)
![菜单管理](yunshu-web/src/assets/images/img_5.png)
![日志管理](yunshu-web/src/assets/images/img_6.png)

## 🤝 贡献

1. Fork 本仓库
2. 新建 `feat_xxx` 分支
3. 提交代码
4. 发起 Pull Request

## 📄 License

[MIT](LICENSE)