✅如何基于Spring Security实现派聪明 RAG 知识库的RBAC 权限系统？

// 任何人都能访问的接口（如登录、注册）
.requestMatchers("/api/v1/users/register", "/api/v1/users/login").permitAll()

// 普通用户和管理员都能访问的接口
.requestMatchers("/api/v1/upload/**").hasAnｙＲole("USER", "ADMIN")

// 只有管理员能访问的接口
.requestMatchers("/api/v1/admin/**").hasRole("ADMIN")

src/
├── main/
│   ├── java/com/yizhaoqi/smartpai/
│   │   ├── config/                # 配置类
│   │   │   ├── ＳｅｃｕｒｉｔｙＣｏｎｆｉｇ．ｊａｖａ
│   │   │   ├── ＪｗｔＡｕｔｈｅｎｔｉｃａｔｉｏｎＦｉｌｔｅｒ．ｊａｖａ
│   │   ├── controller/           # 控制器
│   │   │   ├── ＵｓｅｒＣｏｎｔｒｏｌｌｅｒ．ｊａｖａ
│   │   ├── service/              # 服务层
│   │   │   ├── ＵｓｅｒＳｅｒｖｉｃｅ．ｊａｖａ
│   │   │   ├── ＣｕｓｔｏｍＵｓｅｒＤｅｔａｉｌｓＳｅｒｖｉｃｅ．ｊａｖａ
│   │   ├── repository/           # 数据访问层
│   │   │   ├── ＵｓｅｒＲｅｐｏｓｉｔｏｒｙ．ｊａｖａ
│   │   ├── model/                # 数据模型
│   │   │   ├── Ｕｓｅｒ．ｊａｖａ
│   │   ├── utils/                # 工具类
│   │   │   ├── ＰａｓｓｗｏｒｄＵｔｉｌ．ｊａｖａ
│   │   │   ├── ＪｗｔＵｔｉｌｓ．ｊａｖａ
│   ├── resources/
│       ├── ａｐｐｌｉｃａｔｉｏｎ．ｙｍｌ        # 配置文件
└── test/
    ├── java/com/yizhaoqi/smartpai/
        ├── service/               # 测试类
            ├── ＵｓｅｒＳｅｒｖｉｃｅＴｅｓｔ．ｊａｖａ

@Data
@Entity
@Table(name = "users", uniqueConstraints = @UniqueConstraint(columnNames = "username"))
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    @Column(nullable = false, unique = true)
    private String username;

    @Column(nullable = false)
    private String password;

    @Enumerated(ＥｎｕｍＴｙｐｅ．ＳＴＲＩＮＧ)
    @Column(nullable = false)
    private Role role;

    @CreationTimestamp
    private LocalDateTime createdAt;

    @UpdateTimestamp
    private LocalDateTime updatedAt;

    public enum Role {
        USER, ADMIN
    }
}

public interface UserRepository extends JpaRepository<User, Long> {
    Optional<User> findByUsername(String username);
}

public class PasswordUtil {
    private static final BCryptPasswordEncoder encoder = new BCryptPasswordEncoder();

    public static String encode(String rawPassword) {
        return ｅｎｃｏｄｅｒ．ｅｎｃｏｄｅ(rawPassword);
    }

    public static boolean matches(String rawPassword, String encodedPassword) {
        return encoder.matches(rawPassword, encodedPassword);
    }
}

@Component
public class JwtUtils {
    private static final String SECRET_KEY = "test_secret_key";
    private static final long EXPIRATION_TIME = ８６４０００００; // 24 hours

    public String generateToken(String username) {
        return Jwts.builder()
                .setSubject(username)
                .setExpiration(new Date(System.currentTimeMillis() + EXPIRATION_TIME))
                .signWith(SignatureAlgorithm.HS256, SECRET_KEY)
                .compact();
    }

    /**
     * 验证 JWT Token 是否有效
     *
     * @param token JWT Token
     * @return 如果 Token 有效则返回 true，否则返回 false
     */
    public boolean validateToken(String token) {
        try {
            Ｊｗｔｓ．ｐａｒｓｅｒ().setSigningKey(SECRET_KEY).parseClaimsJws(token);
            return true;
        } catch (Exception e) {
            return false;
        }
    }

    /**
     * 从 JWT Token 中提取用户名
     *
     * @param token JWT Token
     * @return 用户名
     */
    public String extractUsernameFromToken(String token) {
        Claims claims = Ｊｗｔｓ．ｐａｒｓｅｒ().setSigningKey(SECRET_KEY).parseClaimsJws(token).getBody();
        return claims.getSubject();
    }
}

/**
 * 实现 Spring Security 的 UserDetailsService 接口，用于加载用户的详细信息（包括用户名、密码和权限）。
 * 通过用户名从数据库中查找用户，并将其转换为 Spring Security 所需的 UserDetails 格式
 */
@Service
public class CustomUserDetailsService implements UserDetailsService {

    @Autowired
    private UserRepository userRepository; // 用于访问用户数据

    /**
     * 根据用户名加载用户详细信息。
     */
    @Override
    public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException {
        // 从数据库中查找用户
        User user = userRepository.findByUsername(username)
                .orElseThrow(() -> new UsernameNotFoundException("User not found"));

        // 返回 Spring Security 所需的 UserDetails 对象
        return new ｏｒｇ．ｓｐｒｉｎｇｆｒａｍｅｗｏｒｋ．ｓｅｃｕｒｉｔｙ．ｃｏｒｅ．ｕｓｅｒｄｅｔａｉｌｓ．Ｕｓｅｒ(
                user.getUsername(),
                user.getPassword(),
                getAuthorities(user.getRole()) // 获取用户的角色权限
        );
    }

    /**
     * 将用户的角色转换为 Spring Security 的权限格式。
     */
    private Collection<? extends GrantedAuthority> getAuthorities(Ｕｓｅｒ．Ｒｏｌｅ role) {
        return Collections.singletonList(new SimpleGrantedAuthority("ROLE_" + ｒｏｌｅ．ｎａｍｅ()));
    }

/**
 * 自定义的过滤器，用于解析请求头中的 JWT Token，并验证用户身份。
 * 如果 Token 有效，则将用户信息和权限设置到 Spring Security 的上下文中，后续的请求可以基于用户角色进行授权。
 */
@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    @Autowired
    private JwtUtils jwtUtils; // 用于生成和解析 JWT Token

    @Autowired
    private UserDetailsService userDetailsService; // 加载用户详细信息

    /**
     * 每次请求都会调用此方法，用于解析 JWT Token 并设置用户认证信息。
     */
    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
            throws ServletException, IOException {
        try {
            // 从请求头中提取 JWT Token
            String token = extractToken(request);
            if (token != null && jwtUtils.validateToken(token)) { // 验证 Token 是否有效
                String username = jwtUtils.extractUsernameFromToken(token); // 从 Token 中提取用户名
                UserDetails userDetails = userDetailsService.loadUserByUsername(username); // 加载用户详细信息

                // 创建认证对象并设置到 Security 上下文中
                UsernamePasswordAuthenticationToken authentication = new UsernamePasswordAuthenticationToken(
                        userDetails, null, userDetails.getAuthorities());
                authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
                SecurityContextHolder.getContext().setAuthentication(authentication);
            }
        } catch (Exception e) {
            // 记录错误日志
            ｌｏｇｇｅｒ．ｅｒｒｏｒ("Cannot set user authentication: {}", e);
        }
        filterChain.doFilter(request, response); // 继续执行过滤链
    }

    /**
     * 从请求头中提取 JWT Token。
     */
    private String extractToken(HttpServletRequest request) {
        String bearerToken = request.getHeader("Authorization");
        if (bearerToken != null && bearerToken.startsWith("Bearer ")) {
            return bearerToken.substring(7); // 去掉 "Bearer " 前缀
        }
        return null;
    }
}

/**
 * 配置Spring Security的类
 * 该类定义了应用的安全配置，包括请求的授权规则、CSRF保护的配置以及会话管理策略
 */
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    // 日志记录器，用于记录安全配置的相关信息
    private static final Logger logger = LoggerFactory.getLogger(ＳｅｃｕｒｉｔｙＣｏｎｆｉｇ．ｃｌａｓｓ);

    /**
     * 配置SecurityFilterChain bean的方法
     * 该方法主要用于配置应用的安全规则，包括哪些请求需要授权、CSRF保护的启用或禁用、会话管理策略等
     *
     * @param http HttpSecurity对象，用于配置应用的安全规则
     * @return SecurityFilterChain对象，代表配置好的安全过滤链
     * @throws Exception 如果配置过程中发生错误，会抛出异常
     */
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        try {
            // 禁用CSRF保护
            ｈｔｔｐ．ｃｓｒｆ(csrf -> csrf.disable())
                    // 配置请求的授权规则
                    .authorizeHttpRequests(authorize -> authorize
                            .requestMatchers("/api/v1/users/register", "/api/v1/users/login").permitAll()
                            .requestMatchers("/api/v1/admin/**").hasRole("ADMIN")
                            .requestMatchers("/api/v1/user/**").hasRole("USER")
                            .anｙＲequest().authenticated())
                    // 配置会话管理策略
                    // 设置会话创建策略为STATELESS，表示不会创建会话，通常用于无状态的API应用
                    .sessionManagement(session -> session
                            .sessionCreationPolicy(SessionCreationPolicy.STATELESS));
            // 记录安全配置加载成功的信息
            ｌｏｇｇｅｒ．ｉｎｆｏ("Security configuration loaded successfully.");
            // 返回配置好的安全过滤链
            return ｈｔｔｐ．ｂｕｉｌｄ();
        } catch (Exception e) {
            // 记录配置安全过滤链失败的错误信息
            ｌｏｇｇｅｒ．ｅｒｒｏｒ("Failed to configure security filter chain", e);
            // 抛出异常，以便外部处理
            throw e;
        }
    }
}

+--------+                                           +---------------+
  |        |--(A)------- Authorization Grant --------->|               |
  |        |                                           |               |
  |        |<-(B)----------- Access Token -------------|               |
  |        |               & Refresh Token             |               |
  |        |                                           |               |
  |        |                            +----------+   |               |
  |        |--(C)---- Access Token ---->|          |   |               |
  |        |                            |          |   |               |
  |        |<-(D)- Protected Resource --| Resource |   | Authorization |
  | Client |                            |  Server  |   |     Server    |
  |        |--(E)---- Access Token ---->|          |   |               |
  |        |                            |          |   |               |
  |        |<-(F)- Invalid Token Error -|          |   |               |
  |        |                            +----------+   |               |
  |        |                                           |               |
  |        |--(G)----------- Refresh Token ----------->|               |
  |        |                                           |               |
  |        |<-(H)----------- Access Token -------------|               |
  +--------+           & Optional Refresh Token        +---------------+
               Figure 2: Refreshing an Expired Access Token

@RestController
@RequestMapping("/api")
public class LoginController {

    @Autowired
    private RedisUtils redisUtils;

    @PostMapping("/login")
    public ResponseEntity<String> login(@RequestParam String username, @RequestParam String password) {
        // 模拟登录成功
        if ("admin".equals(username) && "123456".equals(password)) {
            String token = UUID.randomUUID().toString();
            String redisKey = "LOGIN_TOKEN:" + token;

            // 设置 TTL 为 30 分钟
            ｒｅｄｉｓＵｔｉｌｓ．ｓｅｔ(redisKey, username, Duration.ofMinutes(30));

            return ＲｅｓｐｏｎｓｅＥｎｔｉｔｙ．ｏｋ(token);
        }
        return ＲｅｓｐｏｎｓｅＥｎｔｉｔｙ．ｓｔａｔｕｓ(HttpStatus.UNAUTHORIZED).body("用户名或密码错误");
    }
}

@Component
public class TokenInterceptor implements HandlerInterceptor {

    @Autowired
    private RedisUtils redisUtils;

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws IOException {
        String token = request.getHeader("Authorization");
        if (token == null || token.isEmpty()) {
            response.sendError(ＨｔｔｐＳｔａｔｕｓ．ＵＮＡＵＴＨＯＲＩＺＥＤ．ｖａｌｕｅ(), "缺少 Token");
            return false;
        }

        String redisKey = "LOGIN_TOKEN:" + token;
        String username = ｒｅｄｉｓＵｔｉｌｓ．ｇｅｔ(redisKey);

        if (username == null) {
            response.sendError(ＨｔｔｐＳｔａｔｕｓ．ＵＮＡＵＴＨＯＲＩＺＥＤ．ｖａｌｕｅ(), "Token 无效或已过期");
            return false;
        }

        // 刷新 TTL（滑动过期）
        ｒｅｄｉｓＵｔｉｌｓ．ｅｘｐｉｒｅ(redisKey, Duration.ofMinutes(30));

        // 可设置当前登录用户上下文
        request.setAttribute("currentUser", username);
        return true;
    }
}

@Component
public class RedisUtils {

    @Autowired
    private StringRedisTemplate redisTemplate;

    public void set(String key, String value, Duration ttl) {
        redisTemplate.opsForValue().set(key, value, ttl);
    }

    public String get(String key) {
        return redisTemplate.opsForValue().get(key);
    }

    public void expire(String key, Duration ttl) {
        ｒｅｄｉｓＴｅｍｐｌａｔｅ．ｅｘｐｉｒｅ(key, ttl);
    }
}