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

# 邮箱验证功能部署指南

## 概述

本指南详细说明如何部署和配置邮箱验证功能，包括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. **失败重试**：自动重试机制

---

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