# cmdAdmin

**Repository Path**: cmdshare/cmdAdmin

## Basic Information

- **Project Name**: cmdAdmin
- **Description**: CmdAdmin 是基于SpringBoot4 和 Vue3 、JDK21、mysql/postgresql开发的企业级管理系统脚手架，采用前后端分离架构，集成 JWT 认证与Redis令牌管理，实现基于角色的细粒度权限控制和动态路由生成，内置用户、角色、菜单、部门等完整核心管理模块，为企业内部管理系统开发提供开箱即用的框架基础，大幅缩短项目搭建与开发周期。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 54
- **Forks**: 22
- **Created**: 2020-07-10
- **Last Updated**: 2026-02-09

## Categories & Tags

**Categories**: backend

**Tags**: springboot4, JPA, Postgresql, Vue, JWT

## README

# CmdAdmin - 企业级管理系统脚手架

<p align="center">
  <img src="https://img.shields.io/badge/Spring%20Boot-4.0.0-brightgreen" alt="Spring Boot">
  <img src="https://img.shields.io/badge/Vue-3.5-blue" alt="Vue">
  <img src="https://img.shields.io/badge/JDK-21-orange" alt="JDK">
  <img src="https://img.shields.io/badge/PostgreSQL-15+-blue" alt="PostgreSQL">
  <img src="https://img.shields.io/badge/MySQL-8+-blue" alt="MySQL">
  <img src="https://img.shields.io/badge/Redis-6+-red" alt="Redis">
  <img src="https://img.shields.io/badge/License-MIT-yellow" alt="License">
</p>

---

## 🚀 在线演示 & 文档

<table align="center">
  <tr>
    <td align="center" width="250">
      <h3>🌐 演示地址</h3>
      <a href="http://152.136.170.138/" target="_blank">
        <img src="https://img.shields.io/badge/点击访问-在线演示-blue?style=for-the-badge&logo=google-chrome" alt="在线演示">
      </a>
      <br><br>
      <code>http://152.136.170.138/</code>
    </td>
    <td align="center" width="250">
      <h3>📖 在线文档</h3>
      <a href="http://152.136.170.138/docs/" target="_blank">
        <img src="https://img.shields.io/badge/查看-在线文档-green?style=for-the-badge&logo=readthedocs" alt="在线文档">
      </a>
      <br><br>
      <code>http://152.136.170.138/docs/</code>
    </td>
    <td align="center" width="250">
      <h3>🔑 演示账号</h3>
      <table>
        <tr><td><b>账号</b></td><td>admin</td></tr>
        <tr><td><b>密码</b></td><td>admin123</td></tr>
        <tr><td><b>角色</b></td><td>超级管理员</td></tr>
      </table>
    </td>
  </tr>
</table>

> ⚠️ **提示**：演示环境已开启只读模式，部分操作可能受限。

---

<p align="center">
  <a href="#项目概述">项目概述</a> •
  <a href="#技术栈">技术栈</a> •
  <a href="#功能模块">功能模块</a> •
  <a href="#快速开始">快速开始</a>
</p>

---

## 项目概述

**CmdAdmin** 是一个基于 **Spring Boot 4** 和 **Vue 3** 的企业级管理系统脚手架，采用前后端分离架构设计，提供了完整的用户认证、权限管理、动态路由和菜单管理功能。系统界面美观、功能完善、易于扩展，适合作为企业级应用的基础框架。

### 核心特性

- 🚀 **最新技术栈**：Spring Boot 4 + Vue 3 + TypeScript
- 🔐 **安全认证**：JWT + Spring Security + Redis 分布式会话
- 🎨 **精美界面**：Element Plus + SCSS 现代化 UI 设计
- 📊 **数据可视化**：ECharts 图表展示
- ⏰ **定时任务**：Quartz 分布式任务调度
- 📝 **日志管理**：登录日志、操作日志、异常日志完整记录
- 🔧 **系统监控**：服务器监控、Redis 缓存监控
- 🌐 **前后端分离**：RESTful API 设计，支持跨域

---

## 技术栈

### 后端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| [Spring Boot](https://spring.io/projects/spring-boot) | 4.0.0 | 核心框架，提供自动配置和快速开发能力 |
| [JDK](https://openjdk.org/) | 21 | Java 开发工具包，使用最新 LTS 版本 |
| [Spring Data JPA](https://spring.io/projects/spring-data-jpa) | - | 数据持久层，简化数据库操作 |
| [Spring Security](https://spring.io/projects/spring-security) | - | 安全框架，提供认证和授权功能 |
| [Spring Boot Quartz](https://docs.spring.io/spring-boot/docs/current/reference/html/io.html#io.quartz) | - | 定时任务调度框架 |
| [Spring Boot Actuator](https://docs.spring.io/spring-boot/docs/current/reference/html/actuator.html) | - | 应用监控和管理端点 |
| [PostgreSQL](https://www.postgresql.org/) | 15+ | 关系型数据库，主数据存储 |
| [MySQL](https://www.mysql.com/) | 8+ | 关系型数据库，开发环境支持 |
| [Redis](https://redis.io/) | 6+ | 缓存数据库，会话存储和缓存 |
| [JWT (JSON Web Token)](https://jwt.io/) | 0.12.5 | 无状态身份认证机制 |
| [Fastjson2](https://github.com/alibaba/fastjson2) | 2.0.50 | 高性能 JSON 处理库 |
| [Lombok](https://projectlombok.org/) | - | 代码简化工具，减少样板代码 |
| [Maven](https://maven.apache.org/) | 3.8+ | 项目构建和依赖管理工具 |

### 前端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| [Vue](https://vuejs.org/) | 3.5.13 | 渐进式 JavaScript 框架 |
| [Vue Router](https://router.vuejs.org/) | 4.5.0 | 官方路由管理器，支持动态路由 |
| [Pinia](https://pinia.vuejs.org/) | 3.0.2 | 状态管理库，Vuex 的继任者 |
| [TypeScript](https://www.typescriptlang.org/) | 5.8.3 | 类型安全的 JavaScript 超集 |
| [Vite](https://vitejs.dev/) | 6.2.6 | 下一代前端构建工具，极速冷启动 |
| [Element Plus](https://element-plus.org/) | 2.9.7 | 基于 Vue 3 的组件库 |
| [Element Plus Icons](https://element-plus.org/en-US/component/icon.html) | 2.3.2 | 图标库 |
| [ECharts](https://echarts.apache.org/) | 5.6.0 | 开源可视化库，数据图表展示 |
| [SCSS](https://sass-lang.com/) | 1.86.3 | CSS 预处理器，支持变量和嵌套 |
| [unplugin-auto-import](https://github.com/unplugin/unplugin-auto-import) | 19.1.2 | 自动导入 API，无需手动 import |
| [unplugin-vue-components](https://github.com/unplugin/unplugin-vue-components) | 28.4.1 | 组件自动导入，支持 Element Plus 按需加载 |
| [WangEditor](https://www.wangeditor.com/) | 5.1.23 | 富文本编辑器 |
| [FormCreate](https://www.form-create.com/) | 3.4.0 | 表单设计器，支持可视化表单构建 |
| [SortableJS](https://sortablejs.github.io/Sortable/) | 1.15.6 | 拖拽排序库 |
| [LuckySheet](https://mengshukeji.github.io/Luckysheet/) | 2.1.13 | 在线电子表格，类似 Excel |
| [Monaco Editor](https://microsoft.github.io/monaco-editor/) | 0.55.1 | VS Code 同款代码编辑器 |
| [Vue Cropper](https://github.com/xyxiao001/vue-cropper) | 1.1.4 | 图片裁剪组件 |
| [SheetJS (xlsx)](https://sheetjs.com/) | 0.18.5 | Excel 文件读写库 |
| [FileSaver.js](https://github.com/eligrey/FileSaver.js) | 2.0.5 | 文件保存工具 |

---

## 功能模块

### 🔐 认证授权

- **JWT 认证**：基于 JWT 的无状态认证机制
- **Redis 会话**：登录令牌存储于 Redis，支持分布式部署
- **Token 刷新**：支持无感知续期，自动刷新过期令牌
- **多端登录控制**：支持限制同时登录设备数量

### 👥 系统管理

| 模块 | 功能说明 |
|------|----------|
| **用户管理** | 用户增删改查、状态管理、密码重置、批量导入导出 |
| **角色管理** | 角色增删改查、菜单权限分配、数据权限隔离 |
| **菜单管理** | 多级菜单嵌套、图标配置、动态路由生成、权限标识 |
| **部门管理** | 树形结构展示、部门负责人、数据权限隔离 |
| **岗位管理** | 岗位信息维护、编码管理、排序管理 |

### 🛠️ 系统工具

| 模块 | 功能说明 |
|------|----------|
| **字典管理** | 字典类型管理、字典数据维护、支持缓存刷新 |
| **参数管理** | 系统运行参数配置、运行时参数调整、参数缓存 |
| **通知公告** | 公告发布管理、公告类型设置、公告状态管理 |
| **定时任务** | Cron 表达式配置、任务调度、执行日志、暂停/恢复/立即执行 |

### 📊 系统监控

| 模块 | 功能说明 |
|------|----------|
| **服务器监控** | CPU 使用率、内存使用、磁盘空间、JVM 运行状态、系统负载 |
| **缓存监控** | Redis 连接状态、缓存 Key 列表、缓存命中率、缓存清理操作 |

### 📝 日志管理

| 模块 | 功能说明 |
|------|----------|
| **登录日志** | 登录信息记录、IP/地点/浏览器/OS、登录状态、条件查询 |
| **操作日志** | 操作行为记录、请求参数、操作结果、执行时长、异常信息 |
| **异常日志** | 系统异常捕获、异常堆栈信息、发生时间、请求信息 |

---

## 目录结构

```
cmdAdmin/
├── src/                          # 后端源代码
│   ├── main/
│   │   ├── java/                 # Java 源代码
│   │   │   └── com/
│   │   │       └── cmdadmin/
│   │   │           ├── CmdAdminApplication.java    # 应用启动类
│   │   │           ├── common/                     # 公共组件
│   │   │           │   ├── config/                 # 配置类
│   │   │           │   ├── filter/                 # 过滤器
│   │   │           │   ├── response/               # 统一响应格式
│   │   │           │   └── utils/                  # 工具类
│   │   │           └── system/                     # 系统模块
│   │   │               ├── controller/             # 控制器
│   │   │               ├── entity/                 # 实体类
│   │   │               ├── repository/             # 数据访问层
│   │   │               └── service/                # 业务逻辑层
│   │   └── resources/            # 资源文件
│   │       ├── db/               # 数据库脚本
│   │       ├── application.yml   # 应用配置
│   │       └── logback-spring.xml # 日志配置
│   └── test/                     # 测试代码
├── admin-web/                    # 前端代码
│   ├── src/
│   │   ├── api/                  # API 接口
│   │   ├── assets/               # 静态资源
│   │   ├── components/           # 公共组件
│   │   ├── directives/           # 自定义指令
│   │   ├── router/               # 路由配置
│   │   ├── services/             # 服务层（API 封装）
│   │   ├── stores/               # 状态管理（Pinia）
│   │   ├── views/                # 页面视图
│   │   └── App.vue               # 根组件
│   ├── package.json
│   └── vite.config.ts
├── docs/                         # 项目文档
├── pom.xml                       # Maven 配置
└── README.md                     # 项目说明文档
```

---

## 快速开始

### 环境要求

- **JDK**：21+
- **Maven**：3.8+
- **Node.js**：18+
- **PostgreSQL**：15+ 或 **MySQL**：8+
- **Redis**：6+

### 后端启动

#### 方式一：使用 PostgreSQL（推荐生产环境）

1. **创建数据库**

```sql
CREATE DATABASE cmdadmin WITH ENCODING = 'UTF8';
```

2. **修改配置文件**

编辑 `src/main/resources/application.yml`，激活 test 或 prod 配置：

```yaml
spring:
  profiles:
    active: test  # 或 prod
```

#### 方式二：使用 MySQL（开发环境）

1. **创建数据库**

```sql
CREATE DATABASE cmdadmin CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

2. **修改配置文件**

编辑 `src/main/resources/application.yml`，激活 dev 配置：

```yaml
spring:
  profiles:
    active: dev
```

MySQL 配置已预设，会自动加载 `application-dev.yml`

3. **启动后端服务**

```bash
# 方式一：使用 Maven
mvn spring-boot:run

# 方式二：打包后运行
mvn clean package
java -jar target/cmdAdmin-1.0-SNAPSHOT.jar
```

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

### 前端启动

1. **进入前端目录**

```bash
cd admin-web
```

2. **安装依赖**

```bash
npm install
```

3. **启动开发服务器**

```bash
npm run dev
```

前端开发服务器默认运行在 `http://localhost:5173`

4. **构建生产环境**

```bash
npm run build
```

---

## 配置说明

### JWT 配置

```yaml
jwt:
  secret: cmd_admin_secret_key_2024  # JWT 密钥
  expiration: 86400000  # 过期时间（毫秒），默认 24 小时
  refresh-expiration: 604800000  # 刷新令牌过期时间（毫秒），默认 7 天
  redis-key-prefix: "jwt:token:"  # Redis 中存储令牌的前缀
```

### 前端代理配置

在 `admin-web/vite.config.ts` 中配置：

```typescript
server: {
  port: 5173,
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, '')
    }
  }
}
```

---

## 前端组件使用说明

### 字典组件

系统内置字典组件，基于字典类型自动加载字典数据。

#### DictSelect - 字典下拉选择

```vue
<template>
  <DictSelect v-model="form.status" dictType="sys_user_status" />
</template>
```

#### DictRadio - 字典单选组

```vue
<template>
  <DictRadio v-model="form.status" dictType="sys_user_status" />
</template>
```

#### DictTag - 字典标签显示

```vue
<template>
  <DictTag :value="row.status" dictType="sys_user_status" />
</template>
```

### 权限指令

#### v-permission - 按钮级权限控制

```vue
<template>
  <el-button v-permission="'system:user:add'" type="primary">新增用户</el-button>
</template>
```

---

## 默认账号

| 账号 | 密码 | 角色 |
|------|------|------|
| admin | admin123 | 超级管理员 |
| test | test123 | 普通用户 |

---

## 更新日志

### 2025-02-04
- **优化组件映射**：使用 `import.meta.glob` 自动扫描视图组件，无需手动维护映射表
- **修复路由路径**：统一日志和监控模块的路由路径
- **修复警告**：解决 Element Plus 和 Vue 的弃用警告
- **清理日志**：删除项目中 95 处调试日志语句

### 2025-02-03
- **按钮级权限控制**：新增 `v-permission` 自定义指令
- **仪表盘改为静态路由**：默认每个人都有权限
- **修复角色权限树**：解决选中状态不更新问题
- **优化用户状态持久化**：刷新页面后用户信息不丢失

### 2025-01-20
- **新增个人中心页面**：支持修改个人信息、头像、密码
- **新增系统设置页面**：支持系统参数配置
- **优化动态路由加载**：修复浏览器刷新后动态路由丢失问题
- **新增字典组件**：DictSelect、DictRadio、DictTag

### 2025-01-10
- **新增定时任务管理**：支持 Cron 表达式配置、任务执行日志
- **新增服务器监控**：CPU、内存、磁盘、JVM 实时监控
- **新增缓存监控**：Redis 缓存监控和管理

### 2025-01-01
- **新增日志管理**：登录日志、操作日志、异常日志
- **新增岗位管理**：岗位信息维护和用户关联
- **新增参数管理**：系统运行参数配置
- **新增通知公告**：公告发布和管理

### v1.0.0 (2024-12)
- 初始版本发布
- 完成基础功能开发
- 用户、角色、菜单管理
- JWT 认证体系

---

## 开发规范

### 后端规范

1. **代码注释**：类和方法必须添加 JavaDoc 注释
2. **命名规范**：类名大驼峰，方法名小驼峰，常量全大写下划线
3. **异常处理**：业务异常使用自定义异常类，全局异常统一处理
4. **事务管理**：服务层方法添加 `@Transactional`

### 前端规范

1. **组件命名**：大驼峰命名，文件名与组件名一致
2. **组合式函数**：使用 Composition API，逻辑复用使用 Composables
3. **类型定义**：使用 TypeScript，定义接口类型，避免使用 any
4. **样式规范**：使用 SCSS，BEM 命名规范

---

## 部署说明

### 生产环境部署

1. **后端部署**

```bash
# 打包
mvn clean package -DskipTests

# 运行
nohup java -jar -Dspring.profiles.active=prod target/cmdAdmin-1.0-SNAPSHOT.jar > app.log 2>&1 &
```

2. **前端部署**

```bash
# 构建
npm run build

# 将 dist 目录部署到 Nginx
```

3. **Nginx 配置**

```nginx
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        root /path/to/admin-web/dist;
        index index.html;
        try_files $uri $uri/ /index.html;
    }
    
    location /api {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}
```

---

## 安全说明

1. **密码安全**：使用 BCrypt 加密存储，禁止明文传输
2. **接口安全**：JWT 令牌认证，接口权限控制
3. **数据安全**：SQL 注入防护（JPA 参数绑定），XSS 攻击防护

---

## 贡献指南

欢迎提交 Issue 和 Pull Request！

---

## 许可证

[MIT License](LICENSE)

---

<p align="center">
  如果这个项目对您有帮助，请给个 ⭐ Star 支持一下！
</p>