# zpw-boot

**Repository Path**: PaperHouse/zpw-boot

## Basic Information

- **Project Name**: zpw-boot
- **Description**: 基于 Spring Boot 3 + Vue 3 的企业级后台管理系统，采用单体架构设计。技术栈：
后端： Spring Boot 3、Spring Security、MyBatis、Druid、Redis
前端： Vue 3、Vite、TypeScript
模块划分： 多模块 Maven 项目，包含系统管理、代码生成器、业务模块等
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-03-15
- **Last Updated**: 2026-05-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ZPW Boot

基于 Spring Boot 3 + Vue 3 的前后端分离企业级快速开发平台

## 项目简介

ZPW Boot 是一个现代化的企业级快速开发平台，采用前后端分离的单体架构，集成了用户管理、角色权限、部门管理、租户管理、系统监控、代码生成等核心功能，支持多租户 SaaS 模式，适用于各类管理系统的快速开发。

## 技术栈

### 后端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 3.2.12 | 核心框架 |
| Spring Security | 6.x | 安全认证与授权 |
| MyBatis-Plus | 3.5.7 | ORM 框架 |
| Dynamic Datasource | 4.3.1 | 动态多数据源 |
| Druid | 1.2.24 | 数据库连接池 |
| Redis + Lettuce | - | 缓存与会话管理 |
| JWT (jjwt) | 0.12.3 | 身份认证 |
| Hutool | 5.8.11 | 工具类库 |
| FastJSON2 | 2.0.50 | JSON 解析 |
| EasyPOI | 4.1.0 | Excel 导入导出 |
| FreeMarker | 2.3.31 | 代码生成模板引擎 |
| Springdoc OpenAPI | 2.6.0 | 接口文档 |
| Undertow | - | Web 容器 |
| MySQL | 8.0.33 | 关系型数据库 |
| Guava | 32.1.3-jre | Google 工具库 |
| OSHI | 6.4.13 | 系统监控 |

### 前端技术

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.4.x | 前端框架 |
| TypeScript | 5.4.x | 类型安全 |
| Vite | 5.1.x | 构建工具 |
| Element Plus | 2.9.x | UI 组件库 |
| Pinia | 2.1.x | 状态管理 |
| Vue Router | 4.3.x | 路由管理 |
| Axios | 1.6.x | HTTP 请求 |
| ECharts | 5.5.x | 数据图表 |
| WangEditor | 5.1.x | 富文本编辑器 |
| Vue I18n | 9.10.x | 国际化 |

## 项目结构

```
zpw-boot
├── zpw-server                  # 服务端启动模块（聚合所有业务模块）
├── zpw-auth                    # 认证授权模块（登录、验证码、JWT）
├── zpw-base                    # 基础设施模块
│   ├── zpw-base-core           # 核心工具类（统一返回、异常处理、通用工具）
│   ├── zpw-base-datasource     # 数据源配置（动态数据源、Druid）
│   ├── zpw-base-security       # 安全模块（Spring Security、JWT 过滤器）
│   ├── zpw-base-redis          # Redis 封装（缓存、分布式锁）
│   ├── zpw-base-log            # 日志模块（操作日志、登录日志）
│   ├── zpw-base-web            # Web 通用封装（拦截器、过滤器）
│   ├── zpw-base-dict           # 字典模块（字典翻译）
│   └── zpw-base-excel          # Excel 模块（EasyPOI 导入导出）
├── zpw-module-system           # 系统管理模块
│   ├── zpw-system-api          # 系统管理 API 接口定义
│   └── zpw-system-biz          # 系统管理业务实现
├── zpw-module-admin            # 后台管理模块（监控相关）
│   ├── zpw-admin-api           # 管理 API 接口定义
│   └── zpw-admin-biz           # 管理业务实现
├── zpw-module-business         # 业务模块（自定义业务逻辑）
│   ├── zpw-business-api        # 业务 API 接口定义
│   └── zpw-business-biz        # 业务实现
├── zpw-module-generator        # 代码生成器（前后端代码一键生成）
├── ui/pc                       # 前端项目（Vue 3 + Element Plus）
└── db                          # 数据库脚本
    ├── zpw-boot.sql            # 主库初始化脚本
    └── tenant_init.sql         # 租户初始化脚本
```

## 核心功能

### 系统管理

- **用户管理**：用户增删改查、密码重置、状态管理、个人资料
- **角色管理**：角色分配、权限绑定、数据权限
- **部门管理**：树形部门结构、部门权限
- **岗位管理**：岗位定义与分配
- **菜单管理**：动态路由、按钮权限、菜单数据权限
- **字典管理**：系统字典、字典项管理
- **参数管理**：系统参数配置
- **通知公告**：系统公告发布

### 多租户

- **租户管理**：租户增删改查、状态控制
- **租户套餐**：套餐定义、菜单权限绑定
- **数据隔离**：基于 tenant_id 的数据隔离机制

### 系统监控

- **在线用户**：实时在线用户查看、强制下线
- **服务监控**：CPU、内存、磁盘等系统资源监控
- **缓存监控**：Redis 缓存使用情况监控
- **数据监控**：Druid 数据源连接池监控

### 日志管理

- **操作日志**：用户操作记录自动采集
- **登录日志**：登录信息记录与审计

### 开发工具

- **代码生成**：基于数据库表结构，一键生成前后端 CRUD 代码（支持单表、主子表）
- **接口文档**：集成 Springdoc OpenAPI，自动生成接口文档

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.8+
- MySQL 8.0+
- Redis 6.0+
- Node.js 16+（推荐 18+）
- pnpm（推荐）

### 后端启动

1. 创建数据库并导入脚本

```sql
-- 创建数据库
CREATE DATABASE `zpw-boot` DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

-- 导入主库数据
source db/zpw-boot.sql;
```

2. 修改配置文件

编辑 `zpw-server/src/main/resources/application-dev.yml`：

```yaml
spring:
  datasource:
    dynamic:
      datasource:
        master:
          url: jdbc:mysql://127.0.0.1:3306/zpw-boot?characterEncoding=UTF-8&useUnicode=true&useSSL=false&tinyInt1isBit=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai
          username: root
          password: your_password
  redis:
    host: localhost
    port: 6379
```

3. 编译并启动

```bash
# 编译
mvn clean install -DskipTests

# 启动
mvn spring-boot:run -pl zpw-server
```

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

### 前端启动

```bash
cd ui/pc

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev
```

前端默认运行在 `http://localhost:8888`

### 访问系统

- 前端地址：http://localhost:8888
- 后端 API：http://localhost:8090/api
- 接口文档：http://localhost:8090/api/doc.html
- Druid 监控：http://localhost:8090/api/druid/index.html（账号：admin，密码：123456）

默认管理员账号：`admin` / `admin123`

## 配置说明

### 数据库配置

支持动态多数据源，可在 `application-dev.yml` 中配置：

```yaml
spring:
  datasource:
    dynamic:
      primary: master
      strict: false
      datasource:
        master:
          url: jdbc:mysql://127.0.0.1:3306/zpw-boot
          username: root
          password: 123456
          driver-class-name: com.mysql.cj.jdbc.Driver
```

### 安全配置

白名单配置在 `zpw-server/src/main/resources/application.yml` 中：

```yaml
zpw:
  security:
    client:
      ignores:
        pattern:
          - /actuator/**
          - /druid/**
          - /doc.html
          - /v3/api-docs/**
        get:
          - /auth/captchaImage
        post:
          - /auth/login
          - /auth/register
          - /auth/logout
```

### 租户配置

可配置不需要租户隔离的表：

```yaml
zpw:
  tenant:
    ignore-tables:
      - sys_tenant
      - sys_tenant_package
      - sys_menu
      - sys_config
```

### 文件上传

支持本地存储、MinIO、阿里云 OSS：

```yaml
zpw:
  uploadType: minio  # local / minio / alioss
  path:
    upload: /opt/upFiles
```

### JWT 配置

```yaml
jwt:
  config:
    key: zpwxyzzpwxyzzpwxyzzpwxyzzpwxyzzpwxyz  # 签名密钥
    ttl: 7200000       # Token 有效期（2小时）
    remember: 604800000  # 记住我有效期（7天）
```

## 模块依赖关系

```
zpw-server（启动入口）
├── zpw-auth（认证授权）
│   ├── zpw-base-core
│   ├── zpw-base-web
│   ├── zpw-base-redis
│   └── zpw-base-security
├── zpw-system-biz（系统管理）
│   ├── zpw-system-api
│   ├── zpw-base-core
│   ├── zpw-base-datasource
│   ├── zpw-base-redis
│   ├── zpw-base-security
│   ├── zpw-base-log
│   ├── zpw-base-dict
│   ├── zpw-base-excel
│   └── zpw-base-web
├── zpw-admin-biz（后台管理/监控）
├── zpw-business-biz（业务模块）
└── zpw-module-generator（代码生成器）
```

## 开发规范

- 代码遵循阿里巴巴 Java 开发手册
- RESTful API 设计规范
- 统一返回结果封装（Result）
- 统一异常处理（GlobalExceptionHandler）
- 操作日志自动记录（AOP 注解驱动）
- 基于注解的数据权限控制
- 前后端统一的分页查询规范

## 代码生成器

支持根据数据库表结构一键生成以下代码：

- **后端**：Entity、Mapper、MapperXML、Service、ServiceImpl、Controller
- **前端**：API 接口文件、列表页面（含搜索、分页、导入导出）、新增/编辑弹窗
- **SQL**：菜单初始化 SQL 脚本
- **支持模式**：单表 CRUD、主子表（一对多）

## 许可证

[MIT License](LICENSE)

## 联系方式

如有问题或建议，欢迎提交 Issue 或 Pull Request。