datawhale/whale-town-end
3
4
Fork 2
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs：重新组织系统文档结构

Browse Source 
- 将日志系统文档移动到 docs/systems/logger/detailed-specification.md
- 将邮箱验证部署指南移动到 docs/systems/email-verification/deployment-guide.md
- 创建邮箱验证系统完整文档 docs/systems/email-verification/README.md
- 按功能模块组织文档，提高可维护性
This commit is contained in:
moyin
2025-12-17 20:20:00 +08:00
parent 0065357fa5
commit e58cc57769
3 changed files with 581 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
docs/systems/email-verification/README.md Normal file
View File

@@ -0,0 +1,265 @@
# 邮箱验证系统
## 概述
邮箱验证系统提供完整的邮箱验证功能，包括验证码生成、发送、验证和管理。
## 功能特性
- 📧 邮箱验证码发送
- 🔐 验证码安全验证
- ⏰ 验证码过期管理
- 🚫 防刷机制（频率限制）
- 📊 验证统计和监控
## 系统架构
```
邮箱验证系统
├── 验证码服务 (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. **发送验证码**
```typescript
POST /auth/send-email-verification
{
"email": "user@example.com"
}
```
2. **用户注册**
```typescript
POST /auth/register
{
"username": "testuser",
"password": "password123",
"nickname": "测试用户",
"email": "user@example.com",
"email_verification_code": "123456"
}
```
### 独立邮箱验证
1. **验证邮箱**
```typescript
POST /auth/verify-email
{
"email": "user@example.com",
"verification_code": "123456"
}
```
## 配置说明
### 环境变量
```bash
# 邮件服务配置
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=
```
### 验证码配置
```typescript
// 验证码长度
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`
- **描述**：向指定邮箱发送验证码
- **参数**：
```typescript
{
email: string; // 邮箱地址
}
```
### 验证邮箱验证码
- **接口**：`POST /auth/verify-email`
- **描述**：使用验证码验证邮箱
- **参数**：
```typescript
{
email: string; // 邮箱地址
verification_code: string; // 6位数字验证码
}
```
### 重新发送验证码
- **接口**：`POST /auth/resend-email-verification`
- **描述**：重新向指定邮箱发送验证码
- **参数**：
```typescript
{
email: string; // 邮箱地址
}
```
## 错误处理
### 常见错误码
- `VERIFICATION_CODE_NOT_FOUND`：验证码不存在或已过期
- `VERIFICATION_CODE_INVALID`：验证码错误
- `TOO_MANY_ATTEMPTS`：验证尝试次数过多
- `RATE_LIMIT_EXCEEDED`：发送频率过高
- `EMAIL_SEND_FAILED`：邮件发送失败
### 错误响应格式
```typescript
{
success: false,
message: "错误描述",
error_code: "ERROR_CODE"
}
```
## 监控和日志
### 关键指标
- 验证码发送成功率
- 验证码验证成功率
- 邮件发送延迟
- Redis连接状态
### 日志记录
- 验证码生成和验证日志
- 邮件发送状态日志
- 错误和异常日志
- 性能监控日志
## 安全考虑
### 防刷机制
1. **发送频率限制**：每个邮箱60秒内只能发送一次
2. **每小时限制**：每个邮箱每小时最多发送5次
3. **验证尝试限制**：每个验证码最多尝试3次
### 数据安全
1. **验证码加密存储**：Redis中的验证码经过加密
2. **过期自动清理**：验证码5分钟后自动过期
3. **日志脱敏**：日志中不记录完整验证码
## 部署指南
详细的部署说明请参考：[deployment-guide.md](./deployment-guide.md)
## 测试
### 单元测试
```bash
# 运行验证服务测试
npm test -- verification.service.spec.ts
# 运行邮件服务测试
npm test -- email.service.spec.ts
```
### 集成测试
```bash
# 运行邮箱验证集成测试
npm run test:e2e -- email-verification
```
## 故障排除
### 常见问题
1. **验证码收不到**
- 检查SMTP配置
- 检查邮箱是否在垃圾邮件中
- 检查网络连接
2. **验证码验证失败**
- 检查验证码是否过期
- 检查验证码输入是否正确
- 检查Redis连接状态
3. **发送频率限制**
- 等待冷却时间结束
- 检查是否达到每小时限制
## 更新日志
- **v1.0.0** (2025-12-17)
- 初始版本发布
- 支持基本的邮箱验证功能
- 集成Redis缓存
- 添加防刷机制

316
docs/systems/email-verification/deployment-guide.md Normal file
View File

@@ -0,0 +1,316 @@
# 邮箱验证功能部署指南
## 概述
本指南详细说明如何部署和配置邮箱验证功能，包括Redis缓存、邮件服务配置等。
## 1. 安装依赖
```bash
# 安装新增的依赖包
pnpm install ioredis nodemailer
# 安装类型定义
pnpm install -D @types/nodemailer
```
## 2. Redis 服务配置
### 2.1 安装 Redis
#### Ubuntu/Debian
```bash
sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server
```
#### CentOS/RHEL
```bash
sudo yum install redis
sudo systemctl start redis
sudo systemctl enable redis
```
#### Docker 方式
```bash
docker run -d --name redis -p 6379:6379 redis:7-alpine
```
### 2.2 Redis 配置验证
```bash
# 测试 Redis 连接
redis-cli ping
# 应该返回 PONG
```
## 3. 邮件服务配置
### 3.1 Gmail 配置示例
1. **启用两步验证**：
- 登录 Google 账户
- 进入"安全性"设置
- 启用"两步验证"
2. **生成应用专用密码**：
- 在"安全性"设置中找到"应用专用密码"
- 生成新的应用密码
- 记录生成的16位密码
3. **环境变量配置**：
```env
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-16-digit-app-password
EMAIL_FROM="Whale Town Game" <noreply@gmail.com>
```
### 3.2 其他邮件服务商配置
#### 163邮箱
```env
EMAIL_HOST=smtp.163.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-email@163.com
EMAIL_PASS=your-authorization-code
```
#### QQ邮箱
```env
EMAIL_HOST=smtp.qq.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-email@qq.com
EMAIL_PASS=your-authorization-code
```
#### 阿里云邮件推送
```env
EMAIL_HOST=smtpdm.aliyun.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-smtp-username
EMAIL_PASS=your-smtp-password
```
## 4. 环境变量配置
### 4.1 创建环境配置文件
```bash
# 复制环境变量模板
cp .env.production.example .env
# 编辑环境变量
nano .env
```
### 4.2 完整的环境变量配置
```env
# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=pixel_game
DB_PASSWORD=your_db_password
DB_NAME=pixel_game_db
# 应用配置
NODE_ENV=production
PORT=3000
# JWT 配置
JWT_SECRET=your_jwt_secret_key_here_at_least_32_characters
JWT_EXPIRES_IN=7d
# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0
# 邮件服务配置
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-email@gmail.com
EMAIL_PASS=your-app-password
EMAIL_FROM="Whale Town Game" <noreply@whaletown.com>
```
## 5. 数据库迁移
由于添加了新的字段，需要更新数据库结构：
```sql
-- 添加邮箱验证状态字段
ALTER TABLE users ADD COLUMN email_verified BOOLEAN NOT NULL DEFAULT FALSE COMMENT '邮箱是否已验证';
-- 为已有用户设置默认值
UPDATE users SET email_verified = FALSE WHERE email_verified IS NULL;
-- 如果是OAuth用户且有邮箱，可以设为已验证
UPDATE users SET email_verified = TRUE WHERE github_id IS NOT NULL AND email IS NOT NULL;
```
## 6. 启动和测试
### 6.1 启动应用
```bash
# 安装依赖
pnpm install
# 构建应用
pnpm run build
# 启动应用
pnpm run start:prod
```
### 6.2 功能测试
#### 测试邮箱验证码发送
```bash
curl -X POST http://localhost:3000/auth/send-email-verification \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com"}'
```
#### 测试邮箱验证
```bash
curl -X POST http://localhost:3000/auth/verify-email \
-H "Content-Type: application/json" \
-d '{"email":"test@example.com","verification_code":"123456"}'
```
#### 测试密码重置
```bash
curl -X POST http://localhost:3000/auth/forgot-password \
-H "Content-Type: application/json" \
-d '{"identifier":"test@example.com"}'
```
## 7. 监控和日志
### 7.1 查看应用日志
```bash
# PM2 日志
pm2 logs pixel-game-server
# 或者查看文件日志
tail -f logs/dev.log
```
### 7.2 Redis 监控
```bash
# 查看 Redis 信息
redis-cli info
# 监控 Redis 命令
redis-cli monitor
# 查看验证码相关的键
redis-cli keys "verification_*"
```
### 7.3 邮件发送监控
应用会记录邮件发送的日志，包括：
- 发送成功/失败状态
- 收件人信息
- 发送时间
- 错误信息（如果有）
## 8. 故障排除
### 8.1 Redis 连接问题
**问题**：Redis连接失败
```
Redis连接错误: Error: connect ECONNREFUSED 127.0.0.1:6379
```
**解决方案**：
1. 检查Redis服务状态：`sudo systemctl status redis`
2. 启动Redis服务：`sudo systemctl start redis`
3. 检查防火墙设置
4. 验证Redis配置文件
### 8.2 邮件发送问题
**问题**：邮件发送失败
```
邮件发送失败: Error: Invalid login: 535-5.7.8 Username and Password not accepted
```
**解决方案**：
1. 检查邮箱用户名和密码
2. 确认已启用应用专用密码（Gmail）
3. 检查邮件服务商的SMTP设置
4. 验证网络连接
### 8.3 验证码问题
**问题**：验证码验证失败
**解决方案**：
1. 检查Redis中是否存在验证码：`redis-cli get verification_code:email_verification:test@example.com`
2. 检查验证码是否过期
3. 验证验证码格式（6位数字）
4. 检查应用日志
## 9. 安全建议
### 9.1 邮件服务安全
1. **使用应用专用密码**：不要使用主密码
2. **启用TLS/SSL**：确保邮件传输加密
3. **限制发送频率**：防止邮件轰炸
4. **监控发送量**：避免被标记为垃圾邮件
### 9.2 Redis 安全
1. **设置密码**：`requirepass your_redis_password`
2. **绑定IP**：`bind 127.0.0.1`
3. **禁用危险命令**：`rename-command FLUSHDB ""`
4. **定期备份**：设置Redis数据备份
### 9.3 验证码安全
1. **设置过期时间**：默认5分钟
2. **限制尝试次数**：最多3次
3. **防刷机制**：60秒冷却时间
4. **记录日志**：监控异常行为
## 10. 性能优化
### 10.1 Redis 优化
```redis
# Redis 配置优化
maxmemory 256mb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
save 60 10000
```
### 10.2 邮件发送优化
1. **连接池**：复用SMTP连接
2. **异步发送**：不阻塞主流程
3. **队列机制**：处理大量邮件
4. **失败重试**：自动重试机制
---
*部署完成后，建议进行完整的功能测试，确保所有邮箱验证功能正常工作。*

0
docs/日志系统详细说明.md → docs/systems/logger/detailed-specification.md
View File