BookStack项目邮件发送失败问题排查与解决方案

问题背景

在使用BookStack文档管理系统时，用户遇到了通过内部邮件中继发送测试邮件失败的问题。系统版本为v24.10.3，部署在Kubernetes环境中，使用linuxserver/bookstack:latest镜像。邮件配置使用了简单的25端口无加密中继服务。

问题现象

用户配置了基本的SMTP参数：

• MAIL_DRIVER=smtp
• MAIL_HOST=mail.domain.com
• MAIL_PORT=25
• 无用户名和密码认证
• 无加密设置

尽管配置看似正确，系统仍无法发送邮件，且日志中没有明确的错误信息。

技术分析

BookStack邮件处理机制

BookStack底层使用Laravel的邮件系统，即使在无加密配置下，系统仍会尝试与邮件服务器协商TLS加密。这是现代邮件系统的安全特性，旨在尽可能使用加密传输。

Postfix中继服务器行为

当Postfix作为中继服务器时，默认配置可能会声明支持TLS（即使实际未启用）。这种声明会导致客户端尝试建立TLS连接，而服务器无法正确处理，最终导致连接失败。

解决方案

1. 明确禁用Postfix的TLS声明

在Postfix的主配置文件main.cf中，添加或修改以下参数：

smtpd_tls_security_level = none

这一设置明确告知客户端该服务器不支持TLS加密，防止客户端尝试建立加密连接。

2. 验证BookStack实际配置

通过以下命令可以验证BookStack实际使用的邮件配置：

php /app/www/artisan tinker --execute="dd(config('mail.mailers.smtp'))"

预期输出应包含：

"tls_required" => false

3. 容器环境注意事项

在容器化部署中，需要注意：

• 环境变量优先级高于.env文件
• 配置变更后可能需要重启服务
• 确保容器网络能够解析邮件服务器域名

实施效果

完成上述配置后，系统能够正常通过25端口无加密中继发送邮件，同时不影响Postfix作为客户端时使用TLS连接外部邮件服务。

最佳实践建议

1. 对于内部邮件中继，考虑使用更现代的STARTTLS加密方式
2. 定期检查邮件服务器配置，确保安全性与兼容性平衡
3. 在容器部署时，优先使用环境变量而非文件配置
4. 重要系统配置变更前进行备份

通过以上措施，可以确保BookStack在各种邮件服务器配置下都能可靠地发送通知邮件。