Leantime邮件发送配置问题排查指南

问题背景

在使用Leantime项目管理工具时，许多用户可能会遇到SMTP邮件发送失败的问题。特别是在使用第三方邮件服务（如Mailjet）时，系统默认以"leantime"作为发件人地址，导致邮件被服务商拦截。

核心配置项解析

Leantime提供了多个环境变量用于配置邮件发送功能，其中最关键的是发件人地址设置：

1. LEAN_EMAIL_RETURN - 用于设置邮件的返回地址（即发件人地址）
2. LEAN_EMAIL - 同样可以用于设置发件人地址（部分版本可能优先使用此变量）

这两个配置项都要求使用有效的电子邮件地址格式。如果留空或不正确配置，系统将使用默认的"leantime"作为发件人，这会导致大多数邮件服务商拒绝发送。

完整SMTP配置示例

以下是一个完整的Mailjet SMTP配置示例：

## Email
LEAN_EMAIL_RETURN = '[e-mail]'
LEAN_EMAIL = '[e-mail]'
LEAN_EMAIL_USE_SMTP = true
LEAN_EMAIL_SMTP_HOSTS = 'in-v3.mailjet.com'
LEAN_EMAIL_SMTP_AUTH = true
LEAN_EMAIL_SMTP_USERNAME = 'your_username'
LEAN_EMAIL_SMTP_PASSWORD = 'your_password'
LEAN_EMAIL_SMTP_AUTO_TLS = true
LEAN_EMAIL_SMTP_SECURE = 'TLS'
LEAN_EMAIL_SMTP_SSLNOVERIFY = false
LEAN_EMAIL_SMTP_PORT = '587'

常见问题排查

1. 连接超时问题

当使用SSL协议和465端口时，可能会出现连接超时的情况。这是因为：

• 465端口通常与TLS协议配合使用
• 许多现代邮件服务更推荐使用587端口和STARTTLS

解决方案：尝试将协议改为TLS，端口改为587。

2. 调试模式启用

如果遇到问题，可以启用调试模式：

LEAN_DEBUG=1

这将：

• 清除服务器缓存中的旧配置
• 在日志文件(/storage/logs/)中记录详细的SMTP调试信息

3. 密码重置次数限制

Leantime会对密码重置请求进行限制。如果测试时触发限制，可以通过以下方式解决：

• 在数据库的zp_user表中重置用户的密码重置计数
• 使用不同的测试账户继续测试

4. 邮件测试工具

Leantime提供了命令行工具测试邮件功能：

php bin/leantime email:testemail --address="[e-mail]"

最佳实践建议

1. 协议和端口选择：优先尝试TLS+587组合，这是目前最广泛支持的配置
2. 发件人地址：确保LEAN_EMAIL_RETURN和LEAN_EMAIL都设置为服务商允许的地址
3. 日志分析：遇到问题时首先检查/storage/logs/目录下的日志文件
4. 分步测试：先使用命令行工具测试基本功能，再测试具体功能模块

通过以上配置和排查方法，大多数Leantime邮件发送问题都能得到解决。如果问题仍然存在，建议检查服务器防火墙设置和邮件服务商的具体要求。