MES/yawei-mes/.tasks/2026-02-25_token滑动机制.md

# Token滑动机制技术文档

## 一、概述

本系统采用基于Redis的Token滑动窗口机制，实现用户会话的自动续期功能。当用户在系统中持续活动时，Token会自动刷新，避免频繁登录，提升用户体验。

## 二、核心配置

### 2.1 配置文件（application.yml）

```yaml
# token配置
token:
    # 令牌自定义标识
    header: Authorization
    # 令牌密钥
    secret: abcdefghijklmnopqrstuvwxyz
    # 令牌有效期（默认30分钟，单位：分钟）
    expireTime: 10080
```

**配置说明：**
- `header`: HTTP请求头中Token的字段名
- `secret`: JWT签名密钥
- `expireTime`: Token有效期，当前配置为10080分钟（7天）

## 三、核心实现

### 3.1 数据模型（LoginUser）

```java
public class LoginUser implements UserDetails {
    /**
     * 用户唯一标识
     */
    private String token;

    /**
     * 登录时间
     */
    private Long loginTime;

    /**
     * 过期时间
     */
    private Long expireTime;
    
    // ... 其他字段
}
```

### 3.2 Token服务（TokenService）

#### 3.2.1 关键常量

```java
// 令牌有效期（从配置文件读取）
@Value("${token.expireTime}")
private int expireTime;

// 毫秒常量
protected static final long MILLIS_SECOND = 1000;
protected static final long MILLIS_MINUTE = 60 * MILLIS_SECOND;

// 滑动窗口触发阈值：20分钟
private static final Long MILLIS_MINUTE_TEN = 20 * 60 * 1000L;
```

#### 3.2.2 创建Token

```java
public String createToken(LoginUser loginUser) {
    String token = IdUtils.fastUUID();
    loginUser.setToken(token);
    setUserAgent(loginUser);
    refreshToken(loginUser);  // 初始化Token过期时间

    Map<String, Object> claims = new HashMap<>();
    claims.put(Constants.LOGIN_USER_KEY, token);
    return createToken(claims);
}
```

#### 3.2.3 验证Token（滑动机制核心）

```java
/**
 * 验证令牌有效期，相差不足20分钟，自动刷新缓存
 * 
 * @param loginUser
 */
public void verifyToken(LoginUser loginUser) {
    long expireTime = loginUser.getExpireTime();
    long currentTime = System.currentTimeMillis();
    
    // 如果距离过期时间不足20分钟，触发刷新
    if (expireTime - currentTime <= MILLIS_MINUTE_TEN) {
        refreshToken(loginUser);
    }
}
```

#### 3.2.4 刷新Token

```java
/**
 * 刷新令牌有效期
 * 
 * @param loginUser 登录信息
 */
public void refreshToken(LoginUser loginUser) {
    // 更新登录时间为当前时间
    loginUser.setLoginTime(System.currentTimeMillis());
    
    // 重新计算过期时间 = 当前时间 + 配置的有效期
    loginUser.setExpireTime(loginUser.getLoginTime() + expireTime * MILLIS_MINUTE);
    
    // 将更新后的用户信息存入Redis，并设置过期时间
    String userKey = getTokenKey(loginUser.getToken());
    redisCache.setCacheObject(userKey, loginUser, expireTime, TimeUnit.MINUTES);
}
```

#### 3.2.5 获取登录用户

```java
public LoginUser getLoginUser(HttpServletRequest request) {
    // 获取请求携带的令牌
    String token = getToken(request);
    if (StringUtils.isNotEmpty(token)) {
        try {
            Claims claims = parseToken(token);
            // 解析对应的权限以及用户信息
            String uuid = (String) claims.get(Constants.LOGIN_USER_KEY);
            String userKey = getTokenKey(uuid);
            LoginUser user = redisCache.getCacheObject(userKey);
            return user;
        } catch (Exception e) {
            // Token解析失败
        }
    }
    return null;
}
```

## 四、滑动机制工作流程

### 4.1 流程图

```
用户请求 → 获取Token → 从Redis获取LoginUser → 验证Token有效期
                                                    ↓
                                            距离过期 ≤ 20分钟？
                                            ↓              ↓
                                          是              否
                                            ↓              ↓
                                      刷新Token      继续使用
                                            ↓
                                    更新过期时间
                                            ↓
                                    更新Redis缓存
```

### 4.2 详细说明

1. **用户登录**
   - 创建Token（UUID）
   - 设置初始过期时间 = 当前时间 + expireTime
   - 存入Redis，设置过期时间

2. **用户请求**
   - 从请求头获取Token
   - 从Redis获取LoginUser对象
   - 调用`verifyToken()`验证

3. **滑动窗口判断**
   - 计算剩余有效时间 = expireTime - currentTime
   - 如果剩余时间 ≤ 20分钟，触发刷新
   - 否则，继续使用当前Token

4. **Token刷新**
   - 更新loginTime为当前时间
   - 重新计算expireTime
   - 更新Redis中的LoginUser对象

## 五、关键特性

### 5.1 滑动窗口策略

- **触发条件**：距离过期时间不足20分钟
- **刷新动作**：重置过期时间为当前时间 + expireTime
- **优势**：用户持续活动时，Token自动续期，无需重新登录

### 5.2 Redis存储

- **Key格式**：`login_tokens:{uuid}`
- **Value**：LoginUser对象（序列化）
- **过期时间**：与Token过期时间一致
- **优势**：分布式环境下共享会话，自动清理过期数据

### 5.3 双重过期机制

1. **LoginUser.expireTime**：业务层面的过期时间判断
2. **Redis TTL**：存储层面的自动清理机制

## 六、配置建议

### 6.1 生产环境配置

```yaml
token:
    expireTime: 120  # 2小时
```

**说明**：
- 滑动窗口触发阈值固定为20分钟
- 如果用户在2小时内有任何操作，且距离过期不足20分钟，会自动续期2小时
- 如果用户超过2小时无操作，Token过期，需要重新登录

### 6.2 开发环境配置

```yaml
token:
    expireTime: 10080  # 7天
```

**说明**：
- 方便开发调试，减少频繁登录
- 生产环境不建议设置过长

## 七、安全考虑

### 7.1 Token安全

- 使用JWT签名，防止Token篡改
- Token存储在Redis中，支持主动失效
- 支持单点登录控制

### 7.2 滑动窗口安全

- 20分钟的滑动窗口阈值，平衡用户体验和安全性
- 即使Token被盗用，最长有效期仍受expireTime限制
- 可通过删除Redis中的Token实现强制下线

## 八、扩展功能

### 8.1 积木报表Token验证

```java
// JimuReportTokenService.java
public boolean isTokenValid(String token) {
    LoginUser loginUser = tokenService.getLoginUser(request);
    if (loginUser != null) {
        // 检查token是否过期
        long expireTime = loginUser.getExpireTime();
        long currentTime = System.currentTimeMillis();
        return currentTime < expireTime;
    }
    return false;
}
```

### 8.2 用户代理信息记录

```java
public void setUserAgent(LoginUser loginUser) {
    UserAgent userAgent = UserAgent.parseUserAgentString(
        ServletUtils.getRequest().getHeader("User-Agent")
    );
    String ip = IpUtils.getIpAddr();
    loginUser.setIpaddr(ip);
    loginUser.setLoginLocation(AddressUtils.getRealAddressByIP(ip));
    loginUser.setBrowser(userAgent.getBrowser().getName());
    loginUser.setOs(userAgent.getOperatingSystem().getName());
}
```

## 九、总结

本系统的Token滑动机制通过以下方式实现了高效的会话管理：

1. **自动续期**：用户活跃时自动延长会话，提升体验
2. **灵活配置**：通过配置文件调整有效期和滑动窗口
3. **分布式支持**：基于Redis实现，支持集群部署
4. **安全可控**：双重过期机制，支持主动失效

**核心优势**：在保证安全性的前提下，最大化提升用户体验，避免频繁登录带来的困扰。