Keila邮件发送队列阻塞问题分析与解决方案

问题现象

在使用自托管Keila邮件营销平台两年半后，用户突然遇到邮件无法正常发送的问题。具体表现为：在营销活动统计页面，发送状态持续显示为"正在发送"的旋转图标，但实际邮件并未发出。系统日志中也没有明显的错误信息，即使将日志级别设置为debug模式。

问题排查过程

初步诊断

根据经验，邮件发送队列阻塞通常与以下因素有关：

1. 发件人(Sender)配置异常
2. 后台任务处理系统(Oban)运行异常
3. 数据库(Postgres)连接问题
4. 系统资源限制

发件人测试

通过Elixir控制台直接测试发件人功能：

import Swoosh.Email
s = Keila.Mailings.get_sender("your_sender_id")
e = new() |> from(s.from_email) |> to(s.from_email) |> subject("Test") |> text_body("Test")
Keila.Mailer.deliver_with_sender(e, s)

测试结果显示发件人配置本身没有问题，邮件可以正常发送。

队列状态检查

检查Oban任务队列状态：

Oban.drain_queue(queue: :mailer, with_scheduled: true)

返回结果显示队列中没有待处理任务：

%{discard: 0, cancelled: 0, success: 0, failure: 0, snoozed: 0}

数据库检查

直接检查PostgreSQL中的oban_jobs表，确认是否有邮件任务卡在队列中。

问题根源

经过一系列排查，最终发现问题可能与以下情况有关：

1. 系统中存在两个同名的"test"项目
2. 项目间的某种冲突导致邮件发送队列阻塞
3. 系统对同名项目的处理可能存在边界情况未处理

解决方案

1. 删除重复项目：删除其中一个同名的"test"项目后，邮件发送功能恢复正常
2. 项目命名规范：确保项目名称唯一，避免使用重复名称
3. 系统监控：建议设置对Oban队列的监控，及时发现处理异常

最佳实践建议

1. 定期维护：定期检查系统中的项目和组织结构
2. 命名规范：为项目和发件人制定明确的命名规范
3. 日志监控：配置完善的日志监控系统，即使日志级别设置为debug未显示错误，也应检查系统级日志
4. 队列管理：熟悉Oban队列管理命令，便于问题排查
5. 测试环境：重大变更前在测试环境验证

总结

Keila作为自托管的邮件营销平台，在长期运行后可能出现各种运维问题。本次案例表明，即使是看似简单的项目命名问题，也可能导致核心功能异常。建议管理员不仅要关注明显的错误提示，还要注意系统结构和配置的合理性，建立完善的监控和维护机制，确保系统长期稳定运行。