Docmost项目邮件服务配置问题排查指南

问题背景

在使用Docmost文档协作平台时，管理员发现邀请新成员的功能无法正常工作。具体表现为系统发送的邀请邮件未能成功送达目标邮箱。通过检查数据库发现邀请记录已生成，但邮件发送环节出现问题。

错误排查过程

检查系统日志后发现以下关键错误信息：

[EmailProcessor] Error processing send-email job. Reason: connect ECONNREFUSED 127.0.0.1:587

这表明系统尝试连接本地SMTP服务器(端口587)时被拒绝。进一步检查发现部署配置中确实缺少邮件服务相关的环境变量设置。

解决方案

临时解决方案

在等待配置正式SMTP服务期间，可以采用以下临时方案：

1. 部署Mailpit作为开发用SMTP服务器
2. 手动复制系统生成的邀请链接进行分享

配置示例：

services:
  docmost:
    environment:
      - MAIL_DRIVER=smtp
      - SMTP_HOST=mailpit
      - SMTP_PORT=1025
      - MAIL_FROM_ADDRESS=[e-mail]
      - MAIL_FROM_NAME=Docmost
  mailpit:
    image: 'axllent/mailpit:latest'

正式解决方案

对于生产环境，建议采用以下方案之一：

1. 使用第三方邮件服务(如SendGrid、Mailgun等)
2. 自建专业邮件服务器(需具备相关技术能力)

配置要点

完整的邮件服务配置应包含以下关键参数：

• MAIL_DRIVER: 邮件驱动类型(smtp)
• SMTP_HOST: SMTP服务器地址
• SMTP_PORT: SMTP服务端口(通常587或465)
• SMTP_USERNAME: 认证用户名(如使用)
• SMTP_PASSWORD: 认证密码(如使用)
• MAIL_FROM_ADDRESS: 发件人邮箱地址
• MAIL_FROM_NAME: 发件人显示名称

技术建议

1. 邮件服务是Docmost的核心功能依赖，必须正确配置
2. 自建邮件服务器需考虑IP信誉、反垃圾邮件策略等复杂因素
3. 开发环境可使用Mailpit等工具模拟SMTP服务
4. 生产环境建议使用专业邮件服务提供商
5. 定期检查邮件发送日志，确保服务正常运行

通过以上配置和优化，可以确保Docmost平台的成员邀请功能正常工作，提升团队协作效率。