邮件发送失败？Billion Mail 3分钟定位+解决全指南
项目地址: https://gitcode.com/gh_mirrors/bi/Billion-Mail 你是否遇到邮件发送后石沉大海？收件人收不到、进入垃圾邮件或批量发送超时？本文将通过3大排查维度、5个实用工具和7个真实案例，教你快速定位并解决Billion Mail邮件发送问题，让你的营销邮件送达率提升90%。读完本文你将掌握：如何查看关键日志定位错误、配置文件检查要点、使用bm.sh工具进行故障排除，以及常见问题的解决方案。
一、日志排查：3个关键位置锁定问题
邮件发送失败的第一线索往往藏在日志中。Billion Mail采用Docker容器化部署，各组件日志分散在不同容器中，以下是获取关键日志的方法：
1.1 Postfix邮件服务器日志
Postfix作为核心邮件传输代理（MTA），其日志包含邮件投递状态、SMTP交互过程等关键信息。通过bm.sh脚本可直接查看Postfix容器日志：
./bm.sh logs postfix
关键错误代码参考：
| 错误代码 | 含义 | 排查方向 |
|---|---|---|
| 550 | 收件人地址不存在 | 检查收件人列表有效性 |
| 554 | 邮件被拒绝 | 检查发件人信誉、内容是否合规 |
| 451 | 暂时无法处理 | 检查服务器负载、网络连接 |
1.2 Dovecot邮件投递日志
Dovecot负责邮件的接收和存储，若用户收不到邮件，可查看其日志：
./bm.sh logs dovecot
日志路径：conf/dovecot/10-logging.conf 中定义了日志级别和位置，默认日志级别为info，可临时改为debug获取更详细信息。
1.3 Rspamd垃圾邮件过滤日志
Rspamd的评分会影响邮件是否被标记为垃圾邮件，查看其日志了解邮件评分情况：
./bm.sh logs rspamd
关键配置文件：conf/rspamd/local.d/milter_headers.conf 控制是否添加X-Spam评分头，建议开启以便跟踪。
二、配置检查：4个核心文件验证
2.1 Postfix主配置
Postfix的conf/postfix/main.cf是邮件发送的核心配置，重点检查：
smtpd_recipient_restrictions：确保包含permit_sasl_authenticated允许认证用户发送milter_default_action：默认应设为accept，避免误拦截message_size_limit：默认100MB，若发送大附件可适当调大
2.2 DKIM签名配置
DKIM签名是邮件送达率的关键，通过以下命令检查DKIM记录是否正确生成：
./bm.sh show-record example.com
确保DNS已正确添加TXT记录，格式参考：conf/rspamd/statistic.conf 中的DKIM配置示例。
2.3 SPF记录配置
SPF记录防止域名被伪造发送邮件，在DNS中添加：
v=spf1 +a +mx +ip4:你的服务器IP -all
可通过bm.sh工具验证SPF配置：
./bm.sh check-spf example.com
2.4 网络端口检查
确保服务器开放必要端口，Billion Mail需要的端口包括：
| 端口 | 用途 |
|---|---|
| 25 | SMTP |
| 587 | SUBMISSION |
| 465 | SMTPS |
| 143/993 | IMAP/IMAPS |
| 110/995 | POP3/POP3S |
检查端口是否开放：
./bm.sh check-ports
三、工具使用：bm.sh一站式故障排除
bm.sh脚本是Billion Mail提供的管理工具，集成了日志查看、服务重启、域名管理等功能，是排查问题的利器。
3.1 查看默认登录信息
忘记管理员密码？执行：
./bm default
将显示管理员用户名、密码及访问地址，如：
Username: admin@billionmail.com
Password: BillionMail123
Address: https://your-server-ip:8443/billionmail
3.2 重启服务组件
若修改了配置，需要重启对应服务：
# 重启Postfix
./bm.sh restart postfix
# 重启所有服务
./bm.sh restart all
3.3 生成DKIM密钥
新添加域名后，需生成DKIM密钥并添加到DNS：
./bm.sh dkim example.com
执行后会输出DKIM的TXT记录值，参考README-zh_CN.md中的DNS配置说明。
四、常见问题解决方案
4.1 邮件进入垃圾邮件
原因：DKIM/SPF未配置或配置错误、邮件内容评分过高。
解决方案：
- 检查DKIM签名：发送测试邮件后查看邮件头是否有
DKIM-Signature - 优化邮件内容：减少敏感词、增加文本比例、避免过多链接
- 查看Rspamd评分：在conf/rspamd/rspamd.conf中降低
required_score值（默认6.0）
4.2 发送速度慢
原因：Postfix并发连接数限制、服务器带宽不足。
解决方案：
- 修改Postfix配置：conf/postfix/main.cf中增加
default_destination_concurrency_limit值 - 检查服务器负载：通过
docker stats查看容器资源使用情况
4.3 无法发送外部邮件
原因：防火墙阻止、ISP封锁25端口、DNS配置错误。
解决方案：
- 检查防火墙规则，确保出站25/587端口开放
- 尝试使用SUBMISSION端口（587）发送
- 验证DNS配置：
nslookup -type=MX example.com查看MX记录是否正确
五、高级排查：数据库与API问题
5.1 数据库连接问题
若核心服务无法启动，可能是数据库连接问题，查看日志：
./bm.sh logs core
检查core/hack/config.yaml中的数据库连接参数是否与.env文件一致。
5.2 API调用失败
Billion Mail提供了丰富的API接口，若调用失败，检查：
- API密钥是否正确：在管理界面的"设置-API"中生成
- 请求格式是否正确：参考core/api/batch_mail/v1/中的API文档
- 查看API日志：core/logs/api.log（需在配置中开启debug级别）
六、总结与后续学习
通过本文介绍的日志排查、配置检查和工具使用方法，大多数邮件发送问题都能在3分钟内定位并解决。关键是熟悉各组件的日志位置和核心配置文件，善用bm.sh工具。
进阶学习资源：
- 官方文档：README-zh_CN.md
- 视频教程：在BiliBili搜索"Billion Mail 安装与配置"
- 社区支持：提交issue到项目仓库（参考SECURITY.md中的问题提交规范）
记住，邮件营销的成功不仅依赖工具，还需要持续优化内容、维护发件人信誉，定期检查各项配置。遇到复杂问题，可收集完整日志（Postfix、Dovecot、Rspamd）并附上邮件头信息，寻求社区帮助。
希望本文能帮助你解决Billion Mail的邮件发送问题，提升邮件营销效果！如有其他问题，欢迎在评论区留言讨论。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
