# my-base-admin-auth

**Repository Path**: catberus/my-base-admin-auth

## Basic Information

- **Project Name**: my-base-admin-auth
- **Description**: 包括基本认证和授权的脚手架
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-26
- **Last Updated**: 2026-07-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Base-Admin-Auth 后台管理脚手架

基于 RuoYi-Vue-Plus 精简的后台管理脚手架，聚焦认证授权核心能力。

## 特性

- **无状态 JWT 认证** — 权限写进 payload，正常请求零 Redis 依赖
- **RBAC 权限模型** — 5 表标准模型，`@PreAuthorize` 方法级权限控制
- **双 Token 模式** — JWT access token (15 min) + UUID refresh token (7d)，token rotation 防重放
- **可插拔 TokenStore** — Redis / DB / Caffeine 三种 refresh token 存储后端，配置切换
- **统一响应结构** — 所有接口统一 `R<T>` 包装，分页接口 `R<TableDataInfo<T>>`

## 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Spring Boot | 3.5.9 | 基础框架 |
| Spring Security | 6.x | 认证授权 |
| MyBatis Plus | 3.5.16 | ORM 框架 |
| nimbus-jose-jwt | 9.x | JWT 签发与验证 |
| Redisson | 3.52.0 | Redis 客户端 |
| Hutool | 5.8.43 | 工具类库 |
| MapStruct Plus | 1.5.0 | 对象转换 |

## 项目结构

```
my-base-admin-auth/
├── base-admin/                     # 启动模块
├── base-common/
│   ├── base-common-security/       # JWT + Spring Security 认证模块
│   ├── base-common-core/           # 核心领域模型、接口、枚举
│   ├── base-common-mybatis/        # MyBatis-Plus 配置、BaseMapperPlus、分页
│   ├── base-common-web/            # 全局异常处理、XSS 过滤
│   ├── base-common-redis/          # Redis/Redisson 工具
│   ├── base-common-json/           # Jackson 配置
│   └── base-common-log/            # 操作日志 AOP
├── base-modules/
│   └── base-system/                # 系统管理（用户/角色/菜单/认证）
├── docs/                           # 文档
└── script/sql/                     # 数据库脚本
```

---

## 一、认证架构

### 1.1 JWT 无状态认证流程

```
登录:
  POST /auth/login
  → 验证密码 → 加载权限 → JWT(含权限) + UUID refresh token
  → refresh token 存 Redis/DB/Caffeine
  → 返回 TokenPair

每次请求:
  Authorization: Bearer {jwt}
  → 验签 + iss/aud 校验 + 过期检查（纯密码学，无 Redis）
  → 从 JWT claims 提取 permissions + roles
  → 构建 SecurityContext → @PreAuthorize 匹配

刷新:
  POST /auth/refresh
  → 从存储取 refresh token → 重新加载权限
  → 签发新 JWT(含最新权限) + 新 refresh token
  → 删除旧 refresh token（rotation）
```

### 1.2 JWT Payload 结构

```json
{
  "sub": "1",
  "iss": "my-base-admin",
  "aud": "my-base-admin-api",
  "typ": "Bearer",
  "iat": 1715300000,
  "exp": 1715300900,
  "jti": "uuid",
  "userType": "sys",
  "username": "admin",
  "nickname": "管理员",
  "permissions": ["system:user:list", "system:user:add", ...],
  "roles": ["admin"]
}
```

### 1.3 Token 配置

```yaml
base:
  security:
    jwt-secret: ${JWT_SECRET:your-secret-key}
    issuer: my-base-admin
    audience: my-base-admin-api
    storage: redis              # redis | db | caffeine
    access-token-ttl: 900       # 15 分钟
    refresh-token-ttl: 604800   # 7 天
```

### 1.4 API 接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/auth/login` | POST | 登录，返回 TokenPair |
| `/auth/refresh` | POST | 刷新 token，返回新 TokenPair |
| `/auth/logout` | POST | 登出，删除 refresh token |

### 1.5 TokenStore 后端

| 后端 | 配置值 | 适用场景 |
|------|--------|---------|
| Redis | `redis`（默认） | 生产环境，多实例 |
| Database | `db` | 无 Redis 的环境 |
| Caffeine | `caffeine` | 单机开发 |

---

## 二、RBAC 权限模型

### 2.1 数据模型（5 表）

```
sys_user ←→ sys_user_role ←→ sys_role ←→ sys_role_menu ←→ sys_menu
```

| 表 | 说明 |
|---|---|
| `sys_user` | 用户 |
| `sys_role` | 角色（role_key: admin, common） |
| `sys_menu` | 菜单 + 按钮权限（perms 字段） |
| `sys_user_role` | 用户-角色关联 |
| `sys_role_menu` | 角色-菜单关联 |

权限标识格式：`{模块}:{资源}:{操作}`，如 `system:user:list`、`system:user:add`。

### 2.2 权限使用

Controller 方法上使用 `@PreAuthorize` 注解：

```java
@PreAuthorize("hasAuthority('system:user:list')")
@GetMapping("/list")
public R<TableDataInfo<SysUserVo>> list(SysUserBo user, PageQuery pageQuery) {
    return R.ok(userService.selectPageUserList(user, pageQuery));
}
```

### 2.3 超级管理员

`user_id = 1` 为超级管理员，权限加载绕过 `sys_role_menu` 关联，直接查询所有有效权限标识。

---

## 三、统一响应结构

所有接口统一返回 `R<T>`：

```json
// 普通接口
{ "code": 200, "msg": "操作成功", "data": {...} }

// 分页接口
{ "code": 200, "msg": "操作成功", "data": { "total": 100, "rows": [...] } }
```

---

## 四、快速开始

### 4.1 环境要求

- JDK 17+
- Maven 3.6+
- MySQL 8.0+
- Redis 6.0+

### 4.2 配置

修改 `base-admin/src/main/resources/application-dev.yml`：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/base_admin
    username: root
    password: your-password
  data:
    redis:
      host: localhost
      port: 6379
```

### 4.3 初始化数据库

```bash
mysql -u root -p base_admin < script/sql/base_admin_auth.sql
mysql -u root -p base_admin < script/sql/sys_auth_session.sql
```

### 4.4 启动

```bash
mvn spring-boot:run -pl base-admin
```

---

## 五、命名规范

| 类型 | 规范 | 示例 |
|------|------|------|
| 模块名 | base-{module} | base-system |
| 包名 | org.dromara.{module} | org.dromara.system |
| 实体类 | PascalCase | SysUser |
| 业务对象 | XxxBo | SysUserBo |
| 视图对象 | XxxVo | SysUserVo |
| Service 接口 | IXxxService | ISysUserService |
| Service 实现 | XxxServiceImpl | SysUserServiceImpl |
| Controller | XxxController | SysUserController |
| 请求路径 | /{module}/{entity} | /system/user |
| 权限标识 | {module}:{entity}:{action} | system:user:add |

---

## 六、模块依赖

```
base-admin (启动模块)
  ├── base-system (业务模块)
  ├── base-common-security (JWT + Spring Security)
  ├── base-common-web (全局异常、XSS)
  ├── base-common-mybatis (ORM)
  ├── base-common-redis (Redis)
  └── base-common-log (日志 AOP)

base-common-security
  ├── base-common-core (LoginUser, R, TokenPair)
  ├── base-common-json (Jackson)
  └── base-common-redis (RedisTokenStore)
```

---

## License

MIT