OneUptime 自托管 SendGrid Inbound Email 集成指南构建「入站邮件监控器」的完整 Webhook 链路【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本文面向自托管 OneUptime 的运维与开发者系统讲解如何借助 SendGrid Inbound Parse 将「发往唯一监控器专属邮箱地址的邮件」转化为告警的创建与解除动作。读完本文你将掌握入站邮件监控器的整体工作流程、网络拓扑与端口要求、DNS MX 与 SendGrid 控制台的完整配置步骤、Docker Compose 与 Kubernetes Helm 两种环境变量配置方式以及从 Webhook 入口到队列处理、Worker 心跳轮询的源码级实现原理。入站邮件监控器的工作原理OneUptime 的**入站邮件监控器Incoming Email Monitor**允许你通过邮件来触发监控器的告警状态变化当一封邮件发送到监控器专属的唯一地址时OneUptime 会按你配置的判定条件创建或解除告警。整体工作流程如下你在 OneUptime 中创建一个入站邮件监控器OneUptime 为这个监控器生成一个唯一的专属邮箱地址例如monitor-abc123inbound.yourdomain.com当有邮件发送到该地址时SendGrid 接收邮件并通过 Webhook 转发给 OneUptimeOneUptime 根据你配置的判定条件如发件人、主题、正文、接收时间等创建或解除告警。需要特别说明的是SendGrid 负责接收邮件通过你的域名 MX 记录OneUptime 本身不需要任何入站 SMTP 监听服务它只以 HTTPS Webhook 的形式被动接收 SendGrid 推送的已解析邮件内容。前置条件在开始配置前请确认满足以下条件一个有权访问Inbound Parse功能的 SendGrid 账户一个你拥有完全控制权、可以修改 DNS 记录的域名一个公网可达的 HTTPS 端点用于将 SendGrid 的 Webhook 转发到 OneUptime。网络拓扑与端口要求Inbound Parse 需要的是 SendGrid 主动发起连接到 OneUptime因此仅允许出站访问互联网是不够的——OneUptime 服务器必须能够接收来自 SendGrid 的入站 HTTPS 请求。完整的网络流向如下方向目标协议 / 端口用途SendGrid → OneUptimehttps://your-oneuptime-domain.com/incoming-email/sendgrid/YOUR_SECRETHTTPS / TCP 443以 Multipart-POST 形式投递已解析的邮件内容发件方邮件服务器 → SendGridmx.sendgrid.net通过你接收域名的公共 MX 记录SMTP / TCP 25由 SendGrid 接收邮件而非 OneUptime 服务器OneUptime → SendGrid仅当另行配置了邮件发送时api.sendgrid.comHTTPS / TCP 443通过 Mail Send API 发送通知公网暴露与反向代理为 Webhook 主机名发布 DNS 记录并使用公网可信证书例如 Lets Encrypt。私有部署时可以只通过一个能内部访问 OneUptime 的公网反向代理或网关仅暴露 Webhook 路径。代理转发时必须保持路径、密钥值、Content-Type 及 Multipart 内容不变。允许 POST 请求且不得要求交互式登录或浏览器验证如人机校验。OneUptime 不需要入站 SMTP 监听器。接收域名必须属于 SendGrid 的已验证域名authenticated domain否则无法使用 Inbound Parse。Webhook 密钥Secret与安全将INBOUND_EMAIL_WEBHOOK_SECRET设置为一个强随机值并用它替换 URL 中的YOUR_SECRET。最后一个路径段是必需的OneUptime 会将其与配置值做比对若环境变量的值为空则会跳过该校验。从源码看该校验发生在 IncomingEmail.ts 中路由定义为POST /incoming-email/sendgrid/:secret随后调用 provider 的validateWebhook而 SendGridInboundProvider.ts 中的实现是——若配置了webhookSecret则要求路径中的pathSecret与之一致否则未配置密钥时接受所有请求。因此请保持完整 URL 与监控器专属邮箱地址的保密性包括代理日志中也不要泄露OneUptime 目前不校验SendGrid 的签名 Inbound Parse 头或 OAuth Token如确有需要应由前置网关在转发前按 SendGrid 的安全文档自行校验。关于 IP 白名单的说明SendGrid 不提供可靠的 Inbound Parse 来源 IP 静态列表。mx.sendgrid.net的投递 IP 与 DNS 结果不能作为 Webhook 放行白名单。请遵循 SendGrid 官方文档中关于 Webhook / Inbound Parse 防火墙配置的建议。与邮件发送Mail Send解耦Inbound Parse 与邮件发送是相互独立的接收邮件OneUptime 无需调用 SendGrid API发送通知若用 SendGrid 发送通知需放行 DNS 与到api.sendgrid.com的出站 HTTPSMail Send 提交任务时不需要入站回执使用 SMTP 发送放行 OneUptime 中配置的 SMTP 服务器与端口即可。验收验证验证时请检查公共 MX 记录、向测试监控器发送一封真实邮件、确认 Webhook 已收到请求并确认对应告警被创建或解除。空 POST 或发送测试邮件本身都不能证明 Inbound Parse 链路是通的——必须看到真实邮件完整走完整个链路。配置步骤步骤 1选择入站邮件专用域名你需要一个仅用于入站邮件的子域名建议使用inbound.yourdomain.comemail.yourdomain.commonitor.yourdomain.com独立子域名的好处是 MX 记录只影响入站邮件不影响主域名的正常收发。步骤 2配置 DNS MX 记录在 DNS 配置中为入站子域名添加 MX 记录将邮件转发给 SendGrid类型主机/名称优先级值MXinbound10mx.sendgrid.net提示DNS 变更可能需要最长 48 小时才能全球生效配置后请耐心等待并验证。步骤 3配置 SendGrid Inbound Parse登录 SendGrid 控制台导航到Settings Inbound Parse点击Host URL 添加Add Host URL按以下内容配置字段值接收域名Domain你的入站子域名例如inbound.yourdomain.com目标 URLDestination URLhttps://your-oneuptime-domain.com/incoming-email/sendgrid/YOUR_SECRET点击添加Add保存。步骤 4配置 OneUptime 环境变量Docker Compose 方式在config.env文件中添加以下环境变量# 入站邮件配置 INBOUND_EMAIL_PROVIDERSendGrid INBOUND_EMAIL_DOMAINinbound.yourdomain.com INBOUND_EMAIL_WEBHOOK_SECRETreplace-with-a-strong-random-secretKubernetesHelm方式inboundEmail: provider: SendGrid domain: inbound.yourdomain.com webhookSecret: replace-with-a-strong-random-secret目标 URL 中使用的密钥值必须与上述webhookSecret完全一致。配置修改后请重启 OneUptime使环境变量生效。从配置解析源码看EnvironmentConfig.ts 中定义了InboundEmailProviderType枚举当前值为SendGrid并依次读取INBOUND_EMAIL_PROVIDER默认SendGrid、INBOUND_EMAIL_DOMAIN必填未设置则入站邮件功能未配置与INBOUND_EMAIL_WEBHOOK_SECRET可选用于路径密钥比对。InboundEmailProviderFactory.isConfigured()的实现即Boolean(InboundEmailDomain)因此只要未设置INBOUND_EMAIL_DOMAINWebhook 入口就会返回 Inbound email is not configured 错误。步骤 5创建入站邮件监控器登录 OneUptime 控制台导航到Monitors Create Monitor选择Incoming Email入站邮件作为监控器类型配置监控器与判定条件例如对发件人、主题、正文、接收时间等条件进行匹配点击Create完成创建。创建完成后页面会显示该监控器专属的唯一邮箱地址。环境变量参考变量描述是否必需默认值INBOUND_EMAIL_PROVIDER使用的入站邮件提供商是SendGrid源码默认值INBOUND_EMAIL_DOMAIN配置为入站邮件的子域名是-INBOUND_EMAIL_WEBHOOK_SECRET与 URL 最后一段/incoming-email/sendgrid/YOUR_SECRET比对公网端点务必配置空值将跳过校验推荐-源码视角一封入站邮件的完整处理链路了解底层实现有助于排查问题与二次开发。以下链路均在当前仓库源码中可查Webhook 入口IncomingEmail.ts 注册POST /incoming-email/sendgrid/:secret先经MultipartFormDataMiddleware解析 multipart/form-data再校验INBOUND_EMAIL_DOMAIN是否已配置随后调用 provider 完成密钥校验与邮件解析。邮件解析SendGridInboundProvider.ts 从 SendGrid Webhook 的from、to、subject、text、html、headers、attachments、attachment-info等字段中提取发件人、收件人、主题、纯文本/HTML 正文、头信息与附件元数据封装为 ParsedInboundEmail 结构。监控器密钥提取provider 用正则^monitor-([a-zA-Z0-9-]){inboundDomain}$从收件地址中提取监控器专属密钥与生成地址的方法generateMonitorEmailAddress(secretKey)返回monitor-{secretKey}{inboundDomain}严格对应。若无法提取密钥Webhook 会直接报错 Invalid monitor email address。异步入队TelemetryQueueService.ts 的addIncomingEmailJob将密钥、发件人、收件人、主题、正文、头与附件打包为jobType: incoming-email的任务以incoming-email-{secretKey}-{timestamp}-{id}为任务 ID 投入 Telemetry 队列Webhook 随即返回202 Accepted避免在请求线程中做重活。队列消费与监控器匹配ProcessProbeIngest.ts 中的processIncomingEmailFromQueue按incomingEmailSecretKey与monitorType: IncomingEmail查找对应监控器对收件人地址中的密钥做脱敏处理后构造 IncomingEmailMonitorRequest写入监控器的incomingEmailMonitorRequest字段。Worker 轮询判定CheckOnlineStatus.ts 每 30 秒执行一次监控器扫描IncomingEmailMonitor:CheckOnlineStatus为所有入站邮件监控器刷新心跳时间戳incomingEmailMonitorHeartbeatCheckedAt并仅对判定条件中包含CheckOn.EmailReceivedAt邮件接收时间步骤的监控器触发monitorResource评估从而创建或解除对应告警。这套「Webhook 快速接收 队列异步处理 Worker 周期性评估」的分层设计保证了高并发邮件涌入时 Webhook 入口的响应速度也让告警判定逻辑可以复用通用监控评估管线。故障排查邮件未被接收检查 DNS 传播情况dig MX inbound.yourdomain.com应返回mx.sendgrid.net。如果返回为空或指向其他服务器说明 MX 记录尚未生效或配置有误。核对 SendGrid Inbound Parse 设置登录 SendGrid 控制台进入Settings Inbound Parse核对接收域名与 Webhook URL 是否正确特别注意 URL 最后一段的密钥是否与INBOUND_EMAIL_WEBHOOK_SECRET完全一致以及接收域名是否已完成 SendGrid 域名认证。检查 OneUptime 日志查看 OneUptime 的详细错误日志Webhook 入口会记录收到的请求体键名、解析出的发件人/收件人/主题、提取的密钥及队列投递状态。若日志提示 Inbound email is not configured请确认已设置INBOUND_EMAIL_DOMAIN并重启服务。支持如果 SendGrid Inbound Email 集成仍无法正常工作复查上文「故障排查」章节的各个步骤检查 OneUptime 日志中的详细错误信息联系 OneUptime 支持邮箱hellooneuptime.com。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考