OneUptime SMTP 配置指南基于 OAuth 2.0 接入 Microsoft 365 与 Google Workspace 发信【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读OneUptime 作为开源的可观测性与告警平台所有通知邮件告警、事件、状态页公告等都依赖邮件传输能力。它支持通过自定义 SMTP 服务器发送邮件并提供用户名密码、OAuth 2.0与**无认证中继服务器**三种认证方式。本篇指南以 OneUptime 官方 SMTP 配置文档为主体结合仓库源码数据模型、服务校验与邮件发送实现完整讲解如何在 OneUptime 中配置 OAuth 2.0 认证分别接入 Microsoft 365/Exchange Online 与 Google Workspace 的企业邮箱发信通道并给出故障排查与安全加固建议。读完本文你将能独立完成两种主流企业邮箱的 OAuth 集成并理解 OneUptime 底层如何获取、缓存与使用 OAuth 令牌。一、OneUptime 的 SMTP 配置模型三种认证方式OneUptime 允许项目使用自定义 SMTP 服务器发送通知邮件支持的认证方式由模型字段authType决定其定义见 SMTPAuthenticationType.ts认证方式枚举值适用场景用户名密码Username and Password默认传统 SMTP 认证兼容绝大多数自建或第三方邮件服务器OAuth 2.0OAuthMicrosoft 365、Google Workspace 等已禁用基础认证的企业环境无认证None不需要认证的中继relay服务器如仅限内网使用的转发网关从源码结构看每个项目可维护多条 SMTP 配置name字段在同一项目内唯一模型定义于 ProjectSmtpConfig.ts通过 CRUD API 端点/smtp-config暴露并受项目级权限控制创建/编辑/删除需要ProjectOwner、ProjectAdmin或对应的Create/Edit/DeleteProjectSMTPConfig权限。除了authType模型还包含transportType传输类型字段定义邮件实际如何投递SMTP默认使用hostnameport建立 SMTP 连接Microsoft Graph不经过 SMTP 协议直接调用 Microsoft Graph REST API 投递适用于租户已禁用 SMTP AUTH 的场景。后续配置 OAuth 时Microsoft 365 走 SMTP 传输 XOAUTH2Google Workspace 同样走 SMTP 传输transportType保持默认的SMTP即可。本文聚焦 SMTP OAuth 的完整链路。二、OAuth 2.0 认证两种授权类型Grant Type企业邮箱尤其 Microsoft 365普遍出于安全考虑关闭了基础认证Basic AuthOAuth 2.0 成为唯一可行的自动化发信方案。OneUptime 支持两种 OAuth 授权类型定义见 OAuthProviderType.ts授权类型枚举值对应 RFC使用方客户端凭据Client CredentialsClient CredentialsRFC 6749Microsoft 365 及大多数 OAuth 2.0 提供商JWT 承载断言JWT BearerJWT BearerRFC 7523Google Workspace 服务账号Service Account两种流程所需的字段均为clientId、clientSecret、tokenUrl、scopeJWT Bearer 额外依赖username要被模拟发信的用户邮箱。OneUptime 通过统一的 SMTPOAuthService 的getAccessToken()获取访问令牌——它会根据oauthProviderType自动选择 Client Credentials 或 JWT Bearer 流程并对令牌进行缓存、在过期前自动刷新避免每次发信都重新换取令牌。OAuth 必填字段一览配置 OAuth 认证时需要在 OneUptime 的 SMTP 设置中填写以下字段字段说明主机名HostnameSMTP 服务器地址端口Port一般为587STARTTLS或465隐式 TLS用户名Username发信邮箱地址认证类型Authentication Type选择OAuthOAuth 提供方类型Microsoft 365 选Client CredentialsGoogle Workspace 选JWT Bearer客户端 IDClient IDOAuth 应用/客户端 IDGoogle 场景下为服务账号邮箱客户端密钥Client SecretOAuth 客户端密钥Google 场景下为私钥令牌 URLToken URLOAuth 令牌端点地址范围ScopeSMTP 访问所需的 OAuth 范围OneUptime 在把模型转换为发送配置时会严格校验这些字段见 ProjectSmtpConfigService.ts 的toEmailServer()传输类型为SMTP时hostname、port必填Username and Password时username、password必填OAuth时clientId、clientSecret、tokenUrl、scope必填SMTP 传输下username发信邮箱也必填None时无需任何凭据无论哪种方式fromEmail发件邮箱与fromName发件人名称必填。校验不通过会抛出BadDataException在界面上直接提示缺失字段防止保存一份无法发信的配置。三、Microsoft 365Exchange OnlineOAuth 配置在 Microsoft 365 中使用 OAuth 发信需要在 Microsoft Entra原 Azure AD注册应用并完成 Exchange Online 侧的服务主体授权。完整的链路是Entra 应用 → 客户端密钥 → SMTP.SendAsApp 应用权限 → Exchange Online 服务主体 邮箱 FullAccess 权限 → OneUptime 配置。步骤 1在 Microsoft Entra 注册应用登录 Microsoft Entra 管理中心进入身份 应用程序 应用注册点击新注册为应用命名例如OneUptime SMTP支持的账户类型选择仅此组织目录中的账户重定向 URI留空客户端凭据流程不需要点击注册。注册完成后在概览页记录两个值应用程序客户端ID—— 即后续的客户端 ID目录租户ID—— 拼装令牌 URL 时需要。步骤 2创建客户端密钥在应用注册中进入证书和机密 客户端机密点击新客户端机密添加说明并选择有效期点击添加立即复制机密值——关闭页面后不再显示。步骤 3添加 SMTP API 权限进入API 权限点击添加权限选择我的组织使用的 API搜索并选择Office 365 Exchange Online选择应用程序权限搜索并勾选SMTP.SendAsApp点击添加权限点击为 [你的组织] 授予管理员同意需要管理员权限。SMTP.SendAsApp是应用权限Application Permission让应用以自身身份通过 SMTP AUTH 发送邮件而无需逐用户交互授权——这正是客户端凭据流程能自动化运行的前提。步骤 4在 Exchange Online 注册服务主体并授权邮箱应用要真正发出邮件还需在 Exchange Online 注册服务主体并授予邮箱权限。需要先安装并连接 Exchange Online PowerShell 模块Install-Module -Name ExchangeOnlineManagement -ForceImport-Module ExchangeOnlineManagement Connect-ExchangeOnline -Organization your-tenant-id注册服务主体注意使用企业应用程序中的对象 ID而不是应用注册页的对象 ID# 对象 ID 在 Microsoft Entra 企业应用程序 你的应用 对象 ID 中查找 New-ServicePrincipal -AppId application-client-id -ObjectId enterprise-app-object-id为服务主体授予对指定发件邮箱的完整访问权限# 授予服务主体对邮箱的完整访问权限 Add-MailboxPermission -Identity senderyourdomain.com -User service-principal-id -AccessRights FullAccess重要提示必须使用Add-MailboxPermission而非Add-RecipientPermission。Add-RecipientPermission只授予收件人SendAs权限不足以让服务主体通过 SMTP OAuth 发信实际发信时会报认证/权限错误Add-MailboxPermissionFullAccess才是真正生效的命令。步骤 5在 OneUptime 中填写配置在 OneUptime 中新建或编辑一条 SMTP 配置填写如下值字段值主机名smtp.office365.com端口587用户名已授权的发件邮箱如senderyourdomain.com认证类型OAuthOAuth 提供方类型Client Credentials客户端 ID步骤 1 的应用程序客户端ID客户端密钥步骤 2 的机密值令牌 URLhttps://login.microsoftonline.com/tenant-id/oauth2/v2.0/token范围https://outlook.office365.com/.default发件邮箱Correo de origen与用户名相同安全连接TLS启用将tenant-id替换为步骤 1 记录的目录租户ID。端口587对应 STARTTLSOneUptime 会据此自动协商加密连接源码中连接设置解析逻辑位于 Notification 模块 MailService.ts它会根据端口与 TLS 选项推导secure、requireTLS等连接参数。四、Google Workspace OAuth 配置与 Microsoft 不同Google 的 SMTP 服务器smtp.gmail.com不支持直接使用客户端凭据流程因此 Google Workspace 必须使用服务账号 全域委派Domain-wide Delegation由服务账号模拟用户发信。前置条件一个 Google Workspace 账号普通 Gmail 消费级账号不支持此能力可访问 Google Workspace 管理控制台且具备超级管理员权限可访问 Google Cloud Console。步骤 1创建 Google Cloud 项目打开 Google Cloud Console点击项目下拉菜单选择新建项目输入项目名称并点击创建切换到刚创建的项目。步骤 2启用 Gmail API进入API 和服务 库搜索 Gmail API点击Gmail API再点击启用。步骤 3创建服务账号进入API 和服务 凭据点击创建凭据 服务账号输入服务账号的名称和说明点击创建并继续跳过可选步骤点击完成。步骤 4创建服务账号密钥点击刚创建的服务账号进入密钥标签页点击添加密钥 创建新密钥选择JSON并点击创建安全保存下载的 JSON 文件其中包含client_id—— 客户端 IDprivate_key—— 客户端密钥私钥。步骤 5启用全域委派在服务账号详情页点击显示高级设置记录客户端 ID数字 ID勾选启用 Google Workspace 全域委派点击保存。步骤 6在 Google Workspace 管理控制台授权服务账号登录 Google Workspace 管理控制台进入安全 访问权限和数据控制 API 控制点击管理全域委派点击新增输入步骤 5 的客户端 ID在OAuth 范围中输入https://mail.google.com/点击授权。注意委派配置的生效存在传播延迟通常需要几分钟极端情况下最长可达 24 小时。步骤 7在 OneUptime 中填写配置在 OneUptime 中新建或编辑 SMTP 配置字段值主机名smtp.gmail.com端口587用户名用于发信的 Google Workspace 邮箱如notificationsyourdomain.com该用户将被服务账号模拟认证类型OAuthOAuth 提供方类型JWT Bearer客户端 ID服务账号 JSON 中的client_email如your-serviceyour-project.iam.gserviceaccount.com客户端密钥服务账号 JSON 中的private_key完整私钥包含-----BEGIN PRIVATE KEY-----与-----END PRIVATE KEY-----行令牌 URLhttps://oauth2.googleapis.com/token范围https://mail.google.com/发件邮箱Correo de origen与用户名相同安全连接TLS启用关键易错点GoogleJWT Bearer场景下客户端 ID 填的是服务账号的邮箱地址client_email而不是数字形式的client_id。服务账号会模拟用户名字段指定的用户来发送邮件。这与 OAuthProviderType.ts 中 JWT Bearer 的字段约定一致Client ID 服务账号邮箱、Client Secret 私钥、Username 被模拟用户。五、OneUptime 底层如何发送从令牌到 XOAUTH2 投递理解底层实现有助于定位问题。当配置为 OAuth 认证时OneUptime 的发信链路如下对应 Notification 模块 MailService.ts从项目 SMTP 配置读取clientId、clientSecret、tokenUrl、scope与username调用SMTPOAuthService.getAccessToken()获取访问令牌先查缓存命中则直接返回避免重复的凭据交换使用 nodemailer 创建传输器authMethod设为XOAUTH2auth传入{ type: OAuth2, user: username, accessToken }通过 SMTP 协议向目标服务器投递邮件。对于用户名密码与无认证模式传输器则直接使用{ user, pass }或完全省略auth。另外发送代码为每个邮件服务器维护了连接池pool: true并限制最大并发连接数以提升批量通知场景下的吞吐。平台的各业务服务如告警、状态页、值班通知通过 MailService 的sendMail()将邮件与服务器凭据序列化后统一转发给 Notification 服务/api/notification/email/send执行实际投递——也就是说只要 SMTP 配置正确所有通知场景会自动复用这条发信通道。六、故障排查Microsoft 365 常见问题问题解决方案Authentication unsuccessful确认服务主体已在 Exchange 注册且已通过Add-MailboxPermission获得邮箱权限AADSTS700016: Application not found检查客户端 ID 是否正确、应用是否存在于你的租户中AADSTS7000215: Invalid client secret重新生成客户端密钥原密钥可能已过期The mailbox is not enabled for this operation执行Add-MailboxPermission授予邮箱访问权限Google Workspace 常见问题问题解决方案invalid_grant确认全域委派配置正确且已传播生效unauthorized_client确认客户端 ID 已在 Google Workspace 管理控制台完成授权access_denied检查https://mail.google.com/范围是否已授权Domain policy has disabled third-party Drive apps在 Google Workspace 管理控制台 安全 API 控制中启用 API 访问通用排查建议先做连通性测试在 OneUptime 中使用发送测试邮件按钮验证配置是否可用查看日志检查 OneUptime 日志中的详细错误信息发信失败时错误会带上下文便于区分是配置缺字段还是服务端拒绝令牌缓存OneUptime 会缓存 OAuth 令牌并在过期前自动刷新因此令牌层面一般无需人工干预。七、安全最佳实践定期轮换密钥在日历中为客户端密钥/服务账号密钥设置到期提醒在过期前完成轮换使用专用凭据为 OneUptime 创建独立的应用注册与服务账号避免与其他应用共用凭据便于隔离与审计最小权限原则只授予必要的最小权限——Microsoft 侧仅授予SMTP.SendAsAppGoogle 侧仅授权mail.google.com范围不要顺手开放其他高权限 API监控使用情况定期查看邮件投递记录与 OAuth 应用登录日志及时发现异常活动安全存储绝不把客户端密钥、服务账号私钥提交到版本控制系统。八、结语通过 OAuth 2.0OneUptime 可以在企业禁用基础认证的情况下依然稳定地向 Microsoft 365 与 Google Workspace 邮箱发送通知邮件。两者思路一致但细节迥异Microsoft 走客户端凭据 SMTP.SendAsApp 服务主体邮箱授权Google 走服务账号 JWT Bearer 全域委派。配合 OneUptime 内置的令牌缓存、自动刷新与测试邮件功能只要按上文完成云侧配置并准确填写 ProjectSmtpConfig 的各个字段即可在项目中投入使用。建议同时参考仓库中的模型定义与 发送实现以便在异常时快速定位是云侧权限问题还是配置缺字段问题。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OneUptime SMTP 配置指南：基于 OAuth 2.0 接入 Microsoft 365 与 Google Workspace 发信
OneUptime SMTP 配置指南基于 OAuth 2.0 接入 Microsoft 365 与 Google Workspace 发信【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime导读OneUptime 作为开源的可观测性与告警平台所有通知邮件告警、事件、状态页公告等都依赖邮件传输能力。它支持通过自定义 SMTP 服务器发送邮件并提供用户名密码、OAuth 2.0与**无认证中继服务器**三种认证方式。本篇指南以 OneUptime 官方 SMTP 配置文档为主体结合仓库源码数据模型、服务校验与邮件发送实现完整讲解如何在 OneUptime 中配置 OAuth 2.0 认证分别接入 Microsoft 365/Exchange Online 与 Google Workspace 的企业邮箱发信通道并给出故障排查与安全加固建议。读完本文你将能独立完成两种主流企业邮箱的 OAuth 集成并理解 OneUptime 底层如何获取、缓存与使用 OAuth 令牌。一、OneUptime 的 SMTP 配置模型三种认证方式OneUptime 允许项目使用自定义 SMTP 服务器发送通知邮件支持的认证方式由模型字段authType决定其定义见 SMTPAuthenticationType.ts认证方式枚举值适用场景用户名密码Username and Password默认传统 SMTP 认证兼容绝大多数自建或第三方邮件服务器OAuth 2.0OAuthMicrosoft 365、Google Workspace 等已禁用基础认证的企业环境无认证None不需要认证的中继relay服务器如仅限内网使用的转发网关从源码结构看每个项目可维护多条 SMTP 配置name字段在同一项目内唯一模型定义于 ProjectSmtpConfig.ts通过 CRUD API 端点/smtp-config暴露并受项目级权限控制创建/编辑/删除需要ProjectOwner、ProjectAdmin或对应的Create/Edit/DeleteProjectSMTPConfig权限。除了authType模型还包含transportType传输类型字段定义邮件实际如何投递SMTP默认使用hostnameport建立 SMTP 连接Microsoft Graph不经过 SMTP 协议直接调用 Microsoft Graph REST API 投递适用于租户已禁用 SMTP AUTH 的场景。后续配置 OAuth 时Microsoft 365 走 SMTP 传输 XOAUTH2Google Workspace 同样走 SMTP 传输transportType保持默认的SMTP即可。本文聚焦 SMTP OAuth 的完整链路。二、OAuth 2.0 认证两种授权类型Grant Type企业邮箱尤其 Microsoft 365普遍出于安全考虑关闭了基础认证Basic AuthOAuth 2.0 成为唯一可行的自动化发信方案。OneUptime 支持两种 OAuth 授权类型定义见 OAuthProviderType.ts授权类型枚举值对应 RFC使用方客户端凭据Client CredentialsClient CredentialsRFC 6749Microsoft 365 及大多数 OAuth 2.0 提供商JWT 承载断言JWT BearerJWT BearerRFC 7523Google Workspace 服务账号Service Account两种流程所需的字段均为clientId、clientSecret、tokenUrl、scopeJWT Bearer 额外依赖username要被模拟发信的用户邮箱。OneUptime 通过统一的 SMTPOAuthService 的getAccessToken()获取访问令牌——它会根据oauthProviderType自动选择 Client Credentials 或 JWT Bearer 流程并对令牌进行缓存、在过期前自动刷新避免每次发信都重新换取令牌。OAuth 必填字段一览配置 OAuth 认证时需要在 OneUptime 的 SMTP 设置中填写以下字段字段说明主机名HostnameSMTP 服务器地址端口Port一般为587STARTTLS或465隐式 TLS用户名Username发信邮箱地址认证类型Authentication Type选择OAuthOAuth 提供方类型Microsoft 365 选Client CredentialsGoogle Workspace 选JWT Bearer客户端 IDClient IDOAuth 应用/客户端 IDGoogle 场景下为服务账号邮箱客户端密钥Client SecretOAuth 客户端密钥Google 场景下为私钥令牌 URLToken URLOAuth 令牌端点地址范围ScopeSMTP 访问所需的 OAuth 范围OneUptime 在把模型转换为发送配置时会严格校验这些字段见 ProjectSmtpConfigService.ts 的toEmailServer()传输类型为SMTP时hostname、port必填Username and Password时username、password必填OAuth时clientId、clientSecret、tokenUrl、scope必填SMTP 传输下username发信邮箱也必填None时无需任何凭据无论哪种方式fromEmail发件邮箱与fromName发件人名称必填。校验不通过会抛出BadDataException在界面上直接提示缺失字段防止保存一份无法发信的配置。三、Microsoft 365Exchange OnlineOAuth 配置在 Microsoft 365 中使用 OAuth 发信需要在 Microsoft Entra原 Azure AD注册应用并完成 Exchange Online 侧的服务主体授权。完整的链路是Entra 应用 → 客户端密钥 → SMTP.SendAsApp 应用权限 → Exchange Online 服务主体 邮箱 FullAccess 权限 → OneUptime 配置。步骤 1在 Microsoft Entra 注册应用登录 Microsoft Entra 管理中心进入身份 应用程序 应用注册点击新注册为应用命名例如OneUptime SMTP支持的账户类型选择仅此组织目录中的账户重定向 URI留空客户端凭据流程不需要点击注册。注册完成后在概览页记录两个值应用程序客户端ID—— 即后续的客户端 ID目录租户ID—— 拼装令牌 URL 时需要。步骤 2创建客户端密钥在应用注册中进入证书和机密 客户端机密点击新客户端机密添加说明并选择有效期点击添加立即复制机密值——关闭页面后不再显示。步骤 3添加 SMTP API 权限进入API 权限点击添加权限选择我的组织使用的 API搜索并选择Office 365 Exchange Online选择应用程序权限搜索并勾选SMTP.SendAsApp点击添加权限点击为 [你的组织] 授予管理员同意需要管理员权限。SMTP.SendAsApp是应用权限Application Permission让应用以自身身份通过 SMTP AUTH 发送邮件而无需逐用户交互授权——这正是客户端凭据流程能自动化运行的前提。步骤 4在 Exchange Online 注册服务主体并授权邮箱应用要真正发出邮件还需在 Exchange Online 注册服务主体并授予邮箱权限。需要先安装并连接 Exchange Online PowerShell 模块Install-Module -Name ExchangeOnlineManagement -ForceImport-Module ExchangeOnlineManagement Connect-ExchangeOnline -Organization your-tenant-id注册服务主体注意使用企业应用程序中的对象 ID而不是应用注册页的对象 ID# 对象 ID 在 Microsoft Entra 企业应用程序 你的应用 对象 ID 中查找 New-ServicePrincipal -AppId application-client-id -ObjectId enterprise-app-object-id为服务主体授予对指定发件邮箱的完整访问权限# 授予服务主体对邮箱的完整访问权限 Add-MailboxPermission -Identity senderyourdomain.com -User service-principal-id -AccessRights FullAccess重要提示必须使用Add-MailboxPermission而非Add-RecipientPermission。Add-RecipientPermission只授予收件人SendAs权限不足以让服务主体通过 SMTP OAuth 发信实际发信时会报认证/权限错误Add-MailboxPermissionFullAccess才是真正生效的命令。步骤 5在 OneUptime 中填写配置在 OneUptime 中新建或编辑一条 SMTP 配置填写如下值字段值主机名smtp.office365.com端口587用户名已授权的发件邮箱如senderyourdomain.com认证类型OAuthOAuth 提供方类型Client Credentials客户端 ID步骤 1 的应用程序客户端ID客户端密钥步骤 2 的机密值令牌 URLhttps://login.microsoftonline.com/tenant-id/oauth2/v2.0/token范围https://outlook.office365.com/.default发件邮箱Correo de origen与用户名相同安全连接TLS启用将tenant-id替换为步骤 1 记录的目录租户ID。端口587对应 STARTTLSOneUptime 会据此自动协商加密连接源码中连接设置解析逻辑位于 Notification 模块 MailService.ts它会根据端口与 TLS 选项推导secure、requireTLS等连接参数。四、Google Workspace OAuth 配置与 Microsoft 不同Google 的 SMTP 服务器smtp.gmail.com不支持直接使用客户端凭据流程因此 Google Workspace 必须使用服务账号 全域委派Domain-wide Delegation由服务账号模拟用户发信。前置条件一个 Google Workspace 账号普通 Gmail 消费级账号不支持此能力可访问 Google Workspace 管理控制台且具备超级管理员权限可访问 Google Cloud Console。步骤 1创建 Google Cloud 项目打开 Google Cloud Console点击项目下拉菜单选择新建项目输入项目名称并点击创建切换到刚创建的项目。步骤 2启用 Gmail API进入API 和服务 库搜索 Gmail API点击Gmail API再点击启用。步骤 3创建服务账号进入API 和服务 凭据点击创建凭据 服务账号输入服务账号的名称和说明点击创建并继续跳过可选步骤点击完成。步骤 4创建服务账号密钥点击刚创建的服务账号进入密钥标签页点击添加密钥 创建新密钥选择JSON并点击创建安全保存下载的 JSON 文件其中包含client_id—— 客户端 IDprivate_key—— 客户端密钥私钥。步骤 5启用全域委派在服务账号详情页点击显示高级设置记录客户端 ID数字 ID勾选启用 Google Workspace 全域委派点击保存。步骤 6在 Google Workspace 管理控制台授权服务账号登录 Google Workspace 管理控制台进入安全 访问权限和数据控制 API 控制点击管理全域委派点击新增输入步骤 5 的客户端 ID在OAuth 范围中输入https://mail.google.com/点击授权。注意委派配置的生效存在传播延迟通常需要几分钟极端情况下最长可达 24 小时。步骤 7在 OneUptime 中填写配置在 OneUptime 中新建或编辑 SMTP 配置字段值主机名smtp.gmail.com端口587用户名用于发信的 Google Workspace 邮箱如notificationsyourdomain.com该用户将被服务账号模拟认证类型OAuthOAuth 提供方类型JWT Bearer客户端 ID服务账号 JSON 中的client_email如your-serviceyour-project.iam.gserviceaccount.com客户端密钥服务账号 JSON 中的private_key完整私钥包含-----BEGIN PRIVATE KEY-----与-----END PRIVATE KEY-----行令牌 URLhttps://oauth2.googleapis.com/token范围https://mail.google.com/发件邮箱Correo de origen与用户名相同安全连接TLS启用关键易错点GoogleJWT Bearer场景下客户端 ID 填的是服务账号的邮箱地址client_email而不是数字形式的client_id。服务账号会模拟用户名字段指定的用户来发送邮件。这与 OAuthProviderType.ts 中 JWT Bearer 的字段约定一致Client ID 服务账号邮箱、Client Secret 私钥、Username 被模拟用户。五、OneUptime 底层如何发送从令牌到 XOAUTH2 投递理解底层实现有助于定位问题。当配置为 OAuth 认证时OneUptime 的发信链路如下对应 Notification 模块 MailService.ts从项目 SMTP 配置读取clientId、clientSecret、tokenUrl、scope与username调用SMTPOAuthService.getAccessToken()获取访问令牌先查缓存命中则直接返回避免重复的凭据交换使用 nodemailer 创建传输器authMethod设为XOAUTH2auth传入{ type: OAuth2, user: username, accessToken }通过 SMTP 协议向目标服务器投递邮件。对于用户名密码与无认证模式传输器则直接使用{ user, pass }或完全省略auth。另外发送代码为每个邮件服务器维护了连接池pool: true并限制最大并发连接数以提升批量通知场景下的吞吐。平台的各业务服务如告警、状态页、值班通知通过 MailService 的sendMail()将邮件与服务器凭据序列化后统一转发给 Notification 服务/api/notification/email/send执行实际投递——也就是说只要 SMTP 配置正确所有通知场景会自动复用这条发信通道。六、故障排查Microsoft 365 常见问题问题解决方案Authentication unsuccessful确认服务主体已在 Exchange 注册且已通过Add-MailboxPermission获得邮箱权限AADSTS700016: Application not found检查客户端 ID 是否正确、应用是否存在于你的租户中AADSTS7000215: Invalid client secret重新生成客户端密钥原密钥可能已过期The mailbox is not enabled for this operation执行Add-MailboxPermission授予邮箱访问权限Google Workspace 常见问题问题解决方案invalid_grant确认全域委派配置正确且已传播生效unauthorized_client确认客户端 ID 已在 Google Workspace 管理控制台完成授权access_denied检查https://mail.google.com/范围是否已授权Domain policy has disabled third-party Drive apps在 Google Workspace 管理控制台 安全 API 控制中启用 API 访问通用排查建议先做连通性测试在 OneUptime 中使用发送测试邮件按钮验证配置是否可用查看日志检查 OneUptime 日志中的详细错误信息发信失败时错误会带上下文便于区分是配置缺字段还是服务端拒绝令牌缓存OneUptime 会缓存 OAuth 令牌并在过期前自动刷新因此令牌层面一般无需人工干预。七、安全最佳实践定期轮换密钥在日历中为客户端密钥/服务账号密钥设置到期提醒在过期前完成轮换使用专用凭据为 OneUptime 创建独立的应用注册与服务账号避免与其他应用共用凭据便于隔离与审计最小权限原则只授予必要的最小权限——Microsoft 侧仅授予SMTP.SendAsAppGoogle 侧仅授权mail.google.com范围不要顺手开放其他高权限 API监控使用情况定期查看邮件投递记录与 OAuth 应用登录日志及时发现异常活动安全存储绝不把客户端密钥、服务账号私钥提交到版本控制系统。八、结语通过 OAuth 2.0OneUptime 可以在企业禁用基础认证的情况下依然稳定地向 Microsoft 365 与 Google Workspace 邮箱发送通知邮件。两者思路一致但细节迥异Microsoft 走客户端凭据 SMTP.SendAsApp 服务主体邮箱授权Google 走服务账号 JWT Bearer 全域委派。配合 OneUptime 内置的令牌缓存、自动刷新与测试邮件功能只要按上文完成云侧配置并准确填写 ProjectSmtpConfig 的各个字段即可在项目中投入使用。建议同时参考仓库中的模型定义与 发送实现以便在异常时快速定位是云侧权限问题还是配置缺字段问题。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考