whale-town-end/docs/systems/email-verification/deployment-guide.md

邮箱验证功能部署指南

概述

本指南详细说明如何部署和配置邮箱验证功能，包括Redis缓存、邮件服务配置等。

1. 安装依赖

# 安装新增的依赖包
pnpm install ioredis nodemailer

# 安装类型定义
pnpm install -D @types/nodemailer

2. Redis 服务配置

2.1 安装 Redis

Ubuntu/Debian

sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server

CentOS/RHEL

sudo yum install redis
sudo systemctl start redis
sudo systemctl enable redis

Docker 方式

docker run -d --name redis -p 6379:6379 redis:7-alpine

2.2 Redis 配置验证

# 测试 Redis 连接
redis-cli ping
# 应该返回 PONG

3. 邮件服务配置

3.1 Gmail 配置示例

1. 启用两步验证：

   • 登录 Google 账户
   • 进入"安全性"设置
   • 启用"两步验证"

2. 生成应用专用密码：

   • 在"安全性"设置中找到"应用专用密码"
   • 生成新的应用密码
   • 记录生成的16位密码

3. 环境变量配置：

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邮箱

EMAIL_HOST=smtp.163.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-email@163.com
EMAIL_PASS=your-authorization-code

QQ邮箱

EMAIL_HOST=smtp.qq.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-email@qq.com
EMAIL_PASS=your-authorization-code

阿里云邮件推送

EMAIL_HOST=smtpdm.aliyun.com
EMAIL_PORT=587
EMAIL_SECURE=false
EMAIL_USER=your-smtp-username
EMAIL_PASS=your-smtp-password

4. 环境变量配置

4.1 创建环境配置文件

# 复制环境变量模板
cp .env.production.example .env

# 编辑环境变量
nano .env

4.2 完整的环境变量配置

# 数据库配置
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. 数据库迁移

由于添加了新的字段，需要更新数据库结构：

-- 添加邮箱验证状态字段
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 启动应用

# 安装依赖
pnpm install

# 构建应用
pnpm run build

# 启动应用
pnpm run start:prod

6.2 功能测试

测试邮箱验证码发送

curl -X POST http://localhost:3000/auth/send-email-verification \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com"}'

测试邮箱验证

curl -X POST http://localhost:3000/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","verification_code":"123456"}'

测试密码重置

curl -X POST http://localhost:3000/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"identifier":"test@example.com"}'

7. 监控和日志

7.1 查看应用日志

# PM2 日志
pm2 logs pixel-game-server

# 或者查看文件日志
tail -f logs/dev.log

7.2 Redis 监控

# 查看 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 配置优化
maxmemory 256mb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
save 60 10000

10.2 邮件发送优化

1. 连接池：复用SMTP连接
2. 异步发送：不阻塞主流程
3. 队列机制：处理大量邮件
4. 失败重试：自动重试机制

---

部署完成后，建议进行完整的功能测试，确保所有邮箱验证功能正常工作。