# qingyue

**Repository Path**: xiaopengyou/qingyue

## Basic Information

- **Project Name**: qingyue
- **Description**: QingYue 是一套基于 Spring Boot 4 和 Vue 3 的前后端分离单体管理系统，参考 Pig 与 RuoYi-Vue，保留常用后台管理能力，并重点优化移动端体验，适合个人及团队快速二次开发。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: PIG, ruoyi, qingyue, Spring, SpringBoot

## README



# 清越管理系统（QingYue）

清越是一个前后端分离的单体管理系统，后端基于 Spring Boot、Spring Security 和 MyBatis-Plus，前端基于 Vue 3、Element Plus、TypeScript 与 Vite。项目提供用户与权限管理、站点配置、消息中心、文件管理、任务调度、代码生成等通用后台能力，适合作为中后台系统的基础框架。

## 项目由来

我个人一直很喜欢若依和 Pig，尤其喜欢 Pig 的页面设计。Pig 以微服务架构为主，也提供 Boot 单体启动方式；但对个人二次开发而言，完整工程包含的模块较多，按自己的需求裁剪和维护仍显得偏重。

反复权衡后，我把个人常用的能力单独整理成了 QingYue：保留熟悉的后台管理体验，采用前后端分离、后端单体启动的方式，并针对手机访问持续优化页面布局、搜索、表格、弹窗和侧边面板。

QingYue 在整理过程中参考了以下优秀开源项目，感谢原作者和社区贡献者：
- [Pig](https://gitee.com/log4j/pig)
- [RuoYi-Vue](https://gitee.com/y_project/RuoYi-Vue)

## 为什么前后端放在同一个仓库

在 AI 辅助开发的加持下，我个人认为所有人都可以成为全栈开发者。把前端、后端、数据库脚本和说明文档放在同一个仓库，可以让开发者和 AI 同时看到一条完整的业务链路，减少接口修改时来回切换项目、同步版本和补充上下文的成本。

仓库统一管理不代表代码混在一起：`qingyue-api` 与 `qingyue-ui` 仍是两个边界清晰、可以独立启动和构建的项目，并分别提供自己的 README。

> 当前认证体系为 Spring Security + Redis 随机不透明令牌。本项目不再提供 OAuth2 授权服务器及 `/oauth2/token` 接口；微信、钉钉等第三方社交登录仍然保留。

## 技术栈

### 后端

| 技术 | 版本或用途 |
| --- | --- |
| Java | 17+，推荐使用 JDK 21 |
| Spring Boot | 4.1.0 |
| Spring Security | 无状态登录、接口鉴权、方法级权限 |
| MyBatis-Plus | 3.5.16，ORM、分页和数据权限 |
| MyBatis-Plus-Join | 多表关联查询 |
| Dynamic Datasource | 动态数据源 |
| MySQL | 默认业务数据库 |
| Redis | 登录会话、验证码、缓存和在线令牌 |
| Druid | 数据库连接池 |
| Quartz | 定时任务 |
| Hutool | 通用工具、HTTP、JSON、AES/SM4 |
| SMS4J / Jakarta Mail | 短信与邮件 |
| AWS SDK S3 | S3 兼容对象存储 |
| Fesod Sheet | Excel 导入导出 |

后端同时引入了 PostgreSQL、Oracle、SQL Server、DB2、达梦、人大金仓和瀚高等数据库驱动；默认配置使用 MySQL。

### 前端

| 技术 | 版本 |
| --- | --- |
| Vue | 3.5.40 |
| Vite | 8.1.5 |
| TypeScript | 4.9.5 |
| Element Plus | 2.13.7 |
| Pinia | 2.0.36 |
| Vue Router | 4.6.4 |
| Axios | 1.18.0 |
| ECharts | 5.6.0 |

## 主要功能

- **用户与权限管理**：用户、部门、岗位、角色、菜单和按钮权限管理，动态菜单路由、方法级权限和数据权限控制。
- **认证体系**：密码、短信验证码和第三方社交账号登录，Redis 登录令牌、刷新令牌、在线用户和强制下线。
- **验证码**：数学验证码、滑块拼图和点选文字等验证码模式。
- **安全防护**：`sk-` 内部 API Key，支持状态、过期时间和 IP 白名单；操作日志、账号锁定和密码有效期。
- **系统配置**：字典、公共参数、系统配置和站点配置。
- **消息中心**：站内信、短信、邮件和 Webhook 消息。
- **文件管理**：本地文件与 S3 兼容对象存储。
- **办公功能**：行政区域、日程和首页工作台。
- **定时任务**：Quartz 任务调度及执行日志。
- **系统监控**：Redis 运行信息监控。
- **开发工具**：数据源管理、字段类型配置、模板管理和代码生成。
- **其他特性**：Excel 导入导出、请求加密和 XSS 防护。

## 系统架构

```mermaid
flowchart LR
    Browser[Vue 3 管理端] -->|HTTP| API[Spring Boot API]

    subgraph Backend[qingyue-api]
        API --> Security[Spring Security]
        Security --> Token[Redis Token / API Key]
        Security --> Controller[业务 Controller]
        Controller --> Service[Service]
        Service --> Mapper[MyBatis-Plus Mapper]
        Controller --> Quartz[Quartz / 消息 / 文件 / 代码生成]
    end

    Token --> Redis[(Redis DB 6)]
    Mapper --> MySQL[(MySQL qingyue)]
    Quartz --> Storage[(本地文件或 S3)]
```

## 项目结构

```text
qingyue/
├── pom.xml                         Maven 父工程
├── qingyue-api/                    Spring Boot 单体后端
│   ├── src/main/java/com/qingyue/
│   │   ├── common/                 公共模型、常量和工具
│   │   ├── framework/              安全框架、数据源、日志切面
│   │   └── project/                系统管理(用户/部门/角色等)、监控、定时任务、代码生成
│   └── src/main/resources/         应用配置、Mapper XML、模板
├── qingyue-ui/                     Vue 3 管理端
│   ├── src/api/                    HTTP API
│   ├── src/components/             公共组件
│   ├── src/router/                 静态与动态路由
│   ├── src/stores/                 Pinia 状态
│   ├── src/utils/                  请求、加密和通用工具
│   └── src/views/                  登录页及业务页面
└── docs/
    └── sql/                        MySQL 初始化脚本
```

## 环境要求

- JDK 17 或更高版本，建议 JDK 21。
- Maven 3.6 或更高版本。
- Node.js `>= 20.19.0`。
- npm `>= 7.0.0`。
- MySQL 和 Redis。

默认本地端口：

| 服务 | 地址 |
| --- | --- |
| 后端 | `http://127.0.0.1:9999/admin` |
| 前端 | `http://127.0.0.1:8888` |
| MySQL | `127.0.0.1:3306/qingyue` |
| Redis | `127.0.0.1:6379`，数据库 `6` |

## 本地运行

### 1. 准备数据库和 Redis

创建名为 `qingyue` 的业务数据库，导入初始化脚本，并启动 Redis：

```bash
mysql -uroot -p -e "CREATE DATABASE qingyue DEFAULT CHARACTER SET utf8mb4;"
mysql -uroot -p qingyue < docs/sql/qingyue_2026-08-12.sql
```

默认数据库连接位于：
`qingyue-api/src/main/resources/application-dev.yml`

默认 Redis 配置位于：
`qingyue-api/src/main/resources/application-dev.yml`

生产环境使用 `application-prod.yml`，可通过 `--spring.profiles.active=prod` 切换。

> 生产环境不要继续使用仓库中的示例数据库密码、Jasypt 密码和前端加密密钥。

### 2. 启动后端

在项目根目录执行：

```bash
mvn -pl qingyue-api spring-boot:run
```

也可以进入后端目录运行：

```bash
cd qingyue-api
mvn spring-boot:run
```

启动类为：`com.qingyue.QingYueApplication`

### 3. 启动前端

```bash
cd qingyue-ui
npm ci
npm run dev
```

开发服务器默认监听 `8888` 端口，并将 `/api` 请求代理到 `http://127.0.0.1:9999`。

浏览器访问 `http://127.0.0.1:8888`，默认登录账号：

| 用户名 | 密码 |
| --- | --- |
| `admin` | `admin123` |

> 首次登录后请及时修改默认密码。

## 构建

### 后端

```bash
mvn clean package
```

跳过测试构建：

```bash
mvn clean package -DskipTests
```

构建产物：
`qingyue-api/target/qingyue-api.jar`

运行 JAR：
```bash
java -jar qingyue-api/target/qingyue-api.jar
```

### 前端

```bash
cd qingyue-ui
npm run build
```

构建产物位于 `qingyue-ui/dist/`。

## 登录与鉴权

### 登录接口

| 功能 | 接口 |
| --- | --- |
| 密码登录 | `POST /admin/login` |
| 短信登录 | `POST /admin/login/mobile` |
| 社交登录 | `POST /admin/login/social` |
| 刷新令牌 | `POST /admin/token/refresh` |
| 退出登录 | `DELETE /admin/token/logout` |
| 检查令牌 | `GET /admin/token/check_token` |

登录成功后返回兼容前端存储逻辑的字段：

```json
{
  "access_token": "访问令牌",
  "refresh_token": "刷新令牌",
  "token_type": "Bearer",
  "expires_in": 7200
}
```

访问受保护接口时携带：
```http
Authorization: Bearer <access_token>
```

### 内部 API Key

内部密钥以 `sk-` 开头。服务端只保存 SHA-256 摘要，明文仅在创建时返回一次。

API Key 与普通登录令牌共用 `Authorization: Bearer` 请求头，但会单独校验：
- 密钥状态
- 过期时间
- IP 白名单
- 密钥所属用户的账号状态和权限

### OAuth2 状态

本项目已经移除 Spring Authorization Server、OAuth2 客户端管理和 `/admin/oauth2/token`。已有旧 OAuth2 Token 不能迁移，需要重新登录。

第三方社交登录仍可能使用微信、钉钉等平台的 OAuth 授权流程；此时 QingYue 是外部平台的客户端，而不是 OAuth2 授权服务器。

## 关键配置

### 后端认证配置

```yaml
security:
  encodeKey: thanks,qingyue12
  token-timeout: 7200
  refresh-token-timeout: 2592000
  client:
    ignore-urls:
      - /code/**
      - /token/**
```

- `security.encodeKey`：登录密码 AES/SM4 解密密钥。
- `security.token-timeout`：访问令牌有效期，单位秒。
- `security.refresh-token-timeout`：刷新令牌有效期，单位秒。
- `security.client.ignore-urls`：无需登录即可访问的路径。

> **注意**：前端的 `VITE_PWD_ENC_KEY` 必须与后端登录密码解密密钥一致。

### 文件存储

默认使用本地文件：

```yaml
file:
  type: local
  local:
    base-path: ${user.dir}/data/files
```

将 `file.type` 改为 `oss` 并配置对应 S3 参数后，可以切换到 S3 兼容对象存储。

### 前端环境变量

主要配置位于 `qingyue-ui/.env` 和 `qingyue-ui/.env.development`：

| 变量 | 作用 |
| --- | --- |
| `VITE_API_URL` | 前端请求前缀 |
| `VITE_ADMIN_PROXY_PATH` | 本地开发代理目标 |
| `VITE_PWD_ENC_KEY` | 登录密码加密密钥 |
| `VITE_WEBSOCKET_ENABLE` | 是否启用 WebSocket 消息 |
| `VITE_REQUEST_TIMEOUT` | 请求超时时间 |
| `VITE_PORT` | 前端开发端口 |

## 开发约定

- 后端统一返回 `R<T>`，成功状态码为 `0`，失败状态码为 `1`。
- 后端应用上下文路径为 `/admin`。
- 前端 API 在开发环境通过 `/api` 代理访问后端。
- 权限使用 `@HasPermission`、`@PreAuthorize` 和 `@Inner` 控制。
- 普通业务接口默认需要认证；公开路径统一配置在 `security.client.ignore-urls`。
- **不要**把数据库密码、对象存储密钥、短信密钥和社交平台密钥提交到仓库。

## 测试与检查

后端：
```bash
mvn clean test
```

前端生产构建检查：
```bash
cd qingyue-ui
npm run build
```

前端 ESLint：
```bash
cd qingyue-ui
npm run lint:eslint
```

> 注意：当前 ESLint 脚本包含 `--fix`，执行时会直接修改源文件。

## 相关文档

- [后端项目 README](qingyue-api/README.md)
- [前端项目 README](qingyue-ui/README.md)
- [MySQL 初始化脚本](docs/sql/qingyue_2026-08-12.sql)

## 致谢

感谢 [Pig](https://gitee.com/log4j/pig) 与 [RuoYi-Vue](https://gitee.com/y_project/RuoYi-Vue) 提供的优秀设计、代码和开源社区。使用或分发本项目时，请同时遵守项目内代码及其上游依赖对应的开源许可证。

## 开源许可证

QingYue 根项目采用 [Apache License 2.0](LICENSE)。来源于第三方项目的代码、资源和依赖仍受各自原始许可证与版权声明约束；根目录许可证不会覆盖或移除这些声明。分发前请同时阅读 [NOTICE](NOTICE)。

Copyright 2026 mafei.