# QKL-Boot 企业级脚手架（Java+Vue+UniApp）

**Repository Path**: gzqkl/qkl-boot

## Basic Information

- **Project Name**: QKL-Boot 企业级脚手架（Java+Vue+UniApp）
- **Description**: QKL-Boot 企业级脚手架是一套企业级前后端脚手架 monorepo：后端 Spring Boot 3.5、管理端 Vue3 + Element Plus、移动端 UniApp。内置鉴权 RBAC、可裁剪业务模块、多云文件与通道能力，支持自托管部署。Apache 2.0 全量源码开放，无加密核心、无后门回传，适合二次开发与 Cursor 等 AI 工具快速落地业务。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 2
- **Created**: 2026-07-30
- **Last Updated**: 2026-08-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 脚手架, Java, Vue, uni-app

## README

# QKL-Boot 企业级脚手架（Java+Vue+UniApp）

[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
[![Java](https://img.shields.io/badge/Java-17-orange.svg)](./qkl-boot-java)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5-brightgreen.svg)](./qkl-boot-java)
[![Vue3](https://img.shields.io/badge/Admin-Vue3%20%2B%20Element%20Plus-42b883.svg)](./qkl-boot-admin)

企业级**低代码 / 脚手架** monorepo：后端可裁剪模块 + PC 管理端 + UniApp 移动端，适合**自托管部署**与**AI 工具二开**（Cursor 等，见 [二次开发指南](./docs/二次开发指南.md) / [AGENTS.md](./AGENTS.md)）。

> 维护：晴空蓝网络科技（Qingkonglan）· 协议：[Apache License 2.0](./LICENSE) · 第三方可免费使用

## 为什么选这套脚手架

- **源码全开源**：后端、Admin、UniApp 三仓完整可编译源码，无加密 Jar、无闭源核心、无「只给半成品」套路。
- **Apache 2.0**：个人与企业可免费使用、修改、二次开发与商用分发（请遵守 LICENSE / NOTICE，并自行核查第三方依赖许可证）。
- **没有后门**：不预置远程控制、不强制「电联授权」、不收集业务数据回传厂商；密钥与通道配置在你自己的服务器上。
- **数据在你手里**：默认自托管（MySQL / Redis / 对象存储），可内网部署、可按模块裁剪出厂。
- **可审计、可二开**：鉴权、权限、上传、支付回调等关键路径均可对照源码审查；配套 [AGENTS.md](./AGENTS.md) / Cursor Skill，适合用 AI 工具快速落地业务。

## 界面预览

更多截图见 [`docs/screenshots/`](./docs/screenshots/)。

### 管理端（Admin）

![工作台](./docs/screenshots/admin-workbench.png)

![用户管理](./docs/screenshots/admin-user.png)

![多云文件存储](./docs/screenshots/admin-file-storage.png)

![AI 模型配置](./docs/screenshots/admin-ai-model.png)

![消息触达场景](./docs/screenshots/admin-notify-scene.png)

![操作日志](./docs/screenshots/admin-oper-log.png)

### 移动端（UniApp）

<p>
  <img src="./docs/screenshots/uniapp-home.png" width="220" alt="移动端首页" />
  <img src="./docs/screenshots/uniapp-message.png" width="220" alt="消息中心" />
  <img src="./docs/screenshots/uniapp-my.png" width="220" alt="我的" />
</p>

<p>
  <img src="./docs/screenshots/uniapp-ai-chat.png" width="220" alt="智能客服" />
  <img src="./docs/screenshots/uniapp-ocr.png" width="220" alt="OCR 识别" />
  <img src="./docs/screenshots/uniapp-tab-list.png" width="220" alt="列表模板" />
</p>

## 特性

- **鉴权与 RBAC**：JWT + Redis 会话、双端隔离（`/admin` · `/mobile` · `/open`）、密码策略与登录锁定可配
- **可裁剪模块**：demo / ai / finance / print / notify / channel（配置关 · Maven Profile · Liquibase contexts）
- **文件与通道**：本地 / OSS / MinIO / 腾讯云 COS / 华为云 OBS / 七牛等；短信邮件地图等通道可配
- **低代码**：Online 单表 CRUD、代码生成；支付 / AI / 打印等可裁剪模块
- **部署友好**：Docker Compose、备份脚本、[发行包模板](./delivery/README.md)、强制改密与生产密钥门禁

## 仓库结构

| 目录 | 说明 |
| --- | --- |
| [qkl-boot-java](./qkl-boot-java/) | 后端（Spring Boot 3.5 / JDK 17 / Maven 多模块） |
| [qkl-boot-admin](./qkl-boot-admin/) | 管理后台（Vue3 + Element Plus + Vite） |
| [qkl-boot-uniapp](./qkl-boot-uniapp/) | C 端（UniApp3） |
| [docs](./docs/) | 开源文档中心（使用者手册 + 贡献者材料） |
| [delivery](./delivery/) | 发行包 / 部署包模板（组装产物在 `delivery/out/`，不入库） |

## 技术架构

### 总体架构

三仓 **monorepo**，**唯一后端** `qkl-bootstrap` 对外提供三类前缀，管理端与移动端严格隔离：

```text
浏览器 / 小程序
    │
    ├─ Admin（5173） ──► /admin/**  ──┐
    │                                 │
    └─ UniApp（5174 / 微信）─► /mobile/** ─┼─► qkl-bootstrap :8080
                                          │
第三方回调 / 支付 ──────────► /open/** ──┘
                                          │
                    MySQL 8 · Redis 7 · 本地/对象存储
```

| 端 | 技术定位 | 默认端口 | 只允许调用 |
| --- | --- | --- | --- |
| `qkl-boot-java` | 业务与鉴权唯一入口 | **8080** | — |
| `qkl-boot-admin` | B 端 RBAC 管理后台 | **5173** | `/admin/**` |
| `qkl-boot-uniapp` | C 端（H5 / 微信小程序 / App） | H5 **5174** | `/mobile/**` |

开放回调、支付通知等挂在 `/open/**`，不要挂到 admin / mobile。

### 后端（qkl-boot-java）

| 项 | 版本 / 选型 |
| --- | --- |
| 语言 | **JDK 17**（`maven.compiler.release=17`） |
| 框架 | **Spring Boot 3.5.16** |
| ORM | **MyBatis-Plus 3.5.14** |
| 迁移 | Liquibase（`classpath:db/master.yaml`） |
| 缓存 / 会话 | Redis + JWT（jjwt **0.12.6**） |
| API 文档 | springdoc **2.8.9** + Knife4j **4.5.0**（开发可开） |
| 工具 | Hutool **5.8.34** · EasyExcel **4.0.3** · MapStruct **1.6.3** |
| 支付 SDK | 微信支付 **0.2.17** · 支付宝 **4.39.218.ALL**（`qkl-finance`） |
| 定时任务 | 内嵌 Quartz（后台可配） |
| 打包 | Maven 多模块；启动模块 **`qkl-bootstrap`** 单 Jar |

Maven 模块划分：

| 模块 | 职责 |
| --- | --- |
| `qkl-common` | 公共组件、文件 SPI、统一返回等 |
| `qkl-system-api` | 系统域 API / 跨模块契约 |
| `qkl-system` | 鉴权、RBAC、组织、站点、Online/代码生成等内核 |
| `qkl-channel` | 短信 / 邮件 / 地图等通道 |
| `qkl-notify` | 统一消息触达、订阅模板 |
| `qkl-demo` | 演示样板（可裁剪） |
| `qkl-ai` | 对话 / 知识库 / OCR / 工作流（可裁剪） |
| `qkl-finance` | 微信支付 / 支付宝（可裁剪） |
| `qkl-print` | 打印相关（可裁剪） |
| `qkl-bootstrap` | 启动与装配入口 |

可选模块通过 `qkl.*.enable`、Maven Profile（如 `-Pno-demo,no-ai`）、`LIQUIBASE_CONTEXTS` 三级裁剪，详见 [二次开发指南](./docs/二次开发指南.md)。

### 管理端（qkl-boot-admin）

| 项 | 版本 / 选型 |
| --- | --- |
| 框架 | **Vue 3.5.x** |
| UI | **Element Plus 2.9.x** + `@element-plus/icons-vue` |
| 构建 | **Vite 6.x** · TypeScript **5.6.x** · `vue-tsc` |
| 状态 / 路由 | Pinia **2.3.x** · Vue Router **4.5.x** |
| 请求 | Axios **1.7.x**（统一 `@/utils/request`，成功 `code === 200`） |
| 其它 | ECharts **6.x** · vue-i18n · wangEditor（富文本） |

开发代理：`.env.development` 中 `VITE_PROXY_TARGET` → 后端 `8080`，前端只请求 `/admin/**`。

### 移动端（qkl-boot-uniapp）

| 项 | 版本 / 选型 |
| --- | --- |
| 框架 | **UniApp 3**（`@dcloudio/*` `3.0.0-4080420251103001`） |
| Vue | **Vue 3.4.x** |
| UI | **uview-plus 3.3.x** |
| 构建 | **Vite 5.2.8** · TypeScript **4.9.x** |
| 状态 | Pinia **2.1.7** |
| 其它 | dayjs · mescroll-uni · clipboard 等 |

业务页强制放在 `src/subpackages/{domain}/`；主包仅基座（首页 / 消息 / 我的 / 登录等）。仅请求 `/mobile/**`。

### 基础设施

| 组件 | 版本 | 说明 |
| --- | --- | --- |
| MySQL | **8.0.x** | 业务库；Compose 镜像 `mysql:8.0` |
| Redis | **7.x** | 会话、缓存、限流等 |
| 对象存储 | 本地 / 阿里云 OSS / MinIO / 腾讯云 COS / 华为云 OBS / 七牛 | 后台「文件中心」热切换 |
| Docker（可选） | 20+ | `qkl-boot-java/docker compose up -d` 起 MySQL + Redis |

---

## 开发环境要求

### 必备软件

| 软件 | 最低 / 建议版本 | 用途 |
| --- | --- | --- |
| **JDK** | **17**（必须；勿用 8/11） | 编译与运行后端 |
| **Maven** | **3.9+** 建议 | 多模块构建；仓库自带 `.mvn/settings.xml` |
| **Node.js** | **18+**（建议 **20 LTS**） | Admin / UniApp |
| **pnpm** | **9+** | 前端包管理（推荐；亦可用 npm，但文档以 pnpm 为准） |
| **MySQL** | **8.0.x** | 本地库或 Docker |
| **Redis** | **7.x** | 本地或 Docker |
| **Git** | 2.x | 拉取与提交 |

### 推荐开发工具

| 用途 | 推荐 |
| --- | --- |
| 后端 | IntelliJ IDEA 2023+ / VS Code + Java 扩展；运行入口 `QklBootApplication` 或 `mvn -pl qkl-bootstrap` |
| Admin | VS Code / Cursor + Vue / Volar |
| UniApp H5 | 同前端 IDE，`pnpm dev:h5` |
| 微信小程序 | 微信开发者工具；`pnpm dev:mp-weixin` 后导入 `dist/dev/mp-weixin`（以实际输出目录为准） |
| AI 二开 | Cursor（仓库已含 `AGENTS.md`、`.cursor/rules`、`.cursor/skills`） |

### 本机端口（勿冲突）

| 端口 | 服务 |
| --- | --- |
| 3306 | MySQL |
| 6379 | Redis |
| 8080 | 后端 |
| 5173 | Admin Vite |
| 5174 | UniApp H5 |

### 操作系统与其它说明

- **Windows 10/11、macOS、Linux** 均可开发；路径与脚本注意 PowerShell / Bash 差异。
- 首次后端启动由 **Liquibase** 自动建表迁移，**不要**手工灌全量 SQL。
- 真实 `.env`、密钥、证书勿提交 Git；复制 `qkl-boot-java/.env.example` 为 `.env` 后按本机修改。
- 微信小程序真机 / 正式环境需配置合法域名、AppId；本地可关 `urlCheck` 调试（上线前须打开）。
- 生产部署另见 [生产部署与运维手册](./docs/QKL-Boot-生产部署与运维手册.md)、[宝塔部署](./docs/QKL-Boot-宝塔部署手册.md)。

版本号以仓库锁定文件为准：后端见 `qkl-boot-java/pom.xml`；Admin / UniApp 见各自 `package.json`。

## 快速开始

### 1. 后端

```bash
cd qkl-boot-java
cp .env.example .env          # 按需改库账号；勿提交真实 .env
docker compose up -d          # MySQL8 + Redis7
mvn -pl qkl-bootstrap -am spring-boot:run -s .mvn/settings.xml
```

- 健康检查：`http://localhost:8080/actuator/health`
- 接口文档（开发）：`http://localhost:8080/doc.html`
- 超管：`admin`；未设 `ADMIN_SEED_PASSWORD` 时临时密码在**启动日志**，登录后须强制改密

精简打包示例：

```bash
mvn -pl qkl-bootstrap -am package -Pno-demo,no-ai -DskipTests
```

### 2. 管理端

```bash
cd qkl-boot-admin
pnpm install
pnpm dev                      # http://localhost:5173 ，代理 /admin → 8080
```

### 3. 移动端

```bash
cd qkl-boot-uniapp
pnpm install
pnpm dev:h5                   # http://localhost:5174 ，代理 /mobile → 8080
# 联调账号示例：user / user1234（以种子为准）
pnpm dev:mp-weixin
```

更完整的联调清单：[三仓联调一页纸](./docs/三仓联调一页纸.md)。

## 文档

| 文档 | 说明 |
| --- | --- |
| [文档中心](./docs/README.md) | 开源使用者手册索引 |
| [功能介绍](./docs/QKL-Boot功能介绍.md) | 已有能力总览 |
| [二次开发指南](./docs/二次开发指南.md) | **AI 工具二开**（提示词 / 样板 / 检查清单） |
| [AGENTS.md](./AGENTS.md) | AI Agent 硬约束 |
| [生产部署与运维](./docs/QKL-Boot-生产部署与运维手册.md) | 自托管部署 / 运维 / 密钥 |
| [宝塔部署](./docs/QKL-Boot-宝塔部署手册.md) | 宝塔面板专项 |
| [CHANGELOG](./CHANGELOG.md) | 发版说明（tag `qkl-boot-v1.0.0`） |
| [CONTRIBUTING](./CONTRIBUTING.md) | 如何贡献 |
| [SECURITY](./SECURITY.md) | 安全漏洞报告 |

## 发行包组装（可选）

```powershell
# 仓库根目录
.\scripts\package-delivery.ps1
# 产物：delivery/out/qkl-boot-vX.Y.Z/
```

## 使用说明

- 需自备 MySQL / Redis 与密钥；生产请用 `prod` profile  
- 支付 / 短信 / 地图 / 微信等需在后台填写真实厂商配置后方可联调  
- 模块裁剪见 [二次开发指南](./docs/二次开发指南.md)  

## 安全提示

生产环境请使用 `prod` profile，替换全部默认密钥，关闭 Mock 与测试旁路。详见 [SECURITY.md](./SECURITY.md) 与 [生产部署与运维手册](./docs/QKL-Boot-生产部署与运维手册.md)。

## 许可证

本项目采用 [Apache License 2.0](./LICENSE) 开源。版权声明见 [NOTICE](./NOTICE)。

第三方依赖各自保留其许可证；二次分发前请自行核查。