chinese-family-tree-2/docs/EMAIL_CONFIGURATION.md

邮箱服务配置说明

📧 当前配置

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

配置信息

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

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

🧪 测试邮件发送

方法 1：通过 API 测试

# 测试发送邀请邮件
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 邮箱被限制发送

解决方案：

# 检查环境变量
echo $SMTP_USER
echo $SMTP_HOST

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

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

解决方案：

• 配置 SPF 记录
• 配置 DKIM 签名
• 使用企业邮箱

3. 发送频率限制

163 邮箱对发送频率有限制：

• 免费邮箱：每天约 50 封
• VIP 邮箱：每天约 500 封

建议：

• 使用企业邮箱
• 或使用专业邮件服务（如 SendGrid、阿里云邮件推送）

🔐 安全建议

1. 保护授权密码

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

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

2. 定期更换密码

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

3. 监控邮件发送

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

🚀 生产环境配置

推荐方案

方案 1：使用企业邮箱

• 阿里云企业邮箱
• 腾讯企业邮箱
• 网易企业邮箱

方案 2：使用专业邮件服务

• SendGrid：免费额度 100 封/天
• 阿里云邮件推送：按量付费
• AWS SES：按量付费

配置示例（SendGrid）

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

📊 监控和日志

添加邮件发送统计

// 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 邮箱帮助中心
• Nodemailer 文档
• SMTP 协议说明

📞 技术支持

如遇到邮件发送问题，请：

1. 检查环境变量配置
2. 查看应用日志
3. 联系系统管理员