# vue3-template-server

**Repository Path**: lyDevelop/vue3-template-server

## Basic Information

- **Project Name**: vue3-template-server
- **Description**: 基于 JDK17、SpringBoot3、Spring Security 6、JWT、Redis、Mybatis-Plus、Knife4j、Vue 3、Element-Plus 构建的前后端分离单体权限管理系统。
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 10
- **Forks**: 8
- **Created**: 2024-04-14
- **Last Updated**: 2026-09-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: SpringBoot

## README

# Vue3 Template Server

基于 Java 17 和 Spring Boot 3 的后台管理服务端，提供 JWT 认证、RBAC 权限、部门/个人数据范围、用户与菜单管理、MinIO 文件存储、Excel 导入导出和 OnlyOffice 在线编辑能力。

本仓库只包含服务端代码；Vue 3、Element Plus 前端需单独部署。

## 技术栈

| 分类 | 技术与版本 |
| --- | --- |
| 运行环境 | Java 17、Spring Boot 3.2.4 |
| 安全 | Spring Security 6、JWT、BCrypt |
| 数据访问 | MyBatis-Plus 3.5.5、MySQL 8、Flyway |
| 缓存 | Redis |
| 文件与文档 | MinIO Java SDK 8.5.2、OnlyOffice Document Server |
| 导入导出 | EasyExcel 3.2.1 |
| API 文档 | Springdoc OpenAPI、Knife4j |
| 测试 | JUnit 5、Spring Test、H2 |

## 主要功能

- 用户、角色、菜单、部门和字典管理。
- JWT 无状态认证；每次请求从服务端重新加载有效角色、权限、部门和数据范围。
- RBAC 操作权限与数据范围同时校验，支持 `ALL`、`DEPT_AND_SUB`、`DEPT`、`SELF`。
- MinIO 文件上传、列表、下载、批量下载和删除；新文件对象键包含部门与上传者归属。
- Excel 用户模板下载、批量导入与导出；导入保持整批事务原子性。
- OnlyOffice 查看、编辑、强制保存及最终保存，回调使用 JWT 和对象绑定凭证双重校验。
- Flyway 增量迁移、OpenAPI/Knife4j 在线接口文档。

## 项目结构

```text
src/main/java/org/example/system
├── config/             Spring、MyBatis-Plus、OnlyOffice 等配置
├── controller/         REST API
├── mapper/             MyBatis Mapper 接口
├── plugin/             数据权限、EasyExcel 等扩展
├── security/           认证、授权和文件访问边界
└── service/            业务服务
src/main/resources
├── db/migration/       Flyway 增量 SQL
├── mapper/             MyBatis XML
├── application.yml     公共配置与默认 dev profile
├── application-dev.yml 本地开发配置
└── application-prod.yml Docker/生产 profile 示例
sql/vue3_database.sql   空数据库首次初始化脚本
```

## 环境要求

- JDK 17
- Maven 3.9+
- MySQL 8.x
- Redis 6.x 或更高版本
- MinIO
- OnlyOffice Document Server（仅在线文档功能需要）

不要把真实数据库密码、JWT 密钥、MinIO 凭证或 OnlyOffice 密钥提交到仓库。生产环境应通过环境变量或外部配置文件覆盖示例值。

## 快速启动

### 1. 初始化基础设施

仓库中的 `docker-compose.yml` 包含应用、MySQL、Redis、MinIO 和 OnlyOffice。部分数据卷仍使用宿主机绝对路径，启动前必须改成当前机器可用的目录。

### 2. 初始化数据库

仅对空数据库执行一次基础脚本：

```sh
mysql -u <user> -p < sql/vue3_database.sql
```

后续启动由 Flyway 自动执行 `src/main/resources/db/migration` 中尚未应用的增量迁移。不要重复执行初始化脚本，也不要用它覆盖已有业务库。

### 3. 配置开发环境

`application.yml` 默认启用 `dev` profile。配置以下连接信息时，优先使用未纳入版本控制的外部配置或环境变量：

- `spring.datasource.*`
- `spring.data.redis.*`
- `jwt.key` 与 `jwt.ttl`
- `oss.type`、`oss.minio.*`
- `onlyoffice.*` 与 `backend.callback-host`

### 4. 启动服务

```sh
mvn spring-boot:run
```

也可以直接运行 `org.example.system.SystemApplication`。本地默认监听 `8080` 端口。

启动后访问：

- Knife4j：<http://localhost:8080/doc.html>
- Swagger UI：<http://localhost:8080/swagger-ui/index.html>
- OpenAPI JSON：<http://localhost:8080/v3/api-docs>

## 认证与权限

登录成功后，请在受保护请求中携带：

```http
Authorization: Bearer <access-token>
```

数据范围值固定为：

| 值 | 范围 | 用户数据语义 | 部门数据语义 |
| --- | --- | --- | --- |
| `0` | `ALL` | 全部 | 全部 |
| `1` | `DEPT_AND_SUB` | 本部门及后代部门 | 本部门及后代部门 |
| `2` | `DEPT` | 本部门 | 本部门 |
| `3` | `SELF` | 仅本人 | 仅可读本部门，不可写 |

ROOT 身份只接受当前服务端加载到的有效 ROOT 角色。JWT 中的旧角色、部门、范围以及 Redis 中的旧权限集合不会直接用于授权。

菜单权限标识、菜单类型、父节点、新增和删除等全局授权定义仅 ROOT 可修改；具备菜单编辑权限的普通管理员只能修改不改变授权含义的展示属性。

分页请求统一限制为 `pageNum >= 1` 且 `1 <= pageSize <= 100`，超限请求返回参数校验错误。

## 文件访问

新上传文件使用以下对象键：

```text
scoped/d-{deptId}/u-{userId}/{yyyyMMdd}/{uuid}-{filename}
```

列表、单文件下载、ZIP 下载和删除都通过同一归属规则校验。没有归属信息的历史对象仅 `ALL` 或 ROOT 可访问；如需让普通用户访问，必须先根据实际业务规则迁移历史对象。

ZIP 下载默认限制：

| 配置 | 默认值 | 说明 |
| --- | ---: | --- |
| `oss.minio.zip-max-files` | `100` | 单次最多文件数 |
| `oss.minio.zip-max-bytes` | `536870912` | 实际读取的未压缩总字节数（512 MiB） |

ZIP 会先写入受控临时文件，完成全部授权和读取后再响应；重复对象、任一读取失败或超限都会整体失败，临时文件会在失败或响应关闭时清理。

## OnlyOffice 配置

OnlyOffice JWT 必须启用，且应用与 Document Server 的 browser、inbox、outbox 必须使用同一密钥。缺少配置时编辑配置和回调都会失败关闭，不会降级为无签名模式。

推荐通过环境变量提供生产配置：

```yaml
onlyoffice:
  server-url: ${ONLYOFFICE_SERVER_URL}
  jwt-secret: ${ONLYOFFICE_JWT_SECRET}
  jwt-enabled: true
  connect-timeout-ms: 5000
  read-timeout-ms: 15000
  max-download-bytes: 104857600
  max-redirects: 3

backend:
  callback-host: ${BACKEND_CALLBACK_HOST}

file-access:
  proxy-token-ttl-seconds: 300
  callback-token-ttl-seconds: 86400
```

配置要求：

- `onlyoffice.server-url` 是回调文档下载唯一允许的协议、主机和端口；每次重定向也必须保持一致。
- Document Server 必须通过 `Authorization: Bearer <token>` 发送出站回调 JWT，JWT 内容需与回调正文一致。
- `backend.callback-host` 必须是 Document Server 能访问到的本服务地址，不能在 Docker 中使用只指向容器自身的 `localhost`。
- `/api/v1/onlyoffice/config` 需要登录并具备 `sys:file:download` 权限。
- `/api/v1/onlyoffice/callback` 和 `/api/v1/files/minio/**` 对登录态公开，但分别强制校验回调凭证或短期对象下载凭证。

前端从上传结果取得文件 URL 后请求编辑配置：

```js
const response = await axios.get('/api/v1/onlyoffice/config', {
  params: {
    fileName: uploadedFile.name,
    fileUrl: uploadedFile.url,
    editable: true
  }
})

new DocsAPI.DocEditor('editor-container', response.data.data)
```

## 核心 API

| 模块 | 路径前缀 | 主要能力 |
| --- | --- | --- |
| 认证 | `/api/v1/auth` | 登录、退出、验证码 |
| 用户 | `/api/v1/users` | 分页、新增、修改、删除、导入导出、注册 |
| 角色 | `/api/v1/roles` | 角色管理、菜单授权 |
| 菜单 | `/api/v1/menus` | 菜单、路由和菜单选项 |
| 部门 | `/api/v1/dept` | 部门树、表单和维护 |
| 字典 | `/api/v1/dict` | 字典与字典类型管理 |
| 文件 | `/api/v1/files` | 上传、列表、下载、ZIP、删除、文档代理 |
| OnlyOffice | `/api/v1/onlyoffice` | 编辑配置与保存回调 |
| 在线用户 | `/api/v1/online` | 在线用户列表与强制退出 |

具体参数、响应和权限要求以启动后的 OpenAPI 文档为准。

## 测试

`pom.xml` 默认 `skipTests=true`，执行测试时必须显式覆盖：

```sh
mvn -DskipTests=false \
  -Dtest=BasePageQueryValidationTest,DataPermissionRegressionTest,MapperPermissionResolutionTest,RegistrationLoggingTest,FileAccessGuardTest,OnlyOfficeServiceImplTest,MinioOssServiceImplTest \
  test
```

当前目标回归包含 69 项测试，覆盖数据权限、事务回滚、菜单授权、分页边界、文件凭证、ZIP 限制和 OnlyOffice 回调安全。测试不连接开发数据库、Redis 或真实 MinIO；OnlyOffice 下载使用本地受控 HTTP 服务。真实 MySQL InnoDB 并发行为和真实 OnlyOffice 互通仍需在部署环境验证。

## 打包与 Docker 部署

先执行上方目标回归，再构建 JAR：

```sh
mvn -DskipTests package
docker build -t server-image .
cp .env.example .env
# 使用 `openssl rand -base64 48` 生成随机值，写入 .env 的 ONLYOFFICE_JWT_SECRET
docker compose up -d
```

Dockerfile 会以 `prod` profile 启动服务。Compose 默认地址：

- 应用与 Knife4j：<http://localhost:8090/doc.html>
- OnlyOffice Document Server：<http://localhost:8082>
- MinIO API / Console：<http://localhost:9000> / <http://localhost:9001>

应用与 OnlyOffice 在 Compose 网络内分别使用 `http://onlyoffice:80` 和 `http://microservice:8080` 通信，并共享 `.env` 中的 `ONLYOFFICE_JWT_SECRET`。前端加载编辑器脚本时使用宿主机地址 `http://localhost:8082`。

如果 OnlyOffice 回调正文中的下载 URL 使用了外部域名而不是 `onlyoffice:80`，请把 `.env` 中的 `ONLYOFFICE_SERVER_URL` 设置成该完整 origin；该地址必须同时能被浏览器和应用容器解析、访问，不能直接使用只指向容器自身的 `localhost`。生产环境建议通过反向代理暴露统一域名，否则同源下载校验会失败。

常用命令：

```sh
docker compose ps
docker compose logs -f microservice
docker compose logs -f onlyoffice
docker compose down
```

`build.sh` 会删除 `target`、替换本地 `server-image` 并重启 Compose 服务，只适用于已经核对过当前 Docker 环境和卷路径的本机，不应直接用于生产发布。

## 部署检查

- 使用外部密钥覆盖 JWT、数据库、Redis、MinIO 和 OnlyOffice 示例配置。
- 确认 Flyway 迁移成功且没有重复执行基础初始化 SQL。
- 确认 OnlyOffice 能访问 `backend.callback-host`，且双方 JWT 配置一致。
- 根据业务归属规则处理无 `scoped/` 前缀的历史 MinIO 对象。
- 在真实 MySQL 上验证部门移动与批量导入并发行为。
- 检查日志中没有访问令牌、真实密码或完整签名 URL。