故障排除
若无法连接邮件账户或同步邮件，请按以下清单排查常见问题。
1. 检查活动日志
在 Perfex CRM 中进入 Utilities → Activity Log 查看与 IMAP 连接或同步失败相关的错误信息。
2. 启用调试模式
获取更详细的错误输出：
- 打开 Perfex CRM 安装根目录下的
index.php - 找到以下行：
define('ENVIRONMENT', 'production');
- 修改为：
define('ENVIRONMENT', 'development');
- 保存文件并重新加载页面以查看原始错误信息
注意
测试完成后请记得改回 production！
3. 查看主机错误日志
若页面空白或 Perfex 中无错误显示：
- 登录 虚拟主机控制面板（如 cPanel 或 Plesk）
- 找到 "Error Log"，通常在 "Metrics" 或 "Logs" 部分
- 查找近期错误，如 "memory exhausted"、"timeout" 或 IMAP 相关错误
4. 确认 Cron 配置
确保 cron 任务正常运行。没有 cron，Mailbox 模块无法同步邮件。
请参考 Perfex CRM 文档或联系服务器管理员排查 cron 问题。
5. OAuth 与密码认证
Mailbox 模块支持两种认证方式：
OAuth2 认证（推荐）
对于 Gmail 和 Outlook 用户，推荐使用 OAuth2。更安全，无需存储密码。
常见 OAuth 问题：
| 问题 | 解决方案 |
|---|---|
| "OAuth connection failed" | 在 Setup → Settings → Mailbox Settings 中核对 OAuth 凭据。检查 redirect URI 配置。确认 OAuth 应用具有所需权限。 |
| "Token expired" | OAuth token 会自动刷新。尝试断开并重新连接。Gmail：未验证应用 token 7 天后过期。 |
| "OAuth not available" | OAuth 仅适用于 Gmail 和 Outlook。其他提供商需使用密码认证。 |
密码认证
邮件提供商不支持 OAuth2 时，使用密码认证。
检查是否需要应用专用密码
部分提供商（如 Gmail、Yahoo、Outlook）要求使用 应用专用密码 而非账户密码，尤其在启用 2FA（双因素认证） 时。
示例：Gmail 用户
- 访问 https://myaccount.google.com/security
- 启用 2-Step Verification（若尚未启用）
- 在 "Signing in to Google" 下找到 App Passwords
- 为 "Mail" 生成新的应用专用密码
- 在模块的 Mailbox Config 中使用该密码，而非 Gmail 常规密码
注意
需要应用专用密码而未使用时，会导致认证失败或登录被阻止。
提示
对于 Gmail 和 Outlook，强烈建议使用 OAuth2 而非应用专用密码，以获得更好安全性和易用性。参见 Gmail OAuth Setup 或 Outlook OAuth Setup。
6. 按员工设置与全局设置
模块支持按员工和全局 IMAP 设置：
- 按员工设置：每位员工可配置自己的 IMAP 服务器、端口、加密和文件夹映射
- 全局设置：当未配置按员工设置时使用的备用 设置
若邮件未同步：
- 检查 Mailbox Config 中的按员工设置
- 确认 IMAP 服务器、端口和加密正确
- 检查文件夹映射（尤其使用非标准文件夹名时）
- 在活动日志中查看具体错误信息
7. 已读状态同步问题
若已启用 "Sync Read Status to Email Server" 但 Gmail/Outlook 中未反映变更：
- 旧邮件：2.1.7 版本之前导入的邮件可能未存储 UID。仅新邮件会同步已读状态。
- UID 缺失：在活动日志中查找 "Email ID XXX has no UID stored" 信息（旧邮件属正常情况）。
- 需 OAuth：已读状态同步在 OAuth 认证下效果最佳。
- 手动同步：在 Settings 中使用 Manual Sync 按钮测试连接。
仍需要帮助？
若问题仍未解决，我们的支持团队可协助您。请通过 Themesic Support Portal 提交工单，我们将尽快处理。