# 邮箱服务配置说明

## 📧 当前配置

本项目使用 **163 邮箱** 作为 SMTP 服务器，用于发送协作邀请邮件。

### 配置信息

```env
SMTP_HOST="smtp.163.com"
SMTP_PORT="465"
SMTP_USER="cftservice@163.com"
SMTP_PASS="SChncqpqS9TDPUD2"
SMTP_FROM="中华家谱 <cftservice@163.com>"
```

## 🔧 配置步骤

### 1. 环境变量配置

在项目根目录的 `.env` 文件中添加以上配置。

### 2. 163 邮箱设置

#### 2.1 开启 SMTP 服务
1. 登录 163 邮箱
2. 进入 **设置** → **POP3/SMTP/IMAP**
3. 开启 **SMTP 服务**
4. 获取授权密码（不是邮箱登录密码）

#### 2.2 授权密码
- 当前使用的授权密码：`SChncqpqS9TDPUD2`
- ⚠️ **安全提示**：请勿将此密码泄露给他人

### 3. 端口说明

| 端口 | 加密方式 | 说明 |
|------|---------|------|
| 465 | SSL/TLS | 推荐使用（当前配置） |
| 25 | 无加密 | 不推荐 |
| 587 | STARTTLS | 可选 |

## 📨 邮件功能

### 当前支持的邮件类型

1. **协作邀请邮件**
   - 邀请用户加入家族树
   - 发送初始密码（新用户）
   - 提供登录链接

### 邮件模板

邮件模板位于：`/lib/mail.ts`

```typescript
export async function sendInvitationEmail(
  to: string,
  inviterName: string,
  treeName: string,
  role: string,
  password?: string
)
```

## 🧪 测试邮件发送

### 方法 1：通过 API 测试

```bash
# 测试发送邀请邮件
curl -X POST http://localhost:3000/api/trees/[treeId]/invite \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "role": "VIEWER"
  }'
```

### 方法 2：通过界面测试

1. 登录系统
2. 进入任一家族树
3. 点击 **设置** → **协作者管理**
4. 添加协作者并发送邀请

## 🔍 故障排查

### 常见问题

#### 1. 邮件发送失败

**可能原因**：
- SMTP 服务未开启
- 授权密码错误
- 网络连接问题
- 163 邮箱被限制发送

**解决方案**：
```bash
# 检查环境变量
echo $SMTP_USER
echo $SMTP_HOST

# 查看应用日志
tail -f logs/app.log
```

#### 2. 邮件被标记为垃圾邮件

**解决方案**：
- 配置 SPF 记录
- 配置 DKIM 签名
- 使用企业邮箱

#### 3. 发送频率限制

163 邮箱对发送频率有限制：
- 免费邮箱：每天约 50 封
- VIP 邮箱：每天约 500 封

**建议**：
- 使用企业邮箱
- 或使用专业邮件服务（如 SendGrid、阿里云邮件推送）

## 🔐 安全建议

### 1. 保护授权密码

```bash
# 不要将 .env 文件提交到 Git
echo ".env" >> .gitignore

# 使用环境变量管理工具
# 如：dotenv-vault, AWS Secrets Manager
```

### 2. 定期更换密码

建议每 3-6 个月更换一次授权密码。

### 3. 监控邮件发送

```typescript
// 添加邮件发送日志
console.log(`邮件已发送至: ${to}`)
console.log(`发送时间: ${new Date().toISOString()}`)
```

## 🚀 生产环境配置

### 推荐方案

#### 方案 1：使用企业邮箱
- 阿里云企业邮箱
- 腾讯企业邮箱
- 网易企业邮箱

#### 方案 2：使用专业邮件服务
- **SendGrid**：免费额度 100 封/天
- **阿里云邮件推送**：按量付费
- **AWS SES**：按量付费

### 配置示例（SendGrid）

```env
SMTP_HOST="smtp.sendgrid.net"
SMTP_PORT="465"
SMTP_USER="apikey"
SMTP_PASS="your-sendgrid-api-key"
SMTP_FROM="noreply@yourdomain.com"
```

## 📊 监控和日志

### 添加邮件发送统计

```typescript
// lib/mail.ts
let emailSentCount = 0

export async function sendInvitationEmail(...) {
  try {
    await transporter.sendMail({...})
    emailSentCount++
    console.log(`邮件发送成功，总计: ${emailSentCount}`)
  } catch (error) {
    console.error('邮件发送失败:', error)
    throw error
  }
}
```

## 📝 维护记录

| 日期 | 操作 | 操作人 |
|------|------|--------|
| 2025-11-23 | 配置 163 邮箱服务 | System |
| - | - | - |

## 🔗 相关链接

- [163 邮箱帮助中心](https://help.mail.163.com/)
- [Nodemailer 文档](https://nodemailer.com/)
- [SMTP 协议说明](https://zh.wikipedia.org/wiki/SMTP)

## 📞 技术支持

如遇到邮件发送问题，请：
1. 检查环境变量配置
2. 查看应用日志
3. 联系系统管理员