OneUptime 传入电子邮件监控器（Incoming Email Monitor）实战指南：用邮件驱动告警创建与解除

OneUptime 传入电子邮件监控器Incoming Email Monitor实战指南用邮件驱动告警创建与解除【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime 的Incoming Email Monitor传入电子邮件监控器允许你为每个监控器生成一个专属的接收邮箱地址任何发往该地址的邮件都会被解析并按你配置的判定条件自动创建或解除告警。本文将系统讲解其工作原理、创建步骤、六类可用过滤字段与全部过滤条件、五种典型配置场景、模板变量、自托管时的 SendGrid 收件链路与环境变量配置并结合仓库源码剖析底层判定逻辑帮助你快速把基于邮件的第三方告警体系接入 OneUptime 的事件管理流程。工作原理邮件如何变成告警传入电子邮件监控器的工作流程只有三步核心思想是以邮件为信令signal生成专属地址当你创建 Incoming Email Monitor 时OneUptime 会为该监控器生成一个独一无二的接收邮箱地址解析与判定任何发往该地址的邮件都会被接收并与你配置的 Alert Creation Criteria告警创建条件和 Alert Resolution Criteria告警解除条件逐一比对自动处置根据判定结果OneUptime 创建新告警或解除当前处于激活状态的既有告警。这是把旧式邮件告警体系接入 OneUptime 事件管理工作流的强力桥梁——尤其适合那些没有现代 API、只能发邮件的遗留系统。从源码看邮件的解析与判定是异步进行的。服务端在收到 webhook 后将邮件结构化封装为IncomingEmailMonitorRequest定义见 Common/Types/Monitor/IncomingEmailMonitor/IncomingEmailMonitorRequest.ts其中携带emailFrom、emailTo、emailSubject、emailBody、emailBodyHtml、emailHeaders、emailReceivedAt、checkedAt、attachments等字段随后 MonitorCriteriaEvaluator.ts 在监控器类型为MonitorType.IncomingEmail时把该请求交给IncomingEmailCriteria.isMonitorInstanceCriteriaFilterMet()逐条评估用户配置的过滤条件详见下文过滤条件一节。创建传入电子邮件监控器在 OneUptime 仪表盘Dashboard中按以下步骤创建进入Monitors监控器页面点击Create Monitor创建监控器监控器类型选择Incoming Email传入电子邮件配置监控器基本信息Name名称给监控器起一个描述性名称Description描述说明该监控器的用途配置Alert Creation Criteria告警创建条件——满足哪些条件时创建告警配置Alert Resolution Criteria告警解除条件——满足哪些条件时解除告警点击Create创建。创建完成后该监控器的专属邮箱地址会显示在监控器详情页中你可以直接复制并配置到外部系统中让它们向该地址发送邮件。地址格式每个传入电子邮件监控器都会获得一个符合如下格式的专属地址monitor-{secret-key}{inbound-domain}例如monitor-abc123def456inbound.yourdomain.com地址中的monitor-前缀、{secret-key}密钥段与{inbound-domain}入站域名结构在 SendGridInboundProvider.ts 中有精确的源码实现extractSecretKeyFromEmail()使用正则^monitor-([a-zA-Z0-9-])...不区分大小写从To地址中提取密钥generateMonitorEmailAddress(secretKey)则用monitor-${secretKey}${inboundDomain}拼回完整地址。密钥本质上是一个随机对象 IDUUID 形态字符串具体形如monitor-{uuid}inbound.example.com。该地址本身即身份凭据仓库中的密钥脱敏逻辑MonitorPayloadRedaction.ts专门对monitor-{secretKey}{inboundDomain}形态的地址进行扫描遮蔽防止密钥落入日志等出口管道这也再次印证了地址必须像密码一样保密。创建后开箱即得的默认条件新建的传入电子邮件监控器会自带两个读取邮件正文Email Body的默认判定条件条件过滤类型过滤条件值作用Offline离线Email BodyContains包含error将监控器标记为离线并打开一个告警事件Online在线Email BodyNot Contains不包含error将监控器标记为在线这套默认配置覆盖了最常见的场景某个任务或第三方工具会把执行结果通过邮件发送出来——正文包含error的邮件让监控器变红触发告警下一条不含error的邮件又让监控器恢复绿色解除告警。所有字符串匹配均不区分大小写因此Error、ERROR都会命中。你可以把默认值改成发送方真正会写的文案例如FAILED、exit code 1等。需要注意的是这些默认条件不是静默检测dead man switch——只有当邮件真正送达时读取主题、发件人、正文或收件人的条件才会被评估其余时间什么都不会触发。如果想对邮件长时间未到发出告警需要额外添加Email Received/Not Received In Minutes类型的条件见下文示例三。六种可用的过滤字段Filter Types你可以基于邮件的以下六个字段维度来构建判定条件过滤类型说明Email Subject入站邮件的主题行Email From发件人邮箱地址Email Body邮件的纯文本正文内容Email To收件人邮箱地址Email Received基于时间的条件用于判断邮件接收时间JavaScript Expression一段必须求值为 true 的自定义 JavaScript 表达式在 CriteriaFilter.ts 的CheckOn枚举中对应值为EmailSubject Email Subject、EmailFrom Email From Address、EmailBody Email Body、EmailTo Email To Address、EmailReceivedAt Email Received与界面展示名称完全一致。邮件正文只用纯文本正文匹配基于邮件的纯文本版本HTML 格式会被剥离。对应源码中SendGrid 解析器取 webhook 表单里的text字段作为正文SendGridInboundProvider.tshtml字段仅作为bodyHtml附加信息保留在请求结构中。因此配置正文匹配时应以纯文本内容为准。过滤条件Filter Conditions详解不同过滤类型支持不同的条件运算。下面按类别完整列出。字符串类条件主题、发件人、正文、收件人过滤条件说明示例Contains字段包含指定文本主题包含 CRITICALNot Contains字段不包含指定文本主题不含 TESTEquals字段与指定文本完全相等发件人等于 alertsservice.comNot Equals字段与指定文本不相等主题不等于 OKStarts With字段以指定文本开头主题以 [ALERT] 开头Ends With字段以指定文本结尾主题以 - Production 结尾Is Empty字段为空或全为空白正文为空Is Not Empty字段有内容主题非空这些字符串条件的底层实现在 IncomingEmailCriteria.ts 的evaluateStringCriteria()方法中。关键实现事实大小写不敏感所有比较都先做toLowerCase()再执行includes//startsWith/endsWith与文档声明一致空值处理IsEmpty判断!fieldValue || fieldValue.trim() 即空白字符串也视为空返回值即判定理由每条条件命中后返回类似Email subject contains CRITICAL.的人类可读字符串这些文本会进入评估摘要evaluation summary供你在监控器详情中回看这条告警为什么被触发。时间类条件Email Received过滤条件说明示例Received In Minutes邮件在 X 分钟内被收到邮件在 30 分钟内被收到Not Received In MinutesX 分钟内没有收到任何邮件60 分钟内未收到邮件对应源码枚举值为RecievedInMinutes Recieved In Minutes与NotRecievedInMinutes Not Recieved In Minutes见 CriteriaFilter.ts。判定逻辑在 IncomingEmailCriteria.ts计算emailReceivedAt最近一封邮件的接收时间与checkedAt或当前时间的分钟差differenceInMinutesRecievedInMinutes当differenceInMinutes value时命中返回Email received in X minutes. It was received N minutes ago.NotRecievedInMinutes当differenceInMinutes value时命中返回Email not received in X minutes. It was received N minutes ago.配置值会被parseInt解析为数字解析失败则视为不命中。JavaScript 表达式条件过滤条件说明Evaluates To True表达式求值返回真值truthy需要特别注意表达式运行在隔离环境isolated environment中邮件字段不会被注入为变量因此表达式无法读取触发评估的那封邮件的主题、发件人、正文或收件人。要基于邮件内容做匹配请使用Email Subject、Email From、Email Body、Email To四类字段型条件。典型配置示例示例一根据关键邮件的主题创建与解除告警告警创建条件Email SubjectContainsCRITICAL或 Email SubjectContainsALERT或 Email SubjectContainsERROR告警解除条件Email SubjectContainsRESOLVED或 Email SubjectContainsOK或 Email SubjectContainsRECOVERED同一条件组内的多个子条件默认按或OR组合任一命中即触发跨组创建组与解除组则是相互独立的评估逻辑。示例二盯住指定发件人告警创建条件Email FromEqualsmonitoringlegacy-system.com且ANDEmail SubjectContainsFailed告警解除条件Email FromEqualsmonitoringlegacy-system.com且ANDEmail SubjectContainsSuccess当需要在同一条件组内实现并且AND语义时将多个子条件加入同一组即可。示例三心跳监控没有邮件 告警告警创建条件Email ReceivedNot Received In Minutes值为60如果 60 分钟内没有收到任何邮件就触发告警——非常适合监控必须按时发送完成邮件的定时任务cron job或批处理流程。告警解除条件Email ReceivedReceived In Minutes值为5只要收到一封邮件就立即解除告警。注意Received In Minutes判定的是最近一封邮件的接收时间距现在是否在阈值分钟之内differenceInMinutes value因此一旦新邮件到达该条件即满足。典型应用场景集成遗留系统很多老系统只支持邮件告警。利用 Incoming Email Monitor 可以把邮件告警转化为 OneUptime 告警事件收到恢复邮件时自动解除事件集中管理多个遗留系统的告警流。监控第三方服务接入一切能发通知邮件的服务云厂商告警AWS、GCP、Azure 的通知邮件安全扫描工具备份完成通知SSL 证书到期告警。监控定时任务完成邮件未按时到达即触发告警通过错误通知邮件追踪任务失败监控数据管道的完成状态。多供应商告警聚合通过邮件接入 Nagios、Zabbix 等工具的告警在 OneUptime 中统一事件管理流程让所有告警拥有单一事实来源single source of truth。事件模板变量配置告警事件模板Incident Templates时可以直接引用以下从入站邮件中提取的变量变量说明{{emailSubject}}收到的邮件主题{{emailFrom}}发件人邮箱地址{{emailTo}}收件人邮箱地址{{emailBody}}邮件的纯文本正文{{emailReceivedAt}}邮件接收时间这些变量与请求结构IncomingEmailMonitorRequest的字段一一对应emailSubject、emailFrom、emailTo、emailBody、emailReceivedAt使事件描述可以自动带上触发邮件的完整上下文。监控器摘要视图Monitor Summary创建监控器后其摘要页面会展示最近一封入站邮件的关键信息Last Email Received At最近一封邮件的接收时间From最近一封邮件的发件人Subject最近一封邮件的主题行Email Headers最近一封邮件的完整邮件头可展开查看Email Body最近一封邮件的正文内容可展开查看。这些信息对排查邮件是否送达、条件为何未命中非常有用——也对应源码中emailHeaders与emailBody等字段被完整保留在请求结构中的设计。自托管配置接入 SendGrid Inbound Parse如果你在自托管 OneUptime必须配置入站邮件提供商Inbound Email Provider。当前仓库支持SendGrid Inbound Parse完整英文版配置指南见 SendGrid Inbound Email Integration。网络访问要点SendGrid Inbound Parse 需要主动发起连接到你的 OneUptime 实例因此只允许 OneUptime 出网是不够的。关键通路如下方向目标协议/端口用途SendGrid → OneUptimehttps://your-oneuptime-domain.com/incoming-email/sendgrid/YOUR_SECRETHTTPS / TCP 443以 multipart POST 形式投递解析后的邮件发件服务器 → SendGridmx.sendgrid.net由入站域名的公共 MX 记录决定SMTP / TCP 25在 SendGrid 侧接收邮件不直连你的 OneUptimeOneUptime → SendGridapi.sendgrid.com仅当另行配置 SendGrid 作为发件服务时HTTPS / TCP 443通过 Mail Send API 发送通知邮件Webhook 主机名需有公共 DNS 与受信证书私有化部署可通过公共反向代理仅暴露该 webhook 路径但要保留路径、密钥、Content-Type 与 multipart 请求体且不能有交互式登录或浏览器验证挑战。OneUptime 服务器本身不需要监听 SMTP 端口。配置步骤摘要选择入站域名推荐使用专用子域名如inbound.yourdomain.com、email.yourdomain.com、monitor.yourdomain.com配置 DNS MX 记录类型主机/名称优先级值MXinbound10mx.sendgrid.net即inbound.example.com. IN MX 10 mx.sendgrid.net.。DNS 变更最长可能需要 48 小时生效通常几小时内完成在 SendGrid 中认证该域名Settings Sender Authentication Authenticate Your Domain并按提示添加 DKIM 的 CNAME 记录配置 Inbound ParseSettings Inbound Parse Add Host URL字段值Receiving Domain你的入站子域名如inbound.yourdomain.comDestination URLhttps://your-oneuptime-domain.com/incoming-email/sendgrid/YOUR_SECRETCheck incoming emails for spam可选按需开启Send raw, full MIME message不勾选无需POST the raw, full MIME message不勾选无需配置 OneUptime 环境变量见下节创建 Incoming Email Monitor步骤见上文创建一节端到端测试从仪表盘复制监控器地址发送一封主题命中创建条件的测试邮件然后在监控器摘要页确认邮件已收到、告警已创建。环境变量参考源码层面入站邮件相关配置集中定义在 EnvironmentConfig.ts由 InboundEmailProviderFactory.ts 读取并实例化对应提供商变量说明是否必填默认值INBOUND_EMAIL_PROVIDER入站邮件提供商当前仅支持SendGrid是SendGridINBOUND_EMAIL_DOMAIN配置的入站子域名是无INBOUND_EMAIL_WEBHOOK_SECRET与 webhook URL 最后一段比较/incoming-email/sendgrid/YOUR_SECRET公网端点建议配置置空则跳过校验推荐无Docker Compose 部署时在config.env中加入# Inbound Email Configuration INBOUND_EMAIL_PROVIDERSendGrid INBOUND_EMAIL_DOMAINinbound.yourdomain.com INBOUND_EMAIL_WEBHOOK_SECRETreplace-with-a-strong-random-secretKubernetesHelm部署时在values.yaml中加入inboundEmail: provider: SendGrid domain: inbound.yourdomain.com webhookSecret: replace-with-a-strong-random-secretINBOUND_EMAIL_WEBHOOK_SECRET必须与 Step 4 中 Destination URL 末尾的YOUR_SECRET保持一致修改后需重启 OneUptime 服务。当配置了密钥时SendGridInboundProvider.ts 的validateWebhook()会比较 URL 路径中的 secret 与配置值未配置则放行所有请求此时 webhook URL 本身即秘密。另外SendGrid Inbound Parse 默认不提供 webhook 签名仓库当前也未校验其签名头或 OAuth token——若需要此类机制应在转发给 OneUptime 之前由网关完成校验。入站邮件解析的底层细节SendGrid 会把邮件以multipart/form-data表单形式 POST 到 OneUptime字段包括from、to、subject、text、html、headers、envelope、attachments、attachment-info等见 SendGridInboundProvider.ts 的注释。解析器据此提取出from/to通过正则提取尖括号内的地址兼容Name userdomain.com与userdomain.com等格式并统一转小写、去除首尾空白subject原样保留body取text字段纯文本bodyHtml取html字段headers按行拆分、以第一个冒号分隔成键值对象attachments解析附件的文件名、Content-Type 与大小。这些字段最终成为IncomingEmailMonitorRequest驱动后续的条件评估。注意事项邮箱地址安全监控器邮箱地址内含机密密钥请像对待密码一样对待它不要公开分享邮件大小过大尤其带大附件的邮件可能被邮件服务商截断或拒绝处理延迟邮件是异步处理的从发送邮件到告警创建之间可能存在数秒延迟大小写不敏感所有字符串比较Contains、Equals 等均不区分大小写纯文本正文正文条件只评估邮件的纯文本版本HTML 格式会被忽略。故障排查收不到邮件确认邮箱地址拼写正确检查是否有笔误检查邮件是否被垃圾邮件过滤器拦截确认入站邮件提供商配置正确参考上文的 DNS 与 Inbound Parse 校验可用dig MX inbound.yourdomain.com确认 MX 记录是否返回mx.sendgrid.net查看 OneUptime 日志中是否有错误信息关注 webhook 请求是否到达、Telemetry / ProbeIngest 相关日志。告警未被创建确认你的条件与邮件内容相匹配检查监控器是否处于禁用状态在监控器详情中回看评估日志evaluation logs与摘要确认邮件是否收到、每条条件是否命中先用精确字符串匹配做测试再过渡到模式匹配。告警未被解除确认解除条件与恢复邮件内容相匹配确保确实存在一个处于激活状态的告警可以被解除确认恢复邮件发送到了同一个监控器地址地址错误则无法触发评估。结语Incoming Email Monitor 是 OneUptime 把邮件即信令落地的功能通过monitor-{secret-key}{inbound-domain}专属地址与完整的字符串、时间、表达式判定体系它能把遗留系统、第三方服务、定时任务乃至多供应商告警全部收敛进 OneUptime 的事件管理流程。自托管场景下配合 SendGrid Inbound Parse 与INBOUND_EMAIL_*环境变量即可在数小时内完成端到端接通而源码中对大小写不敏感匹配、纯文本正文、时间差判定与密钥脱敏的严谨处理则为这条链路提供了可验证的可靠性保障。想要深入源码的读者可以从 IncomingEmailCriteria.ts 与 SendGridInboundProvider.ts 两个文件开始。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考