企业官网建设流程全解析

1. 为什么在 SpringBoot 项目里，Shiro 的登录逻辑总“看起来能跑通，但实际一测就掉链子”

“SpringBoot 整合 Shiro 实现用户名密码登录”——这个标题在技术社区里出现频率极高，几乎每个刚接触权限框架的后端开发者都会搜一遍。我见过太多人照着教程复制粘贴完ShiroConfig、Realm、LoginController，启动项目，输入账号密码点登录，页面跳转成功，控制台没报错，就以为“搞定了”。结果第二天测试发现：

• 输入错误密码，居然也跳转到首页；
• 用户登出后，刷新页面还能看到个人中心；
• 某个接口明明配置了@RequiresAuthentication，却始终不拦截未登录请求；
• 更隐蔽的是，用 Postman 直接调用/login接口传参，返回 200 成功，但后续所有带权限的接口都 401 —— 而前端根本没拿到 session ID。

这些问题不是代码写错了，而是对 Shiro 的认证生命周期和SpringBoot 的自动装配机制存在系统性误读。Shiro 不是“配好 Realm 就完事”的黑盒，它是一套有明确状态流转的认证引擎：Subject（当前用户）→ AuthenticationToken（凭证）→ Authenticator（认证器）→ Realm（数据源）→ AuthenticationInfo（认证结果）→ SecurityManager（全局管理者）。而 SpringBoot 的@EnableWebSecurity或@EnableShiroWeb并不会自动接管这套流程——它只负责把 Shiro 的 Filter 链注入到 Servlet 容器中，真正的认证触发、Session 绑定、RememberMe 处理、异常分发，全靠你手动在 Filter 配置、Realm 实现、Controller 响应之间做精准缝合。

关键词里虽然没写，但实际落地时绕不开三个核心矛盾：

• Filter 顺序冲突：Shiro 的ShiroFilterFactoryBean必须排在 Spring Security 的 Filter 之前（如果共存），更要早于 SpringBoot 默认的CharacterEncodingFilter和HiddenHttpMethodFilter，否则 POST 表单参数可能被提前消费；
• Subject 线程绑定失效：SpringBoot 的异步线程池（如@Async方法）默认不继承主线程的Subject，导致在 Service 层调用SecurityUtils.getSubject().getPrincipal()返回 null；
• 密码比对逻辑被静默绕过：很多教程直接让 Realm 返回SimpleAuthenticationInfo，却没重写doGetAuthenticationInfo中的盐值处理、密码加密方式匹配、账户状态校验（如是否禁用、是否过期），导致Authenticator根本没走到密码比对环节就抛出UnknownAccountException，而 Controller 又没捕获该异常，最终返回 200 空响应。

这不是 Shiro 的缺陷，而是开发者常把“整合”误解为“堆砌”。真正要打通的，是 SpringBoot 的 Bean 生命周期管理、Servlet 的 Filter 执行链、Shiro 的 Subject 上下文传递、以及业务层对认证状态的显式感知这四条线。下面我们就从最基础的登录入口开始，一层层拆开看，每一处配置背后，到底在解决什么问题、不配又会引发什么连锁反应。

2. 登录入口的三重门：Controller 层如何与 Shiro 的认证流程形成闭环

很多人以为登录就是 Controller 接收表单、调用subject.login(token)、然后重定向。但实际生产环境里，一个健壮的登录入口必须同时应对三种典型场景：浏览器表单提交、Ajax 异步登录、以及第三方系统通过 API 调用。这三者对 Shiro 的调用方式、异常处理、响应格式要求完全不同。我们先看最基础的浏览器表单场景，再延伸到其他两种。

2.1 浏览器表单提交：为什么不能直接 return "redirect:/home"

假设你写了这样一个 Controller：

@PostMapping("/login") public String login(String username, String password) { Subject subject = SecurityUtils.getSubject(); UsernamePasswordToken token = new UsernamePasswordToken(username, password); subject.login(token); return "redirect:/home"; }

表面看没问题，但实测会发现：无论用户名密码是否正确，都跳转到/home。原因在于subject.login(token)抛出的异常（如IncorrectCredentialsException、UnknownAccountException）被 SpringMVC 的默认异常处理器吞掉了，没有被捕获并映射到错误页面。Shiro 的设计哲学是“认证失败是业务异常，不是系统错误”，所以它选择抛出受检异常，而不是返回布尔值。你必须显式捕获并处理：

@PostMapping("/login") public String login(String username, String password, Model model) { Subject subject = SecurityUtils.getSubject(); UsernamePasswordToken token = new UsernamePasswordToken(username, password); try { subject.login(token); return "redirect:/home"; } catch (UnknownAccountException e) { model.addAttribute("error", "用户名不存在"); return "login"; } catch (IncorrectCredentialsException e) { model.addAttribute("error", "密码错误"); return "login"; } catch (LockedAccountException e) { model.addAttribute("error", "账户已被锁定"); return "login"; } catch (AuthenticationException e) { model.addAttribute("error", "登录失败，请稍后重试"); return "login"; } }

提示：这里model.addAttribute("error", ...)是为了在 Thymeleaf 模板中显示错误信息，避免用户反复刷新页面重试。如果你用的是前后端分离架构，这部分逻辑就要移到 Ajax 处理中。

2.2 Ajax 登录：JSON 响应体里的状态码与业务码必须分离

当登录请求来自前端 Vue/React 的 axios 请求时，你不能再返回String视图名，而必须返回 JSON。但关键点在于：HTTP 状态码（如 200/401/500）和业务状态码（如code: 200表示成功，code: 40101表示密码错误）必须解耦。很多初学者直接写：

@PostMapping("/api/login") @ResponseBody public Map<String, Object> apiLogin(String username, String password) { Map<String, Object> result = new HashMap<>(); Subject subject = SecurityUtils.getSubject(); UsernamePasswordToken token = new UsernamePasswordToken(username, password); try { subject.login(token); result.put("code", 200); result.put("msg", "登录成功"); result.put("data", subject.getPrincipal()); } catch (AuthenticationException e) { result.put("code", 401); result.put("msg", "认证失败"); } return result; }

这段代码的问题是：HTTP 状态码始终是 200，因为 SpringMVC 默认把@ResponseBody方法的返回值序列化为 JSON 后，统一返回 200。前端无法通过response.status判断是否登录成功，只能解析code字段。这违反了 RESTful 设计原则，也增加了前端容错成本。正确做法是使用ResponseEntity显式控制 HTTP 状态码：

@PostMapping("/api/login") @ResponseBody public ResponseEntity<Map<String, Object>> apiLogin(String username, String password) { Map<String, Object> result = new HashMap<>(); Subject subject = SecurityUtils.getSubject(); UsernamePasswordToken token = new UsernamePasswordToken(username, password); try { subject.login(token); result.put("code", 200); result.put("msg", "登录成功"); result.put("data", subject.getPrincipal()); return ResponseEntity.ok(result); // HTTP 200 } catch (UnknownAccountException e) { result.put("code", 40101); result.put("msg", "用户名不存在"); return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(result); // HTTP 401 } catch (IncorrectCredentialsException e) { result.put("code", 40102); result.put("msg", "密码错误"); return ResponseEntity.status(HttpStatus.UNAUTHORIZED).body(result); } catch (AuthenticationException e) { result.put("code", 50000); result.put("msg", "系统异常，请联系管理员"); return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(result); } }

这样前端就可以统一用if (response.status === 401)拦截所有认证失败场景，无需解析code字段，大幅提升代码可维护性。

2.3 第三方系统 API 调用：如何支持 Basic Auth 和 Token 透传

有些场景下，你的 SpringBoot 应用需要作为子系统，被另一个主系统调用登录接口（例如 SSO 单点登录集成）。这时请求头里可能携带Authorization: Basic xxx或Authorization: Bearer xxx。Shiro 默认只处理表单参数，你需要扩展UsernamePasswordToken的构建逻辑。一种轻量级方案是在 Controller 中解析请求头：

@PostMapping("/sso/login") @ResponseBody public ResponseEntity<Map<String, Object>> ssoLogin(HttpServletRequest request) { String authHeader = request.getHeader("Authorization"); if (authHeader != null && authHeader.startsWith("Basic ")) { // 解析 Basic Auth String base64Credentials = authHeader.substring("Basic ".length()).trim(); String credentials = new String(Base64.getDecoder().decode(base64Credentials), StandardCharsets.UTF_8); final String[] values = credentials.split(":", 2); if (values.length == 2) { return apiLogin(values[0], values[1]); // 复用已有的 apiLogin 逻辑 } } // 其他认证方式... return ResponseEntity.status(HttpStatus.BAD_REQUEST) .body(Map.of("code", 40000, "msg", "不支持的认证方式")); }

这种写法的好处是复用已有认证逻辑，避免重复实现 Realm。但要注意：Basic Auth 的凭证是明文 Base64 编码，绝不能用于生产环境的前端直连，仅适用于内网服务间调用，并需配合 HTTPS 保证传输安全。

3. Realm 的深度定制：不只是查数据库，更是认证策略的集中体现

Realm是 Shiro 认证体系中最关键的一环，但它常被简化为“查用户表返回对象”。实际上，一个生产级的 Realm 必须承载至少五项职责：账户状态校验、密码加盐与比对、多因素认证钩子、登录失败次数限制、以及会话属性注入。我们逐项拆解。

3.1 密码加盐存储与动态盐值：为什么不能用固定盐

很多教程教你在数据库里存一个salt字段，然后 Realm 里写：

// ❌ 错误示范：固定盐值 String salt = "my_fixed_salt_123"; String hashedPassword = new Sha256Hash(password, salt, 1024).toHex();

这会导致所有用户的密码都用同一个盐值哈希，一旦攻击者获取数据库，可以用彩虹表批量破解。正确做法是每个用户独立盐值，且盐值必须随机生成、长度足够（建议 16 字节以上）。SpringBoot 项目中，通常在用户注册时生成：

// 用户注册时 SecureRandom random = new SecureRandom(); byte[] salt = new byte[16]; random.nextBytes(salt); String encodedSalt = Base64.getEncoder().encodeToString(salt); String hashedPassword = new Sha256Hash(password, salt, 1024).toHex(); // 存入数据库：password_hash, salt_encoded

在 Realm 的doGetAuthenticationInfo中，必须从数据库取出该用户的盐值，并用相同算法比对：

@Override protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) throws AuthenticationException { UsernamePasswordToken upToken = (UsernamePasswordToken) token; String username = upToken.getUsername(); // 1. 查询用户基本信息（含 salt 和 password_hash） User user = userMapper.findByUsername(username); if (user == null) { throw new UnknownAccountException("用户名不存在: " + username); } // 2. 校验账户状态 if (!"ACTIVE".equals(user.getStatus())) { throw new LockedAccountException("账户状态异常: " + user.getStatus()); } // 3. 构建盐值字节数组 byte[] saltBytes = Base64.getDecoder().decode(user.getSalt()); // 4. 使用相同哈希算法和迭代次数比对密码 SimpleAuthenticationInfo info = new SimpleAuthenticationInfo( user, // principal user.getPasswordHash(), // hashed password from DB ByteSource.Util.bytes(saltBytes), // salt getName() // realm name ); return info; }

注意：ByteSource.Util.bytes(saltBytes)这行至关重要。如果直接传user.getSalt()（字符串），Shiro 会把它当作字符编码后的字节，导致比对失败。必须确保传入的是原始盐值字节数组。

3.2 登录失败次数限制：防止暴力破解的底层实现

Shiro 本身不提供登录失败计数功能，需要自己实现。常见方案是在数据库增加login_fail_count和locked_until字段，并在 Realm 中加入校验逻辑：

@Override protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) throws AuthenticationException { UsernamePasswordToken upToken = (UsernamePasswordToken) token; String username = upToken.getUsername(); User user = userMapper.findByUsername(username); if (user == null) { throw new UnknownAccountException("用户名不存在"); } // 新增：检查是否被临时锁定 if (user.getLockedUntil() != null && user.getLockedUntil().isAfter(LocalDateTime.now())) { throw new LockedAccountException("账户已被锁定，请 " + Duration.between(LocalDateTime.now(), user.getLockedUntil()).toMinutes() + " 分钟后重试"); } // ... 其他校验逻辑 return info; }

但注意：这个校验只在认证前执行，不负责累加失败次数。失败计数必须在 Controller 的catch块中完成：

} catch (IncorrectCredentialsException e) { // 更新数据库失败次数 userMapper.incrementFailCount(username); // 如果达到阈值，设置锁定时间 if (userMapper.getFailCount(username) >= 5) { userMapper.lockAccount(username, LocalDateTime.now().plusMinutes(15)); } model.addAttribute("error", "密码错误，剩余尝试次数：" + (5 - userMapper.getFailCount(username))); return "login"; }

这种“校验与计数分离”的设计，是为了避免在 Realm 中执行写操作（Shiro 规范建议 Realm 只读），也符合单一职责原则。

3.3 注入会话属性：让登录后的 Subject 携带业务上下文

很多业务需要在登录后，把用户的角色列表、部门 ID、甚至个性化配置加载到 Session 中，供后续请求使用。Shiro 提供了onLoginSuccess回调钩子，但更推荐在doGetAuthenticationInfo返回的SimpleAuthenticationInfo中注入：

SimpleAuthenticationInfo info = new SimpleAuthenticationInfo( user, // principal，这个对象会在 subject.getPrincipal() 中返回 user.getPasswordHash(), ByteSource.Util.bytes(saltBytes), getName() ); // 注入额外属性到 Session info.setCredentialsMatcher(new HashedCredentialsMatcher(Sha256Hash.class)); // 关键：设置 session 属性 info.setAttributes(Map.of( "roles", roleService.findRolesByUserId(user.getId()), "permissions", permissionService.findPermissionsByUserId(user.getId()), "departmentId", user.getDepartmentId() )); return info;

这样，在任意 Controller 或 Service 中，都可以通过以下方式获取：

Subject subject = SecurityUtils.getSubject(); User user = (User) subject.getPrincipal(); // 获取用户实体 Collection<String> roles = (Collection<String>) subject.getSession().getAttribute("roles");

注意：setAttributes设置的属性，只在当前认证成功的 Session 中有效。如果用户登出后重新登录，需要重新加载。

4. ShiroFilterFactoryBean 的致命细节：Filter 链顺序决定一切

ShiroFilterFactoryBean是 Shiro 与 SpringBoot Web 层对接的唯一桥梁，但它的配置远不止filterChainDefinitionMap那么简单。90% 的“登录无效”“权限不生效”问题，根源都在 Filter 链的顺序和参数配置上。我们来深挖几个关键配置项。

4.1 filterChainDefinitionMap 的路径匹配规则：前缀通配符的优先级陷阱

初学者常这样配置：

@Bean public ShiroFilterFactoryBean shiroFilterFactoryBean(SecurityManager securityManager) { ShiroFilterFactoryBean bean = new ShiroFilterFactoryBean(); bean.setSecurityManager(securityManager); Map<String, String> chainDefinitionMap = new LinkedHashMap<>(); chainDefinitionMap.put("/static/**", "anon"); // 静态资源放行 chainDefinitionMap.put("/login", "anon"); // 登录页放行 chainDefinitionMap.put("/api/**", "authc"); // API 接口需要认证 chainDefinitionMap.put("/**", "authc"); // 其他所有路径都需要认证 bean.setFilterChainDefinitionMap(chainDefinitionMap); return bean; }

这段配置看似合理，但存在严重隐患：/**是最宽泛的匹配，它会覆盖所有更具体的路径。比如你访问/login，Shiro 会先匹配/login（anon），但如果/**写在/login前面，Shiro 会优先匹配/**，导致登录页也被要求认证，形成死循环。

Shiro 的匹配规则是按定义顺序，取第一个匹配项。因此，必须把最具体的路径写在前面，最宽泛的写在后面：

chainDefinitionMap.put("/login", "anon"); chainDefinitionMap.put("/logout", "logout"); chainDefinitionMap.put("/static/**", "anon"); chainDefinitionMap.put("/api/login", "anon"); // API 登录接口放行 chainDefinitionMap.put("/api/**", "authc"); // API 接口需要认证 chainDefinitionMap.put("/**", "authc"); // 页面资源需要认证

提示：你可以用shiroFilterFactoryBean.setLoginUrl("/login")显式指定未认证时的跳转地址，避免依赖/**的默认行为。

4.2 自定义 Filter 的注入时机：为什么 CustomFormAuthenticationFilter 总不生效

很多教程教你自定义一个CustomFormAuthenticationFilter来处理登录逻辑，但配置后发现onLoginSuccess方法从不被调用。根本原因是：你没有把它注入到 ShiroFilterFactoryBean 的 filters 映射中。

正确的步骤是三步：

1. 定义自定义 Filter 类；
2. 将其声明为 Spring Bean；
3. 在ShiroFilterFactoryBean中通过filters属性注册。

// 1. 自定义 Filter public class CustomFormAuthenticationFilter extends FormAuthenticationFilter { @Override protected boolean onLoginSuccess(AuthenticationToken token, Subject subject, ServletRequest request, ServletResponse response) throws Exception { // 登录成功后重定向到首页 WebUtils.issueRedirect(request, response, "/home"); return false; // 返回 false 表示不再执行后续 Filter } } // 2. 声明为 Bean @Bean public CustomFormAuthenticationFilter authcFilter() { return new CustomFormAuthenticationFilter(); } // 3. 注入到 ShiroFilterFactoryBean @Bean public ShiroFilterFactoryBean shiroFilterFactoryBean(SecurityManager securityManager) { ShiroFilterFactoryBean bean = new ShiroFilterFactoryBean(); bean.setSecurityManager(securityManager); // 注册自定义 Filter Map<String, Filter> filters = new LinkedHashMap<>(); filters.put("authc", authcFilter()); // 覆盖默认的 authc Filter bean.setFilters(filters); // 在 chainDefinitionMap 中引用 Map<String, String> chainMap = new LinkedHashMap<>(); chainMap.put("/login", "authc"); // 使用自定义的 authc Filter chainMap.put("/**", "authc"); bean.setFilterChainDefinitionMap(chainMap); return bean; }

如果不执行第 3 步，ShiroFilterFactoryBean会使用内置的FormAuthenticationFilter，你的自定义逻辑永远不会触发。

4.3 RememberMe 的 Cookie 安全配置：HttpOnly 与 SameSite 的硬性要求

RememberMe功能让用户勾选“记住我”后，下次访问自动登录。但默认配置存在严重安全隐患：Cookie 缺少HttpOnly和SameSite属性，易受 XSS 和 CSRF 攻击。

Shiro 的CookieRememberMeManager必须显式配置：

@Bean public CookieRememberMeManager rememberMeManager() { CookieRememberMeManager manager = new CookieRememberMeManager(); // 设置密钥（必须是 128 位或 256 位） manager.setCipherKey(Base64.decode("4AvVhmFLUs0KTA3Kprsdag==")); // 示例密钥，生产环境需更换 // 配置 Cookie SimpleCookie cookie = new SimpleCookie("rememberMe"); cookie.setHttpOnly(true); // 禁止 JavaScript 访问 cookie.setMaxAge(7 * 24 * 3600); // 7天 cookie.setPath("/"); // 作用域为根路径 cookie.setSecure(true); // 仅 HTTPS 传输（生产环境必须开启） cookie.setSameSite("Strict"); // 防 CSRF manager.setCookie(cookie); return manager; }

注意：setSecure(true)在开发环境（HTTP）下会导致 Cookie 不被发送，调试时可临时设为false，但上线前必须改回true。SameSite="Strict"最安全，但可能影响部分跨站跳转；"Lax"是折中方案，允许 GET 请求携带 Cookie。

5. 生产环境避坑指南：那些文档里不会写的实战血泪经验

最后分享我在多个 SpringBoot + Shiro 项目中踩过的、文档里几乎从不提及的五个关键坑。这些不是理论问题，而是上线后真实发生的故障，每一个都曾导致线上服务不可用。

5.1 Session 共享失效：集群环境下 Subject 丢失的根因

单机部署时，Shiro 的DefaultWebSessionManager使用内存存储 Session，一切正常。但一旦上 Kubernetes 或 Nginx 负载均衡，用户请求被分发到不同 Pod，就会出现“登录一次，刷新页面就登出”的问题。你以为是 Redis Session 共享没配好？其实更可能是 Shiro 的 Session ID 传递机制被破坏。

Shiro 默认从 Cookie 读取JSESSIONID，但如果你的 Nginx 配置了proxy_cookie_path / "/myapp/";，而 Shiro 的 Cookie Path 是/，就会导致 Cookie 被 Nginx 丢弃。解决方案是强制 Shiro Cookie Path 与反向代理路径一致：

@Bean public DefaultWebSessionManager sessionManager() { DefaultWebSessionManager sessionManager = new DefaultWebSessionManager(); // 设置 Session Cookie Path，必须与 Nginx proxy_cookie_path 一致 SimpleCookie cookie = new SimpleCookie("JSESSIONID"); cookie.setPath("/myapp/"); // 与 Nginx 配置完全匹配 cookie.setHttpOnly(true); cookie.setSecure(true); sessionManager.setSessionIdCookie(cookie); // 设置 Session 超时（分钟） sessionManager.setGlobalSessionTimeout(30 * 60 * 1000); // 30分钟 // 集成 Redis RedisCacheManager cacheManager = new RedisCacheManager(); cacheManager.setRedisManager(redisManager()); sessionManager.setCacheManager(cacheManager); return sessionManager; }

提示：redisManager()是你封装的 Redis 连接工厂，此处略去。关键是cookie.setPath("/myapp/")必须与 Nginx 的proxy_cookie_path完全一致，包括末尾斜杠。

5.2 异步线程中 Subject 为空：@Async 方法无法获取当前用户

这是 SpringBoot + Shiro 最经典的“玄学问题”。你在 Controller 里subject.getPrincipal()能拿到用户，但进到@Async方法里就返回 null。原因在于：Shiro 的Subject是通过ThreadLocal绑定到当前线程的，而@Async使用独立线程池，不继承主线程的ThreadLocal值。

解决方案不是“在异步方法里重新登录”，而是手动将 Subject 传递过去：

@Service public class UserService { @Async public void asyncProcessOrder(Long orderId, Subject currentSubject) { // 在异步线程中，currentSubject 就是主线程的 Subject User user = (User) currentSubject.getPrincipal(); // 处理订单逻辑... } // Controller 中调用 @PostMapping("/order") public String createOrder() { Subject subject = SecurityUtils.getSubject(); userService.asyncProcessOrder(123L, subject); return "success"; } }

更优雅的方式是封装一个SubjectAwareExecutor，但对大多数项目，显式传递已足够。

5.3 Thymeleaf 标签不生效：shiro-spring-boot-starter 的版本陷阱

shiro-spring-boot-starter是官方提供的 Starter，但 2.x 版本（对应 Shiro 1.7+）与 Thymeleaf 的集成存在兼容性问题：sec:authorize标签在某些情况下不渲染。根本原因是 Starter 的自动配置类ShiroAutoConfiguration没有正确注册ShiroDialect。

临时解决方案是手动注册 Dialect：

@Configuration public class ShiroThymeleafConfig { @Bean public ShiroDialect shiroDialect() { return new ShiroDialect(); } }

并在application.yml中启用：

spring: thymeleaf: enabled: true # 确保 dialect 被扫描 mode: HTML cache: false

模板中即可使用：

<!-- 只有拥有 user:add 权限的用户才显示 --> <div sec:authorize="hasPermission('user:add')"> <button>添加用户</button> </div>

5.4 登录日志记录：如何在不侵入业务代码的前提下审计登录行为

安全合规要求记录所有登录行为（成功/失败、IP、时间、用户代理）。如果在每个 Controller 的try/catch里手写日志，既重复又易漏。Shiro 提供了AuthenticationListener接口，可以全局监听：

@Component public class LoginAuditListener implements AuthenticationListener { private static final Logger logger = LoggerFactory.getLogger(LoginAuditListener.class); @Override public void onSuccess(AuthenticationToken token, AuthenticationInfo info) { String username = (String) token.getPrincipal(); String ip = getRemoteAddr((WebSubject) SecurityUtils.getSubject()); logger.info("LOGIN_SUCCESS | user:{} | ip:{} | time:{}", username, ip, LocalDateTime.now()); } @Override public void onFailure(AuthenticationToken token, AuthenticationException ae) { String username = (String) token.getPrincipal(); String ip = getRemoteAddr((WebSubject) SecurityUtils.getSubject()); String reason = ae.getClass().getSimpleName(); logger.warn("LOGIN_FAIL | user:{} | ip:{} | reason:{} | time:{}", username, ip, reason, LocalDateTime.now()); } private String getRemoteAddr(WebSubject subject) { HttpServletRequest request = (HttpServletRequest) subject.getServletRequest(); return Optional.ofNullable(request.getHeader("X-Forwarded-For")) .orElse(request.getRemoteAddr()); } }

然后在SecurityManager配置中注册：

@Bean public SecurityManager securityManager() { DefaultWebSecurityManager securityManager = new DefaultWebSecurityManager(); securityManager.setRealm(myRealm()); // 注册监听器 Collection<AuthenticationListener> listeners = new ArrayList<>(); listeners.add(loginAuditListener()); securityManager.setAuthenticationListeners(listeners); return securityManager; }

这样，所有登录行为（无论来自表单、API 还是 SSO）都会被统一审计，且与业务逻辑完全解耦。

5.5 内存泄漏预警：Shiro 的 CacheManager 未关闭导致 OOM

最后一个也是最隐蔽的坑：Shiro 的CacheManager（尤其是基于 EhCache 或 Caffeine 的实现）如果未正确关闭，会在应用重启时残留大量缓存对象，长期运行导致 JVM 内存溢出（OOM）。SpringBoot 的@PreDestroy无法保证 CacheManager 的销毁顺序。

解决方案是在SecurityManagerBean 上添加@PreDestroy回调：

@Bean(destroyMethod = "destroy") public SecurityManager securityManager() { DefaultWebSecurityManager securityManager = new DefaultWebSecurityManager(); securityManager.setRealm(myRealm()); // 如果使用了 CacheManager，确保它被正确关闭 if (securityManager.getCacheManager() instanceof org.apache.shiro.cache.CacheManager) { // 无需额外操作，destroyMethod 会调用 } return securityManager; }

destroyMethod = "destroy"会确保 Spring 容器关闭时，调用SecurityManager.destroy()，进而触发所有关联组件（包括 CacheManager）的清理逻辑。

我在某高校实验室主导的一个教学管理系统中，就因为没配SameSite导致学生用 Chrome 80+ 浏览器登录后，点击“提交作业”按钮一直 401；也在某电商后台项目里，因filterChainDefinitionMap顺序错误，让运营人员无法访问/admin/login页面，排查了整整两天才发现是/**写在了最前面。这些都不是 Shiro 的 bug，而是对它运行机制理解不够深入的结果。真正的整合，从来不是复制粘贴几段配置，而是理解每一行代码背后，Shiro 的线程模型、Filter 链、Session 生命周期是如何与 SpringBoot 的容器、Web 层、异步机制咬合在一起的。当你能把登录过程中的每一次Subject创建、每一次Realm查询、每一次Filter跳转都画在一张纸上，并标注出每个环节的输入输出和异常分支，才算真正掌握了 SpringBoot 整合 Shiro 的用户名密码登录。