一、概述
用户注册、邮件验证和找回密码是知识库系统的核心安全功能。
本文将详细介绍如何实现一个完整的用户认证体系,涵盖注册流程、邮件激活验证、密码找回重置三大模块,并配套密码策略管理和前端交互实现。
1.1 功能定位
| 功能模块 | 说明 | 使用场景 |
|---|---|---|
| 用户注册 | 新用户自助注册并选择所属团队空间 | 新成员加入 |
| 邮件验证 | 注册后发送激活邮件,点击链接激活账户 | 身份验证 |
| 找回密码 | 通过邮箱获取验证码,重置登录密码 | 忘记密码 |
| 密码策略 | 动态配置密码复杂度要求(低/中/高三级) | 安全合规 |
| 前端集成 | 登录页注册Tab、激活页、找回密码页 | 用户交互 |
1.2 业务流程

1.3 技术架构

1.4 核心技术栈
| 技术 | 用途 |
|---|---|
| Spring Boot 3.x | 后端框架 |
| Spring Security | 认证授权 |
| Spring Mail (JavaMailSender) | 邮件发送 |
| MyBatis Plus | 数据库操作 |
| Redis | 验证码缓存、配置缓存 |
| BCrypt | 密码加密 |
| UUID | 激活Token生成 |
| React 18 + TypeScript | 前端开发 |
| Ant Design 5.x | 前端UI组件 |
| Zustand | 前端状态管理 |
二、数据库设计
2.1 用户表结构
用户表 kb_user 是认证体系的核心,需要支持注册、激活、密码重置等功能的字段设计:
CREATE TABLE `kb_user` (
`id` BIGINT NOT NULL COMMENT '用户ID(雪花算法生成)',
`username` VARCHAR(50) NOT NULL COMMENT '用户名',
`password` VARCHAR(200) NOT NULL COMMENT '密码(BCrypt加密)',
`email` VARCHAR(100) DEFAULT NULL COMMENT '邮箱',
`phone` VARCHAR(20) DEFAULT NULL COMMENT '手机号',
`real_name` VARCHAR(50) DEFAULT NULL COMMENT '真实姓名',
`avatar` VARCHAR(500) DEFAULT NULL COMMENT '头像URL',
`status` TINYINT NOT NULL DEFAULT 0 COMMENT '状态(0-禁用,1-启用,2-锁定)',
`email_verified` TINYINT NOT NULL DEFAULT 0 COMMENT '邮箱是否已验证(0-否,1-是)',
`activation_token` VARCHAR(100) DEFAULT NULL COMMENT '激活Token(UUID)',
`activation_token_expiry` DATETIME DEFAULT NULL COMMENT '激活Token过期时间',
`last_login_time` DATETIME DEFAULT NULL COMMENT '最后登录时间',
`last_login_ip` VARCHAR(50) DEFAULT NULL COMMENT '最后登录IP',
`position` VARCHAR(100) DEFAULT NULL COMMENT '职位',
`remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
`version` INT NOT NULL DEFAULT 0 COMMENT '乐观锁版本号',
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
`create_by` BIGINT DEFAULT NULL COMMENT '创建人',
`update_by` BIGINT DEFAULT NULL COMMENT '更新人',
`deleted` TINYINT NOT NULL DEFAULT 0 COMMENT '删除标识(0-未删除,1-已删除)',
PRIMARY KEY (`id`),
UNIQUE KEY `uk_username` (`username`),
UNIQUE KEY `uk_email` (`email`),
KEY `idx_status` (`status`),
KEY `idx_activation_token` (`activation_token`),
KEY `idx_email_verified` (`email_verified`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户表';2.2 用户角色关联表
CREATE TABLE `kb_user_role` (
`id` BIGINT NOT NULL COMMENT 'ID',
`user_id` BIGINT NOT NULL COMMENT '用户ID',
`role_id` BIGINT NOT NULL COMMENT '角色ID',
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
PRIMARY KEY (`id`),
KEY `idx_user_id` (`user_id`),
KEY `idx_role_id` (`role_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户角色关联表';2.3 字段说明
| 字段 | 类型 | 说明 | 注册赋值 | 激活后赋值 |
|---|---|---|---|---|
| id | BIGINT | 雪花算法ID | 自动生成 | - |
| username | VARCHAR(50) | 用户名,唯一 | 用户填写 | - |
| password | VARCHAR(200) | BCrypt加密密码 | 加密存储 | - |
| VARCHAR(100) | 邮箱,唯一 | 用户填写 | - | |
| real\_name | VARCHAR(50) | 真实姓名 | 用户填写 | - |
| status | TINYINT | 0=禁用 1=启用 | 0 | 1 |
| email\_verified | TINYINT | 0=未验证 1=已验证 | 0 | 1 |
| activation\_token | VARCHAR(100) | UUID激活Token | 生成UUID | 清除(NULL) |
| activation\_token\_expiry | DATETIME | Token过期时间 | 创建时间+24h | 清除(NULL) |
2.4 索引设计
- **唯一索引 **
uk_username:防止用户名重复,注册时校验 - **唯一索引 **
uk_email:防止邮箱重复注册,同时用于找回密码时查用户 - **索引 **
idx_activation_token:加速激活邮件的Token查询 - **索引 **
idx_status:查询启用/禁用用户列表 - **索引 **
idx_email_verified:统计已验证用户
2.5 Redis缓存设计
密码重置验证码存储在Redis中:
| Key | Value | TTL | 说明 |
|---|---|---|---|
password:reset:code:user@example.com | 6位数字验证码 | 10分钟 | 密码重置验证码 |
kb:system:config | Hash(所有系统配置) | 永久 | 系统配置缓存 |
Redis配置Key前缀隔离,防止Key冲突:
# application.yml
spring:
data:
redis:
host: ${REDIS_HOST:localhost}
port: ${REDIS_PORT:6379}
password: ${REDIS_PASSWORD:}三、实体类设计
3.1 创建User实体类
创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/entity/User.java:
package com.knowledge.base.userauth.entity;
import com.baomidou.mybatisplus.annotation.TableName;
import com.knowledge.base.common.config.BaseEntity;
import lombok.Data;
import lombok.EqualsAndHashCode;
import java.time.LocalDateTime;
/**
* 用户实体类
*
* <p>存储用户认证与个人信息,支持邮箱验证和密码重置</p>
*
* @author 苏三
* @since 1.0.0
*/
@Data
@EqualsAndHashCode(callSuper = true)
@TableName("kb_user")
public class User extends BaseEntity {
/**
* 用户名
*/
private String username;
/**
* 密码(BCrypt加密存储)
*/
private String password;
/**
* 邮箱
*/
private String email;
/**
* 手机号
*/
private String phone;
/**
* 真实姓名
*/
private String realName;
/**
* 头像URL
*/
private String avatar;
/**
* 状态(0-禁用,1-启用,2-锁定)
*/
private Integer status;
/**
* 邮箱是否已验证(0-否,1-是)
*/
private Integer emailVerified;
/**
* 激活Token(邮箱验证用,验证后清除)
*/
private String activationToken;
/**
* 激活Token过期时间
*/
private LocalDateTime activationTokenExpiry;
/**
* 最后登录时间
*/
private LocalDateTime lastLoginTime;
/**
* 最后登录IP
*/
private String lastLoginIp;
/**
* 职位
*/
private String position;
/**
* 备注
*/
private String remark;
}3.2 设计思路
- 继承BaseEntity:复用
id、createdAt、updatedAt、createBy、updateBy、deleted、version基础字段 - status字段三态设计:0=禁用(注册后未激活),1=启用(激活后),2=锁定(登录失败次数过多)
- emailVerified 独立于 status:明确区分"邮箱是否验证"与"账户是否启用"
- activationToken 用后清除:验证成功后 set null,防止Token被重复使用
四、DTO和VO设计
4.1 创建RegisterDTO
创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/dto/RegisterDTO.java:
package com.knowledge.base.userauth.dto;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import jakarta.validation.constraints.Size;
import lombok.Data;
import java.io.Serializable;
/**
* 用户注册DTO
*
* @author 苏三
* @since 1.0.0
*/
@Data
@Schema(description = "用户注册请求")
public class RegisterDTO implements Serializable {
private static final long serialVersionUID = 1L;
@NotBlank(message = "用户名不能为空")
@Size(min = 4, max = 20, message = "用户名长度4-20个字符")
@Schema(description = "用户名", example = "zhangsan")
private String username;
@NotBlank(message = "密码不能为空")
@Size(min = 6, max = 50, message = "密码长度6-50个字符")
@Schema(description = "密码", example = "Abc123!@")
private String password;
@NotBlank(message = "确认密码不能为空")
@Schema(description = "确认密码", example = "Abc123!@")
private String confirmPassword;
@NotBlank(message = "邮箱不能为空")
@Email(message = "邮箱格式不正确")
@Schema(description = "邮箱", example = "user@example.com")
private String email;
@NotBlank(message = "真实姓名不能为空")
@Size(max = 50, message = "真实姓名长度不能超过50个字符")
@Schema(description = "真实姓名", example = "张三")
private String realName;
@Schema(description = "手机号", example = "13800138000")
private String phone;
@NotNull(message = "请选择团队空间")
@Schema(description = "团队空间ID", example = "1")
private Long teamId;
}4.2 创建RegisterVO
创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/vo/RegisterVO.java:
package com.knowledge.base.userauth.vo;
import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import java.io.Serializable;
/**
* 用户注册响应VO
*
* @author 苏三
* @since 1.0.0
*/
@Data
@Schema(description = "注册响应")
public class RegisterVO implements Serializable {
private static final long serialVersionUID = 1L;
@Schema(description = "用户ID")
private Long userId;
@Schema(description = "是否需要邮箱验证")
private boolean emailVerificationRequired;
@Schema(description = "提示消息")
private String message;
@Schema(description = "登录信息(邮箱不需要验证时直接返回)")
private LoginVO loginInfo;
}4.3 创建密码重置相关DTO
创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/dto/SendResetCodeDTO.java:
package com.knowledge.base.userauth.dto;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import lombok.Data;
import java.io.Serializable;
/**
* 发送重置验证码DTO
*
* @author 苏三
* @since 1.0.0
*/
@Data
@Schema(description = "发送密码重置验证码请求")
public class SendResetCodeDTO implements Serializable {
private static final long serialVersionUID = 1L;
@NotBlank(message = "邮箱不能为空")
@Email(message = "邮箱格式不正确")
@Schema(description = "注册邮箱", example = "user@example.com")
private String email;
}创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/dto/VerifyResetCodeDTO.java:
package com.knowledge.base.userauth.dto;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import lombok.Data;
import java.io.Serializable;
/**
* 验证重置码DTO
*
* @author 苏三
* @since 1.0.0
*/
@Data
@Schema(description = "验证密码重置码请求")
public class VerifyResetCodeDTO implements Serializable {
private static final long serialVersionUID = 1L;
@NotBlank(message = "邮箱不能为空")
@Email(message = "邮箱格式不正确")
@Schema(description = "注册邮箱", example = "user@example.com")
private String email;
@NotBlank(message = "验证码不能为空")
@Size(min = 6, max = 6, message = "验证码为6位数字")
@Schema(description = "6位验证码", example = "123456")
private String code;
}创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/dto/ResetPasswordDTO.java:
package com.knowledge.base.userauth.dto;
import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.Email;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;
import lombok.Data;
import java.io.Serializable;
/**
* 重置密码DTO
*
* @author 苏三
* @since 1.0.0
*/
@Data
@Schema(description = "重置密码请求")
public class ResetPasswordDTO implements Serializable {
private static final long serialVersionUID = 1L;
@NotBlank(message = "邮箱不能为空")
@Email(message = "邮箱格式不正确")
@Schema(description = "注册邮箱", example = "user@example.com")
private String email;
@NotBlank(message = "验证码不能为空")
@Schema(description = "6位验证码", example = "123456")
private String code;
@NotBlank(message = "新密码不能为空")
@Size(min = 6, max = 50, message = "密码长度6-50个字符")
@Schema(description = "新密码", example = "NewPass123!")
private String newPassword;
}4.4 设计说明
DTO与VO的职责分离:
| 类型 | 用途 | 校验 | 文件 |
|---|---|---|---|
| RegisterDTO | 接收注册表单数据 | @NotBlank、@Size、@Email | 入参校验 |
| SendResetCodeDTO | 接收邮箱 | @Email | 入参校验 |
| VerifyResetCodeDTO | 接收邮箱+验证码 | 双重校验 | 入参校验 |
| ResetPasswordDTO | 接收邮箱+验证码+新密码 | 三重校验 | 入参校验 |
| RegisterVO | 返回注册结果 | 无 | 响应构造 |
设计原则:
- DTO仅包含客户端提交的字段,用
@Valid开启校验 - VO包含服务端计算出的字段(如
emailVerificationRequired) - 密码重置分三步,每步使用独立DTO,避免单一大对象耦合
五、数据访问层
5.1 创建UserMapper接口
创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/mapper/UserMapper.java:
package com.knowledge.base.userauth.mapper;
import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.knowledge.base.userauth.entity.User;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
/**
* 用户Mapper接口
*
* @author 苏三
* @since 1.0.0
*/
@Mapper
public interface UserMapper extends BaseMapper<User> {
/**
* 根据用户名查询用户
*/
User selectByUsername(@Param("username") String username);
/**
* 根据邮箱查询用户
*/
User selectByEmail(@Param("email") String email);
/**
* 根据手机号查询用户
*/
User selectByPhone(@Param("phone") String phone);
/**
* 根据激活Token查询用户
*/
User selectByActivationToken(@Param("activationToken") String activationToken);
}5.2 创建Mapper XML
创建 kb-user-auth/src/main/resources/mapper/UserMapper.xml:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
"http://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.knowledge.base.userauth.mapper.UserMapper">
<resultMap id="BaseResultMap" type="com.knowledge.base.userauth.entity.User">
<id column="id" property="id" />
<result column="username" property="username" />
<result column="password" property="password" />
<result column="email" property="email" />
<result column="phone" property="phone" />
<result column="real_name" property="realName" />
<result column="avatar" property="avatar" />
<result column="status" property="status" />
<result column="email_verified" property="emailVerified" />
<result column="activation_token" property="activationToken" />
<result column="activation_token_expiry" property="activationTokenExpiry" />
<result column="last_login_time" property="lastLoginTime" />
<result column="last_login_ip" property="lastLoginIp" />
<result column="position" property="position" />
<result column="remark" property="remark" />
<result column="version" property="version" />
<result column="created_at" property="createdAt" />
<result column="updated_at" property="updatedAt" />
<result column="create_by" property="createBy" />
<result column="update_by" property="updateBy" />
<result column="deleted" property="deleted" />
</resultMap>
<sql id="Base_Column_List">
id, username, password, email, phone, real_name, avatar,
status, email_verified, activation_token, activation_token_expiry,
last_login_time, last_login_ip, position, remark,
version, created_at, updated_at, create_by, update_by, deleted
</sql>
<!-- 根据用户名查询用户(排除已删除) -->
<select id="selectByUsername" resultMap="BaseResultMap">
SELECT <include refid="Base_Column_List" />
FROM kb_user
WHERE username = #{username}
AND deleted = 0
</select>
<!-- 根据邮箱查询用户 -->
<select id="selectByEmail" resultMap="BaseResultMap">
SELECT <include refid="Base_Column_List" />
FROM kb_user
WHERE email = #{email}
AND deleted = 0
</select>
<!-- 根据手机号查询用户 -->
<select id="selectByPhone" resultMap="BaseResultMap">
SELECT <include refid="Base_Column_List" />
FROM kb_user
WHERE phone = #{phone}
AND deleted = 0
</select>
<!-- 根据激活Token查询用户 -->
<select id="selectByActivationToken" resultMap="BaseResultMap">
SELECT <include refid="Base_Column_List" />
FROM kb_user
WHERE activation_token = #{activationToken}
AND deleted = 0
</select>
</mapper>5.3 MyBatis Plus自动能力
继承 BaseMapper<User> 后,以下SQL自动生成无需手写:
// 基本CRUD - 自动生成
userMapper.insert(user); // INSERT INTO kb_user ...
userMapper.selectById(id); // SELECT ... WHERE id = ?
userMapper.selectList(wrapper); // SELECT ... WHERE 条件
userMapper.updateById(user); // UPDATE kb_user SET ... WHERE id = ?
userMapper.deleteById(id); // 逻辑删除 UPDATE kb_user SET deleted = 1 WHERE id = ?六、业务逻辑层
6.1 邮件服务
创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/service/EmailService.java:
package com.knowledge.base.userauth.service;
/**
* 邮件服务接口
*
* @author 苏三
* @since 1.0.0
*/
public interface EmailService {
/**
* 发送账户激活邮件
*
* @param to 收件人邮箱
* @param username 用户名
* @param token 激活Token
*/
void sendActivationEmail(String to, String username, String token);
/**
* 发送密码重置验证码邮件
*
* @param to 收件人邮箱
* @param code 6位验证码
*/
void sendResetCodeEmail(String to, String code);
}创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/service/impl/EmailServiceImpl.java:
package com.knowledge.base.userauth.service.impl;
import com.knowledge.base.userauth.service.EmailService;
import jakarta.annotation.Resource;
import jakarta.mail.MessagingException;
import jakarta.mail.internet.MimeMessage;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.mail.javamail.JavaMailSender;
import org.springframework.mail.javamail.MimeMessageHelper;
import org.springframework.stereotype.Service;
/**
* 邮件服务实现
*
* <p>发送HTML格式的激活邮件和密码重置验证码邮件</p>
*
* @author 苏三
* @since 1.0.0
*/
@Slf4j
@Service
public class EmailServiceImpl implements EmailService {
@Resource
private JavaMailSender mailSender;
@Value("${spring.mail.username}")
private String from;
@Value("${app.frontend-url:http://localhost:3002}")
private String frontendUrl;
/**
* 发送账户激活邮件
*/
@Override
public void sendActivationEmail(String to, String username, String token) {
try {
String activationUrl = frontendUrl + "/activate?token=" + token;
String htmlContent = buildActivationEmail(username, activationUrl);
MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
helper.setFrom(from);
helper.setTo(to);
helper.setSubject("【知识库系统】账户激活邮件");
helper.setText(htmlContent, true);
mailSender.send(message);
log.info("激活邮件发送成功:to={}, username={}", to, username);
} catch (MessagingException e) {
log.error("激活邮件发送失败:to={}, username={}", to, username, e);
throw new RuntimeException("邮件发送失败:" + e.getMessage());
}
}
/**
* 发送密码重置验证码邮件
*/
@Override
public void sendResetCodeEmail(String to, String code) {
try {
String htmlContent = buildResetCodeEmail(code);
MimeMessage message = mailSender.createMimeMessage();
MimeMessageHelper helper = new MimeMessageHelper(message, true, "UTF-8");
helper.setFrom(from);
helper.setTo(to);
helper.setSubject("【知识库系统】密码重置验证码");
helper.setText(htmlContent, true);
mailSender.send(message);
log.info("密码重置验证码邮件发送成功:to={}", to);
} catch (MessagingException e) {
log.error("密码重置验证码邮件发送失败:to={}", to, e);
throw new RuntimeException("邮件发送失败:" + e.getMessage());
}
}
/**
* 构建激活邮件HTML内容
*/
private String buildActivationEmail(String username, String activationUrl) {
return """
<div style="max-width:600px;margin:0 auto;font-family:Arial,sans-serif;">
<div style="background:linear-gradient(135deg,#3b82f6,#8b5cf6);padding:30px;
text-align:center;border-radius:12px 12px 0 0;">
<h1 style="color:#ffffff;margin:0;font-size:24px;">📚 知识库系统</h1>
<p style="color:#e0e7ff;margin:8px 0 0;">账户激活邮件</p>
</div>
<div style="background:#ffffff;padding:30px;border:1px solid #e5e7eb;
border-radius:0 0 12px 12px;">
<p style="color:#374151;font-size:16px;">
你好,<strong>%s</strong>:
</p>
<p style="color:#6b7280;font-size:14px;line-height:1.8;">
感谢你注册知识库系统!请点击下方按钮激活你的账户:
</p>
<div style="text-align:center;margin:30px 0;">
<a href="%s" style="display:inline-block;padding:14px 40px;
background:linear-gradient(135deg,#3b82f6,#8b5cf6);
color:#ffffff;text-decoration:none;border-radius:8px;
font-size:16px;font-weight:600;">
激活账户
</a>
</div>
<p style="color:#9ca3af;font-size:12px;text-align:center;">
或者复制以下链接到浏览器:<br/>
<span style="color:#3b82f6;">%s</span>
</p>
<div style="border-top:1px solid #e5e7eb;margin-top:30px;padding-top:20px;
text-align:center;">
<p style="color:#9ca3af;font-size:12px;">
⏰ 此链接在24小时内有效 | 如非本人操作请忽略此邮件
</p>
</div>
</div>
</div>
""".formatted(username, activationUrl, activationUrl);
}
/**
* 构建密码重置验证码邮件HTML内容
*/
private String buildResetCodeEmail(String code) {
return """
<div style="max-width:600px;margin:0 auto;font-family:Arial,sans-serif;">
<div style="background:linear-gradient(135deg,#f59e0b,#ef4444);padding:30px;
text-align:center;border-radius:12px 12px 0 0;">
<h1 style="color:#ffffff;margin:0;font-size:24px;">🔐 知识库系统 - 密码重置</h1>
</div>
<div style="background:#ffffff;padding:30px;border:1px solid #e5e7eb;
border-radius:0 0 12px 12px;">
<p style="color:#374151;font-size:16px;">
你正在申请重置密码,验证码如下:
</p>
<div style="text-align:center;margin:30px 0;">
<span style="display:inline-block;padding:16px 40px;
background:#fef3c7;border:2px dashed #f59e0b;
border-radius:8px;font-size:32px;font-weight:700;
color:#92400e;letter-spacing:8px;">
%s
</span>
</div>
<div style="border-top:1px solid #e5e7eb;margin-top:30px;padding-top:20px;
text-align:center;">
<p style="color:#9ca3af;font-size:12px;">
⏰ 验证码有效期为10分钟 | 如非本人操作请忽略此邮件
</p>
</div>
</div>
</div>
""".formatted(code);
}
}6.2 验证Token工具类
创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/util/VerificationTokenUtil.java:
package com.knowledge.base.userauth.util;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
import java.time.LocalDateTime;
import java.util.UUID;
/**
* 验证Token工具类
*
* <p>生成邮箱激活Token,管理Token过期时间</p>
*
* @author 苏三
* @since 1.0.0
*/
@Component
public class VerificationTokenUtil {
/** Token过期时间(小时),可在application.yml中配置 {@code app.activation-token-expiry-hours} */
@Value("${app.activation-token-expiry-hours:24}")
private int tokenExpiryHours;
/**
* 生成UUID格式的激活Token
*/
public String generateToken() {
return UUID.randomUUID().toString();
}
/**
* 计算Token过期时间(当前时间 + 配置的小时数)
*/
public LocalDateTime calculateExpiryTime() {
return LocalDateTime.now().plusHours(tokenExpiryHours);
}
/**
* 判断Token是否已过期
*/
public boolean isTokenExpired(LocalDateTime expiryTime) {
return expiryTime == null || LocalDateTime.now().isAfter(expiryTime);
}
}6.3 密码策略服务
创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/service/SecurityConfigService.java:
package com.knowledge.base.userauth.service;
/**
* 安全配置服务接口
*
* @author 苏三
* @since 1.0.0
*/
public interface SecurityConfigService {
/**
* 获取系统配置值
*/
String getConfig(String configKey);
/**
* 验证密码是否符合策略要求
*
* @param password 明文密码
* @throws RuntimeException 密码不符合策略时抛出
*/
void validatePassword(String password);
}创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/service/impl/SecurityConfigServiceImpl.java:
package com.knowledge.base.userauth.service.impl;
import com.knowledge.base.common.config.SystemConfigCache;
import com.knowledge.base.userauth.service.SecurityConfigService;
import jakarta.annotation.Resource;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;
/**
* 安全配置服务实现
*
* <p>从Redis缓存读取系统配置,实现密码策略校验和登录锁定</p>
*
* @author 苏三
* @since 1.0.0
*/
@Slf4j
@Service
public class SecurityConfigServiceImpl implements SecurityConfigService {
@Resource
private SystemConfigCache systemConfigCache;
/** 登录失败记录(内存缓存,生产环境建议迁移到Redis) */
private final Map<String, LoginFailRecord> loginFailMap = new ConcurrentHashMap<>();
@Override
public String getConfig(String configKey) {
return systemConfigCache.getConfig(configKey);
}
@Override
public void validatePassword(String password) {
// 1. 读取最小长度配置
int minLength = getConfigInt("auth.password.min.length", 8);
if (password.length() < minLength) {
throw new RuntimeException("密码长度不能少于" + minLength + "个字符");
}
// 2. 读取密码策略等级
String policy = getConfig("system.passwordPolicy");
if (policy == null) policy = "medium";
// 3. 读取是否需要特殊字符
boolean requireSpecial = "true".equals(getConfig("auth.password.require.special"));
switch (policy) {
case "low" -> {
if (requireSpecial && !password.matches(".*[^a-zA-Z0-9].*")) {
throw new RuntimeException("密码必须包含至少一个特殊字符");
}
}
case "high" -> {
if (!password.matches("^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[^a-zA-Z0-9]).+$")) {
throw new RuntimeException("密码必须包含大写字母、小写字母、数字和特殊字符");
}
}
default -> {
// medium: 必须包含字母和数字
if (!password.matches("^(?=.*[a-zA-Z])(?=.*\\d).+$")) {
throw new RuntimeException("密码必须同时包含字母和数字");
}
if (requireSpecial && !password.matches(".*[^a-zA-Z0-9].*")) {
throw new RuntimeException("密码必须包含至少一个特殊字符");
}
}
}
}
private int getConfigInt(String key, int defaultValue) {
String value = systemConfigCache.getConfig(key);
if (value == null || value.isEmpty()) return defaultValue;
try {
return Integer.parseInt(value);
} catch (NumberFormatException e) {
return defaultValue;
}
}
/** 登录失败记录 */
private static class LoginFailRecord {
int count;
long firstFailTime;
long lockUntil;
}
}6.4 核心业务逻辑 - UserService
创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/service/UserService.java:
package com.knowledge.base.userauth.service;
import com.baomidou.mybatisplus.extension.service.IService;
import com.knowledge.base.userauth.dto.RegisterDTO;
import com.knowledge.base.userauth.entity.User;
import com.knowledge.base.userauth.vo.RegisterVO;
/**
* 用户Service接口
*
* @author 苏三
* @since 1.0.0
*/
public interface UserService extends IService<User> {
/**
* 用户注册
*/
RegisterVO register(RegisterDTO registerDTO);
/**
* 邮箱验证激活
*/
String verifyEmail(String token);
/**
* 发送密码重置验证码
*/
void sendResetCode(String email);
/**
* 验证重置码
*/
boolean verifyResetCode(String email, String code);
/**
* 重置密码
*/
void resetPassword(String email, String code, String newPassword);
}创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/service/impl/UserServiceImpl.java 核心实现:
// kb-user-auth/src/main/java/com/knowledge/base/userauth/service/impl/UserServiceImpl.java
import cn.hutool.crypto.digest.BCrypt;
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.knowledge.base.common.exception.BusinessException;
import com.knowledge.base.common.utils.SnowflakeIdGenerator;
import com.knowledge.base.userauth.dto.RegisterDTO;
import com.knowledge.base.userauth.entity.User;
import com.knowledge.base.userauth.mapper.UserMapper;
import com.knowledge.base.userauth.service.EmailService;
import com.knowledge.base.userauth.service.SecurityConfigService;
import com.knowledge.base.userauth.service.UserService;
import com.knowledge.base.userauth.util.VerificationTokenUtil;
import com.knowledge.base.userauth.vo.RegisterVO;
import jakarta.annotation.Resource;
import lombok.extern.slf4j.Slf4j;
import org.springframework.data.redis.core.StringRedisTemplate;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.util.concurrent.TimeUnit;
/**
* 用户Service实现
*
* <p>实现注册、邮箱激活、密码重置等核心认证功能</p>
*
* @author 苏三
* @since 1.0.0
*/
@Slf4j
@Service
public class UserServiceImpl extends ServiceImpl<UserMapper, User> implements UserService {
@Resource
private UserMapper userMapper;
@Resource
private EmailService emailService;
@Resource
private VerificationTokenUtil verificationTokenUtil;
@Resource
private SecurityConfigService securityConfigService;
@Resource
private StringRedisTemplate stringRedisTemplate;
// ==================== 用户注册 ====================
@Override
@Transactional(rollbackFor = Exception.class)
public RegisterVO register(RegisterDTO registerDTO) {
// 1. 检查系统是否允许注册
String registrationEnabled = securityConfigService.getConfig("user.registration.enabled");
if (registrationEnabled != null && !"true".equals(registrationEnabled)) {
throw new BusinessException("系统已关闭注册功能");
}
// 2. 验证两次密码是否一致
if (!registerDTO.getPassword().equals(registerDTO.getConfirmPassword())) {
throw new BusinessException("两次输入的密码不一致");
}
// 3. 密码策略校验
securityConfigService.validatePassword(registerDTO.getPassword());
// 4. 检查用户名唯一性
if (userMapper.selectByUsername(registerDTO.getUsername()) != null) {
throw new BusinessException("用户名已存在");
}
// 5. 检查邮箱唯一性
if (userMapper.selectByEmail(registerDTO.getEmail()) != null) {
throw new BusinessException("该邮箱已被注册");
}
// 6. 检查手机号唯一性(如果填写了)
if (registerDTO.getPhone() != null && !registerDTO.getPhone().isEmpty()) {
if (userMapper.selectByPhone(registerDTO.getPhone()) != null) {
throw new BusinessException("该手机号已被注册");
}
}
// 7. 创建用户对象
User user = new User();
user.setId(SnowflakeIdGenerator.generateId());
user.setUsername(registerDTO.getUsername());
user.setPassword(BCrypt.hashpw(registerDTO.getPassword(), BCrypt.gensalt()));
user.setEmail(registerDTO.getEmail());
user.setPhone(registerDTO.getPhone());
user.setRealName(registerDTO.getRealName());
user.setStatus(0); // 邮箱未验证前禁用
user.setEmailVerified(0); // 未验证
// 8. 生成激活Token
String activationToken = verificationTokenUtil.generateToken();
user.setActivationToken(activationToken);
user.setActivationTokenExpiry(verificationTokenUtil.calculateExpiryTime());
// 9. 保存到数据库
userMapper.insert(user);
log.info("用户注册成功:username={}, email={}", user.getUsername(), user.getEmail());
// 10. 发送激活邮件(失败则回滚事务)
emailService.sendActivationEmail(user.getEmail(), user.getUsername(), activationToken);
// 11. 构建响应
RegisterVO vo = new RegisterVO();
vo.setUserId(user.getId());
vo.setEmailVerificationRequired(true);
vo.setMessage("注册成功,请查看邮箱完成账户激活");
return vo;
}
// ==================== 邮箱激活 ====================
@Override
public String verifyEmail(String token) {
// 1. 根据Token查询用户
User user = userMapper.selectByActivationToken(token);
if (user == null) {
throw new BusinessException("无效的激活链接");
}
// 2. 检查Token是否过期
if (verificationTokenUtil.isTokenExpired(user.getActivationTokenExpiry())) {
throw new BusinessException("激活链接已过期,请重新注册");
}
// 3. 检查是否已激活
if (user.getEmailVerified() != null && user.getEmailVerified() == 1) {
return "账户已激活,请直接登录";
}
// 4. 激活账户
user.setEmailVerified(1);
user.setStatus(1); // 启用账户
user.setActivationToken(null);
user.setActivationTokenExpiry(null);
userMapper.updateById(user);
log.info("账户激活成功:username={}, email={}", user.getUsername(), user.getEmail());
return "账户激活成功,请登录系统";
}
// ==================== 密码重置 ====================
@Override
public void sendResetCode(String email) {
// 1. 检查用户是否存在
User user = userMapper.selectByEmail(email);
if (user == null) {
throw new BusinessException("该邮箱未注册");
}
// 2. Redis冷却期检查(60秒内不能重复发送)
String redisKey = "password:reset:code:" + email;
Long ttl = stringRedisTemplate.getExpire(redisKey, TimeUnit.SECONDS);
if (ttl != null && ttl > 540) {
throw new BusinessException("验证码已发送,请" + (ttl - 540) + "秒后再试");
}
// 3. 生成6位随机验证码
String code = String.valueOf((int)(Math.random() * 900000) + 100000);
// 4. 存入Redis,10分钟过期
stringRedisTemplate.opsForValue().set(redisKey, code, 10, TimeUnit.MINUTES);
// 5. 发送邮件
emailService.sendResetCodeEmail(email, code);
log.info("密码重置验证码发送成功:email={}", email);
}
@Override
public boolean verifyResetCode(String email, String code) {
// 1. 从Redis获取验证码
String redisKey = "password:reset:code:" + email;
String storedCode = stringRedisTemplate.opsForValue().get(redisKey);
// 2. 验证码已过期
if (storedCode == null) {
throw new BusinessException("验证码已过期,请重新获取");
}
// 3. 验证码不匹配
if (!storedCode.equals(code)) {
throw new BusinessException("验证码错误");
}
return true;
}
@Override
@Transactional(rollbackFor = Exception.class)
public void resetPassword(String email, String code, String newPassword) {
// 1. 验证验证码
String redisKey = "password:reset:code:" + email;
String storedCode = stringRedisTemplate.opsForValue().get(redisKey);
if (storedCode == null) {
throw new BusinessException("验证码已过期,请重新获取");
}
if (!storedCode.equals(code)) {
throw new BusinessException("验证码错误");
}
// 2. 密码策略校验
securityConfigService.validatePassword(newPassword);
// 3. 查找用户
User user = userMapper.selectByEmail(email);
if (user == null) {
throw new BusinessException("用户不存在");
}
// 4. BCrypt加密并更新密码
user.setPassword(BCrypt.hashpw(newPassword, BCrypt.gensalt()));
userMapper.updateById(user);
// 5. 删除Redis中的验证码(一次性使用)
stringRedisTemplate.delete(redisKey);
log.info("密码重置成功:email={}", email);
}
}6.5 核心流程解析
注册流程关键设计:
- 事务回滚机制:如果邮件发送失败,抛出异常触发
@Transactional回滚,数据库中不会残留无效用户记录 - 双状态字段:
status=0禁用 +emailVerified=0未验证,激活后同时设为 1 - Token一次性:激活后立即清空 Token,防止链接被重复使用

找回密码流程关键设计:
- Redis隔离:验证码 Key 格式
password:reset:code:{email},独立命名空间 - 冷却期保护:60秒内不允许重复发送验证码(TTL > 540秒时拒绝)
- 一次性验证码:密码重置成功后立即删除 Redis Key
七、控制器层
7.1 创建AuthController
创建 kb-user-auth/src/main/java/com/knowledge/base/userauth/controller/AuthController.java 认证相关端点:
// kb-user-auth/src/main/java/com/knowledge/base/userauth/controller/AuthController.java
package com.knowledge.base.userauth.controller;
import com.knowledge.base.common.result.Result;
import com.knowledge.base.userauth.dto.RegisterDTO;
import com.knowledge.base.userauth.dto.ResetPasswordDTO;
import com.knowledge.base.userauth.dto.SendResetCodeDTO;
import com.knowledge.base.userauth.dto.VerifyResetCodeDTO;
import com.knowledge.base.userauth.service.UserService;
import com.knowledge.base.userauth.vo.RegisterVO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.annotation.Resource;
import jakarta.validation.Valid;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;
/**
* 认证Controller
*
* <p>提供用户注册、邮箱激活、密码重置等认证相关接口</p>
*
* @author 苏三
* @since 1.0.0
*/
@Slf4j
@RestController
@RequestMapping("/auth")
@Tag(name = "认证管理", description = "用户注册、激活、密码重置接口")
public class AuthController {
@Resource
private UserService userService;
/**
* 用户注册
*/
@PostMapping("/register")
@Operation(summary = "用户注册", description = "新用户注册并发送激活邮件")
public Result<RegisterVO> register(@Valid @RequestBody RegisterDTO registerDTO) {
log.info("用户注册请求:username={}, email={}", registerDTO.getUsername(), registerDTO.getEmail());
RegisterVO vo = userService.register(registerDTO);
return Result.success(vo);
}
/**
* 邮箱激活验证
*/
@GetMapping("/verify-email")
@Operation(summary = "邮箱验证", description = "通过激活Token验证邮箱并激活账户")
public Result<String> verifyEmail(
@Parameter(description = "激活Token", required = true)
@RequestParam String token) {
log.info("邮箱激活请求:token={}", token);
String message = userService.verifyEmail(token);
return Result.success(message);
}
/**
* 发送密码重置验证码
*/
@PostMapping("/password/reset/send-code")
@Operation(summary = "发送重置验证码", description = "向注册邮箱发送6位数字验证码")
public Result<Void> sendResetCode(@Valid @RequestBody SendResetCodeDTO dto) {
log.info("发送密码重置验证码请求:email={}", dto.getEmail());
userService.sendResetCode(dto.getEmail());
return Result.success("验证码已发送至邮箱");
}
/**
* 验证重置码
*/
@PostMapping("/password/reset/verify-code")
@Operation(summary = "验证重置码", description = "验证密码重置的6位验证码")
public Result<Boolean> verifyResetCode(@Valid @RequestBody VerifyResetCodeDTO dto) {
log.info("验证重置码请求:email={}", dto.getEmail());
boolean valid = userService.verifyResetCode(dto.getEmail(), dto.getCode());
return Result.success("验证成功", valid);
}
/**
* 重置密码
*/
@PostMapping("/password/reset")
@Operation(summary = "重置密码", description = "通过验证码重置登录密码")
public Result<Void> resetPassword(@Valid @RequestBody ResetPasswordDTO dto) {
log.info("重置密码请求:email={}", dto.getEmail());
userService.resetPassword(dto.getEmail(), dto.getCode(), dto.getNewPassword());
return Result.success("密码重置成功");
}
}7.2 安全配置
在 SecurityConfig.java 中,确保以下路径无需认证:
// kb-user-auth/src/main/java/com/knowledge/base/userauth/config/SecurityConfig.java
@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
http
// ... 其他配置 ...
.authorizeHttpRequests(auth -> auth
.requestMatchers(
"/auth/register",
"/auth/verify-email",
"/auth/password/reset/**",
"/auth/login"
).permitAll()
// ... 其他规则 ...
);
return http.build();
}7.3 API接口总览
| 方法 | 路径 | 请求体 | 响应 | 认证 |
|---|---|---|---|---|
| POST | /auth/register | RegisterDTO | RegisterVO | 无需 |
| GET | /auth/verify-email | Query: ?token=xxx | String消息 | 无需 |
| POST | /auth/password/reset/send-code | SendResetCodeDTO | Void | 无需 |
| POST | /auth/password/reset/verify-code | VerifyResetCodeDTO | Boolean | 无需 |
| POST | /auth/password/reset | ResetPasswordDTO | Void | 无需 |
八、邮件配置
8.1 application.yml配置
在 kb-user-auth/src/main/resources/application.yml 中配置邮件服务:
spring:
mail:
host: ${MAIL_HOST:smtp.163.com}
port: ${MAIL_PORT:465}
username: ${MAIL_USERNAME:}
password: ${MAIL_PASSWORD:}
protocol: smtp
properties:
mail:
smtp:
auth: true
ssl:
enable: true
starttls:
enable: true
required: true
# 应用配置
app:
frontend-url: ${FRONTEND_URL:http://localhost:3002}
activation-token-expiry-hours: 248.2 环境变量设置
开发环境在IDEA中配置Run Configuration的环境变量:
MAIL_HOST=smtp.163.com
MAIL_PORT=465
MAIL_USERNAME=your-email@163.com
MAIL_PASSWORD=your-smtp-auth-code
FRONTEND_URL=http://localhost:3002注意:MAIL_PASSWORD 不是邮箱登录密码,而是163邮箱的 **SMTP授权码**。需要在163邮箱设置 → POP3/SMTP/IMAP → 开启服务 → 获取授权码。九、前端实现
9.1 前端路由配置
在 src/router/index.tsx 中添加激活页和找回密码页路由:
// knowledge-base-frontend/src/router/index.tsx
// 邮箱激活页
{
path: 'activate',
element: (
<Suspense fallback={<LoadingFallback />}>
<ActivateAccountPage />
</Suspense>
),
},
// 找回密码页
{
path: 'forgot-password',
element: (
<Suspense fallback={<LoadingFallback />}>
<ForgotPasswordPage />
</Suspense>
),
},9.2 API服务层
在 src/services/auth.service.ts 中添加注册、激活、密码重置相关API方法:
// knowledge-base-frontend/src/services/auth.service.ts
export const authService = {
// 登录
login: (username: string, password: string) => {
return http.post<LoginResponse>('/auth/auth/login', { username, password });
},
// 用户注册
register: (data: {
username: string;
password: string;
confirmPassword: string;
email: string;
realName: string;
teamId: number;
phone?: string;
}) => {
return http.post<RegisterResponse>('/auth/auth/register', data);
},
// 邮箱激活
verifyEmail: (token: string) => {
return http.get<string>(`/auth/auth/verify-email?token=${token}`);
},
// 发送密码重置验证码
sendResetCode: (email: string) => {
return http.post<void>('/auth/auth/password/reset/send-code', { email });
},
// 验证重置码
verifyResetCode: (email: string, code: string) => {
return http.post<boolean>('/auth/auth/password/reset/verify-code', { email, code });
},
// 重置密码
resetPassword: (data: { email: string; code: string; newPassword: string }) => {
return http.post<void>('/auth/auth/password/reset', data);
},
};9.3 TypeScript类型定义
在 src/types/index.ts 中添加:
// knowledge-base-frontend/src/types/index.ts
/** 注册响应 */
export interface RegisterResponse {
userId: number;
emailVerificationRequired: boolean;
message: string;
loginInfo?: LoginResponse;
}9.4 登录页注册Tab(LoginPage.tsx)
在 src/pages/LoginPage.tsx 中实现:
核心逻辑:
// knowledge-base-frontend/src/pages/LoginPage.tsx
// 1. 页面加载时读取系统配置
React.useEffect(() => {
let cancelled = false;
foundationService.config
.getPublic()
.then((configs: Record<string, string>) => {
if (cancelled) return;
// 读取注册开关
const raw = configs['user.registration.enabled'];
setAllowRegistration(raw === 'true');
// 读取密码策略
const policy = configs['system.passwordPolicy'] || 'medium';
const minLengthRaw = configs['auth.password.min.length'];
const requireSpecialRaw = configs['auth.password.require.special'];
setSecurityConfig({
passwordPolicy: policy,
passwordMinLength: minLengthRaw ? parseInt(minLengthRaw, 10) || 8 : 8,
requireSpecialChar: requireSpecialRaw === 'true',
});
})
.catch(() => {
if (!cancelled) setAllowRegistration(false);
});
return () => { cancelled = true; };
}, []);
// 2. 切换到注册Tab时加载团队列表
const handleTabChange = (key: string) => {
setActiveTab(key);
if (key === 'register') {
registerForm.resetFields();
if (!teamsFetched) {
setTeamsFetched(true);
teamService.getTeamTree(true).then(setTeams).catch((err) => {
console.error('获取团队空间列表失败:', err);
});
}
}
};
// 3. 处理注册提交
const handleRegister = async (values: any) => {
setLoading(true);
try {
const response: RegisterResponse = await authService.register({
username: values.username,
password: values.password,
confirmPassword: values.confirmPassword,
email: values.email,
realName: values.realName,
teamId: values.teamId,
phone: values.phone || undefined,
});
message.success(response.message || '注册成功,请查看邮箱完成账户激活');
registerForm.resetFields();
setActiveTab('login');
} catch (error) {
// 错误已由HTTP拦截器处理
} finally {
setLoading(false);
}
};动态密码策略提示函数:
// 生成密码提示文字
function getPasswordHint(config: SecurityConfig): string {
const parts: string[] = [`至少${config.passwordMinLength}个字符`];
switch (config.passwordPolicy) {
case 'low':
if (config.requireSpecialChar) parts.push('包含特殊字符');
break;
case 'high':
parts.push('包含大写字母、小写字母、数字和特殊字符');
break;
case 'medium':
default:
parts.push('同时包含字母和数字');
if (config.requireSpecialChar) parts.push('包含特殊字符');
break;
}
return '密码要求:' + parts.join(',');
}
// 生成密码校验规则
function getPasswordRules(config: SecurityConfig): any[] {
const rules: any[] = [
{ required: true, message: '请输入密码' },
{ min: config.passwordMinLength, message: `密码至少${config.passwordMinLength}个字符` },
];
switch (config.passwordPolicy) {
case 'low':
if (config.requireSpecialChar) {
rules.push({
pattern: /[^a-zA-Z0-9]/,
message: '密码必须包含至少一个特殊字符',
});
}
break;
case 'high':
rules.push({
pattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[^a-zA-Z0-9]).+$/,
message: '密码必须包含大写、小写、数字和特殊字符',
});
break;
case 'medium':
default:
rules.push({
pattern: /^(?=.*[a-zA-Z])(?=.*\d).+$/,
message: '密码必须同时包含字母和数字',
});
if (config.requireSpecialChar) {
rules.push({
pattern: /[^a-zA-Z0-9]/,
message: '密码必须包含至少一个特殊字符',
});
}
break;
}
return rules;
}9.5 邮箱激活页(ActivateAccountPage.tsx)
创建 src/pages/ActivateAccountPage.tsx:
// knowledge-base-frontend/src/pages/ActivateAccountPage.tsx
import React from 'react';
import { Button, Result, Spin, Typography } from 'antd';
import { MailOutlined } from '@ant-design/icons';
import { useSearchParams, useNavigate } from 'react-router-dom';
import { authService } from '@/services';
const ActivateAccountPage: React.FC = () => {
const [searchParams] = useSearchParams();
const navigate = useNavigate();
const [status, setStatus] = React.useState<'loading' | 'success' | 'error'>('loading');
const [message, setMessage] = React.useState('');
React.useEffect(() => {
const token = searchParams.get('token');
if (!token) {
setStatus('error');
setMessage('无效的激活链接:缺少Token参数');
return;
}
authService.verifyEmail(token)
.then((msg) => {
setStatus('success');
setMessage(typeof msg === 'string' ? msg : '激活成功');
})
.catch((err) => {
setStatus('error');
setMessage(err?.response?.data?.message || err?.message || '激活失败,请重新注册');
});
}, [searchParams]);
if (status === 'loading') {
return (
<div style={{ textAlign: 'center', padding: '80px 0' }}>
<Spin size="large" />
<Typography.Paragraph type="secondary" style={{ marginTop: 16 }}>
正在验证激活链接...
</Typography.Paragraph>
</div>
);
}
if (status === 'success') {
return (
<Result
status="success"
title="激活成功!"
subTitle={message || '你的账户已成功激活'}
extra={[
<Button type="primary" key="login" onClick={() => navigate('/login')}>
前往登录
</Button>,
]}
/>
);
}
return (
<Result
status="error"
title="激活失败"
subTitle={message}
extra={[
<Button type="primary" key="login" onClick={() => navigate('/login')}>
返回登录
</Button>,
<Button key="register" onClick={() => navigate('/login')}>
重新注册
</Button>,
]}
/>
);
};
export default ActivateAccountPage;9.6 找回密码页(ForgotPasswordPage.tsx)
创建 src/pages/ForgotPasswordPage.tsx,实现三步向导:
// knowledge-base-frontend/src/pages/ForgotPasswordPage.tsx
import React from 'react';
import { Button, Form, Input, Result, Steps, Typography } from 'antd';
import { MailOutlined, LockOutlined, SafetyOutlined } from '@ant-design/icons';
import { App } from 'antd';
import { useNavigate } from 'react-router-dom';
import { authService } from '@/services';
const ForgotPasswordPage: React.FC = () => {
const { message } = App.useApp();
const navigate = useNavigate();
const [form] = Form.useForm();
const [step, setStep] = React.useState(0); // 0=输入邮箱, 1=输入验证码, 2=设置新密码, 3=成功
const [email, setEmail] = React.useState('');
const [code, setCode] = React.useState('');
const [loading, setLoading] = React.useState(false);
const
倒计时
0天
0小时
0分钟
0秒
= React.useState(0);
// 倒计时
React.useEffect(() => {
if (countdown > 0) {
const timer = setTimeout(() => setCountdown(countdown - 1), 1000);
return () => clearTimeout(timer);
}
},
倒计时
0天
0小时
0分钟
0秒
);
// Step 0: 发送验证码
const handleSendCode = async (values: { email: string }) => {
setLoading(true);
try {
await authService.sendResetCode(values.email);
setEmail(values.email);
setStep(1);
setCountdown(60);
message.success('验证码已发送至邮箱');
} catch (err) {
// 错误已由拦截器处理
} finally {
setLoading(false);
}
};
// Step 1: 验证验证码
const handleVerifyCode = async (values: { code: string }) => {
setLoading(true);
try {
await authService.verifyResetCode(email, values.code);
setCode(values.code);
setStep(2);
message.success('验证通过');
} catch (err) {
// 错误已由拦截器处理
} finally {
setLoading(false);
}
};
// Step 2: 重置密码
const handleResetPassword = async (values: { newPassword: string }) => {
setLoading(true);
try {
await authService.resetPassword({
email,
code,
newPassword: values.newPassword,
});
setStep(3);
} catch (err) {
// 错误已由拦截器处理
} finally {
setLoading(false);
}
};
// 重新发送验证码
const handleResendCode = async () => {
try {
await authService.sendResetCode(email);
setCountdown(60);
message.success('验证码已重新发送');
} catch (err) {
// 错误已由拦截器处理
}
};
// 成功页面
if (step === 3) {
return (
<Result
status="success"
title="密码重置成功!"
subTitle="请使用新密码登录系统"
extra={[
<Button type="primary" key="login" onClick={() => navigate('/login')}>
前往登录
</Button>,
]}
/>
);
}
return (
<div style={{ maxWidth: 420, margin: '0 auto', padding: '40px 0' }}>
<Typography.Title level={3} style={{ textAlign: 'center', marginBottom: 32 }}>
找回密码
</Typography.Title>
<Steps
current={step}
size="small"
style={{ marginBottom: 32 }}
items={[
{ title: '验证邮箱' },
{ title: '输入验证码' },
{ title: '设置新密码' },
]}
/>
{/* Step 0: 输入邮箱 */}
{step === 0 && (
<Form form={form} onFinish={handleSendCode} layout="vertical">
<Form.Item
name="email"
rules={[
{ required: true, message: '请输入注册邮箱' },
{ type: 'email', message: '请输入有效的邮箱地址' },
]}
>
<Input
prefix={<MailOutlined />}
placeholder="请输入注册时使用的邮箱"
size="large"
/>
</Form.Item>
<Form.Item>
<Button type="primary" htmlType="submit" loading={loading} block size="large">
获取验证码
</Button>
</Form.Item>
<div style={{ textAlign: 'center' }}>
<Button type="link" onClick={() => navigate('/login')}>
返回登录
</Button>
</div>
</Form>
)}
{/* Step 1: 输入验证码 */}
{step === 1 && (
<Form form={form} onFinish={handleVerifyCode} layout="vertical">
<Typography.Paragraph type="secondary">
验证码已发送至 <strong>{email}</strong>
</Typography.Paragraph>
<Form.Item
name="code"
rules={[
{ required: true, message: '请输入验证码' },
{ pattern: /^\d{6}$/, message: '验证码为6位数字' },
]}
>
<Input
prefix={<SafetyOutlined />}
placeholder="请输入6位验证码"
size="large"
maxLength={6}
/>
</Form.Item>
<Form.Item>
<Button type="primary" htmlType="submit" loading={loading} block size="large">
验证
</Button>
</Form.Item>
<div style={{ display: 'flex', justifyContent: 'space-between' }}>
<Button type="link" onClick={() => setStep(0)}>
返回上一步
</Button>
<Button
type="link"
onClick={handleResendCode}
disabled={countdown > 0}
>
{countdown > 0 ? `${countdown}s后重发` : '重新发送'}
</Button>
</div>
</Form>
)}
{/* Step 2: 设置新密码 */}
{step === 2 && (
<Form form={form} onFinish={handleResetPassword} layout="vertical">
<Typography.Paragraph type="secondary">
为 <strong>{email}</strong> 设置新密码
</Typography.Paragraph>
<Form.Item
name="newPassword"
rules={[
{ required: true, message: '请输入新密码' },
{ min: 6, message: '密码至少6个字符' },
{ max: 20, message: '密码不超过20个字符' },
{
pattern: /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d).+$/,
message: '密码必须包含大写字母、小写字母和数字',
},
]}
>
<Input.Password
prefix={<LockOutlined />}
placeholder="请输入新密码"
size="large"
autoComplete="new-password"
/>
</Form.Item>
<Form.Item>
<Button type="primary" htmlType="submit" loading={loading} block size="large">
重置密码
</Button>
</Form.Item>
</Form>
)}
</div>
);
};
export default ForgotPasswordPage;9.7 系统设置中的密码策略管理
在管理后台设置页(src/pages/admin/SettingsPage.tsx)中,需要添加密码策略相关的配置项,确保以下配置Key能在系统设置中管理:
| 配置Key | 配置类型 | 说明 |
|---|---|---|
user.registration.enabled | boolean | 是否允许用户自助注册 |
system.passwordPolicy | string | 密码策略级别:low / medium / high |
auth.password.min.length | number | 密码最小长度(默认8) |
auth.password.require.special | boolean | 是否要求特殊字符 |
十、测试
按顺序启动下面这些微服务:
kb-auth-user
kb-document
kb-gateway
启动前端
cd knowledge-base-frontend
npm run dev
浏览器访问登录页面:
切换到注册窗口:

点击注册按钮,在注册的邮箱中会受到这样一封邮件:

点击激活账户按钮,或者访问邮件的那个链接:

可以激活注册的账号。
就可以用账号登录系统了:

可以登录成功:

如果忘记了密码,可以点击登录页面的找回密码按钮:

输入你注册邮箱,点击发送验证码按钮:

在邮箱中能够收到一个验证码。
输入验证码:

点击验证按钮:

就可以输入新密码重置密码了。
十二、总结
12.1 功能总览
| 功能 | 核心类 | 说明 |
|---|---|---|
| 注册 | UserServiceImpl.register() | 校验 → 创建 → 发邮件,事务保护 |
| 激活 | UserServiceImpl.verifyEmail() | Token验证 → 启用账户,一次性使用 |
| 发送验证码 | UserServiceImpl.sendResetCode() | 生成6位数字 → Redis存储 → 发送邮件 |
| 验证验证码 | UserServiceImpl.verifyResetCode() | Redis比对 → 返回验证结果 |
| 重置密码 | UserServiceImpl.resetPassword() | 验证码校验 → 策略校验 → BCrypt加密 → 清除Redis |
| 邮件服务 | EmailServiceImpl | HTML模板邮件,支持激活和密码重置两种 |
| 密码策略 | SecurityConfigServiceImpl.validatePassword() | 低/中/高三级动态策略 |
| Token工具 | VerificationTokenUtil | UUID生成 + 可配置过期时间 |
12.2 安全设计要点
- 密码BCrypt加密:使用
BCrypt.hashpw()10轮盐值加密,不可逆 - 激活Token:UUID随机生成,24小时过期,一次性使用后清除
- 验证码:6位数字随机生成,Redis 10分钟有效期,一次性使用
- 冷却期:60秒内不允许重复发送验证码,防止邮件轰炸
- 事务保护:注册时邮件发送失败则回滚,不产生无效用户
- 密码策略:可动态配置的 low/medium/high 三级复杂度要求
- 注册开关:通过系统配置
user.registration.enabled动态控制