# pure-admin-backend

**Repository Path**: cwk985/pure-admin-backend

## Basic Information

- **Project Name**: pure-admin-backend
- **Description**: pure-admin-backend

企业级后端模板，适配 vue-pure-admin 前端。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pure-admin-backend

企业级后端模板，为 [vue-pure-admin](https://gitee.com/cwk985/vue-pure-admin) 前端提供 RBAC 权限、动态路由、系统管理、监控日志等完整后端能力。

> **仓库地址**：[https://gitee.com/cwk985/pure-admin-backend](https://gitee.com/cwk985/pure-admin-backend)  
> **前端仓库**：[https://gitee.com/cwk985/vue-pure-admin](https://gitee.com/cwk985/vue-pure-admin)

## 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Java | 21 | |
| Spring Boot | 4.1.0 | |
| MyBatis-Plus | 3.5.15 | `mybatis-plus-spring-boot4-starter` |
| Sa-Token | 1.45.0 | `sa-token-spring-boot4-starter`，认证鉴权 |
| MySQL | 8.0 | |
| Redis | 7+ | Lettuce 连接池，会话/缓存/在线用户 |
| SpringDoc | 3.0.3 | Swagger 接口文档 |
| Lombok | | 减少样板代码 |

## 核心特性

- **认证鉴权**：Sa-Token 双 token（access + refresh）无感刷新，Redis 会话管理，`@SaCheckPermission` 注解
- **RBAC 权限**：用户/角色/菜单/部门四级权限体系，事件驱动缓存失效
- **动态路由**：`sys_menu` 表驱动，`/auth/async-routes` 返回 vue-router 路由树
- **系统管理**：用户 CRUD（头像上传/密码重置/角色分配/批量删除/状态切换）、角色 CRUD、菜单/部门树形管理
- **SSE 实时推送**：管理员强制下线 → 被踢用户客户端实时收到通知（`SseSessionRegistry` + ticket 鉴权）
- **监控日志**：登录日志、操作日志（`@Log` + AOP 自动记录 + 敏感字段脱敏）、系统日志（拦截器 + traceId + 异步落库）
- **统一规范**：`Result<T>` 统一响应（`code===0` 成功）、`GlobalExceptionHandler` 全局异常处理、多环境配置（dev/uat/prod）
- **部署**：Docker Compose 一键启动（MySQL + Redis + 后端）、JAR 直接部署、systemd 管理

## 快速开始

### 1. 准备环境

- JDK 21+
- MySQL 8.0+
- Redis 7+

### 2. 初始化数据库

```bash
mysql -u root -p < src/main/resources/db/schema.sql
mysql -u root -p pure_admin < src/main/resources/db/data.sql
```

### 3. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，填入 MYSQL_PWD / REDIS_HOST / REDIS_PWD
```

### 4. 启动

```bash
# Git Bash / macOS / Linux
./dev.sh

# Windows（cmd / PowerShell）
dev.bat
```

接口文档：`http://localhost:8765/api/swagger-ui.html`  
默认账号：**admin / admin123**（超管）、**common / common123**

## API 概览

所有接口前缀 `http://localhost:8765/api`：

| 模块 | 路径 | 主要接口 |
|------|------|---------|
| 认证 | `/auth` | `POST /login` `POST /logout` `POST /refresh-token` `GET /user-info` `GET /async-routes` `PUT /user-info` `POST /avatar` |
| 用户管理 | `/system/users` | CRUD + 状态切换/批量删除/重置密码/分配角色/头像上传 |
| 角色管理 | `/system/roles` | CRUD + 状态切换/分配菜单 |
| 菜单管理 | `/system/menus` | CRUD（树形） |
| 部门管理 | `/system/depts` | CRUD（树形） |
| 在线用户 | `/monitor/online` | `GET /page` 查询 / `DELETE /{token}` 强退 / `POST /sse-ticket` SSE ticket / `GET /subscribe` SSE 订阅 |
| 登录日志 | `/monitor/login-log` | 分页查询/批量删除/清空 |
| 操作日志 | `/monitor/oper-log` | 分页查询/批量删除/清空 |
| 系统日志 | `/monitor/sys-log` | 分页查询/详情/批量删除/清空 |

## 目录结构

```
src/main/java/com/pureadmin/backend/
├── common/            # Result / 异常 / 注解 / 事件 / 共享 DTO
├── config/            # Async / Cors / Jackson / MybatisPlus / OpenApi / SaToken / WebMvc
├── framework/         # BaseEntity / PageQuery / TreeBuilder / RedisUtil / WebUtil
├── security/          # AuthController / AuthService / AsyncRouteService / PermissionService
├── system/            # user / role / menu / dept（各含 controller/dto/entity/mapper/service）
├── monitor/
│   ├── online/        # OnlineController（含 SSE）/ OnlineService / SseSessionRegistry
│   └── log/           # LoginLog / OperLog / ApiLog（controller/service/aspect/mapper）
└── PureAdminBackendApplication.java
```

## 核心设计

### 统一响应

```json
// 成功
{ "code": 0, "message": "操作成功", "data": { ... } }

// 分页
{ "code": 0, "data": { "list": [...], "total": 100, "pageSize": 10, "currentPage": 1 } }
```

业务异常抛 `BusinessException`，由 `GlobalExceptionHandler` 统一转 `Result.failed`。

### 权限校验

- Controller 方法加 `@SaCheckPermission("module:resource:action")`，如 `system:user:list`
- 超管角色 `admin` 返回 `["*:*:*"]`，通达所有权限
- `StpInterfaceImpl` 委托 `PermissionService` 从 Redis 缓存解析权限码

### SSE 实时推送

管理员强制下线时，通过 SSE 实时通知被踢用户客户端：

1. 客户端登录后调 `POST /sse-ticket` 获取 60s 短命 ticket
2. 通过 `EventSource` 连接 `GET /subscribe?ticket=xxx` 建立长连接
3. 管理员强退 → `StpUtil.kickoutByTokenValue()` + SSE 推送 `kickout` 事件
4. `SseSessionRegistry` 维护 `userId → List<SseEmitter>` 映射，30s 心跳保活

### 操作日志

Controller 方法加 `@Log(title="模块", businessType=1新增/2修改/3删除)` 注解，`OperLogAspect`（AOP）自动记录操作人/IP/UA/参数/结果，敏感字段（password/token）自动脱敏。

## 多环境

| Profile | 说明 | 激活方式 |
|---------|------|---------|
| dev（默认） | 本地开发，`.env` 注入配置 | `./dev.sh` |
| uat | 测试环境 | `SPRING_PROFILES_ACTIVE=uat` |
| prod | 生产环境，密码 fail-fast | `SPRING_PROFILES_ACTIVE=prod` |

## 打包部署

```bash
# 打包
./mvnw clean package -DskipTests

# 运行 jar
java -jar target/pure-admin-backend-0.0.1-SNAPSHOT.jar

# Docker Compose 一键部署（含 MySQL + Redis）
docker compose -f ../docker-compose.yml up -d
```

完整部署文档见 [AGENTS.md](./AGENTS.md)。

## License

[MIT](../LICENSE)