一、概述

用户注册、邮件验证和找回密码是知识库系统的核心安全功能。

本文将详细介绍如何实现一个完整的用户认证体系,涵盖注册流程、邮件激活验证、密码找回重置三大模块,并配套密码策略管理和前端交互实现。

1.1 功能定位

功能模块说明使用场景
用户注册新用户自助注册并选择所属团队空间新成员加入
邮件验证注册后发送激活邮件,点击链接激活账户身份验证
找回密码通过邮箱获取验证码,重置登录密码忘记密码
密码策略动态配置密码复杂度要求(低/中/高三级)安全合规
前端集成登录页注册Tab、激活页、找回密码页用户交互

1.2 业务流程

图片.png

1.3 技术架构

图片.png

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 字段说明

字段类型说明注册赋值激活后赋值
idBIGINT雪花算法ID自动生成-
usernameVARCHAR(50)用户名,唯一用户填写-
passwordVARCHAR(200)BCrypt加密密码加密存储-
emailVARCHAR(100)邮箱,唯一用户填写-
real\_nameVARCHAR(50)真实姓名用户填写-
statusTINYINT0=禁用 1=启用01
email\_verifiedTINYINT0=未验证 1=已验证01
activation\_tokenVARCHAR(100)UUID激活Token生成UUID清除(NULL)
activation\_token\_expiryDATETIMEToken过期时间创建时间+24h清除(NULL)

2.4 索引设计

  • **唯一索引 **uk_username:防止用户名重复,注册时校验
  • **唯一索引 **uk_email:防止邮箱重复注册,同时用于找回密码时查用户
  • **索引 **idx_activation_token:加速激活邮件的Token查询
  • **索引 **idx_status:查询启用/禁用用户列表
  • **索引 **idx_email_verified:统计已验证用户

2.5 Redis缓存设计

密码重置验证码存储在Redis中:

KeyValueTTL说明
password:reset:code:user@example.com6位数字验证码10分钟密码重置验证码
kb:system:configHash(所有系统配置)永久系统配置缓存

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 设计思路

  1. 继承BaseEntity:复用 id、createdAt、updatedAt、createBy、updateBy、deleted、version 基础字段
  2. status字段三态设计:0=禁用(注册后未激活),1=启用(激活后),2=锁定(登录失败次数过多)
  3. emailVerified 独立于 status:明确区分"邮箱是否验证"与"账户是否启用"
  4. 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 核心流程解析

注册流程关键设计:

  1. 事务回滚机制:如果邮件发送失败,抛出异常触发 @Transactional 回滚,数据库中不会残留无效用户记录
  2. 双状态字段:status=0 禁用 + emailVerified=0 未验证,激活后同时设为 1
  3. Token一次性:激活后立即清空 Token,防止链接被重复使用

图片.png

找回密码流程关键设计:

  1. Redis隔离:验证码 Key 格式 password:reset:code:{email},独立命名空间
  2. 冷却期保护:60秒内不允许重复发送验证码(TTL > 540秒时拒绝)
  3. 一次性验证码:密码重置成功后立即删除 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/registerRegisterDTORegisterVO无需
GET/auth/verify-emailQuery: ?token=xxxString消息无需
POST/auth/password/reset/send-codeSendResetCodeDTOVoid无需
POST/auth/password/reset/verify-codeVerifyResetCodeDTOBoolean无需
POST/auth/password/resetResetPasswordDTOVoid无需

八、邮件配置

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: 24

8.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.enabledboolean是否允许用户自助注册
system.passwordPolicystring密码策略级别:low / medium / high
auth.password.min.lengthnumber密码最小长度(默认8)
auth.password.require.specialboolean是否要求特殊字符

十、测试

按顺序启动下面这些微服务:

kb-auth-user

kb-document

kb-gateway

启动前端

cd knowledge-base-frontend

npm run dev

浏览器访问登录页面:

http://localhost:3002/login

切换到注册窗口:

图片.png

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

图片.png

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

图片.png

可以激活注册的账号。

就可以用账号登录系统了:

图片.png

可以登录成功:

图片.png

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

图片.png

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

图片.png

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

输入验证码:

图片.png

点击验证按钮:

图片.png

就可以输入新密码重置密码了。

十二、总结

12.1 功能总览

功能核心类说明
注册UserServiceImpl.register()校验 → 创建 → 发邮件,事务保护
激活UserServiceImpl.verifyEmail()Token验证 → 启用账户,一次性使用
发送验证码UserServiceImpl.sendResetCode()生成6位数字 → Redis存储 → 发送邮件
验证验证码UserServiceImpl.verifyResetCode()Redis比对 → 返回验证结果
重置密码UserServiceImpl.resetPassword()验证码校验 → 策略校验 → BCrypt加密 → 清除Redis
邮件服务EmailServiceImplHTML模板邮件,支持激活和密码重置两种
密码策略SecurityConfigServiceImpl.validatePassword()低/中/高三级动态策略
Token工具VerificationTokenUtilUUID生成 + 可配置过期时间

12.2 安全设计要点

  1. 密码BCrypt加密:使用 BCrypt.hashpw() 10轮盐值加密,不可逆
  2. 激活Token:UUID随机生成,24小时过期,一次性使用后清除
  3. 验证码:6位数字随机生成,Redis 10分钟有效期,一次性使用
  4. 冷却期:60秒内不允许重复发送验证码,防止邮件轰炸
  5. 事务保护:注册时邮件发送失败则回滚,不产生无效用户
  6. 密码策略:可动态配置的 low/medium/high 三级复杂度要求
  7. 注册开关:通过系统配置 user.registration.enabled 动态控制
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏