FreeScout邮件同步问题排查与解决方案

问题背景

在使用FreeScout开源客服系统时，部分用户遇到了无法从Seznam.cz邮件服务器同步邮件的问题。系统能够成功建立IMAP连接，但在执行邮件获取操作时出现错误提示"Bad token (expecting date specification)"。

问题现象

用户报告的主要症状包括：

1. 在系统工具中手动执行邮件获取操作时无任何反应
2. 日志中显示IMAP连接成功建立但搜索失败
3. 错误信息显示为"TAG4 NO SEARCH: mtd: internal error: Bad token (expecting date specification)"
4. 使用Thunderbird等邮件客户端可以正常接收邮件

技术分析

通过日志分析发现，问题出在IMAP协议的SEARCH命令执行阶段。FreeScout发送的日期格式与Seznam.cz邮件服务器的预期格式不兼容。具体表现为：

1. 系统发送的SEARCH命令格式为"SINCE 23-Nov-2024"
2. Seznam.cz服务器期望接收带引号的日期格式
3. 这种格式不兼容导致服务器拒绝执行搜索操作

解决方案

临时解决方案

对于急需解决问题的用户，可以暂时降级到FreeScout 1.8.139版本，该版本使用旧的邮件获取机制，不受此问题影响。

永久解决方案

从FreeScout 1.8.150版本开始，系统引入了新的配置选项来解决此问题：

1. 在.env配置文件中添加或修改以下参数：

   APP_SINCE_WITHOUT_QUOTES_ON_FETCHING=true
   

2. 对于使用Docker部署的用户，需要注意：

   • 直接修改容器内的.env文件
   • 或者等待Docker镜像更新以支持此环境变量

3. 修改配置后需要执行以下操作：

   • 清除系统缓存
   • 重启后台任务服务
   • 重新创建容器（如使用Docker部署）

后续验证

解决方案实施后，用户应进行以下验证：

1. 手动执行邮件获取测试
2. 检查系统日志确认无错误信息
3. 验证定时任务（cron job）是否正常执行
4. 确认新旧邮件都能正确同步

技术建议

对于企业级部署，建议：

1. 在升级前先在测试环境验证邮件同步功能
2. 定期检查邮件同步日志
3. 考虑设置邮件同步监控告警
4. 保持系统版本更新以获取最新的兼容性修复

总结

FreeScout与Seznam.cz邮件服务器的兼容性问题主要源于日期格式处理差异。通过合理配置系统参数，用户可以恢复正常的邮件同步功能。对于使用容器化部署的环境，需要特别注意环境变量的传递方式。保持系统更新和定期维护是预防此类问题的有效方法。