用户登录模块设计：JWT双Token机制与安全实践全拆解

1. 用户登录需求不是“写个接口”那么简单登录功能大概是所有系统里最容易被低估的模块了。很多团队排期时给它两天上线后发现要改的地方全是登录Token老过期、同一账号被踢下线、验证码看不清、并发登录串号、改密码后旧Token还能用。每一个问题都让人头疼。我之所以想把这个案例完整拆开讲是因为“用户登录”虽然是个老话题但把它做扎实需要同时考虑认证模型、安全策略、状态管理、前端联动和异常兜底。任何一个环节想漏了线上就会出幺蛾子。这篇文章会从方案选型讲起到完整的代码实现和参数配置最后整理我实际排查过的几类高频故障。适合正在做后台管理系统、App账号体系或内部平台的开发者参考哪怕你刚工作一两年照着落地也没问题。先说我踩过的最大一个坑早期做了一个登录接口只验证用户名密码然后放一个userId到Session里上线第二天收到反馈说两个同事同时登录一个账号后登录的人直接能看到前面人的数据。根本原因就是没有做会话管理Session被覆盖也没有感知。从那之后我对登录设计的理解就变了——登录不只是一个身份校验动作而是一整套“会话生命周期”管理。2. 核心设计思路拆解认证模型与整体架构2.1 先想清楚你要的是Session还是Token做登录方案第一件事不是写代码而是选认证模型。现在主流的方案就两类基于Session的会话保持和基于Token的无状态认证。Session方案的特点是简单直接用户登录成功后服务端生成一个会话标识通常是Session ID存一份用户信息在服务端内存或Redis里然后把ID种到Cookie里发给浏览器。后续请求带上Cookie服务端查一下会话是否存在就能确认身份。优点是实现简单、天然支持服务端主动下线把Session删掉即可缺点是分布式环境下Session同步是个麻烦事。Token方案里最流行的是JWT。用户登录成功后服务端签发一个包含用户标识、过期时间、签名信息的字符串客户端保存后续每次请求放在Header里带过来。服务端只验签不解库天然适合分布式和多端场景。缺点是Token一旦发出去服务端很难主动让它失效除非引入额外的黑名单机制。我在这个案例里选择的是JWT方案主要原因有三个项目是前后端分离架构接口可能被App和Web同时调用无状态模型更方便团队希望后续做微服扩展时不需要改造认证逻辑运维不想维护Session复制机制。但我也同时引入了Refresh Token机制来解决JWT主动失效难的问题后面会细讲。2.2 登录模块的整体流程图和模块划分整个登录模块如果拆开看会包含下面这几个独立的子模块验证码模块负责生成、校验图形验证码或行为验证码防止机器暴力尝试。认证核心模块负责用户名密码校验、密码哈希比对、签发Access Token和Refresh Token。会话管理模块维护已登录用户的有效会话记录支持主动踢人、退出登录、Token续期。安全防护模块包含登录失败次数限制、异地登录提醒、密码策略校验。用户查询模块根据用户名或手机号加载用户账号信息、状态、角色权限。这五个模块在逻辑上是独立的但实际运转时是串联的。用一句话描述完整登录流程就是用户输入账号密码和验证码前端先请求验证码校验接口通过后提交登录请求后端先校验验证码再校验账号密码然后签发Token返回给前端前端保存Token并在后续请求的Header里带上后端通过拦截器统一校验Token的合法性和有效期必要时通过Refresh Token自动续期。我很坚持一个原则验证码校验必须放在密码校验之前。原因很朴素——验证码的校验成本非常低而密码哈希比对的计算开销相对高。如果攻击者用脚本猛撞接口先把验证码这层过滤掉能把大部分无效请求挡在门外减轻数据库和哈希计算的压力。这个顺序问题我见过很多人搞反结果验证码形同虚设。2.3 为什么需要Access Token和Refresh Token双Token机制只用一个JWT做登录令牌会陷入一个两难过期时间设短了用户用着用着就被踢下线体验很差设长了Token泄露后的风险窗口期太长而且用户改密码后旧Token仍然有效。双Token机制可以很好地拆解这个矛盾。Access Token有效期短通常15分钟到2小时用于正常访问接口Refresh Token有效期长通常7天到30天只用于换取新的Access Token。用户持有的Access Token过期后前端拿Refresh Token调用刷新接口服务端验证Refresh Token是否有效有效就签发一个新的Access Token。这个案例里Access Token设置为30分钟Refresh Token设置为7天。这个参数不是拍脑袋定的而是根据业务场景倒推的目标是用户一天之内最多登录一次Access Token如果30分钟过期用户如果连续使用就会在静默状态下自动续期感知不到登录态被清掉。而7天的Refresh Token有效期保证一周内回到系统不需要重新输密码超过一周强制登录一次也顺便提醒用户密码没有换。双Token机制还带来一个额外好处可以实现“改密码后其他端强制下线”。用户修改密码时把所有Refresh Token记录删除这样旧Refresh Token失效自然拿不到新的Access Token达到全端踢出的效果。这不是JWT本身支持的但配合服务端维护的Refresh Token记录表就能做到。3. 核心安全细节与关键技术点3.1 密码存储不能只做MD5加密我在不少项目里见过直接用MD5存密码的这基本等于把密码明文交给了数据库管理员。MD5本身不是加密算法而是摘要算法特点是计算速度快、结果固定这意味着攻击者可以预计算海量常见密码的MD5值拿到数据库后一比对就还原出密码。正确的做法是使用带盐的慢速哈希算法。推荐bcrypt这个算法故意设计得计算很慢一次哈希大概需要100毫秒级别攻击者想暴力破解的成本会成倍增加。bcrypt的另一个好处是盐值自动混入哈希结果中开发者不需要额外维护盐字段。实际使用时只需要一行代码// 加密存储 String encodedPassword BCrypt.hashpw(rawPassword, BCrypt.gensalt(12)); // 校验匹配 boolean matched BCrypt.checkpw(rawPassword, encodedPassword);这里的参数12代表计算轮数的对数数字越大计算越慢。我建议普通项目用10到12之间太小的轮数安全度不够太大的轮数用户登录时等待时间会变长。在普通服务器上轮数10大约耗时50到80毫秒轮数12大约耗时200到300毫秒体验上还能接受。顺带提一句如果项目用的是Spring Security它内置的BCryptPasswordEncoder就是bcrypt实现直接把Bean配置进去就能用不用自己封装工具类。如果项目没有引入Spring Security单独引入一个密码哈希库即可逻辑上是等价的。3.2 验证码设计图形验证码与行为验证码的取舍最常见的验证码形态是图形验证码后端生成一张带干扰线的图片图片里是一串随机字符用户在输入框填入字符后端比对。实现成本低但用户体验确实一般而且随着OCR识别技术进步纯字符图形验证码的安全性已经大不如前。这个案例里我采用的是图形验证码作为兜底再加一层隐藏的行为校验字段。具体做法是后端生成验证码时返回一个UUID作为验证码标识和图形Base64给前端同时把验证码的正确值存储在Redis里设置5分钟过期前端提交登录时带上UUID和用户输入的验证码值后端从Redis取出比对比对完立即删除保证一个验证码只能用一次。至于行为校验不需要接入很重的第三方服务可以在生成验证码时记录一个验证码坐标特征。这个方案听起来玄乎但实现起来不复杂生成验证码时在前端埋点采集鼠标移动轨迹、页面停留时长、输入框聚焦次数登录时一并以密文形式提交后端解密后判断这些特征是否符合人类操作规律。如果没有行为采集数据就直接走图形验证码兜底。这套组合的现实意义很直接正常用户绝大多数情况下不需要看验证码系统自动放行被判定为可疑的请求才弹验证码。既能挡住机器流量又不至于把正常用户惹毛。当然如果你的项目没有精力和资源做行为采集保留一套图形验证码也比什么都没有强。3.3 登录防暴力破解失败次数限制与锁定策略不设失败次数限制的登录接口等于是把账号密码库暴露给任何会写循环脚本的人。我见过一个内部系统的登录接口因为没有限流被脚本以每秒十几次的速度尝试弱密码最后运维发现数据库连接被占满才排查到原因。当时的第一反应就是把登录失败限制加上去。失败限制的思路并不复杂核心是按账号和IP两个维度分别计数。用Redis记录该账号的失败次数如果连续失败5次锁定该账号15分钟同时记录来源IP的失败次数同一个IP连续失败超过20次锁定这个IP一小时。这里为什么要区分两个维度因为攻击者可能换IP撞同一个账号也可能用同一个IP撞一堆账号只限制单一维度会被绕过。具体的数据结构可以这样设计Redis里存两个Key一个是login:fail:user:{userId}值为失败次数另一个是login:fail:ip:{ip}值为次数。每次登录失败就把对应Key自增1并设置过期时间。登录成功或验证码校验通过后重置Key。当次数超过阈值时返回提示“尝试次数过多请稍后再试”。需要注意一个细节锁定状态不建议用另一个Key单独存而是直接通过失败次数Key的过期时间来实现。当失败的Key存在且计数达到阈值时就表示锁定中Key本身过期后锁定自动解除。这样能少维护一种状态也避免了解锁逻辑的遗漏。3.4 Token的生成、校验与续期逻辑JWT的结构分为三段Header、Payload、Signature。Header声明加密算法和Token类型Payload放用户ID、过期时间等声明字段Signature用服务端私钥对前两段做签名。客户端拿到这个三段式字符串后可以解析出Payload里的信息但无法篡改内容因为一旦改动内容签名校验就会失败。我选择使用对称加密算法HS256来签JWT也就是服务端用一个同时用于签名和验签的密钥。这个方案不需要额外的公钥分发流程算法成熟稳定非常适合单个服务端签发的场景。如果以后登录服务独立成一个鉴权中心、多个业务服务各自验签再考虑切换RS256这种非对称算法。生成Access Token的代码逻辑如下String accessToken Jwts.builder() .setSubject(userId.toString()) .claim(username, user.getUsername()) .claim(role, user.getRole()) .setIssuedAt(new Date()) .setExpiration(new Date(System.currentTimeMillis() 30 * 60 * 1000)) .signWith(secretKey, SignatureAlgorithm.HS256) .compact();Refresh Token的生成方式和Access Token基本一致区别在于有效期设置和用途。Refresh Token里不需要放角色权限这些频繁变化的声明只需要用户ID和一个随机生成的会话ID便于后续做会话管理和主动失效。续期逻辑是这样的当服务端校验Access Token发现已经过期则返回一个约定的过期状态码前端收到后自动调用刷新接口同时把Refresh Token发给服务端。服务端从数据库或Redis中查到这个Refresh Token是否存在且状态有效如果有效就重新生成Access Token返回同时可以顺带把Refresh Token轮换掉——意思是一次刷新之后旧Refresh Token作废签发新的Refresh Token。这个轮换机制能有效防止Refresh Token被截获后长时间重用。4. 实操过程从数据库到接口的完整实现4.1 数据库表结构设计与字段说明整个登录模块只需要两张核心表用户表和刷新令牌表。用户表存的是账号基础信息和密码哈希值刷新令牌表存的是已签发的Refresh Token及其状态。用户表的字段设计如下字段名类型说明idbigint主键usernamevarchar(50)登录账号唯一索引passwordvarchar(100)bcrypt哈希值nicknamevarchar(50)用户昵称statustinyint账号状态1正常0禁用last_login_timedatetime最近一次登录时间last_login_ipvarchar(50)最近一次登录IPcreated_atdatetime创建时间updated_atdatetime更新时间刷新令牌表的字段设计如下字段名类型说明idbigint主键user_idbigint关联用户IDtoken_idvarchar(64)Refresh Token的唯一IDexpires_atdatetime过期时间revokedtinyint是否已撤销0有效1撤销created_atdatetime签发时间Refresh Token本身携带的信息已经包含用户ID和过期时间为什么还要在数据库里存一份呢因为只有存下来才能实现主动撤销。用户改密码、管理员禁用账号、用户主动退出登录时把对应记录标记为撤销这个Refresh Token才真正失效。4.2 登录接口的后端实现细节登录接口的核心流程是这样PostMapping(/login) public Result? login(RequestBody LoginRequest request, HttpServletRequest httpRequest) { // 1. 校验验证码 String cachedCaptcha redisTemplate.opsForValue().get(captcha: request.getCaptchaId()); if (cachedCaptcha null || !cachedCaptcha.equalsIgnoreCase(request.getCaptchaCode())) { return Result.error(验证码错误或已过期); } redisTemplate.delete(captcha: request.getCaptchaId()); // 2. 检查账号锁定状态 String failKey login:fail:user: request.getUsername(); String failCount redisTemplate.opsForValue().get(failKey); if (failCount ! null Integer.parseInt(failCount) 5) { return Result.error(尝试次数过多账号已锁定15分钟); } // 3. 校验账号密码 User user userMapper.findByUsername(request.getUsername()); if (user null || !BCrypt.checkpw(request.getPassword(), user.getPassword())) { redisTemplate.opsForValue().increment(failKey); redisTemplate.expire(failKey, 15, TimeUnit.MINUTES); return Result.error(用户名或密码错误); } // 4. 检查账号状态 if (user.getStatus() 0) { return Result.error(账号已被禁用); } // 5. 登录成功清除失败记录签发Token redisTemplate.delete(failKey); String accessToken generateAccessToken(user); String refreshToken generateRefreshToken(user); refreshTokenMapper.save(user.getId(), refreshTokenId, expireDate); updateLoginInfo(user.getId(), httpRequest.getRemoteAddr()); return Result.success(Map.of( accessToken, accessToken, refreshToken, refreshToken )); }这里有几个顺序上的细节值得反复强调验证码校验必须最先执行而且校验通过后必须立即删除Redis中缓存的验证码防止同一个验证码被重复使用锁定状态检查要在密码校验之前否则锁定的账号依然会消耗哈希比对的计算资源账号状态检查要放在密码校验之后这样做可以避免通过接口探测哪些账号被禁用——即使账号被禁用接口返回的还是“用户名或密码错误”这个统一文案不泄露多余信息。4.3 拦截器设计与Token校验完成了登录接口还需要一个全局拦截器来保护需要登录才能访问的接口。这个拦截器的作用是在请求进入Controller之前统一完成Token解析和校验。我用Spring的HandlerInterceptor来实现需要配置白名单路径比如登录接口本身、获取验证码接口、刷新Token接口不需要拦截其余接口全部拦截。public class AuthInterceptor implements HandlerInterceptor { Override public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception { if (OPTIONS.equals(request.getMethod())) { return true; } String authHeader request.getHeader(Authorization); if (authHeader null || !authHeader.startsWith(Bearer )) { response.setStatus(401); return false; } String token authHeader.substring(7); try { Claims claims Jwts.parserBuilder() .setSigningKey(secretKey) .build() .parseClaimsJws(token) .getBody(); Long userId Long.parseLong(claims.getSubject()); request.setAttribute(userId, userId); request.setAttribute(username, claims.get(username)); // 检查账号是否仍然有效 User user userMapper.findById(userId); if (user null || user.getStatus() 0) { response.setStatus(401); return false; } return true; } catch (ExpiredJwtException e) { response.setStatus(401); response.setHeader(X-Token-Expired, true); return false; } catch (JwtException e) { response.setStatus(401); return false; } } }拦截器里校验Token之后再查一次用户状态这一步非常关键。虽然Token本身有效但用户可能已经被管理员禁用如果只校验Token不查状态被禁用的用户还能继续访问接口直到Token过期。加一次查询的代价很小但能避免这类安全隐患。4.4 前端联调与Token携带、刷新策略前端这部分虽然代码不多但细节决定体验。我用axios统一封装请求在请求拦截器里带上Token在响应拦截器里统一处理过期场景。// 请求拦截器 service.interceptors.request.use(config { const token localStorage.getItem(accessToken); if (token) { config.headers[Authorization] Bearer token; } return config; }); // 响应拦截器 service.interceptors.response.use( response response.data, async error { const { response } error; if (response response.status 401) { if (response.headers[x-token-expired]) { // Access Token过期尝试刷新 const refreshed await refreshAccessToken(); if (refreshed) { // 重新发起原始请求 return service(error.config); } } // 刷新失败跳转登录页 window.location.href /login; } return Promise.reject(error); } );这段逻辑里容易踩坑的是防止刷新接口的请求再次触发401后进入refreshAccessToken形成死循环。我的处理方式是给刷新接口的请求单独打一个标记在响应拦截器里判断如果是刷新接口本身报401直接跳登录页不尝试再次刷新。另外refreshAccessToken里要做一个并发锁防止多个请求同时过期后同时发起刷新请求导致Refresh Token被轮换多次前面的请求用旧Token换不到新的。简单做法是记录一个刷新Promise重复调用时直接返回同一个Promise。4.5 退出登录与会话清理退出登录的逻辑看着简单但要考虑三种端的情况Web端、App端、同账号多个并发会话。最稳妥的做法是前端调退出接口把当前Refresh Token标记撤销同时前端清除本地存储的Access Token和Refresh Token。如果某个端没有调退出接口直接关掉了其实问题也不大因为Access Token有效期只有30分钟Refresh Token有7天。最坏情况是Refresh Token在7天内还能被用来换取新的Access Token。如果要求更严格可以把Refresh Token改成单次使用——每次刷新后旧Refresh Token立即作废同时可以检测到同一Refresh Token被重复使用判定为异常把该用户所有Refresh Token全部撤销。这就是前面提到的轮换机制的价值所在。我额外加了一个“全端退出”能力当用户修改密码或管理员手动踢出某个会话时把该用户或指定token_id对应的记录标记为撤销。如果目标是全端退出直接按照user_id把所有Refresh Token全部撤销即可。配合轮换机制旧Access Token最长也只有30分钟的生命周期不会造成太长的风险窗口。5. 高频故障排查实录和避坑指南5.1 登录成功后访问接口马上401有这个问题的同学最先要检查的是服务器时区。JWT的过期时间戳用的是UTC时间如果服务器设置的时区不是UTC8解析出的系统当前时间和签发过期时间之间会出现偏差导致Token刚签发就判定为过期。排查方法很简单在生成Token和解析Token时分别打印一下系统当前时间和Token过期时间对比一下相差的秒数。如果偏差正好是8小时或某个固定偏移量那就是时区问题把应用启动时区显式配置为Asia/Shanghai即可。第二个常见原因是服务端密钥不对。如果项目部署了多个实例每个实例配置的JWT密钥不同就会出现一台机器签发的Token另一台机器校验失败的情况。部署多实例时务必确认JWT密钥在所有实例中完全一致最好用同一个环境变量统一注入。还有一个容易被忽略的场景前端请求的Header名字和后端读取的名字不一致比如前端传的是Authorization后端误写成token结果所有请求都拿不到Token。5.2 并发登录导致会话被踢当同一个账号在多个终端登录时如果不做处理每个会话各自持有独立的Refresh Token互不影响。但如果业务要求同一账号只能在一个终端登录就需要维护一个当前有效会话的标识。我用的方案是在Redis里存一个user:activeSession:{userId}值为当前会话的Token Session ID。登录成功时写入其他接口请求时如果解析出的Session ID和Redis中存储的不一致则判定为被踢下线返回特定状态码。用户被踢下线后会跳转到登录页并提示“您的账号在其他设备登录”。这个方案的思路是后登录的会话覆盖先登录的会话实现简单适合大多数内部系统。如果业务要求同一个账号最多允许两个终端在线那就维护一个在线会话ID列表Redis里的数据结构用List或Set存会话ID新登录时加入超过上限后移除最旧的那个。实现也不复杂但注意要同时维护过期清理逻辑防止Redis里堆积大量已失效的会话记录。5.3 Refresh Token反复刷新失败这类问题的典型场景前端开了多个Tab页一个Token过期后多个Tab同时发起刷新请求每个请求都拿着同一个Refresh Token去换新的Access Token。如果服务端实现了Refresh Token轮换那么第一个请求成功后旧Refresh Token就被撤销了后续请求拿旧Refresh Token就会失败。我前面提到过在前端必须做刷新Promise的并发复用这个坑才能避开。服务端也可以做一层兜底如果同一个Refresh Token在短时间内被连续使用多次不要简单拒绝而是判定为Token重用攻击撤销该用户所有Refresh Token强制重新登录。这个策略来自标准的安全实践对防止Token泄露出奇有效。5.4 网关或跨域配置影响Token传递前后端分离项目里跨域问题几乎必然出现。要重点检查两个配置跨域许可的Header列表里是否包含AuthorizationNginx或网关转发请求时是否设置了proxy_set_header Authorization $http_authorization。这两个问题有典型的症状使用Postman测试接口完全正常但浏览器里请求就401。原因是浏览器发起跨域预检请求时如果服务端返回的Access-Control-Allow-Headers里没有Authorization正式请求的Header就不会被带过去。排查时打开浏览器开发者工具看网络请求如果预检请求正常但正式请求没有Authorization头问题就在第一个配置上。反代场景下如果Nginx没有显式传递Authorization头后端收到的请求里这个头就是空的。这个坑不太容易发现因为本地测试不走Nginx一切正常部署到测试环境就全部401。6. 登录安全体系还能怎么延伸用户名密码加验证码加Token这套组合能满足大多数常规系统的需求但如果系统需要更高级别的安全能力可以在现有基础上继续延伸。多因素认证是目前性价比最高的加固方案。在密码校验通过后如果用户开启了二次验证则要求输入动态验证码或TOTP验证码。实现上可以在用户表增加一个totp_secret字段用户开启二次验证时生成Base32格式的密钥前端用标准TOTP算法每30秒生成一个6位数字验证码。服务端校验时验证这个动态码是否匹配密钥和当前时间窗口。整个过程不依赖短信服务成本为零。另一个值得加的机制是登录风险评估。可以记录用户的常用登录IP和设备指纹如果检测到非常用地区或新设备要求额外验证。这块做轻量实现不需要引入复杂的风控系统在登录成功前后各加一道判断即可。最后提醒一点登录模块的功能越做越多之后不要忘了给整个鉴权流程加上可观测性。关键操作比如登录成功、登录失败、Token刷新、账号锁定都需要打日志。日志里不要记录明文密码和完整Token只记录用户ID、IP、操作类型和结果状态。有了日志线上出了安全问题才有回溯的线索否则排查就像大海捞针。我在这个案例中的体会是登录模块不怕基础怕的是想当然。凡是觉得“不就是查一下密码对不对吗”的地方都是后面出问题的重灾区。把验证顺序、Token生命周期、会话清理机制这些细节想透了整个登录体系才会真正稳定。希望这份拆解能帮你跳过那些我踩过的坑把登录功能做成经得起线上考验的样子。