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

- 将日志系统文档移动到 docs/systems/logger/detailed-specification.md - 将邮箱验证部署指南移动到 docs/systems/email-verification/deployment-guide.md - 创建邮箱验证系统完整文档 docs/systems/email-verification/README.md - 按功能模块组织文档，提高可维护性
2025-12-17 20:20:00 +08:00
parent 0065357fa5
commit e58cc57769
3 changed files with 581 additions and 0 deletions
--- a/docs/systems/email-verification/deployment-guide.md
+++ b/docs/systems/email-verification/deployment-guide.md
@@ -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. **失败重试**：自动重试机制
+
+---
+
+*部署完成后，建议进行完整的功能测试，确保所有邮箱验证功能正常工作。*