Leantime项目中SMTP配置问题的排查与解决

问题背景

在使用Leantime项目（版本3.2.1）进行Docker自托管部署时，用户遇到了SMTP邮件服务无法正常工作的问题。具体表现为当尝试通过系统发送邀请邮件时，系统报错且邮件无法送达。

错误现象

系统日志中显示以下关键错误信息：

1. Invalid address: (From): '[e-mail]'
2. Invalid host: 'domain-at.mail.protection.outlook.com'
3. SMTP connect() failed

配置分析

用户最初的环境变量配置如下：

LEAN_EMAIL_RETURN='[e-mail]'
LEAN_EMAIL_USE_SMTP=true
LEAN_EMAIL_SMTP_HOST='domain-at.mail.protection.outlook.com'
LEAN_EMAIL_SMTP_PORT='25'
LEAN_EMAIL_SMTP_AUTH=false
LEAN_EMAIL_SMTP_AUTO_TLS=true
LEAN_EMAIL_SMTP_SECURE='TLS'
LEAN_EMAIL_SMTP_SSLNOVERIFY=false

问题排查过程

1. 变量名错误：首先发现配置中使用了LEAN_EMAIL_SMTP_HOST，而实际应为LEAN_EMAIL_SMTP_HOSTS（带"s"）。修正后问题依然存在。

2. 引号问题：深入分析后发现环境变量值两边的单引号'导致了问题。Leantime在解析这些配置时，会将引号作为值的一部分处理，而不是作为字符串界定符。

3. 配置验证：正确的配置应该去除值两边的引号，让系统直接获取纯字符串值。

解决方案

修正后的环境变量配置应为：

LEAN_EMAIL_RETURN=[e-mail]
LEAN_EMAIL_USE_SMTP=true
LEAN_EMAIL_SMTP_HOSTS=domain-at.mail.protection.outlook.com
LEAN_EMAIL_SMTP_PORT=25
LEAN_EMAIL_SMTP_AUTH=false
LEAN_EMAIL_SMTP_AUTO_TLS=true
LEAN_EMAIL_SMTP_SECURE=TLS
LEAN_EMAIL_SMTP_SSLNOVERIFY=false

技术要点

1. 环境变量处理：在Docker环境中，环境变量的值通常不需要额外的引号，除非值本身包含空格或特殊字符需要转义。

2. SMTP配置验证：配置SMTP服务时，建议先使用简单的telnet命令测试SMTP服务器是否可达，例如：telnet domain-at.mail.protection.outlook.com 25。

3. 错误日志分析：Leantime使用PHPMailer库处理邮件发送，当出现SMTP连接问题时，应优先检查主机名、端口和认证配置。

最佳实践建议

1. 在配置Leantime的SMTP服务时，避免在环境变量值两边添加不必要的引号。

2. 对于Microsoft SMTP中继服务，确保网络访问控制允许出站连接到指定端口。

3. 配置完成后，建议先使用测试邮件功能验证配置是否正确，而不是直接通过用户邀请等业务功能测试。

4. 对于复杂的SMTP配置，可以考虑使用Leantime的管理界面进行配置，而不是直接通过环境变量。

通过以上分析和修正，用户成功解决了SMTP服务无法正常工作的问题。这个案例提醒我们在配置环境变量时要特别注意值的格式处理，避免因看似无害的引号导致服务异常。