前言
企业智能知识库系统是一个微服务架构下的多租户知识管理平台,涉及文档管理、AI 对话、文件处理、统计分析等多个功能模块。认证与授权体系需要解决四个核心问题:
- 谁在用:用户身份认证,确保每个请求都能追溯到具体用户
- 能做什么:细粒度的功能权限控制,管理员可以管理用户,编辑者可以写文档,审核员可以审批
- 跨服务传递:在微服务架构下,用户身份需要从 kb-user-auth 传递到 kb-document、kb-ai、kb-file 等多个服务
- 前端安全: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 关系

- 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\_code | role\_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 刷新与注销流程

刷新关键设计:刷新时重新从数据库加载用户角色和权限,确保权限变更即时生效。
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 登录与注册完整序列图

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 过滤器链执行顺序

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 Header | Bearer Header → Cookie access_token |
| 网关兜底 | 无 | 支持 X-User-Id Header(网关已验证 JWT 后填充) |
6. 跨服务认证:Feign 拦截器与上下文传播
6.1 架构
微服务之间通过 Feign 调用时,需要自动传播用户身份,下游服务才能知道"当前是谁在操作"。

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 Secure | SameSite=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, "锁定"), // 多次密码错误后自动锁定
}前端对不同状态做不同提示:禁用 → "账号已被禁用,请联系管理员",锁定 → "账号已被锁定,请稍后再试"。
总结
- 无状态 JWT:认证信息完全自包含在 Token 中,不需要 Redis 或数据库存储会话。水平扩展时无需共享会话存储。
- RBAC 灵活组合:用户通过角色获得权限、也可以直接分配权限。
ROLE_SUPER_ADMIN跳过所有权限检查,适合超级管理员场景。 - Token 自动刷新:前端 Axios 拦截器在收到 401 时自动使用 Refresh Token 换新 Token,并有请求排队机制防止并发刷新。用户无感知。
- 双重存储:Cookie(
SameSite=Lax)+ localStorage,Cookie 自动随请求发送(同域),localStorage 提供兜底和持久化。 - Feign Token 传播:
FeignInterceptorConfig自动从ThreadLocal读取 Token 并注入到下游请求 Header,业务代码无需关心跨服务调用时的身份传递。 - 分层的权限控制:后端
@PreAuthorize→ 路由守卫ProtectedRoute→ UI 元素条件渲染。三层防护确保即使前端被绕过,后端仍然有权限检查。 - Fail-Safe 设计:kb-document 的 JWT 过滤器在权限查询失败时授予基础读权限(
document:list+document:category:query),而非拒绝所有访问。前端获取不到模型列表时使用本地常量降级。
适用场景
此认证授权体系适用于:
- 微服务架构:需要在多个服务间传递用户身份的场景
- RBAC 权限管理:需要按角色分配功能权限的企业应用
- 前后端分离:React SPA + Spring Boot API 的典型架构
- 中小规模团队:无需复杂 SSO,用户名密码登录即可满足需求