CISO Assistant项目SMTP邮件发送故障排查与解决方案

问题背景

在使用CISO Assistant开源项目的Docker部署过程中，遇到了邮件通知功能无法正常工作的问题。虽然SMTP配置看似正确，但在创建新用户时系统始终无法发送欢迎邮件，而通过容器内手动测试SMTP连接却可以成功发送邮件。

故障现象

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

1. 连接意外关闭："Connection unexpectedly closed: The read operation timed out"
2. 主邮件发送失败后尝试救援模式也失败
3. 最终返回400错误请求状态

环境配置

项目使用Docker Compose部署，主要服务包括：

• PostgreSQL数据库
• 后端服务容器
• 前端服务容器
• Caddy反向代理
• Huey任务队列

SMTP配置使用了Microsoft 365的企业邮箱服务，启用了TLS加密：

• SMTP服务器：smtp.office365.com
• 端口：587
• 使用TLS：True
• 认证方式：LOGIN

排查过程

1. 基础连接测试：在容器内使用swaks工具手动测试SMTP连接，确认网络可达性和认证正常
2. 配置验证：检查了Docker Compose文件中的环境变量配置，确认参数正确
3. 日志分析：发现系统在发送邮件时出现超时，但手动测试无此问题
4. 密码特殊字符：注意到密码中包含$符号，怀疑可能被解析为环境变量

根本原因

问题出在密码中的特殊字符$上。在Docker环境变量中，$符号会被解释为引用环境变量的开始，即使将密码用单引号或双引号包裹也无法避免这种解析行为。这导致系统实际使用的密码与预期不符，从而引发认证失败。

解决方案

1. 密码转义：对密码中的$符号进行转义处理，使用$形式
2. 替代方案：考虑使用不包含特殊字符的密码
3. 配置方式优化：将敏感信息通过Docker secrets或配置文件方式注入，而非直接写在环境变量中

最佳实践建议

1. 密码复杂性：虽然需要强密码，但应避免在Docker环境变量中使用特殊字符
2. 配置管理：敏感信息应通过更安全的方式管理，如：
   • Docker secrets
   • 配置文件挂载
   • 密钥管理服务
3. 日志级别：调试时可临时提高日志级别，便于发现问题
4. 测试验证：部署后应进行端到端功能测试，包括邮件发送功能

总结

在容器化环境中处理敏感信息时需要特别注意特殊字符的处理。本例中的$符号问题虽然看似简单，但可能导致难以排查的认证失败。通过这次故障排查，我们认识到在DevOps实践中，配置管理的小细节可能对系统功能产生重大影响。建议团队建立完善的配置管理规范，并对特殊字符的使用保持警惕。

对于CISO Assistant项目用户，如果遇到类似邮件发送问题，建议首先检查密码中是否包含特殊字符，特别是$符号，这是Docker环境变量处理中的一个常见陷阱。