Plausible Analytics邮件邀请功能故障排查指南

问题现象

在使用Plausible Analytics 2.1.4版本自托管部署时，管理员发现系统无法通过UI界面发送用户邀请邮件。虽然SMTP测试功能显示连接成功，且通过Elixir REPL手动发送测试邮件也能正常接收，但系统后台仍会记录"Failed to send e-mail"的错误日志。

环境配置分析

典型的Docker Compose部署配置中，邮件相关参数包括：

• MAILER_ADAPTER: Bamboo.Mua
• SMTP_HOST_ADDR: 邮件服务器地址
• SMTP_HOST_PORT: 25/465/587
• SMTP_USER_NAME: 发件邮箱
• SMTP_USER_PWD: 邮箱密码
• SMTP_HOST_SSL_ENABLED: 加密开关

深度排查过程

1. 配置验证
   通过Elixir的Application.get_env(:plausible, Plausible.Mailer)命令确认运行时配置与docker-compose.yml中的定义完全一致。

2. 手动测试
   在容器内使用Bamboo.Email.new_email构造测试邮件，通过Plausible.Mailer.deliver_now发送成功，证明底层SMTP连接和认证正常。

3. 差异对比
   发现系统生成的邀请邮件(from字段使用PlausibleWeb.Email.mailer_email_from())与手动构造的邮件存在细微差异，但测试表明这不是导致失败的原因。

解决方案建议

1. 日志增强
   建议在docker-compose.yml中增加日志级别设置，或通过SENTRY_DSN环境变量接入Sentry错误监控系统，获取更详细的错误堆栈。

2. 协议调试
   对于现代邮件服务器，建议优先使用加密端口(465或587)并启用SSL，而非传统的25端口。虽然测试中25端口可用，但可能触发某些安全策略。

3. 组件检查
   验证Bamboo.Mua适配器与当前Elixir/OTP版本的兼容性，某些情况下可能需要回退到更稳定的SMTP适配器版本。

技术原理

Plausible的邮件系统采用Elixir的Bamboo库实现，该库支持多种邮件传输协议。当UI操作触发邮件发送时，系统会构造包含特定模板的MIME邮件，与简单测试邮件的处理流程存在差异，这解释了为何测试成功而实际功能失败的现象。

最佳实践

1. 生产环境建议使用专业的邮件发送服务(SendGrid/Mailgun等)而非自建SMTP
2. 定期检查Plausible与依赖库(Bamboo等)的版本兼容性矩阵
3. 重要操作(如用户邀请)应实现异步队列和重试机制
4. 监控系统应覆盖邮件发送失败率等关键指标

通过系统性的排查和优化，可以确保Plausible Analytics的邮件通知功能稳定可靠地运行。