MBE 文档中心

阿里云邮件推送配置指南

概述

本指南详细说明如何配置阿里云邮件推送服务，为 MBE 系统提供邮件发送功能。

一、开通阿里云邮件推送服务

1.1 登录阿里云控制台

  1. 访问 阿里云控制台
  2. 使用您的阿里云账号登录

1.2 开通邮件推送服务

  1. 在控制台顶部搜索框输入 "邮件推送" 或 "DirectMail"
  2. 进入 邮件推送 产品页面
  3. 点击 立即开通 或 免费试用
  4. 选择服务区域（推荐：华东1-杭州）
  5. 确认开通（免费版每天 200 封邮件）

1.3 创建发信地址

如何找到创建发信地址的位置：

  1. 登录阿里云邮件推送控制台后，在页面右侧找到 "邮件推送控制台 | 发信地址" 面板
  2. 在该面板的右上角，有一个蓝色的 "新建发信地址" 按钮
  3. 或者按照页面左下角"操作引导"中的第二步提示操作

创建步骤：

  1. 点击 新建发信地址 按钮，弹出创建对话框

  2. 填写对话框中的字段：

    ① 发信域名（必填，下拉选择框）

    • 说明：选择您要使用的域名
    • 如何填写：
      • 如果创建 noreply@mbe.hi-maker.com，通常选择 hi-maker.com 或 mbe.hi-maker.com
      • 从下拉列表中选择已添加并验证的域名
      • 如果列表中没有您的域名，需要先在阿里云邮件推送中添加域名并完成验证

    ② 账号（必填，文本输入框）

    • 说明：发信地址的前缀部分
    • 如何填写：
      • 输入：noreply（或您想要的账号名）
      • ⚠️ 重要：创建后不可修改，请谨慎输入
      • 最终发信地址 = 账号 + @ + 域名
      • 例如：账号 noreply + 域名 mbe.hi-maker.com = noreply@mbe.hi-maker.com

    ③ 回信地址（可选，文本输入框）

    • 说明：当收件人回复邮件时，邮件会发送到此地址
    • 如何填写：
      • 推荐留空（适用于系统通知邮件，通常不需要回复）
      • 或者填写：admin@hi-maker.com 或 support@hi-maker.com
      • 如果填写，可能需要验证该邮箱的所有权
      • 注意：SMTP 发信的回信地址需要在 SMTP 的 reply to 中单独设置

    ④ 发信类型（必填，下拉选择框）

    • 说明：选择邮件类型
    • 如何填写：
      • 选择：触发邮件
      • 适用于：系统通知、验证码、密码重置、注册激活等场景
      • 不适用于：营销邮件、批量邮件（这些需要选择"批量邮件"类型）

  3. 检查填写无误后，点击右下角的蓝色 确定 按钮

  4. 创建成功后，在发信地址列表中找到刚创建的发信地址

  5. 点击 设置密码 或 重置密码，设置 SMTP 密码

    • ⚠️ 重要：请保存好这个密码，稍后需要在 .env 文件中配置
    • 建议使用强密码（包含大小写字母、数字、特殊字符）

1.4 添加并验证域名

在创建发信地址之前，需要先在阿里云邮件推送中添加域名并完成验证。

1.4.1 添加域名

  1. 在阿里云邮件推送控制台，进入 域名管理 页面
  2. 点击 新建域名 或 添加域名 按钮
  3. 输入域名：mbe.hi-maker.com（或 hi-maker.com）
  4. 点击 确定 添加

1.4.2 验证域名

添加域名后，状态会显示为 "待验证"。需要完成以下三项验证：

① 域名所有权验证

  1. 在域名管理页面，找到您的域名 mbe.hi-maker.com
  2. 点击域名或 验证 按钮，查看验证详情
  3. 系统会显示需要添加的 DNS 记录（通常是 CNAME 记录）
  4. 按照提示在域名 DNS 管理中添加 CNAME 记录

示例 CNAME 记录：

类型: CNAME
主机记录: dm.mbe (或系统提示的记录名，如 dm.mbe)
记录值: dm.aliyun.com (或系统提示的值)
TTL: 600

② SPF 验证

在 DNS 管理中添加 SPF 记录：

类型: TXT
主机记录: @
记录值: v=spf1 include:spf1.dm.aliyun.com include:spf2.dm.aliyun.com ~all
TTL: 600

③ MX 验证（可选）

如果系统要求 MX 记录，可以添加：

类型: MX
主机记录: @
记录值: mail.mbe.hi-maker.com (或系统提示的值)
优先级: 10
TTL: 600

1.4.3 完成验证

  1. 添加所有 DNS 记录后，等待 5-30 分钟（DNS 传播需要时间）
  2. 返回阿里云邮件推送控制台的 域名管理 页面
  3. 点击 验证 按钮，系统会自动检查 DNS 记录
  4. 验证成功后，状态会变为 "验证通过"

验证状态说明：

  • 待验证：所有权、SPF 和 MX 验证三项中任意一项未通过
  • 验证通过：配置项全部验证通过

如果验证失败：

  • 检查 DNS 记录是否正确添加
  • 确认记录类型、主机记录、记录值是否完全匹配
  • 等待更长时间（DNS 传播可能需要 24-48 小时）
  • 使用 nslookup 或 dig 命令验证 DNS 记录是否生效

二、配置 DNS 记录（提高邮件送达率）

为了提高邮件送达率，避免被标记为垃圾邮件，建议配置以下 DNS 记录：

2.1 SPF 记录

SPF（Sender Policy Framework）记录用于验证发件人身份。

在 hi-maker.com 的 DNS 管理中添加：

类型: TXT
主机记录: @
记录值: v=spf1 include:spf1.dm.aliyun.com include:spf2.dm.aliyun.com ~all
TTL: 600

说明：

  • @ 表示根域名（hi-maker.com）
  • include:spf1.dm.aliyun.com 和 include:spf2.dm.aliyun.com 允许阿里云邮件服务器发送邮件
  • ~all 表示其他服务器发送的邮件标记为可疑但不过滤

2.2 DKIM 记录

DKIM（DomainKeys Identified Mail）用于邮件签名验证。

  1. 在阿里云邮件推送控制台 → 发信地址 → 选择您的发信地址
  2. 查看 DKIM 配置 部分
  3. 复制显示的 DKIM 记录值
  4. 在 DNS 管理中添加：
类型: TXT
主机记录: default._domainkey (或系统提示的记录名)
记录值: (从阿里云控制台复制)
TTL: 600

2.3 DMARC 记录（可选，推荐）

DMARC（Domain-based Message Authentication）提供邮件认证策略。

类型: TXT
主机记录: _dmarc
记录值: v=DMARC1; p=none; rua=mailto:admin@hi-maker.com
TTL: 600

说明：

  • p=none 表示监控模式，不拒绝未通过验证的邮件
  • rua=mailto:admin@hi-maker.com 指定接收报告的邮箱（请替换为您的邮箱）

2.4 DNS 记录配置示例（Cloudflare）

如果您使用 Cloudflare 管理 DNS：

  1. 登录 Cloudflare Dashboard
  2. 选择域名 hi-maker.com
  3. 进入 DNS → 记录
  4. 添加以下记录：
类型 名称 内容 TTL 代理状态
TXT @ v=spf1 include:spf1.dm.aliyun.com include:spf2.dm.aliyun.com ~all 自动 仅 DNS
TXT default._domainkey (从阿里云复制) 自动 仅 DNS
TXT _dmarc v=DMARC1; p=none; rua=mailto:admin@hi-maker.com 自动 仅 DNS
CNAME dm.mbe dm.aliyun.com 自动 仅 DNS

重要： 所有 DNS 记录的 代理状态 必须设置为 仅 DNS（灰色云朵），不能开启代理（橙色云朵）。

三、获取 SMTP 配置信息

3.1 查看 SMTP 服务器信息

  1. 进入 邮件推送控制台 → 发信地址
  2. 选择您的发信地址
  3. 查看 SMTP 发信 部分，获取以下信息：
    • SMTP 服务器地址：smtpdm.aliyun.com
    • SMTP 端口：
      • 80（非加密，不推荐）
      • 465（SSL 加密，推荐）
      • 25（标准端口，可能被运营商屏蔽）
    • SMTP 用户名：您的发信地址（如 noreply@mbe.hi-maker.com）
    • SMTP 密码：需要单独设置（见下一步）

3.2 设置 SMTP 密码

  1. 在发信地址详情页面，找到 SMTP 密码 部分
  2. 点击 设置密码 或 重置密码
  3. 输入并确认密码（建议使用强密码）
  4. 重要： 保存密码，稍后需要在 .env 文件中配置

四、配置 MBE 系统

4.1 更新环境变量

编辑项目根目录的 .env 文件（如果不存在，从 env.example.txt 复制）：

# ============ 邮件服务配置 ============
# 阿里云邮件推送 SMTP 配置
SMTP_HOST=smtpdm.aliyun.com
SMTP_PORT=465
SMTP_USE_TLS=true
SMTP_USER=noreply@mbe.hi-maker.com
SMTP_PASSWORD=your-smtp-password-here
SMTP_FROM_EMAIL=noreply@mbe.hi-maker.com
SMTP_FROM_NAME=MBE系统

重要提示：

  • 将 your-smtp-password-here 替换为在阿里云控制台设置的 SMTP 密码
  • 确保 .env 文件已添加到 .gitignore，不要提交到代码仓库

4.2 验证配置

运行测试脚本验证配置：

# Windows PowerShell
python scripts\test_email.py

# Linux/Mac
python scripts/test_email.py

测试脚本会：

  1. 检查配置是否完整
  2. 提示输入测试邮箱地址
  3. 发送测试邮件
  4. 显示发送结果

4.3 Docker 环境配置

如果使用 Docker 部署，确保在 docker-compose.prod.yml 中已包含邮件配置（已自动配置）。

重启服务以应用新配置：

# 停止服务
docker-compose -f docker-compose.prod.yml down

# 启动服务
docker-compose -f docker-compose.prod.yml up -d

五、使用邮件服务

5.1 在代码中使用

from src.services.email_service import email_service

# 发送基本邮件
email_service.send_email(
    to_email="user@example.com",
    subject="测试邮件",
    body="这是一封测试邮件"
)

# 发送验证码邮件
email_service.send_verification_email(
    to_email="user@example.com",
    verification_code="123456"
)

# 发送密码重置邮件
email_service.send_password_reset_email(
    to_email="user@example.com",
    reset_token="token123",
    reset_url="https://mbe.hi-maker.com/reset-password?token=token123"
)

# 发送通知邮件
email_service.send_notification_email(
    to_email="user@example.com",
    title="系统通知",
    content="您的账户已激活",
    action_url="https://mbe.hi-maker.com/dashboard",
    action_text="查看详情"
)

5.2 检查邮件服务状态

from src.services.email_service import email_service

if email_service.enabled:
    print("邮件服务已启用")
    print(f"SMTP 服务器: {email_service.smtp_host}:{email_service.smtp_port}")
else:
    print("邮件服务未配置")

六、常见问题

Q1: 邮件发送失败，提示认证错误

解决方案：

  1. 检查 SMTP 用户名和密码是否正确
  2. 确认在阿里云控制台已设置 SMTP 密码
  3. 检查 SMTP 端口是否正确（推荐使用 465）

Q2: 邮件被标记为垃圾邮件

解决方案：

  1. 确保已配置 SPF、DKIM、DMARC 记录
  2. 等待 DNS 记录生效（通常需要 24-48 小时）
  3. 使用专业的发信地址（如 noreply@mbe.hi-maker.com）
  4. 避免使用敏感词汇（如"免费"、"立即"等）
  5. 保持合理的发送频率

Q3: DNS 记录验证失败

解决方案：

  1. 确认 DNS 记录类型正确（TXT 或 CNAME）
  2. 检查主机记录是否正确（注意是否需要包含域名）
  3. 等待 DNS 传播（通常 5-30 分钟）
  4. 使用 nslookup 或 dig 命令验证 DNS 记录是否生效

Q4: 免费额度不够用

解决方案：

  1. 阿里云邮件推送免费版：每天 200 封
  2. 如需更多额度，可以：
    • 升级到付费版（按量付费）
    • 使用多个发信地址（每个地址每天 200 封）
    • 考虑使用其他服务商（如 SendGrid）

Q5: 如何查看邮件发送统计

  1. 登录阿里云邮件推送控制台
  2. 进入 统计报表 → 发送统计
  3. 可以查看：
    • 发送量
    • 送达率
    • 打开率
    • 点击率

七、费用说明

免费版

  • 每日免费额度：200 封
  • 适用场景：小型应用、测试环境

付费版

  • 按量付费：超出免费额度后按实际发送量计费
  • 价格：约 0.01 元/封（具体以阿里云官网为准）
  • 适用场景：生产环境、大量邮件发送

八、安全建议

  1. 保护 SMTP 密码

    • 不要在代码中硬编码密码
    • 使用环境变量存储敏感信息
    • 定期更换 SMTP 密码

  2. 监控发送量

    • 定期检查邮件发送统计
    • 设置异常告警
    • 防止账户被盗用

  3. 遵守邮件规范

    • 不要发送垃圾邮件
    • 提供退订功能
    • 遵守相关法律法规

九、参考资源

十、下一步

配置完成后，您可以：

  1. ✅ 测试邮件发送功能
  2. ✅ 在用户注册流程中集成邮箱验证
  3. ✅ 实现密码重置功能
  4. ✅ 添加系统通知邮件
  5. ✅ 监控邮件发送统计

如有问题，请查看日志文件或联系技术支持。