AFFiNE项目邮件发送故障排查指南

问题现象

在使用AFFiNE自托管版本时，用户报告了邮件发送功能完全失效的问题。具体表现为：

1. 用户注册验证邮件无法发送
2. 工作空间邀请邮件发送失败
3. 系统日志中显示"Bad sender address syntax"错误
4. 管理界面显示邮件已发送但实际上未送达

错误分析

从日志信息可以看出，核心问题出在SMTP协议的MAIL命令执行阶段。系统抛出了两个关键错误：

1. 501错误：表示发件人地址格式不符合SMTP服务器要求
2. 550错误：表示发件域名未与SMTP账户关联

这些错误表明AFFiNE在构造SMTP请求时，发件人地址格式存在问题，或者配置的发件域名未被SMTP服务商认可。

配置要点

正确的SMTP配置应包含以下关键参数：

MAILER_HOST=smtp.example.com
MAILER_PORT=465
MAILER_USER=username
MAILER_SECURE=true
MAILER_PASSWORD=yourpassword

特别注意：

• 必须使用纯邮箱地址格式([e-mail])
• 不能包含发件人名称(AFFiNE Server [e-mail])
• 发件域名必须已在SMTP服务商处完成验证

解决方案

1. 检查发件人地址格式

   • 确保在AFFiNE配置中仅使用纯邮箱地址
   • 移除任何包含在尖括号(<>)中的发件人名称

2. 验证域名配置

   • 确认使用的发件域名已在SMTP服务商处完成配置
   • 检查DNS记录是否包含正确的SPF、DKIM和DMARC记录

3. 测试SMTP连接

   • 使用telnet或专用SMTP测试工具验证SMTP服务器可达性
   • 确认端口465(SSL)或587(TLS)未被防火墙阻止

4. 更新AFFiNE版本

   • 确保使用最新稳定版(v0.21.4或更高)
   • 检查是否有相关修复已包含在更新中

最佳实践

1. 使用专用邮件服务而非个人邮箱账户
2. 为AFFiNE配置专用发件域名和子域名
3. 定期检查邮件发送日志和送达率
4. 考虑实现邮件队列和重试机制

总结

AFFiNE的邮件发送功能依赖于正确的SMTP配置和格式合规的发件人地址。通过遵循上述解决方案和最佳实践，可以确保系统邮件功能稳定可靠。对于自托管用户，建议在部署前充分测试邮件功能，并保持对相关组件的定期更新维护。