# cmdAdmin

**Repository Path**: cmdshare/cmdAdmin

## Basic Information

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

## Statistics

- **Stars**: 50
- **Forks**: 20
- **Created**: 2020-07-10
- **Last Updated**: 2026-02-01

## Categories & Tags

**Categories**: backend

**Tags**: None

## README

# 企业级管理系统脚手架

<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.0-blue" alt="Vue">
  <img src="https://img.shields.io/badge/JDK-21-orange" alt="JDK">
  <img src="https://img.shields.io/badge/PostgreSQL-18-blue" alt="PostgreSQL">
  <img src="https://img.shields.io/badge/License-MIT-yellow" alt="License">
</p>

## 项目概述

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

### 系统截图

#### 登录页面
简洁美观的登录界面，支持记住密码功能。

![登录页面]![输入图片说明](d7aa5bbc-a6f4-417b-a734-14ba7f924a10.png)

#### 系统首页
数据可视化仪表盘，展示关键业务指标和统计图表。

![系统首页]![输入图片说明](5df53385-0182-48ae-b2e4-cdff6f7eed1a.png)

#### 服务器监控
实时监控服务器运行状态，包括CPU、内存、磁盘、JVM等信息。

![服务器监控]![输入图片说明](7507eccd-514f-476f-ad20-49e988703a1f.png)

#### 操作日志
完整的操作日志记录，支持按模块、操作人员等条件查询。

![操作日志]![输入图片说明](04d91958-22a5-4e40-8e7e-834b176a8588.png)

#### 缓存监控
Redis缓存实时监控，支持查看缓存Key、过期时间等详细信息。

![缓存监控]![输入图片说明](f7bc8735-991d-4a8c-898b-02f0aa71d355.png)
## 技术栈

### 后端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 4.0.0 | 核心框架 |
| JDK | 21 | Java开发工具包 |
| Spring Data JPA | - | 数据持久层 |
| PostgreSQL | 18 | 关系型数据库 |
| Redis | - | 缓存数据库 |
| JWT | - | 身份认证 |
| Spring Security | - | 安全框架 |
| Maven | - | 项目构建工具 |

### 前端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.x | 前端框架 |
| Vite | - | 构建工具 |
| Vue Router | 4.x | 路由管理 |
| Pinia | - | 状态管理 |
| Element Plus | - | UI组件库 |
| TypeScript | - | 类型支持 |
| SCSS | - | CSS预处理器 |

## 目录结构

```
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/           # 公共组件
│   │   ├── router/               # 路由配置
│   │   ├── stores/               # 状态管理
│   │   ├── views/                # 页面视图
│   │   └── App.vue               # 根组件
│   ├── package.json
│   └── vite.config.ts
├── docs/                         # 文档和截图
│   └── images/                   # 项目截图
├── pom.xml                       # Maven 配置
└── README.md                     # 项目说明文档
```

## 核心功能

### 1. 用户认证
- 基于JWT的令牌认证机制
- 登录成功后将令牌存入Redis，支持分布式部署
- 每次请求自动验证令牌有效性
- 令牌过期自动刷新，无感知续期
- 支持多端登录控制

### 2. 权限管理
- 基于RBAC（角色基于访问控制）的权限模型
- 支持用户、角色、菜单三级权限分配
- 动态菜单生成，根据用户权限实时渲染
- 细粒度的按钮级权限控制
- 数据权限隔离（部门级别）

### 3. 系统管理

#### 用户管理
- 用户信息的增删改查
- 用户状态管理（启用/禁用）
- 密码重置功能
- 批量导入导出

#### 角色管理
- 角色信息的增删改查
- 角色权限分配（菜单权限）
- 角色状态管理

#### 菜单管理
- 菜单信息的增删改查
- 支持多级菜单嵌套
- 菜单图标、排序、权限标识配置
- 动态路由生成

#### 部门管理
- 部门信息的增删改查
- 树形结构展示
- 部门负责人设置

#### 岗位管理
- 岗位信息的增删改查
- 岗位编码、排序管理

### 4. 系统监控

#### 服务器监控
- CPU使用率监控
- 内存使用情况
- 磁盘空间监控
- JVM运行状态
- 系统负载监控

#### 缓存监控
- Redis连接状态
- 缓存Key列表
- 缓存命中率统计
- 缓存清理操作

### 5. 日志管理

#### 登录日志
- 记录用户登录信息
- 登录IP、地点、浏览器、操作系统
- 登录状态（成功/失败）
- 支持按条件查询和导出

#### 操作日志
- 记录用户操作行为
- 操作模块、请求方式、请求参数
- 操作结果、执行时长
- 异常信息记录

#### 异常日志
- 系统异常自动捕获
- 异常堆栈信息记录
- 异常发生时间、请求信息

### 6. 系统工具

#### 字典管理
- 字典类型管理
- 字典数据管理
- 支持缓存刷新

#### 参数管理
- 系统参数配置
- 运行时参数调整
- 参数缓存管理

#### 通知公告
- 公告发布管理
- 公告类型设置
- 公告状态管理

## 配置说明

### 数据库配置

在 `src/main/resources/application.yml` 中配置：

```yaml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/cmdadmin
    username: postgres
    password: 123456
    driver-class-name: org.postgresql.Driver
  jpa:
    hibernate:
      ddl-auto: update
    show-sql: true
```

### Redis配置

```yaml
spring:
  data:
    redis:
      host: localhost
      port: 6379
      password: 
      database: 0
      timeout: 6000ms
      lettuce:
        pool:
          max-active: 8
          max-wait: -1ms
          max-idle: 8
          min-idle: 0
```

### 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: 3000,
  proxy: {
    '/api': {
      target: 'http://localhost:8080',
      changeOrigin: true,
      rewrite: (path) => path.replace(/^\/api/, '')
    }
  }
}
```

## 启动步骤

### 环境要求

- JDK 21+
- Maven 3.8+
- Node.js 18+
- PostgreSQL 18+
- Redis 6+

### 后端启动

1. 创建数据库
```sql
CREATE DATABASE cmdadmin WITH ENCODING = 'UTF8';
```

2. 修改配置文件
编辑 `src/main/resources/application.yml`，配置数据库和Redis连接信息。

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:3000`

4. 构建生产环境
```bash
npm run build
```

## API接口文档

### 认证相关

#### 用户登录
- **URL**: `/api/auth/login`
- **Method**: `POST`
- **Content-Type**: `application/json`

**请求参数**:
```json
{
  "username": "admin",
  "password": "admin123"
}
```

**响应示例**:
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "userInfo": {
      "id": "1",
      "userName": "admin",
      "nickName": "管理员",
      "roles": ["admin"],
      "menus": []
    }
  }
}
```

#### 获取用户信息
- **URL**: `/api/auth/info`
- **Method**: `GET`
- **Header**: `Authorization: Bearer {token}`

**响应示例**:
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": "1",
    "userName": "admin",
    "nickName": "管理员",
    "roles": [],
    "menus": []
  }
}
```

#### 用户登出
- **URL**: `/api/auth/logout`
- **Method**: `POST`
- **Header**: `Authorization: Bearer {token}`

### 用户管理

#### 获取用户列表
- **URL**: `/api/system/user/list`
- **Method**: `GET`
- **Header**: `Authorization: Bearer {token}`

**请求参数**:
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 否 | 页码，从0开始 |
| size | int | 否 | 每页数量 |
| userName | string | 否 | 用户名 |
| nickName | string | 否 | 昵称 |
| status | string | 否 | 状态：0-启用，1-禁用 |

### 角色管理

#### 获取角色列表
- **URL**: `/api/system/role/list`
- **Method**: `GET`

#### 保存角色
- **URL**: `/api/system/role/save`
- **Method**: `POST`

### 菜单管理

#### 获取菜单列表
- **URL**: `/api/system/menu/list`
- **Method**: `GET`

#### 保存菜单
- **URL**: `/api/system/menu/save`
- **Method**: `POST`

## 核心组件说明

### JWT认证过滤器 (JwtAuthenticationFilter)

JWT认证过滤器用于验证请求中的JWT令牌，确保只有携带有效令牌的请求才能访问受保护的资源。

**主要功能**:
- 从请求头中提取JWT令牌
- 解析和验证令牌有效性
- 检查令牌是否在Redis中存在（支持分布式部署）
- 验证令牌一致性（防止令牌伪造）
- 设置用户认证信息到SecurityContext

**工作流程**:
1. 拦截所有请求
2. 从Authorization头中提取Bearer令牌
3. 验证令牌签名和过期时间
4. 查询Redis验证令牌有效性
5. 设置用户认证上下文
6. 放行请求或返回401

### Redis工具类 (RedisUtils)

Redis工具类封装了常用的Redis操作，提供类型安全的缓存操作。

**主要功能**:
- 字符串缓存操作（set/get）
- 哈希缓存操作（hset/hget）
- 列表缓存操作（lpush/rpop）
- 集合缓存操作（sadd/smembers）
- 有序集合操作（zadd/zrange）
- 缓存过期时间设置
- 缓存删除和批量删除

### 统一响应封装 (ApiResponse)

提供统一的API响应格式，确保前后端交互的一致性。

```java
public class ApiResponse<T> {
    private int code;        // 状态码：200-成功，其他-失败
    private String message;  // 提示信息
    private T data;          // 响应数据
    private long timestamp;  // 时间戳
}
```

## 前端架构

### 目录结构

```
src/
├── api/                    # API接口封装
│   ├── auth.ts            # 认证相关接口
│   └── system.ts          # 系统管理接口
├── assets/                 # 静态资源
│   ├── images/            # 图片资源
│   └── styles/            # 全局样式
├── components/             # 公共组件
│   ├── DictRadio.vue      # 字典单选组件
│   └── ...
├── router/                 # 路由配置
│   └── index.ts
├── services/               # 服务层
│   ├── modules/           # 各模块服务
│   │   ├── user.ts
│   │   ├── role.ts
│   │   └── ...
│   └── request.ts         # 请求封装
├── stores/                 # 状态管理（Pinia）
│   ├── auth.ts            # 认证状态
│   ├── system.ts          # 系统管理状态
│   └── app.ts             # 应用状态
├── views/                  # 页面视图
│   ├── login/             # 登录页面
│   ├── dashboard/         # 首页仪表盘
│   └── system/            # 系统管理页面
│       ├── user/
│       ├── role/
│       └── ...
├── App.vue
└── main.ts
```

### 状态管理

使用 Pinia 进行状态管理，主要 Store 包括：

#### Auth Store
管理用户认证状态，包括：
- 用户信息
- 登录状态
- Token管理
- 权限菜单

#### System Store
管理系统数据状态，包括：
- 用户列表
- 角色列表
- 菜单列表
- 部门列表
- 岗位列表
- 字典数据
- 参数配置
- 通知公告

### 请求封装

统一封装 Axios/Fetch 请求，提供：
- 统一错误处理
- 请求/响应拦截
- Token自动附加
- 401自动跳转登录

## 开发规范

### 后端规范

1. **代码注释**
   - 类和方法必须添加JavaDoc注释
   - 复杂逻辑添加行内注释
   - 接口文档使用Swagger注解

2. **命名规范**
   - 类名：大驼峰（UserService）
   - 方法名：小驼峰（getUserList）
   - 常量：全大写下划线（MAX_RETRY_COUNT）
   - 数据库表：小写下划线（sys_user）

3. **异常处理**
   - 业务异常使用自定义异常类
   - 全局异常统一处理
   - 异常信息记录到日志

4. **事务管理**
   - 服务层方法添加@Transactional
   - 查询操作设置readOnly=true
   - 合理设置事务传播行为

### 前端规范

1. **组件命名**
   - 大驼峰命名（UserManagement）
   - 文件名与组件名一致

2. **组合式函数**
   - 使用Composition API
   - 逻辑复用使用Composables

3. **类型定义**
   - 使用TypeScript
   - 定义接口类型
   - 避免使用any

4. **样式规范**
   - 使用SCSS
   - BEM命名规范
   - 避免深度选择器

## 安全说明

1. **密码安全**
   - 使用BCrypt加密存储
   - 禁止明文传输密码
   - 定期强制修改密码

2. **接口安全**
   - JWT令牌认证
   - 接口权限控制
   - 敏感操作二次确认

3. **数据安全**
   - SQL注入防护（使用JPA参数绑定）
   - XSS攻击防护（前端转义）
   - CSRF攻击防护

## 部署说明

### 生产环境部署

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;
    }
}
```

## 默认账号

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

## 更新日志

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

## 贡献指南

欢迎提交Issue和Pull Request！

## 许可证

[MIT License](LICENSE)

---

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