企业官网建设流程全解析

一年多前给一个管理后台系统做权限升级，遇到了一个很典型的需求：管理员和普通用户是两个完全不同的角色，数据、菜单、接口都不一样，但系统又要求他们各自拥有独立的登录入口——管理员走/super/login，普通用户走/login。当时第一反应是在同一个 Spring Security 过滤器链里把所有规则都堆进去，结果越配越乱，各种跳转互相干扰，跑起来不是 403 就是重定向死循环。后来把方案推倒重来，改成了多 SecurityFilterChain 的设计，每个登录场景独立成链，问题一下子清爽了。

这篇博文就是那次重构的完整复盘，从需求拆解、方案选型到双链配置、认证隔离、登录页处理，再到最后调试踩过的坑，全部整理成可以直接抄作业的源码和步骤。内容不挑版本，主推 Spring Security 5.7+ 的新写法，同时也讲了旧版配置的对应方式，适合正在做多端登录、多角色权限拆分或者准备给老系统做安全模块升级的同学参考。

1. 需求拆解与方案选型：先想清楚再动手

1.1 两个典型的多页面登录场景

多页面登录在业务里最常见的形态有两种，一种是今天要讲的同系统不同角色：管理员和用户都在同一个应用里，数据表可能就是 admin 表和 user 表，甚至可能是同一张表的两个类型，但前端必须提供不同的登录页。另一种是网关层多应用汇聚：多个独立子系统共用一个登录中转站，按来源跳到各自的应用首页。第二种往往涉及 SSO，属于另外一码事，本文只讲第一种，也是最容易踩坑的一种。

同系统多角色登录的核心痛点在于：管理员和用户的认证方式、权限模型、登录后落地页全都不同。如果硬塞进一个过滤器链，会导致链条上的规则越来越多，permitAll和hasRole互相打架，最终代码变成谁也看不懂的一团浆糊。

1.2 三种实现路线对比

针对这个需求，常规有三条路可以走。

我第二次重构直接选了方案C。原因很现实：项目里管理员和普通用户已经放在了不同的表里，密码字段的加密方式可能还不一样。如果强行用一套 UserDetailsService 去查两张表，代码里就会充满if (userType == 1) ... else ...这种分支，看似省事，后续几乎无法维护。让认证逻辑在各链里各管各的，边界就清晰了。

1.3 为什么新写法推荐 SecurityFilterChain 而非 WebSecurityConfigurerAdapter

如果你翻过旧教程，会看到大量继承WebSecurityConfigurerAdapter的例子。Spring Security 从 5.7 版本开始已经弃用这个抽象类，官方给的替代方案就是直接注册SecurityFilterChainBean。回顾一下核心变化：

• 旧写法继承一个 Adapter，重写configure(HttpSecurity)；新写法用SecurityFilterChain类型注册 Bean。
• 旧写法所有规则揉在一个链里，靠.antMatchers()区分；新写法天然支持多个链，用securityMatcher()给每条链划定管辖路径。
• 旧写法的AuthenticationManager一般是全局共享；新写法里每条链的HttpSecurity是独立的，认证细节可以各自定制。

这个转型不只是一个格式变化，它本质上解决了多登录页场景下最棘手的"规则冲突"问题。因为每条链只处理自己匹配到的 URL，其他请求跟它无关，互不干扰。

2. 双 SecurityFilterChain 配置：核心实现与匹配规则

2.1 创建两个链：管理员链与用户链

先用代码展示最核心的双链结构。这里我按新版写法给出完整类，注释标清楚每一段的作用。

import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.annotation.Order; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.crypto.factory.PasswordEncoderFactories; import org.springframework.security.crypto.password.PasswordEncoder; import org.springframework.security.web.SecurityFilterChain; @Configuration @EnableWebSecurity public class MultiLoginSecurityConfig { @Bean public PasswordEncoder passwordEncoder() { return PasswordEncoderFactories.createDelegatingPasswordEncoder(); } /** 第1条链：管理员登录 */ @Bean @Order(1) public SecurityFilterChain adminSecurityFilterChain(HttpSecurity http) throws Exception { http .securityMatcher("/super/**", "/super/login") .authorizeHttpRequests(auth -> auth .requestMatchers("/super/login").permitAll() .requestMatchers("/super/**").hasRole("ADMIN") ) .formLogin(form -> form .loginPage("/super/login") .loginProcessingUrl("/super/doLogin") .defaultSuccessUrl("/super/index", true) .failureUrl("/super/login?error") ) .logout(logout -> logout .logoutUrl("/super/logout") .logoutSuccessUrl("/super/login?logout") ) .csrf(csrf -> csrf.ignoringRequestMatchers("/super/doLogin")); return http.build(); } /** 第2条链：普通用户登录 */ @Bean @Order(2) public SecurityFilterChain userSecurityFilterChain(HttpSecurity http) throws Exception { http .securityMatcher("/user/**", "/login", "/register") .authorizeHttpRequests(auth -> auth .requestMatchers("/login", "/register").permitAll() .requestMatchers("/user/**").hasAnyRole("USER", "ADMIN") ) .formLogin(form -> form .loginPage("/login") .loginProcessingUrl("/doLogin") .defaultSuccessUrl("/user/home", true) .failureUrl("/login?error") ) .logout(logout -> logout .logoutUrl("/logout") .logoutSuccessUrl("/login?logout") ) .csrf(csrf -> csrf.ignoringRequestMatchers("/doLogin")); return http.build(); } }

注意两条链的@Order注释：@Order(1)的先执行，@Order(2)的后执行。代码里管理员链的securityMatcher写了/super/**，用户链写的是/user/**和公开页面，两条链的管辖范围基本不重叠，所以顺序看起来不太敏感。但如果你后面要加兜底链或静态资源链，@Order就变得很关键，稍后专门讲。

2.2 securityMatcher 的匹配细节与执行顺序

securityMatcher()决定一条链要处理哪些请求。Spring Security 在收到 HTTP 请求后，会按@Order从小到大的顺序依次问每条链：这个请求归你管吗？如果匹配，就把请求交给这条链走完全部过滤器；如果不匹配，继续问下一条。直到最后都没有链认领的请求，处理结果取决于是否注册了兜底链。

这里有三个特别容易踩的细节：

1. securityMatcher的路径匹配基于PathPattern，它遵循 Spring MVC 的路径语义。比如/super/**会匹配/super/index，也会匹配/super/xx/yy，但不会匹配/super本身。如果你的登录页恰好就是/super这种不带斜杠后段的路径，得显式把/super和/super/**都加进去。

2. securityMatcher只做路径匹配，不检查权限。换句话说，未登录用户访问/super/index时，管理员链接管请求，发现未认证，就会触发该链配置的登录页跳转，也就是跳/super/login。这正是"哪个链接管，就用哪个链的登录页"的底层原理。

3. 多条链的路径如果重叠，前面的链会抢先接管。所以设计路径前缀时尽量让它们互斥，这是避免行为混乱的最土也是最有效的办法。当年我把/adminDashboard和/userDashboard命名为同前缀不同后段，导致好几回链接管错位，后来统一改成/super/**和/user/**，世界清净了。

再举一个反面例子。假如管理员链接管了/login，然后你又在用户链里允许/login，那用户访问/login时会被管理员链先截走，显示的是管理员登录页，用户登录页永远出不来。这就是为什么在双链或多链场景里，每个公开页面最好有独立路径，不要共用。

2.3 如何理解 HttpSecurity 实例的独立性

上面代码里两个SecurityFilterChain方法的参数都叫HttpSecurity http，但它俩是不同的实例。每一条链的过滤器链是独立构建的，所以你在管理员链里配置的.formLogin()不会污染用户链。这是新版写法一个非常重要的能力：每条链可以拥有自己独立的认证配置、成功处理器、甚至AuthenticationManager。

这一点在实战里特别有用。比如管理员登录要求"密码+验证码"双重认证，而普通用户只要求账号密码，那么可以在管理员链中单独注入一个自定义AuthenticationProvider；用户链则完全不用动。单链方案里做这种差异化配置，需要写一堆if逻辑绕过，而在多链方案里，这是与生俱来的能力。

3. 认证逻辑隔离：独立 UserDetailsService 与密码策略

3.1 多用户体系下的 UserDetailsService 设计

两条链对应的用户数据源不同，所以不能只定义一个UserDetailsServiceBean。Spring Security 允许容器中存在多个该类型的 Bean，关键是每个SecurityFilterChain通过http.userDetailsService(...)指定自己要用哪一个。先看两个服务的定义：

@Service public class AdminUserDetailsService implements UserDetailsService { @Autowired private AdminMapper adminMapper; @Override public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException { Admin admin = adminMapper.findByUsername(username); if (admin == null) { throw new UsernameNotFoundException("管理员不存在"); } return org.springframework.security.core.userdetails.User .withUsername(admin.getUsername()) .password(admin.getPassword()) .authorities("ROLE_ADMIN") .build(); } }

@Service public class NormalUserDetailsService implements UserDetailsService { @Autowired private UserMapper userMapper; @Override public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException { AppUser user = userMapper.findByUsername(username); if (user == null) { throw new UsernameNotFoundException("用户不存在"); } return org.springframework.security.core.userdetails.User .withUsername(user.getUsername()) .password(user.getPassword()) .authorities("ROLE_USER") .build(); } }

注意两个类的名字不同，注入时按类型区分。如果你的两个 Service 类名都以 UserDetailsService 结尾，且恰好都叫类似UserUserDetailsService、AdminUserDetailsService这种带前缀的名字，在按类型注入时不会有歧义，但只要包路径变了，建议用@Qualifier显式标注一眼看清。

然后回到两条链的配置，在原来代码基础上补上用户服务：

@Bean @Order(1) public SecurityFilterChain adminSecurityFilterChain( HttpSecurity http, AdminUserDetailsService adminUserDetailsService) throws Exception { http .securityMatcher("/super/**", "/super/login") .userDetailsService(adminUserDetailsService) // 指定管理员链的认证数据源 .authorizeHttpRequests(auth -> auth .requestMatchers("/super/login").permitAll() .requestMatchers("/super/**").hasRole("ADMIN") ) ... // 其余配置与前面一致 return http.build(); } @Bean @Order(2) public SecurityFilterChain userSecurityFilterChain( HttpSecurity http, NormalUserDetailsService normalUserDetailsService) throws Exception { http .securityMatcher("/user/**", "/login") .userDetailsService(normalUserDetailsService) // 指定用户链的认证数据源 ... return http.build(); }

关键就在.userDetailsService(...)这一行。Spring Security 在构建这条链的认证流程时，如果发现你手动挂了 UserDetailsService，就会自动配一个DaoAuthenticationProvider走"查库-比对密码"的默认路径。

3.2 登录提交到后端后的认证流转过程

为了让你对登录链路有整体把握，这里把一次登录请求的完整流转拆开讲。以普通用户提交/doLogin为例：

1. 浏览器 POST 用户名、密码到/doLogin，该路径由用户链接管。
2. 用户链中的UsernamePasswordAuthenticationFilter拦截请求，从 request 里解析用户名密码，交给链上的AuthenticationManager。
3. AuthenticationManager调用你指定的NormalUserDetailsService.loadUserByUsername(username)查库。
4. 拿到UserDetails后，DaoAuthenticationProvider内部用PasswordEncoder对提交密码加密，与UserDetails.getPassword()比对。
5. 一致则认证通过，创建Authentication对象，存入SecurityContextHolder，然后调用成功处理器做页面跳转；不一致则抛出BadCredentialsException，走失败处理器。

管理员链的流程完全一样，只是查的表和生成的权限不同。所以"多页面登录"从代码角度说白了就是给每条链指定各自的数据源、各自的登录路径、各自的权限前缀。

3.3 密码加密：BCrypt 与 DelegatingPasswordEncoder

上一步后端比对密码时，如果数据库里存了明文，你会在日志里看到Encoded password does not look like BCrypt。这里有个前置必须做掉：密码绝不能明文入库。

建议直接用PasswordEncoderFactories.createDelegatingPasswordEncoder()，这也是 Spring Security 默认推荐的编码器。它默认支持{bcrypt}前缀存储，未来如果你要兼容多种加密算法，比如老系统跑过 MD5 的历史数据，可以往这个委托编码器里继续挂其他加密实现，不用改主逻辑。

补充一个实操细节：如果用BCryptPasswordEncoder直接对比，必须把数据库里的密文原样取出，与明文比对放到matches方法里做：

String rawPassword = "123456"; String encodedPassword = user.getPassword(); // 库里带 {bcrypt} 或者纯 $2a$ 开头 PasswordEncoder encoder = new BCryptPasswordEncoder(); boolean match = encoder.matches(rawPassword, encodedPassword);

如果你用的是DelegatingPasswordEncoder，密文可能长这样：{bcrypt}$2a$10$...。这种带前缀的格式在matches方法内部会自动识别，不需要手动剥前缀。但要注意，如果你把{bcrypt}这一段反手塞进新用户的登录名里，那就会出问题，所以注册用户时一定只保存编码后的密码。这个问题我见过不止一回，排查时第一反应永远是"你会不会把加密后的值存错了字段"。

4. 登录页、控制器路径与跳转控制

4.1 两个登录页如何并存

Spring Boot + Thymeleaf 下，页面模板放在resources/templates下即可。本例中我会放两个模板：super/login.html和login.html。管理员登录页的表单如下：

<!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <meta charset="UTF-8"> <title>管理员登录</title> </head> <body> <h2>管理员登录</h2> <form th:action="@{/super/doLogin}" method="post"> <div>用户名:<input type="text" name="username"/></div> <div>密码:<input type="password" name="password"/></div> <button type="submit">登录</button> </form> </body> </html>

几个细节需要说明：

• th:action指向的是登录处理地址，也就是 Spring Security 中loginProcessingUrl配置的地址，不是loginPage。很多人以为登录表单 action 应该指向登录页本身，结果登录后一直 404。
• 表单字段名必须是username和password，这是UsernamePasswordAuthenticationFilter的默认解析名。如果你前端用了loginName之类的自定义字段名，需要在链配置里额外指定usernameParameter("loginName")。
• 表单POST 方法是硬性要求。Spring Security 默认只监听 POST 的登录提交请求，你换成 GET 它不认。
• CSRF 默认开启，所以如果你的登录页是模板渲染的，表单里必须带上隐藏的 CSRF token。用 Thymeleaf 时，Spring Security 会自动往 model 里注入 token，不需要手写；但如果是前后端分离，自己组装 POST 请求时，就得单独处理 token。

普通用户登录页同理，只是表单地址改为/doLogin。两者的渲染路径由控制层提供。

4.2 控制器设计：既要承载页面，也要处理认证后的跳转

登录页面本身是一个 GET 请求，需要在 Controller 里映射到对应的视图。下面这一段是 Spring MVC 的代码，目的是渲染管理员登录页和用户登录页：

@Controller public class LoginController { @GetMapping("/super/login") public String superLogin() { return "super/login"; } @GetMapping("/login") public String userLogin() { return "login"; } @GetMapping("/super/index") public String superIndex() { return "super/index"; } @GetMapping("/user/home") public String userHome() { return "user/home"; } }

这些路径必须和前面securityMatcher覆盖的路径保持一致。比如/super/login在 Admin Chain 的匹配范围内，但又被permitAll放行，所以未登录时控制器能正常渲染页面。如果这个@GetMapping忘记写，Spring Security 会跳到一个/super/login，然后 Controller 没这个路径，直接 404，页面文案就可能出现怪异内容，第一眼还以为是权限问题。

登录成功落地页的选择也有讲究。我在配置里写了.defaultSuccessUrl("/super/index", true)，第二个参数true是强制跳转开关。

• 填true：无论用户之前访问了什么页面，认证通过后一律去指定页面。
• 填false或省略：如果用户登录前访问的是某个受保护的 URL，认证通过后优先跳回那个 URL；只有直接访问登录页时才会去默认地址。

我的建议是：有明确角色中心页的系统用true，让登录后的去向完全可控；如果是电商类、希望用户从哪个商品页进登录、登录完继续回到商品页的产品，用false体验会更好。

4.3 登出、记住我与 Session 边界

两条链的登出 URL 我分别配了/super/logout和/logout，这样管理员和用户的登出入口完全隔离。一个容易踩的细节是：CSRF 默认会拦截 logout 请求。

Spring Security 的 logout 处理实际上是通过LogoutFilter拦截 POST 请求完成的。若你在页面里放一个<a href="/logout">退出</a>，默认给的是 GET，会被LogoutFilter502 或 403 拦截。正确做法是用表单 POST 提交登出，并在表单里带上 CSRF token。

如果希望保持旧系统习惯，使用 GET 方式登出，可以在链配置里这样放开：

.logout(logout -> logout .logoutUrl("/logout") .logoutRequestMatcher(new AntPathRequestMatcher("/logout", "GET")) .logoutSuccessUrl("/login?logout") )

这种做法在生产环境有利有弊：GET 登出会被第三方网站通过图片请求等方式触发，虽然登出本身不算致命的越权，但造成的体验问题足以让你后悔。除非是历史包袱太重非 GET 不可，否则建议一律 POST。

Session 策略默认是IF_REQUIRED，意味着登录成功后创建会话，但两条链各自登录会产生不同会话属性吗？不是的。Spring Security 的会话在 Servlet 容器层只有一个HttpSession，认证信息存在 session 里的SecurityContext中，不管你从哪个链登录，认证信息都会写进同一个 session 里的同一个 key。所以如果你在用户登录状态下直接访问/super/login，可能会看到"当前已认证，不建议重复登录"，或者被链规则挡回来，根据不同配置行为会有所不同。这块要根据业务决定是否需要互斥登录，常规做法是在成功处理器里判断当前会话已有别的角色认证信息，手动退出并重新登录。

5. 常见问题排查与实战踩坑

5.1 过滤器链不生效的几种典型情况

第一种：你的新链没有注册进容器。Spring 容器中多个SecurityFilterChainBean 会被自动收集，但前提是它们都在配置类里被声明，且配置类本身被 Spring 扫描到。有人把新链写到一个普通方法里，忘了加@Bean，结果 Spring Security 只启用了默认链，所有请求都按默认规则处理，表现为"登录配置全失效"。

第二种：securityMatcher路径写错导致链未接管。最常见的是只写/super/**没写/super/login，登录页 GET 请求到达时，Fallback 链接管了。如果 Fallback 链没有正确放行登录页，就会出现无限重定向。排查技巧：打开 debug 日志，观察请求对应哪条链，路径对不对一目了然：

logging: level: org.springframework.security: DEBUG

第三种：两条链顺序搞反。如果你让用户链的@Order(1)，管理员链@Order(2)，而用户链的securityMatcher又包含了/api/admin/**，那这个请求会被用户链先行接管，权限判断全都按普通用户规则走，管理员永远进不去。调整方法就是把更精确、更需要先行处理的链排前面，或者严格让路径互斥。

5.2 登录成功不跳转：一直回到登录页

这类问题十有八九出在登录表单提交地址与loginProcessingUrl不一致。比如表单 action 是/doLogin，配置里却写了/super/doLogin，那请求会落到用户链或者兜底链去，当然后续逻辑全部走偏。两边对不上时，最直接的现象是点击登录后页面空白或 404，后台日志会有 302 跳回登录页的记录。

另外一个隐蔽原因是UserDetailsService查出的用户权限不匹配。比如用户链里要求hasRole("USER")，但你loadUserByUsername返回的权限是ROLE_USER吗？注意hasRole("USER")实际判断的是ROLE_USER，如果你authorities("USER")，少写了ROLE_前缀，认证虽然成功，授权却永远失败。判权限的规则是链内authorizeHttpRequests阶段执行的，认证成功但授权失败时，照样把你送回登录页，有时还会看到 403，这个现象很有迷惑性。

5.3 静态资源和公共接口被拦截怎么办

多链场景下，静态资源最容易被漏配。假设登录页里引用了/css/login.css，这个路径既不在/super/**也不在/user/**管辖范围，就可能被兜底链设的authenticated()拦下来。处理方式推荐单独出第三条链专门放行静态资源：

@Bean @Order(0) public SecurityFilterChain resourceFilterChain(HttpSecurity http) throws Exception { http .securityMatcher("/css/**", "/js/**", "/images/**", "/favicon.ico") .authorizeHttpRequests(auth -> auth.anyRequest().permitAll()) .requestCache(cache -> cache.disable()) .securityContext(ctx -> ctx.disable()) .sessionManagement(sess -> sess.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .csrf(csrf -> csrf.disable()); return http.build(); }

给静态资源链@Order(0)让它最先执行是有意的：静态资源不应该走任何认证流程，也不该去碰 session。如果有人未登录就直接访问/css/login.css，理论上也不应该触发认证过滤器链。requestCache、securityContext、csrf全部禁用，最大化减少对静态资源的重复缠绕。

还有一类接口，比如验证码生成/captcha、用户注册/register，也应该允许匿名访问。可以在主链的authorizeHttpRequests里直接放行，前提是它在该链的securityMatcher管辖范围内。如果不想为了一个接口单独开一条链，就尽量把这类公共接口收敛到统一的路径前缀下面，比如/public/**，由专门链统一放行。

5.4 常用配置速查表

5.5 完整源码结构与运行前检查清单

如果这一整套配置放到了一个独立的多模块项目里，典型的源码结构大概是：

src/main/java ├── config │ └── MultiLoginSecurityConfig.java ├── controller │ ├── LoginController.java │ └── AdminController.java │ └── UserController.java ├── service │ ├── AdminUserDetailsService.java │ └── NormalUserDetailsService.java ├── mapper │ ├── AdminMapper.java │ └── UserMapper.java └── domain ├── Admin.java └── AppUser.java src/main/resources ├── templates │ ├── super/login.html │ ├── super/index.html │ ├── login.html │ └── user/home.html └── application.yml

跑起来之前，按这个清单过一遍大概率能一次通关：

1. 确认两条链的securityMatcher路径不重叠，公共入口都用独立 URL。
2. 确认@Order(0)的静态资源链是最高优先级。
3. 打开 DEBUG 日志，首次登录先请求登录页，看请求被哪条链接管。
4. 登录表单 POST 地址与 loginProcessingUrl 逐一核对。
5. 两个 UserDetailsService Bean 分别指定到各自的链，不要漏。
6. 确认密码库内存储的密文格式，是否为 BCrypt 前缀或纯$2a$开头。

写在最后

说一点个人经验。我第一次搭多页面登录时，满脑子只有一个 SecurityFilterChain，觉得多链是在过度设计。后来被"同一个登录处理地址、两套页面、不同角色权限"的组合拳打得服服帖帖，才明白多SecurityFilterChain不是绕路，而是 Spring Security 官方给出的标准解法。

遇到这类功能，动手写代码前一定要先画一遍请求路径图：哪个 URL 归哪条链管、登录成功后去哪里、登出跳哪里。只要你把路径边界画清楚了，代码基本不会出大问题；如果项目里已经有一条老链，新链加进去时记得把老链的路径边界同步收敛一遍，别让两条链偷偷共享某个前缀。还有一个小建议，多链配置里养成给每条链写注释的习惯，隔三个月再回来看，你会感谢当时的自己。