OneUptime 自托管指南：使用 SendGrid Inbound Parse 配置邮件入站监控（Incoming Email Monitor）

OneUptime 自托管指南使用 SendGrid Inbound Parse 配置邮件入站监控Incoming Email Monitor【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime 的**邮件入站监控Incoming Email Monitor**允许你基于发送到监控器专属唯一邮箱地址的邮件来创建和解决告警从而将遗留系统、仅支持邮件告警的第三方工具无缝接入现代可观测性平台。本文基于 OneUptime 官方自托管文档完整讲解 SendGrid Inbound Parse 的接入步骤、DNS 配置、环境变量、告警条件设计与安全实践并结合仓库源码如 IncomingEmail.ts 与 IncomingEmailCriteria.ts剖析其底层处理链路帮助你在一小时内完成邮件 → 告警全链路的搭建与验证。前置条件Prerequisites开始配置前请确认你具备以下条件一个启用了Inbound Parse功能的 SendGrid 账号一个你拥有完整 DNS 管理权限的域名一个公网可达的 HTTPS 端点用于将 SendGrid 的 webhook 转发到你的 OneUptime 自托管实例。需要特别强调邮件入站是一个入站链路与 OneUptime 的出站邮件发送完全独立。如果你尚未配置过 OneUptime 的邮件发送功能本节只需要满足上述三个条件即可。网络访问Network AccessInbound Parse 要求SendGrid 主动向 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而不是你的 OneUptime 服务器OneUptime → SendGrid仅当另行配置了以 SendGrid 作为发信商api.sendgrid.comHTTPS / TCP 443通过 Mail Send API 发送通知邮件关键网络注意事项webhook 主机名必须可公开解析为其发布公网 DNS并部署被公共客户端信任的证书含完整证书链。私有部署的暴露方式如果 OneUptime 位于内网可以让公网反向代理或网关只把/incoming-email/sendgrid/*这一个路径暴露出去转发到内网 OneUptime。请确保代理完整保留路径、secret、Content-Type 与 multipart 请求体。禁止交互式认证webhook 路径必须允许 POST 直接通过不能有登录跳转或浏览器验证码挑战。OneUptime 不需要 SMTP 入站监听邮件由 SendGrid 代收OneUptime 只接收 HTTP webhook。详见 SendGrid Inbound Parse 官方文档。不要固化 SendGrid 的 IP 白名单SendGrid 并未提供 Inbound Parse 的可靠静态源 IP 列表。它的发件 IP 以及mx.sendgrid.net解析出的地址都不是 webhook 白名单请遵循其 防火墙配置指南。验证入站≠验证出站一个空 POST 或一次成功的出站邮件测试不能证明 Inbound Parse 链路通畅。正确验证方式是检查公网 MX 记录 → 给测试监控器发邮件 → 确认 webhook 到达 OneUptime 且匹配的告警被创建或解决。Webhook Secret 的安全语义将INBOUND_EMAIL_WEBHOOK_SECRET设置为一个高强度的随机值并用它替换 URL 中的YOUR_SECRET。路由要求最后一个路径段必须存在OneUptime 在配置了 secret 时会比对它的值如果该变量留空则跳过校验。请保持完整 URL 与监控器邮箱地址的私密性包括不要写入代理日志。需要明确一点从源码看OneUptime 目前不校验SendGrid 的签名 Inbound Parse 请求头或 OAuth token。若你需要这些机制应在转发给 OneUptime 之前由网关完成校验参考 SendGrid 的 webhook 安全文档。工作原理How It Works邮件入站监控的完整链路如下你在 OneUptime 中创建一个邮件入站监控器Incoming Email MonitorOneUptime 为该监控器生成一个唯一邮箱地址例如monitor-abc123inbound.yourdomain.com当有人向该地址发邮件时SendGrid 先代收邮件再通过 webhook 转发给 OneUptimeOneUptime 依据你配置的告警条件评估邮件内容决定创建还是解决告警。从源码层面看这条链路有清晰的实现支撑Webhook 入口IncomingEmail.ts 定义了POST /incoming-email/sendgrid/:secret路由先由MultipartFormDataMiddleware解析 multipart 表单再依次完成配置检查 → secret 校验 → 邮件解析 → 从收件地址提取 secretKey → 入队异步处理五个步骤Provider 工厂InboundEmailProviderFactory.ts 根据INBOUND_EMAIL_PROVIDER环境变量选择具体的 Provider目前支持SendGrid并为未知 Provider 抛出BadDataException异步队列解析出的邮件from / to / subject / body / bodyHtml / headers / attachments被封装为IncomingEmailMonitorRequest见 IncomingEmailMonitorRequest.ts通过 Telemetry 队列异步处理入口立即返回 HTTP202 Accepted。也就是说webhook 收到邮件后会立刻应答 202实际告警评估在后台队列中完成——这对 SendGrid 的投递重试机制非常友好。配置步骤Setup Instructions第 1 步选择入站邮件域名你需要一个专门接收入站邮件的子域名OneUptime 建议使用类似inbound.yourdomain.comemail.yourdomain.commonitor.yourdomain.com该子域名将仅用于 OneUptime 监控器的邮件避免与业务邮件混用。第 2 步配置 DNS MX 记录在 DNS 中添加一条 MX 记录将入站子域名的邮件路由到 SendGrid类型主机/名称优先级值MXinbound10mx.sendgrid.net示例如果你的域名是example.com使用inbound.example.cominbound.example.com. IN MX 10 mx.sendgrid.net.注意DNS 变更最长可能需要 48 小时才能在全球传播但通常几小时内即可生效。第 3 步在 SendGrid 中验证域名接收域名必须属于你在 SendGrid 中已验证authenticated的域名之一登录 SendGrid 控制台进入设置Settings发件人认证Sender Authentication点击验证你的域名Authenticate Your Domain按提示添加所需的 DNS 记录DKIM 的 CNAME 记录。第 4 步配置 SendGrid Inbound Parse登录 SendGrid 控制台进入设置SettingsInbound Parse点击添加主机与 URLAdd Host URL按下表配置字段值接收域名Receiving Domain你的入站子域名例如inbound.yourdomain.com目标 URLDestination URLhttps://your-oneuptime-domain.com/incoming-email/sendgrid/YOUR_SECRET检查入站邮件的垃圾邮件Check incoming emails for spam可选——按需开启发送原始完整 MIME 消息Send raw, full MIME message保持不勾选非必需POST 原始完整 MIME 消息POST the raw, full MIME message保持不勾选非必需点击添加Add完成配置。源码提示SendGrid → OneUptime这步之所以使用 multipart/form-data是因为入口路由挂载了MultipartFormDataMiddleware见 IncomingEmail.ts。因此请务必保持请求体为 multipart 格式且目标 URL 中sendgrid之后必须带有 secret 路径段。第 5 步配置 OneUptime 环境变量Docker Compose在config.env文件中添加以下环境变量# Inbound Email Configuration INBOUND_EMAIL_PROVIDERSendGrid INBOUND_EMAIL_DOMAINinbound.yourdomain.com INBOUND_EMAIL_WEBHOOK_SECRETreplace-with-a-strong-random-secretKubernetes 与 Helm在values.yaml中添加inboundEmail: provider: SendGrid domain: inbound.yourdomain.com webhookSecret: replace-with-a-strong-random-secret关键点INBOUND_EMAIL_WEBHOOK_SECRET必须与第 4 步 Destination URL 中的YOUR_SECRET保持一致。修改配置后请重启 OneUptime使环境变量生效。从源码看INBOUND_EMAIL_DOMAIN是是否已配置入站邮件的判定开关InboundEmailProviderFactory.isConfigured()仅检查该变量是否存在见 InboundEmailProviderFactory.ts而INBOUND_EMAIL_PROVIDER决定实例化哪个 Provider 实现。第 6 步创建邮件入站监控器登录 OneUptime 控制台进入监控器Monitors创建监控器Create Monitor选择邮件入站Incoming Email作为监控器类型配置监控器基础信息名称Name给监控器一个描述性名称描述Description说明该监控器的用途。配置告警创建条件Alert Creation Criteria何时创建告警示例邮件主题包含 ALERT 或 CRITICAL配置告警解决条件Alert Resolution Criteria何时解决告警示例邮件主题包含 RESOLVED 或 OK点击创建Create。创建完成后你会在监控器详情页看到该监控器的唯一邮箱地址例如monitor-abc123def456inbound.yourdomain.com。第 7 步测试集成从 OneUptime 控制台复制监控器的邮箱地址向该地址发送一封主题匹配告警条件的测试邮件回到 OneUptime 控制台确认邮件已被接收显示在监控器摘要 Monitor Summary 中如果条件匹配告警已被创建。环境变量参考Environment Variables Reference变量描述必填默认值INBOUND_EMAIL_PROVIDER使用的入站邮件 Provider是-INBOUND_EMAIL_DOMAIN为入站邮件配置的子域名是-INBOUND_EMAIL_WEBHOOK_SECRET与 webhook URL 最后一段/incoming-email/sendgrid/YOUR_SECRET比对的密钥。公网端点必须配置空值会禁用校验推荐-三个变量的作用可从 InboundEmailProviderFactory.ts 与 IncomingEmail.ts 中逐一印证INBOUND_EMAIL_PROVIDER决定走哪个 Provider 分支INBOUND_EMAIL_DOMAIN是isConfigured()的判断依据INBOUND_EMAIL_WEBHOOK_SECRET传入 Provider 后在 webhook 校验阶段与路径中的 secret 比对。支持的邮件匹配条件Supported Email Criteria配置邮件入站监控器时你可以基于以下字段创建条件字段描述可用过滤器邮件主题Email Subject邮件主题行包含、不包含、等于、不等于、以……开头、以……结尾、为空、非空发件人Email From发件人邮箱地址包含、不包含、等于、不等于、以……开头、以……结尾、为空、非空邮件正文Email Body邮件纯文本正文包含、不包含、等于、不等于、以……开头、以……结尾、为空、非空收件人Email To收件人邮箱地址包含、不包含、等于、不等于、以……开头、以……结尾、为空、非空邮件接收时间Email Received距上次收到邮件的时间在 X 分钟内收到Received In Minutes、超过 X 分钟未收到Not Received In Minutes这些条件在源码中有完整实现IncomingEmailCriteria.ts 的isMonitorInstanceCriteriaFilterMet方法会分别针对EmailReceivedAt、EmailSubject、EmailFrom、EmailBody、EmailTo五个CheckOn分支做评估其中字符串类过滤统一走evaluateStringCriteria支持 Contains / NotContains / EqualTo / NotEqualTo / StartsWith / EndsWith / IsEmpty / IsNotEmpty 共 8 种过滤器字符串比较均为不区分大小写。特别值得注意的是邮件接收时间条件该条件由OneUptimeDate.getDifferenceInMinutes(lastEmailTime, checkedAt)计算距上次收件的时间差配合RecievedInMinutes与NotRecievedInMinutes两种过滤类型即可实现心跳heartbeat式监控——这是其他邮件过滤方式无法替代的能力。典型使用场景Example Use Cases遗留系统告警接入许多遗留系统只支持通过邮件发送告警。创建邮件入站监控器可以当遗留系统发送包含[CRITICAL]的邮件时创建 OneUptime 告警当收到[RESOLVED]邮件时自动解决对应告警。第三方服务集成集成一切只能发邮件通知的服务没有 API 集成能力的监控工具云厂商的通知邮件安全扫描工具的输出。邮件心跳Heartbeat via Email使用邮件接收时间条件确保周期性邮件准时到达超过 60 分钟未收到邮件即创建告警非常适合监控批量任务batch jobs或定时任务的完成确认邮件。故障排查Troubleshooting邮件未被接收检查 DNS 传播dig MX inbound.yourdomain.com应当返回mx.sendgrid.net。核对 SendGrid Inbound Parse 设置登录 SendGrid 控制台进入 Settings Inbound Parse确认域名与 webhook URL 均正确。检查 OneUptime 日志在 OneUptime 应用日志Telemetry / ProbeIngest中查找入站邮件 webhook 请求查看是否有错误信息。从源码看入口在入站邮件未配置isConfigured()为 false、secret 校验失败、无法从收件地址提取 secretKey 时都会输出 error 级日志见 IncomingEmail.ts。Webhook 失败检查公网 webhook 路由包含 secret 在内的完整 URL 必须能从互联网到达 OneUptime按网络访问一节测试缺少最后一段 secret 的 URL 不匹配路由因为入口定义为POST /incoming-email/sendgrid/:secret。检查防火墙规则允许 HTTPS POST 直达 webhook 路径不能有登录跳转或浏览器验证码挑战不要将 SendGrid 的发件 IP 作为 webhook 来源白名单。检查 SSL 证书webhook 主机名必须使用有效、公信 CA 签发的证书并包含完整证书链。监控器不创建告警核对条件配置检查告警创建条件是否与邮件内容匹配先用精确字符串测试再使用模式匹配注意字符串比较不区分大小写。检查监控器状态确保监控器未被禁用确认监控器类型是Incoming Email。查看监控器摘要检查邮件是否被接收并处理查看评估日志中条件匹配的详细记录。SendGrid Webhook 投递日志要确认 SendGrid 是否成功发送 webhook遗憾的是SendGrid 对 Inbound Parse不提供详细的投递日志请在你的 OneUptime 服务器日志中查找入站 webhook 请求可使用 RequestBin 之类的工具临时测试 webhook 投递。安全最佳实践Security Best Practices始终使用 HTTPSwebhook 端点必须使用 HTTPS配置 Webhook Secret设置INBOUND_EMAIL_WEBHOOK_SECRET并把它放入 webhook URL例如/incoming-email/sendgrid/your-secret实现额外校验。注意secret 置空会关闭该校验公网部署切勿留空在 SendGrid 验证域名提升邮件投递的安全性与可追溯性限制访问范围只为可信邮件来源创建监控器监控日志定期审查入站邮件日志中的可疑活动。替代 ProviderOneUptime 被设计为支持多种入站邮件 Provider。当前支持情况Provider状态SendGrid已支持Haraka自托管规划中如果你需要其他 Provider 的支持可联系 OneUptime 团队或提交功能请求。小结通过本文的七个步骤你已经可以把任意只能发邮件的系统接入 OneUptime 的告警体系DNS MX 指向 SendGrid → SendGrid Inbound Parse 转发 multipart POST → OneUptime 入口路由/incoming-email/sendgrid/:secret校验并解析 → 异步队列评估五个维度的匹配条件 → 创建或解决告警。其核心价值在于利用邮件这一最通用的接口打通遗留系统与现代化监控平台而邮件接收时间条件又让它成为可靠的批次任务心跳监控方案。配置时请始终牢记三条红线webhook 必须公网可达且带 secret 路径段、不要依赖 SendGrid 静态 IP 白名单、Secret 为空会禁用校验。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考