使用 Logback 发送邮件通知

1. 概述

Logback 是 Java 应用中最主流的日志框架之一。它原生支持高级过滤、日志归档与自动清理旧日志文件，✅ 还支持通过邮件发送日志消息。

本文将演示如何配置 Logback，在应用发生错误时自动发送邮件告警。这在生产环境监控中非常实用，属于“踩坑”后总结出的简单粗暴但高效的方案。

2. 环境准备

Logback 的邮件功能依赖 SMTPAppender，而该组件底层使用了 Jakarta Mail API，同时需要 Java Beans Activation Framework（JAF）支持。

需要引入以下两个依赖（注意：Jakarta EE 已迁移至 Eclipse，因此使用 Angus 实现）：

<dependency>
    <groupId>org.eclipse.angus</groupId>
    <artifactId>angus-mail</artifactId>
    <version>2.0.1</version>
</dependency>
<dependency>
    <groupId>org.eclipse.angus</groupId>
    <artifactId>angus-activation</artifactId>
    <version>2.0.0</version>
    <scope>runtime</scope>
</dependency>

📌 说明：

angus-mail：Eclipse 对 Jakarta Mail API 的实现
angus-activation：替代已废弃的 javax.activation

你可以在 Maven Central 找到最新版本。

3. 配置 SMTPAppender

SMTPAppender 默认行为：

✅ 只在记录 ERROR 级别日志时触发邮件
⚠️ 使用一个容量为 256 的环形缓冲区（cyclic buffer）缓存日志事件
缓冲区满后，旧日志会被丢弃

基础配置示例

<appender name="emailAppender" class="ch.qos.logback.classic.net.SMTPAppender">
    <smtpHost>smtp.example.com</smtpHost>
    <to>dev-team@example.com</to>
    <to>ops@example.com</to>
    <from>app-logger@example.com</from>
    <subject>BAELDUNG: %logger{20} - %msg</subject>
    <layout class="ch.qos.logback.classic.PatternLayout">
        <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{35} - %msg%n</pattern>
    </layout>
</appender>

同时，别忘了将其注册到 root logger：

<root level="INFO">
    <appender-ref ref="emailAppender"/>
</root>

效果说明

一旦发生 ERROR 日志，系统会：

将缓冲区中所有日志（最多 256 条）打包
按 PatternLayout 格式化内容
发送邮件给所有 <to> 指定的收件人

你也可以将 PatternLayout 替换为 HTMLLayout，让邮件内容更易读：

<layout class="ch.qos.logback.classic.html.HTMLLayout"/>

效果如下图所示：

4. 自定义缓冲区大小

默认 256 条可能太多或太少。我们可以通过 cyclicBufferTracker 自定义缓冲区大小。

例如，只保留最近 5 条日志：

<appender name="emailAppender" class="ch.qos.logback.classic.net.SMTPAppender">
    <smtpHost>smtp.example.com</smtpHost>
    <to>dev-team@example.com</to>
    <from>app-logger@example.com</from>
    <subject>BAELDUNG: %logger{20} - %msg</subject>
    <layout class="ch.qos.logback.classic.html.HTMLLayout"/>
    <cyclicBufferTracker class="ch.qos.logback.core.spi.CyclicBufferTracker"> 
        <bufferSize>5</bufferSize>
    </cyclicBufferTracker>
</appender>

✅ 实际场景建议设置为 10~50 条，既能看清上下文，又不至于邮件过长。

5. 使用 Gmail 作为 SMTP 服务

Gmail 要求安全连接，支持 SSL 或 STARTTLS。生产环境推荐使用 STARTTLS。

配置要点

SMTP 服务器：smtp.gmail.com
端口：587
启用 STARTTLS
提供用户名和密码（建议使用 App Password）

完整配置

<appender name="emailAppender" class="ch.qos.logback.classic.net.SMTPAppender">
    <smtpHost>smtp.gmail.com</smtpHost>
    <smtpPort>587</smtpPort>
    <STARTTLS>true</STARTTLS>
    <asynchronousSending>false</asynchronousSending>
    <username>john.doe@gmail.com</username>
    <password>your-app-password</password>
    <to>team-alerts@example.com</to>
    <from>john.doe@gmail.com</from>
    <subject>BAELDUNG: %logger{20} - %msg</subject>
    <layout class="ch.qos.logback.classic.html.HTMLLayout"/>
</appender>

⚠️ 注意事项：

asynchronousSending="false"：确保邮件发送成功前不丢失日志（调试时建议关闭异步）
Gmail 账户需开启“两步验证”，并生成专用的 App Password
如果使用公司 Gmail Workspace，可能需要管理员开启 SMTP 权限

6. 总结

本文介绍了如何使用 Logback 的 SMTPAppender 实现错误日志邮件告警，核心点包括：

✅ 添加 angus-mail 和 angus-activation 依赖
✅ 正确配置 SMTP 参数与缓冲区大小
✅ 支持 HTML 格式美化邮件内容
✅ 兼容 Gmail 等主流邮件服务

这套方案简单、稳定，适合中小项目快速接入。对于大型系统，建议结合 ELK + 告警平台，但 Logback 邮件仍可作为兜底机制。

所有示例代码均已上传至 GitHub：https://github.com/eugenp/tutorials/tree/master/logging-modules/logback

Persistence

REST

Security