whale-town-end/docs/systems/email-verification/README.md

邮箱验证系统

概述

邮箱验证系统提供完整的邮箱验证功能，包括验证码生成、发送、验证和管理。

功能特性

• 📧 邮箱验证码发送
• 🔐 验证码安全验证
• ⏰ 验证码过期管理
• 🚫 防刷机制（频率限制）
• 📊 验证统计和监控

系统架构

邮箱验证系统
├── 验证码服务 (VerificationService)
│   ├── 验证码生成
│   ├── 验证码验证
│   └── 防刷机制
├── 邮件服务 (EmailService)
│   ├── 验证码邮件发送
│   ├── 欢迎邮件发送
│   └── 邮件模板管理
└── Redis缓存
    ├── 验证码存储
    ├── 冷却时间管理
    └── 发送频率限制

核心组件

1. 验证码服务 (VerificationService)

负责验证码的生成、验证和管理：

• 验证码生成：6位数字验证码
• 验证码验证：支持多次尝试限制
• 过期管理：5分钟有效期
• 防刷机制：60秒冷却时间，每小时最多5次

2. 邮件服务 (EmailService)

负责邮件的发送和模板管理：

• 验证码邮件：发送验证码到用户邮箱
• 欢迎邮件：用户注册成功后发送
• 模板支持：支持HTML邮件模板

3. Redis缓存

负责数据的临时存储：

• 验证码存储：verification_code:${type}:${identifier}
• 冷却时间：verification_cooldown:${type}:${identifier}
• 发送频率：verification_hourly:${type}:${identifier}:${date}:${hour}

使用流程

注册流程中的邮箱验证

1. 发送验证码

   POST /auth/send-email-verification
   {
     "email": "user@example.com"
   }
   

2. 用户注册

   POST /auth/register
   {
     "username": "testuser",
     "password": "password123",
     "nickname": "测试用户",
     "email": "user@example.com",
     "email_verification_code": "123456"
   }
   

独立邮箱验证

1. 验证邮箱

   POST /auth/verify-email
   {
     "email": "user@example.com",
     "verification_code": "123456"
   }
   

配置说明

环境变量

# 邮件服务配置
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASS=your-password
SMTP_FROM=noreply@example.com

# Redis配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

验证码配置

// 验证码长度
CODE_LENGTH = 6

// 验证码过期时间（秒）
CODE_EXPIRE_TIME = 300 // 5分钟

// 最大验证尝试次数
MAX_ATTEMPTS = 3

// 发送冷却时间（秒）
RATE_LIMIT_TIME = 60 // 1分钟

// 每小时最大发送次数
MAX_SENDS_PER_HOUR = 5

API接口

发送邮箱验证码

• 接口：POST /auth/send-email-verification
• 描述：向指定邮箱发送验证码
• 参数：

  {
    email: string; // 邮箱地址
  }
  

验证邮箱验证码

• 接口：POST /auth/verify-email
• 描述：使用验证码验证邮箱
• 参数：

  {
    email: string;            // 邮箱地址
    verification_code: string; // 6位数字验证码
  }
  

重新发送验证码

• 接口：POST /auth/resend-email-verification
• 描述：重新向指定邮箱发送验证码
• 参数：

  {
    email: string; // 邮箱地址
  }
  

错误处理

常见错误码

• VERIFICATION_CODE_NOT_FOUND：验证码不存在或已过期
• VERIFICATION_CODE_INVALID：验证码错误
• TOO_MANY_ATTEMPTS：验证尝试次数过多
• RATE_LIMIT_EXCEEDED：发送频率过高
• EMAIL_SEND_FAILED：邮件发送失败

错误响应格式

{
  success: false,
  message: "错误描述",
  error_code: "ERROR_CODE"
}

监控和日志

关键指标

• 验证码发送成功率
• 验证码验证成功率
• 邮件发送延迟
• Redis连接状态

日志记录

• 验证码生成和验证日志
• 邮件发送状态日志
• 错误和异常日志
• 性能监控日志

安全考虑

防刷机制

1. 发送频率限制：每个邮箱60秒内只能发送一次
2. 每小时限制：每个邮箱每小时最多发送5次
3. 验证尝试限制：每个验证码最多尝试3次

数据安全

1. 验证码加密存储：Redis中的验证码经过加密
2. 过期自动清理：验证码5分钟后自动过期
3. 日志脱敏：日志中不记录完整验证码

部署指南

详细的部署说明请参考：deployment-guide.md

测试

单元测试

# 运行验证服务测试
npm test -- verification.service.spec.ts

# 运行邮件服务测试
npm test -- email.service.spec.ts

集成测试

# 运行邮箱验证集成测试
npm run test:e2e -- email-verification

故障排除

常见问题

1. 验证码收不到

   • 检查SMTP配置
   • 检查邮箱是否在垃圾邮件中
   • 检查网络连接

2. 验证码验证失败

   • 检查验证码是否过期
   • 检查验证码输入是否正确
   • 检查Redis连接状态

3. 发送频率限制

   • 等待冷却时间结束
   • 检查是否达到每小时限制

更新日志

• v1.0.0 (2025-12-17)
  • 初始版本发布
  • 支持基本的邮箱验证功能
  • 集成Redis缓存
  • 添加防刷机制