企业官网建设流程全解析

1. 项目背景与核心需求

在当今的Web应用开发中，身份认证和权限控制是每个系统都无法绕开的核心模块。传统的Session-Cookie方案在分布式环境下存在诸多局限，而单纯的JWT方案又难以解决无感刷新和主动注销等问题。这正是双Token机制（Access Token + Refresh Token）逐渐成为主流的原因。

我最近在一个企业级后台管理系统中采用了SpringBoot3 + Sa-Token的组合实现双Token认证，过程中踩了不少坑，也积累了一些实战经验。Sa-Token作为国产轻量级权限认证框架，其API设计非常符合国人习惯，最新版本对SpringBoot3的支持也相当完善。下面我将分享完整的实现方案和避坑指南。

2. 技术选型与环境准备

2.1 为什么选择Sa-Token

相比Shiro和Spring Security，Sa-Token具有几个明显优势：

• 学习曲线平缓，中文文档完善
• 开箱即用的Token管理功能
• 内置分布式会话支持
• 丰富的插件生态（如SSO、OAuth2）
• 对国产框架（如Ruoyi、若依）友好

2.2 基础环境搭建

首先创建SpringBoot3项目，添加依赖：

<dependency> <groupId>cn.dev33</groupId> <artifactId>sa-token-spring-boot3-starter</artifactId> <version>1.34.0</version> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-redis</artifactId> </dependency>

配置application.yml：

sa-token: token-name: satoken timeout: 1800 # token有效期30分钟 activity-timeout: -1 # 无操作不续期 is-share: false # 不共享token is-read-body: true is-read-head: true token-style: uuid # token生成策略

注意：SpringBoot3默认使用Jakarta EE 9+，与SpringBoot2的javax包不兼容，这是第一个容易踩的坑。

3. 双Token机制实现

3.1 核心设计原理

双Token机制的核心逻辑：

• Access Token：短期有效（如30分钟），用于业务请求
• Refresh Token：长期有效（如7天），用于获取新Access Token
• Access Token过期后，客户端用Refresh Token获取新Token
• 服务端可主动使Refresh Token失效实现强制登出

3.2 登录接口实现

创建AuthController：

@RestController @RequestMapping("/auth") public class AuthController { @PostMapping("/login") public Result login(@RequestBody LoginDTO dto) { // 1. 模拟用户验证 if(!"admin".equals(dto.getUsername()) || !"123456".equals(dto.getPassword())) { return Result.fail("账号或密码错误"); } // 2. 生成双Token String accessToken = SaManager.getSaTokenAction().createTokenValue(); String refreshToken = SaManager.getSaTokenAction().createTokenValue(); // 3. 写入Redis（实际项目应设置不同有效期） SaManager.getSaTokenDao().set(accessToken, dto.getUsername(), 1800); SaManager.getSaTokenDao().set("refresh:"+refreshToken, dto.getUsername(), 604800); // 4. 返回客户端 Map<String,String> result = new HashMap<>(); result.put("accessToken", accessToken); result.put("refreshToken", refreshToken); return Result.ok(result); } }

3.3 Token刷新机制

添加刷新接口：

@PostMapping("/refresh") public Result refresh(@RequestHeader("refresh-token") String refreshToken) { // 1. 验证refreshToken有效性 String username = SaManager.getSaTokenDao().get("refresh:"+refreshToken); if(username == null) { return Result.fail(401, "RefreshToken已失效"); } // 2. 生成新accessToken String newAccessToken = SaManager.getSaTokenAction().createTokenValue(); SaManager.getSaTokenDao().set(newAccessToken, username, 1800); // 3. 返回新token（refreshToken不变） return Result.ok(Collections.singletonMap("accessToken", newAccessToken)); }

4. 安全防护与最佳实践

4.1 防止Token盗用

几个关键防护措施：

1. 设置HttpOnly和Secure的Cookie（如果使用Cookie）
2. 实现IP绑定机制（登录时记录IP，每次请求校验）
3. 限制Refresh Token使用频率（如1分钟最多刷新5次）
4. 关键操作要求二次认证

4.2 并发控制方案

当多个请求同时触发Token刷新时，可能出现Race Condition。解决方案：

// 使用Redis分布式锁 String lockKey = "refresh_lock:" + username; try { boolean locked = redisTemplate.opsForValue() .setIfAbsent(lockKey, "1", 10, TimeUnit.SECONDS); if(!locked) { throw new RuntimeException("操作太频繁"); } // 执行刷新逻辑... } finally { redisTemplate.delete(lockKey); }

4.3 会话管理增强

Sa-Token默认的会话存储可能不满足生产需求，建议：

1. 自定义Token存储策略：

@Configuration public class SaTokenConfig { @Bean public SaTokenDao saTokenDao() { return new SaTokenDaoRedis(); } }

2. 实现会话事件监听：

@Component public class MySaTokenListener implements SaTokenListener { @Override public void doLogin(String loginType, Object loginId, String tokenValue, HttpServletRequest request, HttpServletResponse response) { log.info("用户{}登录成功，Token:{}", loginId, tokenValue); } }

5. 常见问题排查指南

5.1 Token失效异常处理

当遇到"token exchange failed"错误时，按以下步骤排查：

1. 检查Redis连接是否正常
2. 验证Token存储的Key命名规则是否一致
3. 确认Token未超过有效期
4. 检查是否有其他服务清除了Redis数据

5.2 SpringBoot3兼容性问题

升级到SpringBoot3后可能遇到：

1. Jakarta包名变更导致ClassNotFound

   • 解决方案：确保所有依赖都支持Jakarta EE 9+

2. 自动配置类路径变化

   • 检查META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

3. Redis客户端兼容性

   • 推荐使用Lettuce而非Jedis

5.3 跨域与Cookie问题

前端获取不到Token的常见原因：

1. 跨域配置未包含凭证模式：

@Bean public CorsFilter corsFilter() { UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource(); CorsConfiguration config = new CorsConfiguration(); config.setAllowCredentials(true); // 关键配置 config.addAllowedOriginPattern("*"); config.addAllowedHeader("*"); config.addAllowedMethod("*"); source.registerCorsConfiguration("/**", config); return new CorsFilter(source); }

2. 前端Axios未设置withCredentials: true

6. 性能优化建议

6.1 Token存储优化

1. 使用Hash结构存储Token元数据：

// 代替简单的Key-Value存储 redisTemplate.opsForHash().put( "user:token:" + username, "access_token", tokenInfo );

2. 启用Redis管道批量操作：

redisTemplate.executePipelined((RedisCallback<Object>) connection -> { connection.stringCommands().set( ("access:" + accessToken).getBytes(), username.getBytes(), Expiration.seconds(1800), RedisStringCommands.SetOption.UPSERT ); return null; });

6.2 无感刷新方案

前端可按照这个逻辑实现无感刷新：

async function requestWithRetry(url, options, retryCount = 0) { try { const response = await fetch(url, options); if (response.status === 401 && retryCount < 2) { const refreshResponse = await refreshToken(); if (refreshResponse.success) { options.headers.Authorization = `Bearer ${refreshResponse.accessToken}`; return requestWithRetry(url, options, retryCount + 1); } } return response; } catch (error) { // 错误处理 } }

7. 扩展功能实现

7.1 踢人下线功能

实现强制下线某个用户的所有会话：

public void kickUser(String username) { // 1. 查找用户所有活跃Token Set<String> tokens = redisTemplate.keys("access:*"); for (String key : tokens) { if(username.equals(redisTemplate.opsForValue().get(key))) { redisTemplate.delete(key); } } // 2. 清除Refresh Token redisTemplate.delete("refresh:*" + username); }

7.2 登录设备管理

记录用户登录设备信息：

public void recordLoginDevice(String username, HttpServletRequest request) { String deviceId = request.getHeader("Device-ID"); if(deviceId == null) { deviceId = DigestUtils.md5Hex(request.getRemoteAddr() + request.getHeader("User-Agent")); } String key = "user:devices:" + username; redisTemplate.opsForZSet().add( key, deviceId, System.currentTimeMillis() ); // 保留最近5个设备 redisTemplate.opsForZSet().removeRange(key, 0, -6); }

在实际项目中，双Token机制配合Sa-Token可以构建出既安全又灵活的身份认证体系。我建议在正式上线前做好以下几项验证：

1. Token过期逻辑测试（包括并发刷新场景）
2. 各种异常情况下的降级方案
3. 完整的压力测试（特别是Token生成和验证环节）
4. 安全审计（重点关注Token生成算法和存储方式）