Obico服务器邮件发送故障排查指南

问题背景

在自托管Obico服务器环境中，用户报告了通过Django发送邮件功能失效的问题。虽然通过命令行可以成功发送测试邮件，但通过Django界面操作时邮件无法送达，且系统日志中没有任何错误记录。

环境配置要点

1. 邮件服务配置：使用Gmail作为SMTP服务器时，需要特别注意以下几点：

   • 必须启用两步验证
   • 需要创建应用专用密码
   • 端口配置（465或587）
   • TLS/SSL加密选项

2. Django设置检查：

   • 确保.env文件正确命名并包含所有必要的邮件配置参数
   • 检查settings.py中的邮件相关配置是否与.env文件一致
   • 特别注意EMAIL_USE_TLS和EMAIL_USE_SSL参数的设置

典型故障现象

1. 用户界面显示邮件已发送，但实际未收到
2. 系统日志中无任何错误记录
3. 新创建的用户名显示为"-"（连字符）
4. 通过Django shell手动发送邮件成功，但系统自动发送失败

深入排查步骤

第一步：验证基础配置

通过Django shell验证配置是否正确加载：

docker compose exec web ./manage.py shell

在shell中执行：

from django.conf import settings
print(settings.EMAIL_HOST)
print(settings.EMAIL_HOST_USER)

第二步：手动发送测试邮件

在Django shell中尝试手动发送邮件：

from django.core.mail import send_mail
from django.conf import settings

send_mail(
    '测试邮件主题',
    '这是一封测试邮件内容',
    settings.EMAIL_HOST_USER,
    ['接收邮箱地址'],
    fail_silently=False,
)

第三步：检查用户数据问题

当发现新创建的用户名显示为"-"时，需要检查：

1. 用户注册流程是否完整
2. 邮箱验证是否完成
3. 用户模型中的相关字段是否被正确填充

第四步：检查邮件发送逻辑

重点检查send_emails函数的实现：

1. 确认用户上下文是否正确获取
2. 验证邮件地址过滤逻辑
3. 检查异步任务队列是否正常工作

解决方案建议

1. 完整重建环境：

   docker compose down
   docker compose up -d --build
   

2. 配置参数调整：

   • 确保.env文件中包含完整的邮件配置
   • 检查settings.py中的邮件相关参数

3. 用户数据修复：

   • 通过管理界面检查问题用户的数据
   • 必要时重建用户账号

4. 日志增强：

   • 在关键函数中添加详细日志记录
   • 监控Celery任务执行情况

经验总结

1. 配置参数不一致是此类问题的常见原因，特别是当部分功能工作而另一部分不工作时
2. 容器环境下的配置加载有时会出现意外情况，重建容器往往能解决奇怪的问题
3. 用户数据完整性对系统功能的影响不容忽视，需要建立完善的数据验证机制

通过系统性的排查和验证，大多数邮件发送问题都能找到根本原因并得到解决。关键在于分步骤验证每个环节，从基础配置到高级功能，逐步缩小问题范围。