前言

企业智能知识库系统是一个微服务架构下的多租户知识管理平台,涉及文档管理、AI 对话、文件处理、统计分析等多个功能模块。认证与授权体系需要解决四个核心问题:

  1. 谁在用:用户身份认证,确保每个请求都能追溯到具体用户
  2. 能做什么:细粒度的功能权限控制,管理员可以管理用户,编辑者可以写文档,审核员可以审批
  3. 跨服务传递:在微服务架构下,用户身份需要从 kb-user-auth 传递到 kb-document、kb-ai、kb-file 等多个服务
  4. 前端安全:React 前端的路由守卫、菜单权限、Token 自动刷新

本系统的认证体系基于 JWT(JSON Web Token)无状态认证 + RBAC(基于角色的访问控制) 模型,支持 Token 自动刷新、黑名单注销、跨服务身份传播、以及前端路由和 UI 元素的权限控制。

1. 一次登录走完发生了什么

用户在前端输入用户名和密码,点击登录,系统执行以下链路:

用户输入 admin / 123456,点击登录
  → LoginPage → authService.login({ username, password })
  → POST /auth/login → AuthController.login()
  → UserServiceImpl.login()
       ├── 查询用户:UserMapper.selectByUsername("admin")
       ├── 密码验证:BCryptPasswordEncoder.matches(password, hash)
       ├── 状态检查:status == 1(正常)
       ├── 加载角色:UserMapper.selectUserRoles(userId) → ["ROLE_SUPER_ADMIN"]
       ├── 加载权限:UserMapper.selectUserPermissions(userId)
       │     → ["document:list", "document:create", ..., "system:settings"]
       ├── 生成JWT:JwtTokenUtil.generateToken(userId, username, roles, permissions)
       │     → Header: {"alg": "HS256"}, Payload: {sub, username, roles, permissions, exp}
       │     → 签名:HMAC-SHA256(header.payload, secret)
       └── 返回 LoginVO: { accessToken, refreshToken, userInfo }
  → 前端 tokenStorage.saveToken(loginResponse)
       ├── Cookie: access_token, refresh_token(SameSite=Lax)
       └── localStorage: token, user_info(兜底存储)
  → useAuthStore: set({ user, token, isAuthenticated: true })
  → 页面跳转至首页,MainLayout 根据权限渲染菜单
完整登录序列图见 4.4 登录与注册完整序列图。

2. 数据库设计:用户、角色、权限模型

2.1 ER 关系

图片.png

  • N:M 关系:用户 ↔ 角色(kb_user_role),角色 ↔ 权限(kb_role_permission)
  • 权限计算:用户的最终权限 = 所有角色的权限并集 + 直接分配的权限

2.2 建表 SQL

-- 用户表
CREATE TABLE kb_user (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    password VARCHAR(255) NOT NULL,       -- BCrypt 哈希
    nickname VARCHAR(50),
    email VARCHAR(100),
    phone VARCHAR(20),
    avatar VARCHAR(500),
    status TINYINT DEFAULT 1,            -- 0=禁用, 1=正常, 2=锁定
    last_login_time DATETIME,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted TINYINT DEFAULT 0            -- 逻辑删除
);

-- 角色表
CREATE TABLE kb_role (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    role_code VARCHAR(50) NOT NULL UNIQUE,  -- ROLE_SUPER_ADMIN, ROLE_ADMIN, ROLE_REVIEWER
    role_name VARCHAR(100) NOT NULL,        -- 超级管理员, 管理员, 审核员
    description VARCHAR(255),
    status TINYINT DEFAULT 1,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- 权限表
CREATE TABLE kb_permission (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    permission_code VARCHAR(100) NOT NULL UNIQUE,  -- document:create, system:user
    permission_name VARCHAR(100) NOT NULL,          -- 文档创建, 用户管理
    module VARCHAR(50),                             -- 文档管理, 系统管理
    description VARCHAR(255),
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- 用户-角色关联表
CREATE TABLE kb_user_role (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    user_id BIGINT NOT NULL,
    role_id BIGINT NOT NULL,
    UNIQUE KEY uk_user_role (user_id, role_id)
);

-- 角色-权限关联表
CREATE TABLE kb_role_permission (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    role_id BIGINT NOT NULL,
    permission_id BIGINT NOT NULL,
    UNIQUE KEY uk_role_permission (role_id, permission_id)
);

-- Token 黑名单表
CREATE TABLE token_blacklist (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    token_id VARCHAR(255) NOT NULL,       -- JWT jti
    user_id BIGINT NOT NULL,
    expiration_time DATETIME NOT NULL,    -- 过期后自动清理
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_expiration (expiration_time)
);

2.3 种子数据:权限定义

-- 文档管理权限
INSERT INTO kb_permission (permission_code, permission_name, module) VALUES
('document:list',     '文档列表查看',   '文档管理'),
('document:create',   '文档创建',       '文档管理'),
('document:edit',     '文档编辑',       '文档管理'),
('document:delete',   '文档删除',       '文档管理'),
('document:review',   '文档审核',       '文档管理'),
('document:category', '文档分类管理',   '文档管理'),
('document:tag',      '文档标签管理',   '文档管理'),
('document:version',  '文档版本管理',   '文档管理');

-- 系统管理权限
INSERT INTO kb_permission (permission_code, permission_name, module) VALUES
('system:user',                '用户管理',       '系统管理'),
('system:role',                '角色管理',       '系统管理'),
('system:permission',          '权限查看',       '系统管理'),
('system:permission:create',   '创建权限',       '系统管理'),
('system:permission:edit',     '编辑权限',       '系统管理'),
('system:permission:delete',   '删除权限',       '系统管理'),
('system:team',                '团队管理',       '系统管理'),
('system:statistics',          '统计分析',       '系统管理'),
('system:settings',            '系统设置',       '系统管理');

2.4 种子数据:角色定义

role\_coderole\_name说明
ROLE\_SUPER\_ADMIN超级管理员全部权限,跳过所有权限检查
ROLE\_ADMIN管理员文档管理 + 系统管理全部权限
ROLE\_REVIEWER审核员文档查看 + 审核
ROLE\_EDITOR编辑者文档 CRUD
ROLE\_VIEWER普通用户文档查看

2.5 设计考量

维度选择理由
ID 策略Snowflake 分布式 ID微服务多实例部署不冲突
逻辑删除deleted = 1保留历史数据,支持审计追溯
角色编码ROLE_ 前缀Spring Security hasRole() 自动添加前缀
权限编码module:action 格式命名空间隔离,易读易扩展
Token 黑名单独立表 + 过期时间索引定时清理过期记录,不无限膨胀

3. JWT 令牌体系:生成、解析、刷新、注销

3.1 JWT 配置

// kb-common/src/main/java/com/knowledge/base/common/config/JwtConfig.java
@ConfigurationProperties(prefix = "jwt")
@Component
@Data
public class JwtConfig {
    private String secret;             // HMAC-SHA256 签名密钥
    private long expiration;           // Access Token 有效期(毫秒)
    private String issuer;             // 签发者标识
    private long refreshExpiration;    // Refresh Token 有效期(毫秒)
}
# application.yml
jwt:
  secret: ${JWT_SECRET:your-256-bit-secret-key-here}
  expiration: 86400000           # 24 小时
  issuer: knowledge-base
  refresh-expiration: 604800000  # 7 天

3.2 JwtTokenUtil:令牌工厂

// kb-common/src/main/java/com/knowledge/base/common/utils/JwtTokenUtil.java
@Component
public class JwtTokenUtil {

    @Resource
    private JwtConfig jwtConfig;

    // ======================== 令牌生成 ========================

    public String generateToken(Long userId, String username,
                                 List<String> roles, List<String> permissions) {
        Date now = new Date();
        Date expiration = new Date(now.getTime() + jwtConfig.getExpiration());

        return Jwts.builder()
            .setSubject(String.valueOf(userId))         // sub = 用户ID
            .claim("username", username)                // 自定义声明
            .claim("roles", roles)
            .claim("permissions", permissions)
            .setIssuer(jwtConfig.getIssuer())
            .setIssuedAt(now)                           // iat
            .setExpiration(expiration)                  // exp
            .setId(UUID.randomUUID().toString())        // jti(用于黑名单)
            .signWith(getSigningKey(), SignatureAlgorithm.HS256)
            .compact();
    }

    public String generateRefreshToken(Long userId) {
        Date now = new Date();
        Date expiration = new Date(now.getTime() + jwtConfig.getRefreshExpiration());
        return Jwts.builder()
            .setSubject(String.valueOf(userId))
            .setIssuer(jwtConfig.getIssuer())
            .setIssuedAt(now)
            .setExpiration(expiration)
            .signWith(getSigningKey(), SignatureAlgorithm.HS256)
            .compact();
    }

    // ======================== 令牌解析 ========================

    public Claims parseToken(String token) {
        return Jwts.parserBuilder()
            .setSigningKey(getSigningKey())
            .build()
            .parseClaimsJws(token)
            .getBody();
    }

    public boolean validateToken(String token) {
        try {
            Claims claims = parseToken(token);
            return !claims.getExpiration().before(new Date())
                && jwtConfig.getIssuer().equals(claims.getIssuer());
        } catch (Exception e) {
            return false;
        }
    }

    // ======================== 从 Token 提取信息 ========================

    public Long getUserIdFromToken(String token) {
        return Long.parseLong(parseToken(token).getSubject());
    }

    public String getUsernameFromToken(String token) {
        return parseToken(token).get("username", String.class);
    }

    @SuppressWarnings("unchecked")
    public List<String> getRolesFromToken(String token) {
        return parseToken(token).get("roles", List.class);
    }

    @SuppressWarnings("unchecked")
    public List<String> getPermissionsFromToken(String token) {
        return parseToken(token).get("permissions", List.class);
    }

    public String getJtiFromToken(String token) {
        return parseToken(token).getId();
    }

    private Key getSigningKey() {
        return Keys.hmacShaKeyFor(jwtConfig.getSecret().getBytes(StandardCharsets.UTF_8));
    }
}

3.3 JWT Payload 结构

{
  "sub": "327396046936346624",
  "username": "admin",
  "roles": ["ROLE_SUPER_ADMIN"],
  "permissions": [
    "document:list", "document:create", "document:edit", "document:delete",
    "document:review", "document:category", "document:tag", "document:version",
    "system:user", "system:role", "system:permission",
    "system:team", "system:statistics", "system:settings"
  ],
  "iss": "knowledge-base",
  "iat": 1719158400,
  "exp": 1719244800,
  "jti": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

3.4 Token 刷新与注销流程

图片.png

刷新关键设计:刷新时重新从数据库加载用户角色和权限,确保权限变更即时生效。

3.5 设计考量

维度选择理由
签名算法HMAC-SHA256对称密钥,仅服务端持有,无需公钥基础设施
权限内嵌Token是避免每次请求都查询数据库,降低延迟
Token 不存储Access Token 不存数据库无状态,水平扩展友好
黑名单注销jti + 过期时间不立即删除 Token,等自然过期后清理记录
Refresh Token独立生成,更长有效期减少密码输入频率,提升用户体验

4. 登录与注册:认证服务核心流程

4.1 数据对象

// 请求:LoginDTO
public class LoginDTO {
    @NotBlank(message = "用户名不能为空")
    private String username;

    @NotBlank(message = "密码不能为空")
    private String password;
}

// 请求:RegisterDTO
public class RegisterDTO {
    @NotBlank(message = "用户名不能为空")
    private String username;

    @NotBlank(message = "密码不能为空")
    @Size(min = 6, message = "密码长度不能少于6位")
    private String password;

    @NotBlank(message = "确认密码不能为空")
    private String confirmPassword;

    @Email(message = "邮箱格式不正确")
    private String email;

    @NotBlank(message = "真实姓名不能为空")
    private String realName;

    private String phone;
    private String teamId;          // 注册时归属团队
}

// 响应:LoginVO
public class LoginVO {
    private String accessToken;           // JWT
    private String refreshToken;          // 刷新令牌
    private String tokenType = "Bearer";
    private Long expiresIn;               // 过期时间(秒)
    private UserVO userInfo;              // 用户信息(含角色和权限)
}

// 用户视图:UserVO
public class UserVO {
    private Long id;
    private String username;
    private String nickname;
    private String email;
    private String phone;
    private String avatar;
    private Integer status;
    private List<String> roles;           // ["ROLE_SUPER_ADMIN"]
    private List<String> permissions;     // ["document:create", ...]
}

4.2 登录实现

// kb-user-auth/.../service/impl/UserServiceImpl.java
@Override
public LoginVO login(String username, String password) {
    // Step 1: 查询用户
    User user = userMapper.selectOne(
        new LambdaQueryWrapper<User>()
            .eq(User::getUsername, username)
            .eq(User::getDeleted, 0)
    );
    if (user == null) {
        throw new BusinessException(ResultCode.USER_NOT_FOUND);
    }

    // Step 2: 验证密码(BCrypt)
    if (!passwordEncoder.matches(password, user.getPassword())) {
        throw new BusinessException(ResultCode.PASSWORD_ERROR);
    }

    // Step 3: 检查用户状态
    if (user.getStatus() != UserStatus.NORMAL.getCode()) {
        throw new BusinessException(
            user.getStatus() == UserStatus.DISABLED.getCode()
                ? ResultCode.USER_DISABLED
                : ResultCode.USER_LOCKED
        );
    }

    // Step 4: 加载角色
    List<String> roles = userMapper.selectUserRoles(user.getId());

    // Step 5: 加载权限(角色权限 + 直接权限取并集)
    List<String> permissions = getUserPermissions(user.getId());

    // Step 6: 生成 JWT
    String accessToken = jwtTokenUtil.generateToken(
        user.getId(), user.getUsername(), roles, permissions);
    String refreshToken = jwtTokenUtil.generateRefreshToken(user.getId());

    // Step 7: 更新最后登录时间
    user.setLastLoginTime(LocalDateTime.now());
    userMapper.updateById(user);

    // Step 8: 构建响应
    LoginVO loginVO = new LoginVO();
    loginVO.setAccessToken(accessToken);
    loginVO.setRefreshToken(refreshToken);
    loginVO.setExpiresIn(jwtConfig.getExpiration() / 1000);
    loginVO.setUserInfo(buildUserVO(user, roles, permissions));

    return loginVO;
}

4.3 注册实现

@Override
public RegisterVO register(RegisterDTO dto) {
    // Step 1: 校验两次密码一致
    if (!dto.getPassword().equals(dto.getConfirmPassword())) {
        throw new BusinessException("两次输入的密码不一致");
    }

    // Step 2: 检查用户名和邮箱唯一性
    if (userMapper.selectCount(
            new LambdaQueryWrapper<User>().eq(User::getUsername, dto.getUsername())) > 0) {
        throw new BusinessException("用户名已存在");
    }

    // Step 3: 创建用户(BCrypt 加密密码)
    User user = new User();
    user.setId(SnowflakeIdGenerator.getInstance().nextId());
    user.setUsername(dto.getUsername());
    user.setPassword(passwordEncoder.encode(dto.getPassword()));
    user.setNickname(dto.getRealName());
    user.setEmail(dto.getEmail());
    user.setPhone(dto.getPhone());
    user.setStatus(UserStatus.NORMAL.getCode());
    userMapper.insert(user);

    // Step 4: 分配默认角色(ROLE_VIEWER)
    Role viewerRole = roleMapper.selectOne(
        new LambdaQueryWrapper<Role>().eq(Role::getRoleCode, "ROLE_VIEWER"));
    if (viewerRole != null) {
        UserRole userRole = new UserRole();
        userRole.setUserId(user.getId());
        userRole.setRoleId(viewerRole.getId());
        userRoleMapper.insert(userRole);
    }

    return RegisterVO.builder()
        .userId(user.getId())
        .message("注册成功")
        .build();
}

4.4 登录与注册完整序列图

图片.png


5. Spring Security 过滤器链

5.1 kb-user-auth 安全配置

// kb-user-auth/src/main/java/com/knowledge/base/userauth/config/SecurityConfig.java
@Configuration
@EnableWebSecurity
@EnableMethodSecurity
public class SecurityConfig {

    @Resource
    private JwtAuthenticationFilter jwtAuthenticationFilter;

    @Resource
    private CustomAuthenticationEntryPoint authenticationEntryPoint;

    @Resource
    private CustomAccessDeniedHandler accessDeniedHandler;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // 1. 禁用 CSRF(API 服务无 Cookie 会话)
            .csrf(AbstractHttpConfigurer::disable)

            // 2. 无状态会话(JWT 自带身份信息)
            .sessionManagement(session ->
                session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))

            // 3. URL 白名单
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(
                    "/auth/login",           // 登录
                    "/auth/register",        // 注册
                    "/auth/refresh",         // 刷新令牌
                    "/auth/forgot-password", // 忘记密码
                    "/auth/reset-password"   // 重置密码
                ).permitAll()
                .requestMatchers("/auth/validate/**").permitAll()  // 内部 Feign
                .requestMatchers(HttpMethod.OPTIONS).permitAll()   // CORS 预检
                .anyRequest().authenticated()
            )

            // 4. 添加 JWT 过滤器(在 UsernamePasswordAuthenticationFilter 之前)
            .addFilterBefore(jwtAuthenticationFilter,
                UsernamePasswordAuthenticationFilter.class)

            // 5. 异常处理
            .exceptionHandling(ex -> ex
                .authenticationEntryPoint(authenticationEntryPoint)  // 401
                .accessDeniedHandler(accessDeniedHandler)            // 403
            );

        return http.build();
    }
}

5.2 JWT 认证过滤器

// kb-user-auth/.../filter/JwtAuthenticationFilter.java
@Component
public class JwtAuthenticationFilter extends OncePerRequestFilter {

    @Resource
    private JwtTokenUtil jwtTokenUtil;

    @Override
    protected void doFilterInternal(
            HttpServletRequest request, HttpServletResponse response,
            FilterChain filterChain) throws ServletException, IOException {

        String authHeader = request.getHeader("Authorization");

        if (authHeader != null && authHeader.startsWith("Bearer ")) {
            String token = authHeader.substring(7);

            if (jwtTokenUtil.validateToken(token)) {
                // 从 Token 中提取身份信息
                Long userId = jwtTokenUtil.getUserIdFromToken(token);
                String username = jwtTokenUtil.getUsernameFromToken(token);
                List<String> roles = jwtTokenUtil.getRolesFromToken(token);
                List<String> permissions = jwtTokenUtil.getPermissionsFromToken(token);

                // 构建 Spring Security 认证对象
                List<SimpleGrantedAuthority> authorities = new ArrayList<>();
                for (String role : roles) {
                    authorities.add(new SimpleGrantedAuthority(role));
                }

                UsernamePasswordAuthenticationToken authentication =
                    new UsernamePasswordAuthenticationToken(userId, null, authorities);
                // 将权限列表附加到 details 中(供 @PreAuthorize 使用)
                authentication.setDetails(permissions);

                SecurityContextHolder.getContext().setAuthentication(authentication);

                // 设置 ThreadLocal 上下文
                UserContextUtil.setUserId(userId);
                UserContextUtil.setUsername(username);
            }
        }

        try {
            filterChain.doFilter(request, response);
        } finally {
            // 清理 ThreadLocal,防止内存泄漏
            UserContextUtil.clear();
        }
    }
}

5.3 过滤器链执行顺序

图片.png

5.4 kb-document 服务的过滤器差异

kb-document 有自己的 JwtAuthenticationFilter,与 kb-user-auth 版本的核心差异:

维度kb-user-auth 版本kb-document 版本
权限降级无权限为空时授予 document:list + document:category:query
UserContext设置基础 Context额外提取 username 和 avatar
Token 来源Bearer HeaderBearer Header → Cookie access_token
网关兜底无支持 X-User-Id Header(网关已验证 JWT 后填充)

6. 跨服务认证:Feign 拦截器与上下文传播

6.1 架构

微服务之间通过 Feign 调用时,需要自动传播用户身份,下游服务才能知道"当前是谁在操作"。

图片.png

6.2 Feign 拦截器

// kb-common/src/main/java/com/knowledge/base/common/feign/FeignInterceptorConfig.java
@Configuration
public class FeignInterceptorConfig {

    @Bean
    public RequestInterceptor requestInterceptor() {
        return requestTemplate -> {
            // 从 ThreadLocal 中获取当前 Token
            String token = UserContextUtil.getToken();
            if (token != null && !token.isEmpty()) {
                requestTemplate.header("Authorization", "Bearer " + token);
            }

            // 同时传递用户 ID(兜底方案)
            Long userId = UserContextUtil.getUserId();
            if (userId != null) {
                requestTemplate.header("X-User-Id", String.valueOf(userId));
            }
        };
    }
}

6.3 UserContextUtil:ThreadLocal 上下文

// kb-common/src/main/java/com/knowledge/base/common/utils/UserContextUtil.java
public class UserContextUtil {

    private static final ThreadLocal<Long> userIdHolder = new ThreadLocal<>();
    private static final ThreadLocal<String> usernameHolder = new ThreadLocal<>();
    private static final ThreadLocal<String> tokenHolder = new ThreadLocal<>();
    private static final ThreadLocal<String> avatarHolder = new ThreadLocal<>();

    // ======================== 设置 ========================

    public static void setUserId(Long userId) { userIdHolder.set(userId); }
    public static void setUsername(String username) { usernameHolder.set(username); }
    public static void setToken(String token) { tokenHolder.set(token); }
    public static void setAvatar(String avatar) { avatarHolder.set(avatar); }

    // ======================== 获取 ========================

    public static Long getUserId() { return userIdHolder.get(); }
    public static String getUsername() { return usernameHolder.get(); }
    public static String getToken() { return tokenHolder.get(); }
    public static String getAvatar() { return avatarHolder.get(); }

    // ======================== 清理 ========================

    public static void clear() {
        userIdHolder.remove();
        usernameHolder.remove();
        tokenHolder.remove();
        avatarHolder.remove();
    }
}

6.4 Token 验证 Feign 接口

// kb-document/.../client/UserServiceClient.java
@FeignClient(name = "kb-user-auth", path = "/auth")
public interface UserServiceClient {

    // 验证 Token(供其他服务确认用户身份)
    @GetMapping("/validate")
    TokenValidateVO validateToken(
        @RequestHeader("Authorization") String authorization,
        @RequestParam("token") String token
    );

    // 查询用户权限(供 JWT 过滤器使用)
    @GetMapping("/user/permissions/{userId}")
    List<String> getUserPermissions(
        @PathVariable Long userId,
        @RequestHeader("Authorization") String authorization
    );

    // 查询指定角色的用户ID列表(供审核通知使用)
    @GetMapping("/user/role/{roleCode}/user-ids")
    List<Long> getUserIdsByRole(
        @PathVariable String roleCode
    );
}

关键设计:@RequestHeader("Authorization") 由 FeignInterceptorConfig 自动注入,无需调用方手动传递。


7. 前端认证:Token 存储、自动刷新、路由守卫

7.1 Token 存储策略

前端采用 Cookie 优先 + localStorage 兜底 的双重存储策略:

// src/utils/token-storage.ts
export const tokenStorage = {
    // ===== 保存 =====
    saveToken(response: LoginResponse): void {
        const accessExpires = new Date(Date.now() + response.expiresIn * 1000);

        // 主存储:Cookie(SameSite=Lax,防止 CSRF)
        cookieManager.set('access_token', response.accessToken, {
            expires: accessExpires,
            path: '/',
            sameSite: 'lax',
        });
        cookieManager.set('refresh_token', response.refreshToken, {
            expires: new Date(Date.now() + 7 * 24 * 3600 * 1000),
            path: '/',
            sameSite: 'lax',
        });

        // 兜底存储:localStorage
        localStorage.setItem('kb_access_token', response.accessToken);
        localStorage.setItem('kb_refresh_token', response.refreshToken);
        localStorage.setItem('kb_token_type', response.tokenType);
        localStorage.setItem('kb_expires_at', accessExpires.toISOString());
        localStorage.setItem('kb_user_info', JSON.stringify(response.userInfo));
    },

    // ===== 读取 =====
    getAccessToken(): string | null {
        return cookieManager.get('access_token')
            || localStorage.getItem('kb_access_token');
    },

    getAuthorizationHeader(): string {
        const token = this.getAccessToken();
        return token ? `Bearer ${token}` : '';
    },

    // ===== 过期检查 =====
    isTokenExpiring(bufferSeconds = 300): boolean {
        const expiresAt = localStorage.getItem('kb_expires_at');
        if (!expiresAt) return true;
        return new Date(expiresAt).getTime() - Date.now() < bufferSeconds * 1000;
    },

    // ===== 清除 =====
    clearToken(): void {
        cookieManager.remove('access_token', { path: '/' });
        cookieManager.remove('refresh_token', { path: '/' });
        localStorage.removeItem('kb_access_token');
        localStorage.removeItem('kb_refresh_token');
        localStorage.removeItem('kb_token_type');
        localStorage.removeItem('kb_expires_at');
        localStorage.removeItem('kb_user_info');
    },
};

7.2 Axios 拦截器:自动刷新

// src/services/request.ts
let isRefreshing = false;
let failedRequestsQueue: Array<{ resolve, reject }> = [];

request.interceptors.request.use((config) => {
    // 跳过无需认证的请求
    if (!config.headers?.['skipAuth']) {
        config.headers.Authorization = tokenStorage.getAuthorizationHeader();
    }
    return config;
});

request.interceptors.response.use(
    (response) => {
        // 统一解包:response.data.data
        return response.data?.data ?? response.data;
    },
    async (error) => {
        const { response, config } = error;

        // === 401:尝试刷新 Token ===
        if (response?.status === 401 && !config._retry) {
            if (isRefreshing) {
                // 已有刷新请求在进行中,排队等待
                return new Promise((resolve, reject) => {
                    failedRequestsQueue.push({ resolve, reject });
                }).then((newToken) => {
                    config.headers.Authorization = `Bearer ${newToken}`;
                    return request(config);
                });
            }

            config._retry = true;
            isRefreshing = true;

            try {
                const refreshToken = tokenStorage.getRefreshToken();
                const newResponse = await authService.refreshToken(refreshToken);
                tokenStorage.updateToken(newResponse);

                // 重放队列中等待的请求
                failedRequestsQueue.forEach(({ resolve }) =>
                    resolve(newResponse.accessToken));
                failedRequestsQueue = [];

                config.headers.Authorization = `Bearer ${newResponse.accessToken}`;
                return request(config);
            } catch (refreshError) {
                failedRequestsQueue.forEach(({ reject }) => reject(refreshError));
                failedRequestsQueue = [];
                authStore.getState().clearAuth();
                window.location.href = '/login';
            } finally {
                isRefreshing = false;
            }
        }

        // === 403:权限不足 ===
        if (response?.status === 403) {
            message.error('权限不足,无法执行此操作');
        }

        return Promise.reject(error);
    }
);

7.3 Zustand 认证 Store

// src/stores/auth.store.ts
export const useAuthStore = create<AuthState>()(
    persist(
        (set, get) => ({
            user: null as User | null,
            token: null as string | null,
            isAuthenticated: false,
            isLoading: false,

            login: async (username: string, password: string) => {
                set({ isLoading: true });
                try {
                    const response = await authService.login({ username, password });
                    tokenStorage.saveToken(response);
                    const user = normalizeLoginUser(response.userInfo);
                    set({
                        user,
                        token: response.accessToken,
                        isAuthenticated: true,
                        isLoading: false,
                    });
                } catch (error) {
                    set({ isLoading: false });
                    throw error;
                }
            },

            logout: async () => {
                try { await authService.logout(); } catch { /* 忽略 */ }
                tokenStorage.clearToken();
                set({ user: null, token: null, isAuthenticated: false });
            },

            checkAuth: async () => {
                const token = tokenStorage.getAccessToken();
                if (!token) return;
                try {
                    const user = await authService.getCurrentUser();
                    set({ user: normalizeLoginUser(user), isAuthenticated: true });
                } catch {
                    // Token 已过期或无效,清除
                    tokenStorage.clearToken();
                    set({ user: null, token: null, isAuthenticated: false });
                }
            },
        }),
        {
            name: 'auth-storage',
            // 仅持久化这三个字段到 localStorage
            partialize: (state) => ({
                user: state.user,
                token: state.token,
                isAuthenticated: state.isAuthenticated,
            }),
        }
    )
);

7.4 路由守卫

// src/router/index.tsx
const ProtectedRoute: React.FC<{
    children: React.ReactNode;
    requireAdmin?: boolean;           // 需要管理后台权限
    requiredPermissions?: string[];   // 需要特定权限
    requireAllPermissions?: boolean;  // 需要全部满足(默认任一满足)
}> = ({ children, requireAdmin, requiredPermissions, requireAllPermissions }) => {
    const token = tokenStorage.getAccessToken();
    const user = getStoredUser();   // 从 tokenStorage 反序列化

    // 1. 未登录 → 跳转登录页
    if (!token) {
        return <Navigate to="/login" replace />;
    }

    // 2. 需要管理员权限但用户没有
    if (requireAdmin && !hasAdminAccess(user)) {
        return <Navigate to="/" replace />;
    }

    // 3. 需要特定权限
    if (requiredPermissions && requiredPermissions.length > 0) {
        const hasAccess = requireAllPermissions
            ? hasAllPermissions(user, requiredPermissions)
            : hasAnyPermission(user, requiredPermissions);
        if (!hasAccess) {
            return <Navigate to="/" replace />;
        }
    }

    return <>{children}</>;
};

路由权限配置示例:

// 仅登录可访问
<Route path="/" element={<ProtectedRoute><DashboardPage /></ProtectedRoute>} />

// 需要管理后台权限
<Route path="/admin" element={<ProtectedRoute requireAdmin>
    <AdminCenterPage /></ProtectedRoute>} />

// 需要特定权限
<Route path="/documents/new" element={
    <ProtectedRoute requiredPermissions={['document:create']}>
        <CreateDocumentPage />
    </ProtectedRoute>
} />

// 公开路由
<Route path="/login" element={<LoginPage />} />

8. 权限模型:RBAC 与前端权限控制

8.1 权限编码体系

模块权限编码说明
文档管理document:list查看文档列表
文档管理document:create创建文档
文档管理document:edit编辑文档
文档管理document:delete删除文档
文档管理document:review审核文档
文档管理document:category管理分类
文档管理document:category:query查看分类
文档管理document:tag管理标签
文档管理document:version管理版本
系统管理system:user管理用户
系统管理system:role管理角色
系统管理system:permission查看权限
系统管理system:permission:create创建权限
系统管理system:permission:edit编辑权限
系统管理system:permission:delete删除权限
系统管理system:team管理团队
系统管理system:statistics查看统计
系统管理system:settings系统设置

8.2 前端权限工具

// src/utils/permission.ts

// 权限常量映射
export const PERMISSIONS = {
    documentList: 'document:list',
    documentCreate: 'document:create',
    documentEdit: 'document:edit',
    documentDelete: 'document:delete',
    documentReview: 'document:review',
    documentCategory: 'document:category',
    documentCategoryQuery: 'document:category:query',
    documentTag: 'document:tag',
    documentVersion: 'document:version',
    systemUser: 'system:user',
    systemRole: 'system:role',
    systemPermission: 'system:permission',
    systemTeam: 'system:team',
    systemStatistics: 'system:statistics',
    systemSettings: 'system:settings',
} as const;

// 管理后台权限集合
export const ADMIN_PERMISSION_CODES = [
    PERMISSIONS.systemUser,
    PERMISSIONS.systemRole,
    PERMISSIONS.systemPermission,
    PERMISSIONS.systemTeam,
    PERMISSIONS.systemStatistics,
    PERMISSIONS.systemSettings,
    PERMISSIONS.documentCategory,
    PERMISSIONS.documentReview,
];

// 权限检查函数
export function getUserPermissions(user: User | null): string[] {
    return user?.permissions || [];
}

export function isSuperAdmin(user: User | null): boolean {
    return user?.roles?.includes('ROLE_SUPER_ADMIN') || false;
}

export function hasPermission(user: User | null, permission: string): boolean {
    if (!user) return false;
    if (isSuperAdmin(user)) return true;          // 超级管理员绕过所有检查
    return getUserPermissions(user).includes(permission);
}

export function hasAnyPermission(user: User | null, permissions: string[]): boolean {
    if (!user) return false;
    if (isSuperAdmin(user)) return true;
    return permissions.some(p => getUserPermissions(user).includes(p));
}

export function hasAllPermissions(user: User | null, permissions: string[]): boolean {
    if (!user) return false;
    if (isSuperAdmin(user)) return true;
    return permissions.every(p => getUserPermissions(user).includes(p));
}

export function hasAdminAccess(user: User | null): boolean {
    return hasAnyPermission(user, ADMIN_PERMISSION_CODES);
}

// 角色标签
export function getPrimaryRoleLabel(user: User | null): string {
    if (!user) return '';
    if (isSuperAdmin(user)) return '超级管理员';
    if (user.roles?.includes('ROLE_ADMIN')) return '管理员';
    if (user.roles?.includes('ROLE_REVIEWER')) return '审核员';
    if (user.roles?.includes('ROLE_EDITOR')) return '编辑者';
    return '知识成员';
}

8.3 前端 UI 权限控制示例

// src/components/layout/MainLayout.tsx

// 顶部导航:条件渲染"文件管理"
{hasPermission(user, PERMISSIONS.documentList) && (
    <span className="nav-link" onClick={() => navigate('/files')}>
        文件管理
    </span>
)}

// 侧边栏:条件渲染"待审核"
{hasPermission(user, PERMISSIONS.documentReview) && (
    <Menu.Item key="/admin/review">
        <AuditOutlined /> 待审核
    </Menu.Item>
)}

// 管理后台下拉菜单:条件渲染
const showAdminMenu = hasAdminAccess(user);

// 管理子菜单项:按具体权限门控
{hasPermission(user, PERMISSIONS.systemUser) && (
    <Menu.Item key="/admin/users">用户管理</Menu.Item>
)}
{hasPermission(user, PERMISSIONS.systemRole) && (
    <Menu.Item key="/admin/roles">角色管理</Menu.Item>
)}
{hasPermission(user, PERMISSIONS.systemPermission) && (
    <Menu.Item key="/admin/permissions">权限管理</Menu.Item>
)}

9. 安全加固与异常处理

9.1 密码安全

措施实现
哈希算法BCrypt(BCryptPasswordEncoder),自适应盐值
传输加密HTTPS(生产环境必需)
密码强度注册时最小 6 位(@Size(min = 6))
错误统一登录失败不区分"用户不存在"和"密码错误"(防枚举)

9.2 Token 安全

措施实现
签名验证每个请求都验证 HMAC-SHA256 签名
过期控制Access Token 24 小时,Refresh Token 7 天
注销即失效jti 写入 token_blacklist,定期查询验证
Cookie SecureSameSite=Lax 防止 CSRF,生产环境加上 Secure
Token ID每个 Token 有唯一 jti,支持精确吊销

9.3 异常处理

// 401:未认证
// kb-common/.../CustomAuthenticationEntryPoint.java
@Component
public class CustomAuthenticationEntryPoint implements AuthenticationEntryPoint {
    @Override
    public void commence(HttpServletRequest request, HttpServletResponse response,
                          AuthenticationException authException) throws IOException {
        response.setContentType("application/json;charset=UTF-8");
        response.setStatus(HttpServletResponse.SC_UNAUTHORIZED);
        response.getWriter().write(
            objectMapper.writeValueAsString(
                Result.error(ResultCode.UNAUTHORIZED)));
    }
}

// 403:无权限
// kb-common/.../CustomAccessDeniedHandler.java
@Component
public class CustomAccessDeniedHandler implements AccessDeniedHandler {
    @Override
    public void handle(HttpServletRequest request, HttpServletResponse response,
                        AccessDeniedException accessDeniedException) throws IOException {
        response.setContentType("application/json;charset=UTF-8");
        response.setStatus(HttpServletResponse.SC_FORBIDDEN);
        response.getWriter().write(
            objectMapper.writeValueAsString(
                Result.error(ResultCode.FORBIDDEN)));
    }
}

// 错误码定义
// kb-common/.../result/ResultCode.java
public enum ResultCode {
    SUCCESS(200, "操作成功"),
    UNAUTHORIZED(401, "未授权,请先登录"),
    FORBIDDEN(403, "禁止访问"),
    USER_NOT_FOUND(10001, "用户不存在"),
    PASSWORD_ERROR(10002, "密码错误"),
    USER_DISABLED(10003, "用户已被禁用"),
    USER_LOCKED(10004, "用户已被锁定"),
    TOKEN_INVALID(10005, "Token无效"),
    TOKEN_EXPIRED(10006, "Token已过期"),
    ACCESS_DENIED(10007, "无权限访问"),
}

9.4 用户状态枚举

// kb-common/.../enums/UserStatus.java
public enum UserStatus {
    DISABLED(0, "禁用"),    // 管理员手动禁用
    NORMAL(1, "正常"),      // 可正常登录
    LOCKED(2, "锁定"),      // 多次密码错误后自动锁定
}

前端对不同状态做不同提示:禁用 → "账号已被禁用,请联系管理员",锁定 → "账号已被锁定,请稍后再试"。


总结

  1. 无状态 JWT:认证信息完全自包含在 Token 中,不需要 Redis 或数据库存储会话。水平扩展时无需共享会话存储。
  2. RBAC 灵活组合:用户通过角色获得权限、也可以直接分配权限。ROLE_SUPER_ADMIN 跳过所有权限检查,适合超级管理员场景。
  3. Token 自动刷新:前端 Axios 拦截器在收到 401 时自动使用 Refresh Token 换新 Token,并有请求排队机制防止并发刷新。用户无感知。
  4. 双重存储:Cookie(SameSite=Lax)+ localStorage,Cookie 自动随请求发送(同域),localStorage 提供兜底和持久化。
  5. Feign Token 传播:FeignInterceptorConfig 自动从 ThreadLocal 读取 Token 并注入到下游请求 Header,业务代码无需关心跨服务调用时的身份传递。
  6. 分层的权限控制:后端 @PreAuthorize → 路由守卫 ProtectedRoute → UI 元素条件渲染。三层防护确保即使前端被绕过,后端仍然有权限检查。
  7. Fail-Safe 设计:kb-document 的 JWT 过滤器在权限查询失败时授予基础读权限(document:list + document:category:query),而非拒绝所有访问。前端获取不到模型列表时使用本地常量降级。

适用场景

此认证授权体系适用于:

  • 微服务架构:需要在多个服务间传递用户身份的场景
  • RBAC 权限管理:需要按角色分配功能权限的企业应用
  • 前后端分离:React SPA + Spring Boot API 的典型架构
  • 中小规模团队:无需复杂 SSO,用户名密码登录即可满足需求
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏