Memos SMTP 邮件插件实战：internal/email 的接口设计、实现原理与自托管通知配置

Memos 的 internal/email 是一个面向自托管实例的 SMTP 邮件发送包：它仅依赖 Go 标准库 net/smtp 和 crypto/tls，把"配置校验、RFC 5322 报文格式化、STARTTLS/SSL 加密连接、同步与异步发送"封装为一组极简 API。读完本篇，你将掌握 email.Config/email.Message 的完整字段语义、Send/SendAsync 的底层调用链与超时行为、各主流邮箱服务商的 SMTP 参数配置，以及该插件如何被集成进 Memos 收件箱（Inbox）邮件通知与"发送测试邮件"功能。

插件定位与设计目标

internal/email 的定位在 doc.go 中有明确说明：它专为自托管环境设计——实例管理员配置自己的 SMTP 服务器，这与 GitHub、GitLab、Discourse 等平台的做法一致。核心能力包括：

• 标准 SMTP 协议支持，基于标准库 net/smtp，不引入任何第三方 SMTP 库，依赖面最小；
• TLS/STARTTLS（587 端口）与 SSL/TLS（465 端口）两种加密模式；
• HTML 与纯文本两种正文格式，多收件人（To、Cc、Bcc），可选 Reply-To；
• 同步发送（Send，返回错误）与异步发送（SendAsync，错误写日志）两种模式；
• 带上下文包装的报错，便于区分配置错误、报文错误、认证错误与连接错误；
• RFC 5322 兼容的报文格式，并对头部值做了注入清洗。

包的目录结构如下（见 README 架构章节）：

internal/email/
├── config.go       # SMTP 配置类型与校验
├── message.go      # 邮件报文类型与 RFC 5322 格式化
├── client.go       # SMTP 客户端（TLS/SSL 连接与发送流程）
├── email.go        # 高层 Send / SendAsync API 与异步队列
├── doc.go          # 包级文档
└── *_test.go       # 单元测试

Config：SMTP 配置结构与校验规则

Config 是插件的入口参数，完整字段定义在 config.go：

type Config struct {
    SMTPHost     string // SMTP 服务器主机名（如 smtp.gmail.com）
    SMTPPort     int    // SMTP 端口（587 TLS、465 SSL、25 明文）
    SMTPUsername string // SMTP 认证用户名（通常是邮箱地址）
    SMTPPassword string // SMTP 认证密码或应用专用密码
    FromEmail    string // "From" 字段中的邮箱地址
    FromName     string // "From" 字段中的显示名（可选）
    UseTLS       bool   // 启用 STARTTLS（推荐，端口 587）
    UseSSL       bool   // 启用 SSL/TLS（端口 465）
}

Validate() 方法定义了三个硬性前提（config.go）：

校验项	规则	错误信息
SMTPHost	不能为空	SMTP host is required
SMTPPort	必须在 1–65535 之间	SMTP port must be between 1 and 65535
FromEmail	不能为空	from email is required

注意：SMTPUsername/SMTPPassword 不是必填项——当两者都为空时，客户端会跳过 SMTP 认证（见下文 createAuth）。这为自托管局域网内允许匿名投递的 Postfix/Exim 服务器留了空间。GetServerAddress() 则将主机和端口拼成 host:port 形式供拨号使用。上述规则在 config_test.go 中有对应的表驱动测试覆盖：缺失主机、端口为 0、缺失 FromEmail 均被判为非法。

Message：多收件人、HTML 正文与头部清洗

Message 类型（message.go）字段如下：

type Message struct {
    To      []string // 必填：收件人
    Cc      []string // 可选：抄送
    Bcc     []string // 可选：密送
    Subject string   // 必填：主题
    Body    string   // 必填：正文（纯文本或 HTML）
    IsHTML  bool     // true 为 HTML，false 为纯文本（默认纯文本）
    ReplyTo string   // 可选：Reply-To 地址
}

Validate() 要求 To 至少有一个收件人、Subject 和 Body 非空，测试见 message_test.go。

RFC 5322 报文格式化

Format(fromEmail, fromName) 用 strings.Builder 手工拼装报文（message.go），要点有四个：

1. From 头：有 FromName 时输出 From: Name <addr>，否则仅输出地址；
2. Bcc 不进报文头：Bcc 收件人只通过 GetAllRecipients() 参与 SMTP 的 RCPT TO 协商，Format 输出的报文里不出现 Bcc: 头——这正是"密送"的正确实现方式，TestMessageFormatMultipleRecipients 明确断言了"Bcc 不应出现在报文头中"；
3. Date 头使用 time.RFC1123Z 格式（如 Mon, 03 Sep 2026 08:00:00 +0000）；
4. Content-Type 根据 IsHTML 切换 text/html 或 text/plain，均带 charset=utf-8。

防头部注入

Format 在写入任何头部值之前都会经过 sanitizeEmailHeaderValue（message.go）：把 \r、\n 替换为空格，再用 strings.Fields 折叠连续空白。这意味着即使有人构造了 "[e-mail]\r\nX-Injected-To: bad" 这样的收件人，也不会注入伪头部。TestMessageFormatSanitizesHeaderValues 用 \r\nX-Injected-* 攻击样本验证了头部区域（\r\n\r\n 之前）不出现注入头。这一机制与 README 安全章节"验证并清洗输入"的要求直接对应。

Client：两条加密连接路径与统一发送流程

Client 是低层实现（client.go），核心常量 smtpOperationTimeout = 15 * time.Second 决定了拨号与连接读写的超时上限。Client.Send 的流程（client.go）为：

1. validateConfig()：配置为 nil 或 Validate() 不通过时，返回 invalid email configuration 包装错误；
2. message.Validate()：报文不合法时返回 invalid email message 包装错误——注意这两步都在建连之前完成，TestClientSendValidation 正是借此断言非法报文不会产生 dial 错误；
3. message.Format(...) 生成报文体，GetAllRecipients() 汇总 To+Cc+Bcc；
4. 按 UseSSL 选择 sendWithSSL（465，tls.DialWithDialer 直连加密）或 sendWithTLS（587，先明文建连再升级）；
5. sendWithClient 完成 AUTH → MAIL FROM → RCPT TO → DATA 的完整 SMTP 事务。

STARTTLS 路径细节

sendWithTLS（client.go）用 net.Dialer{Timeout: 15s} 建立 TCP 连接，随后：

• smtp.NewClient(conn, host) 解析服务器 greeting；
• 若 UseTLS 为 true，先 client.Extension("STARTTLS") 探测服务器是否支持，不支持直接报错 SMTP server does not support STARTTLS，避免静默降级为明文；
• 加密上下文固定 MinVersion: tls.VersionTLS12 并以 SMTPHost 作为 ServerName（SNI/证书校验）。

SSL 路径与认证构造

sendWithSSL（client.go）跳过 STARTTLS 协商，直接用 crypto/tls 拨号。认证由 createAuth 构造：用户名和密码都为空时返回 nil（匿名投递），否则使用 smtp.PlainAuth。认证失败、发件人设置失败、任一收件人被拒、DATA 写入失败，都会以对应上下文（SMTP authentication failed、failed to set sender、failed to set recipient: %s 等）包装返回，对应 README 错误处理章节的分类。

Send 与 SendAsync：同步 API 与有界异步队列

顶层 API 在 email.go 中：

// 同步发送：阻塞直到发出或出错
err := email.Send(config, message)

// 异步发送：立即返回，错误写日志
email.SendAsync(config, message)

Send 对 nil 参数做了兜底（email configuration is required / email message is required），然后就是 NewClient(config).Send(message) 一行转发——每次发送都是新建连接，短事务模型，不维护长连接池。

SendAsync 的实现比"起一个 goroutine"更讲究（email.go）：

• 包级 asyncEmailQueue 是容量 128 的缓冲 channel，init() 启动 2 个常驻 worker 顺序消费并调用 Send；
• 入队采用非阻塞 select { case ...: default: }：队列满时直接丢弃该封邮件并记录 Dropped email because the async queue is full 警告，而不是阻塞调用方。这是一个明确的背压取舍——通知类邮件可容忍丢失，但不能拖慢请求路径；
• worker 失败时以 slog.Warn("Failed to send email asynchronously", ...) 记录，recipients 字段会显示第一个收件人，超过一个时追加 and others。

Email 包测试 验证了这些行为：TestSend 用本地 listener 立即断连，证明 Send 能通过校验并真正发起连接（错误为 failed to create SMTP client）；TestSendAsync 断言调用耗时小于 100ms（不阻塞）；TestSendAsyncConcurrent 用 errgroup 并发 5 次入队验证线程安全。

集成：Memos 如何用这个插件发邮件

在 Memos 中，internal/email 的直接消费者是 server/notification/email.go，它把插件接到收件箱通知链路上：

• 配置来源：SMTP 参数持久化在实例级通知设置中，proto 定义为 instance_setting.proto 的 InstanceNotificationSetting.EmailSetting（enabled、smtp_host、smtp_port、smtp_username、smtp_password、from_email、from_name、reply_to、use_tls、use_ssl）。EmailConfigFromInstanceSetting 负责把它转成 email.Config，与上文 Config 字段一一对应；
• 发送器注入：EmailDispatcher 的 sender 字段是 func(*email.Config, *email.Message) 函数类型，默认取 email.SendAsync（server/notification/email.go），测试时可以通过 NewEmailDispatcher 注入假发送器；
• 收件箱通知：DispatchInboxEmail 处理 MEMO_COMMENT（评论）与 MEMO_MENTION（@提及）两类收件箱事件，且做了访问控制——若接收者无权查看相关 memo（canViewerAccessMemo），则整封邮件被静默抑制，避免邮件泄露私有内容存在性；正文为纯文本，带 Open in Memos: 链接（/memos/{uid} 或 /memos/{uid}#commentUid），要求实例 URL（profile.InstanceURL）已配置，否则记一条 Skipping inbox email notification because instance URL is required 警告并跳过；
• 发送测试邮件：SendTestEmail 用当前设置构造 email.Message{To: [recipient], Subject: "[Memos] Test email", ...} 并通过同步的 email.Send 立即返回结果，供管理界面验证 SMTP 配置是否可用；ValidateEmailSetting 则提前暴露配置错误。

这条链路印证了 README 中"配置由实例管理员提供"的设计：管理员在实例设置里填写 SMTP 参数，插件层不关心参数来自数据库还是环境变量。

服务商配置示例

以下配置完整继承自 README，均可直接复制：

Gmail（需开启两步验证并使用应用专用密码）

// STARTTLS（端口 587，推荐）
config := &email.Config{
    SMTPHost:     "smtp.gmail.com",
    SMTPPort:     587,
    SMTPUsername: "[e-mail]",
    SMTPPassword: "your-16-char-app-password",
    FromEmail:    "[e-mail]",
    FromName:     "Memos",
    UseTLS:       true,
}

// SSL 替代方案（端口 465）
config = &email.Config{
    SMTPHost:     "smtp.gmail.com",
    SMTPPort:     465,
    SMTPUsername: "[e-mail]",
    SMTPPassword: "your-16-char-app-password",
    FromEmail:    "[e-mail]",
    FromName:     "Memos",
    UseSSL:       true,
}

SendGrid

config := &email.Config{
    SMTPHost:     "smtp.sendgrid.net",
    SMTPPort:     587,
    SMTPUsername: "apikey", // SendGrid 固定为 apikey
    SMTPPassword: "your-sendgrid-api-key",
    FromEmail:    "[e-mail]",
    FromName:     "Memos",
    UseTLS:       true,
}

AWS SES

config := &email.Config{
    SMTPHost:     "email-smtp.us-east-1.amazonaws.com",
    SMTPPort:     587,
    SMTPUsername: "your-smtp-username",
    SMTPPassword: "your-smtp-password",
    FromEmail:    "[e-mail]", // 发件地址必须在 SES 中完成验证
    FromName:     "Memos",
    UseTLS:       true,
}

注意把 us-east-1 换成实际区域（email-smtp.[region].amazonaws.com）。

Mailgun 与自托管 SMTP

// Mailgun
config := &email.Config{
    SMTPHost:     "smtp.mailgun.org",
    SMTPPort:     587,
    SMTPUsername: "[e-mail]",
    SMTPPassword: "your-mailgun-smtp-password",
    FromEmail:    "[e-mail]",
    FromName:     "Memos",
    UseTLS:       true,
}

// 自托管（Postfix / Exim 等）
config = &email.Config{
    SMTPHost:     "mail.yourdomain.com",
    SMTPPort:     587,
    SMTPUsername: "username",
    SMTPPassword: "password",
    FromEmail:    "[e-mail]",
    FromName:     "Memos",
    UseTLS:       true,
}

常用端口速查

端口	协议	安全性	适用场景
587	SMTP + STARTTLS	加密	大多数服务商的推荐标准
465	SMTP over SSL/TLS	加密	替代的安全选项
25	SMTP	明文	遗留场景，常被 ISP 封锁
2525	SMTP + STARTTLS	加密	587 被阻时的替代

错误处理与常见报错

所有错误都用 github.com/pkg/errors 包装上下文（errors.Wrap/Wrapf），按前缀即可分类处置：

err := email.Send(config, message)
if err != nil {
    switch {
    case strings.Contains(err.Error(), "invalid email configuration"):
        // 配置错误：缺 host、端口非法等 → 检查 Config
    case strings.Contains(err.Error(), "invalid email message"):
        // 报文校验错误：缺收件人、主题或正文 → 检查 Message
    case strings.Contains(err.Error(), "SMTP authentication failed"):
        // 认证失败 → 检查用户名/密码
    case strings.Contains(err.Error(), "failed to connect"):
        // 网络/连接错误 → 检查主机、端口、防火墙、TLS 设置
    case strings.Contains(err.Error(), "failed to set recipient"):
        // 服务器拒绝了某个收件人
    default:
        // 其他：建 SMTP 客户端失败、STARTTLS 失败、DATA 写入失败等
    }
}

典型报错与修复方向：

• invalid email configuration: SMTP host is required → 设置 config.SMTPHost；
• invalid email configuration: SMTP port must be between 1 and 65535 → 端口设为 587 或 465；
• invalid email message: at least one recipient is required → message.To 至少一个地址；
• SMTP server does not support STARTTLS（源自 client.go）→ 服务器未开放 STARTTLS，改用 UseSSL 或 2525 端口；
• 异步发送失败不会返回错误，而是以 slog.Warn 记录 Failed to send email asynchronously recipients=... error=...。

安全实践要点

1. 生产环境必须加密：587 + UseTLS 或 465 + UseSSL。源码层面 TLS 强制 MinVersion: tls.VersionTLS12，不会协商出 TLS 1.0/1.1；

2. 凭据不硬编码：从环境变量或密钥管理读取：

   config := &email.Config{
       SMTPHost:     os.Getenv("SMTP_HOST"),
       SMTPPort:     587,
       SMTPUsername: os.Getenv("SMTP_USERNAME"),
       SMTPPassword: os.Getenv("SMTP_PASSWORD"),
       FromEmail:    os.Getenv("SMTP_FROM_EMAIL"),
       UseTLS:       true,
   }
   

3. 优先应用专用密码：Gmail 等服务商应使用 app-specific password 而非主密码；

4. 先校验后发送：message.Validate() 在发送前拦截非法报文；头部值已由 Format 内部统一清洗，防头部注入；

5. 限流防滥用：可在调用侧用 golang.org/x/time/rate 之类的手段限制发送速率（如每秒 10 封）；

6. 记录日志：发送失败时记录 recipient 与 error 结构化字段，便于安全监控。异步路径的队列满丢弃（Dropped email because the async queue is full）也应纳入告警观察。

测试与运行验证

包内测试不需要真实 SMTP 服务器：校验类测试直接断言错误，TestSend 用本地 net.Listen 模拟服务端立即断连来验证调用链走到建客户端阶段。运行方式：

# 全量测试
go test ./internal/email/... -v

# 带覆盖率
go test ./internal/email/... -v -cover

# 竞态检测
go test ./internal/email/... -race

依赖要求：Go 1.27+（与 go.mod 的 go 1.27.0 一致）、标准库 net/smtp 与 crypto/tls、github.com/pkg/errors 做错误包装；测试侧另用 testify 与 golang.org/x/sync/errgroup。

当前边界与演进方向

从源码看，插件目前只发送纯文本/HTML 正文，不支持附件、内嵌图片、模板系统与投递状态跟踪；异步队列是进程内、有界（128）、满则丢弃的内存队列，重启即失单，且没有持久化重试。README 的 Roadmap 也列出了这些方向：邮件模板、附件支持、内嵌图片、队列化发送、投递状态追踪与退信处理。对自托管通知场景来说，当前能力（同步/异步、加密、多收件人、测试邮件）已覆盖评论与 @提及通知的完整需求，集成入口在 server/notification/email.go 与 server/router/api/v1/notification_email.go，可作为二次开发的参照。