xuemz-admin V3.0.0

项目简介

xuemz-admin V3.0.0 是一套前后端分离的企业级后台管理系统，由 xuemz-vue-admin-v3 前端与 xuemz-springboot-admin-v3 后端配套组成，提供用户、角色、菜单的 RBAC 权限管理能力。

• 作者：xue_mz
• 前端默认端口：4000（开发服务器）
• 后端默认端口：26429
• 默认账号：admin / 123456（超级管理员 superAdmin）

功能特性

后端能力

• RBAC 权限模型：用户、角色、菜单三级关联，支持按角色分配菜单权限
• JWT 无状态认证：Spring Security + JWT，Token 缓存于 Redis，支持单点 / 多点登录控制
• 菜单树管理：菜单字段适配前端路由（path、component、icon、keepAlive 等）
• 统一响应封装：ReturnData 统一 API 返回格式，全局异常处理
• 数据库版本管理：Flyway 自动迁移 Schema，支持已有库 baseline 接入
• 代码生成器：基于 Velocity 模板，一键生成 Entity / Controller / Service / Mapper / PageDto
• 日志与脱敏：AOP 请求日志记录，敏感字段自动脱敏，支持按环境开关日志详情

前端能力

• RBAC 权限管理：用户管理、角色管理、菜单管理，与后端菜单树联动
• 动态路由：支持后端路由、前端路由过滤、静态路由三种模式，可在系统设置中切换
• JWT 认证：登录后 Token 持久化，Axios 自动携带 Authorization 请求头，Token 失效自动跳转登录
• 登录安全：图形验证码、登录失败次数限制与账号锁定（Mock / 后端均支持）
• 布局与交互：侧边栏菜单、面包屑、TagsView 多标签页、顶栏吸顶、菜单折叠
• 主题与国际化：亮色 / 暗色主题、主色调自定义、中英文切换（vue-i18n）
• 代码生成器页面：对接后端代码生成 API，可视化选择数据表并生成代码
• Mock 开发模式：内置 Mock 数据，无需启动后端即可独立开发前端

技术栈

层级	技术
前端框架	Vue 3.5、TypeScript 5.8、Vite 6
前端 UI	Element Plus 2.14、Pinia 3、Vue Router 4
前端工具	Axios、vue-i18n 11、ECharts 5、Vitest
后端框架	Java 17、Spring Boot 3.4.5
安全	Spring Security、JWT（jjwt 0.12.6）、BCrypt
持久层	MyBatis-Plus 3.5.11、MySQL、Flyway
缓存	Spring Data Redis（Lettuce 连接池）
代码生成	Velocity 模板引擎

仓库结构

前端 xuemz-vue-admin-v3

src/
├── api/           # 接口封装（用户、角色、菜单、代码生成）
├── axios/         # Axios 实例与拦截器
├── components/    # 公共组件（表格、主题、设置抽屉、面包屑等）
├── i18n/          # 国际化语言包（zh / en）
├── layout/        # 布局组件（侧边栏、顶栏、TagsView、Footer）
├── mock/          # Mock 数据与接口
├── permission.ts  # 路由守卫（Token 校验、动态路由注册）
├── router/        # 路由配置（静态路由 + 异步路由表）
├── stores/        # Pinia 状态（app、permission、setting、tagsView）
└── views/         # 页面视图（首页、登录、系统管理、代码生成）

后端 xuemz-springboot-admin-v3

src/main/java/cn/xuemz/
├── config/          # Security、Redis、MyBatis-Plus、Jackson 等
├── controller/      # 接口层
├── service/         # 业务层
├── mapper/          # 数据访问层
├── pojo/            # entity / dto / vo
├── security/        # JWT 过滤器、认证工具类
├── cache/redis/     # Redis 缓存封装
├── generator/       # 代码生成器
└── aop/             # 日志切面

src/main/resources/
├── application.yml              # 主配置
├── application-dev.yml          # 开发环境
├── application-prod.yml         # 生产环境
├── db/migration/                # Flyway 迁移脚本
└── velocity/                    # 代码生成模板（.vm）

环境要求

依赖	版本
Node.js	20+
pnpm	9+（推荐 10.x）
JDK	17+
Maven	3.6+
MySQL	5.7+ / 8.0+
Redis	5.0+

快速开始

1. 启动后端

git clone https://gitee.com/xue-mz/xuemz-springboot-admin-v3
cd xuemz-springboot-admin-v3

# 创建数据库
CREATE DATABASE xuemz_springboot_admin_v3
  DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

# 配置数据库、Redis、JWT（环境变量或 application-local.yml）
mvn spring-boot:run

后端启动后访问：http://localhost:26429

2. 启动前端

git clone https://gitee.com/xue-mz/xuemz-vue-admin-v3
cd xuemz-vue-admin-v3
pnpm install

方式一：Mock 模式（无需后端，快速体验）

pnpm dev:mock
# 访问 http://localhost:4000
# 账号 admin / 123456 或 test / 123456

方式二：联调后端（推荐日常开发）

pnpm dev
# Vite 将 /api 代理到 http://127.0.0.1:26429

3. 生产构建

# 前端
pnpm build

# 后端
mvn clean package -DskipTests
java -jar target/xuemz-springboot-admin-v3-V3.0.0.jar

核心数据表

表名	说明
sys_user	系统用户
sys_role	系统角色
sys_menu	系统菜单
sys_user_role	用户-角色关联
sys_role_menu	角色-菜单关联
sys_codegen_log	代码生成操作记录

Flyway 首次启动自动执行迁移脚本，初始化表结构与超级管理员账号。

前后端对接

统一响应格式：

{
  "code": "200",
  "msg": "成功",
  "data": {}
}

除登录外，所有请求需在 Header 中携带 Authorization: Bearer <jwt-token>。

模块	前缀	说明
用户	/sysUser	登录、登出、用户信息、用户分页
角色	/sysRole	角色列表、角色菜单关联
菜单	/sysMenu	菜单树、按 Token 获取菜单
代码生成	/codeGenerator	表列表、字段信息、代码生成

前端页面模块

模块	路径	说明
首页	/home/index	工作台首页
菜单管理	/manage/menu	菜单树增删改查
角色管理	/manage/roles	角色及菜单权限分配
用户管理	/manage/user	用户及角色关联管理
代码生成	/devtools/codegen	数据库表代码生成（需 superAdmin）

动态路由模式

模式	值	行为
后端路由	back-end（默认）	调用 /sysMenu/sysMenuTreeByToken 获取菜单树，动态注册路由
前端路由	front-end	根据用户角色过滤 asyncRouterMap 静态路由表
静态路由	none	直接使用 asyncRouterMap，不做权限过滤

生产部署

推荐将前端 dist/ 静态文件与后端 API 同域部署，Nginx 将 /api 反向代理到 Spring Boot 服务：

server {
    listen 80;
    server_name your-domain.com;
    root /path/to/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:26429/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

生产环境请保持 VITE_PROD_MOCK=N，并尽快修改默认密码与 JWT 密钥。

版本说明

版本	主要变化
V3.0.0	升级至 Java 17 + Spring Boot 3.4.5；Vue 3 + Vite 6 前端；Velocity 代码生成；Flyway baseline 支持
V2.0.0	Java 8 + Spring Boot 2.7.x 后端（见 xuemz-springboot-admin V2）

许可证

前后端项目均采用 MIT License 开源。