Apollo Portal 发布通知邮件接入指南：SMTP 与自定义邮件服务两种实现方案详解

Apollo Portal 发布通知邮件接入指南SMTP 与自定义邮件服务两种实现方案详解【免费下载链接】apolloApollo is a reliable configuration management system suitable for microservice configuration management scenarios.项目地址: https://gitcode.com/gh_mirrors/apoll/apollo本文以 Apollo 配置中心 Portal 为对象系统讲解在配置发布时如何通过邮件将发布信息通知到相关负责人的完整方案。Apollo 通过 SPI 机制将邮件服务解耦既内置了开箱即用的 SMTP 邮件服务方式一也支持接入公司自有的统一邮件服务方式二。读完本文你将掌握两类接入方式的具体配置步骤、全部邮件模板参数的含义与写法以及邮件从发布事件触发到最终送达的底层实现链路。一、邮件通知的触发场景与通知对象在配置发布时Apollo 会将发布信息以邮件形式通知到相关负责人。目前支持的发送邮件动作包括普通发布NORMAL_RELEASE灰度发布GRAY_RELEASE全量发布即灰度全量发布对应GRAY_RELEASE_MERGE_TO_MASTER合并发布回滚ROLLBACK通知对象包括具有Namespace 编辑权限的人员具有Namespace 发布权限的人员App 负责人App 所有者注通知对象会同时包含权限类型与具体环境两层维度。从 ConfigPublishEmailBuilder.java 的recipients方法可以看出收件人集合由 5 部分用户去重合并而成全局 Namespace 修改权限用户、环境级 Namespace 修改权限用户、全局 Namespace 发布权限用户、环境级 Namespace 发布权限用户以及 App 负责人App Master 角色用户最终通过UserService.findByUserIds反查用户的邮箱地址。由于不同公司的邮件服务往往有不同的实现Apollo 定义了一些 SPI 用来解耦。接入邮件服务的关键就是实现这些 SPI。二、实现方式一使用 Apollo 提供的 SMTP 邮件服务如果公司没有统一的邮件网关Apollo 内置了基于 SMTP 协议的默认邮件服务实现DefaultEmailService可以直接复用。2.1 接入步骤在ApolloPortalDB.ServerConfig表配置以下参数也可以通过管理员工具 - 系统参数页面进行配置修改完一分钟实时生效参数说明email.enabled设置为true即可启用默认的 SMTP 邮件服务email.config.hostSMTP 服务地址如smtp.163.comemail.config.userSMTP 账号用户名email.config.passwordSMTP 账号密码email.supported.envs支持发送邮件的环境列表英文逗号隔开。为避免发布邮件变成垃圾邮件只有配置了的环境下的发布动作才会发送邮件email.sender邮件的发送人可以不配置默认为email.config.userapollo.portal.addressApollo Portal 的地址。方便用户从邮件点击跳转到 Apollo Portal 查看详细的发布信息email.template.framework邮件内容模板框架。将邮件内容模板化、可配置化方便管理和变更邮件内容email.template.release.module.diff发布邮件的 diff 模块email.template.rollback.module.diff回滚邮件的 diff 模块email.template.release.module.rules灰度发布的灰度规则模块关于以上参数的默认值与读取逻辑可以对照 PortalConfig.java 的实现email.enabled默认值为false即不显式开启时邮件发送直接被禁用email.config.host、email.config.user、email.config.password默认均为空字符串email.sender未配置时emailSender()方法会自动回退使用email.config.user的值email.supported.envs会被解析为环境Env集合emailSupportedEnvs()返回空时意味着默认所有环境的发布动作都不发邮件。模板样例见下文 第三节方便大家直接复制使用。三、实现方式二接入公司的统一邮件服务和 SSO 接入类似每个公司也有自己的邮件服务实现。Apollo 定义了 EmailService 接口现有两个实现类CtripEmailService携程实现的 EmailServiceDefaultEmailServiceSMTP 实现EmailService接口本身非常精简只暴露了一个方法public interface EmailService { void send(Email email); }Email实体见 Email.java包含四个字段senderEmailAddress发送人地址、recipients收件人列表、subject主题、bodyHTML 正文。3.1 接入步骤提供自己公司的 EmailService 实现并在 EmailConfiguration 中注册。注册入口见 EmailConfiguration.java它通过ConditionalOnMissingBean(EmailService.class)注册默认的DefaultEmailService。也就是说只要你的容器中已经存在一个自定义的EmailServiceBean默认实现便不会生效。在ApolloPortalDB.ServerConfig表配置以下参数也可以通过管理员工具 - 系统参数页面进行配置修改完一分钟实时生效参数说明email.supported.envs支持发送邮件的环境列表英文逗号隔开。为避免发布邮件变成垃圾邮件只有配置了的环境下的发布动作才会发送邮件email.sender邮件的发送人apollo.portal.addressApollo Portal 的地址。方便用户从邮件点击跳转到 Apollo Portal 查看详细的发布信息email.template.framework邮件内容模板框架。将邮件内容模板化、可配置化方便管理和变更邮件内容email.template.release.module.diff发布邮件的 diff 模块email.template.rollback.module.diff回滚邮件的 diff 模块email.template.release.module.rules灰度发布的灰度规则模块模板样例见下文 第三节方便大家直接复制使用。注运行时使用不同的实现是通过 Spring Profiles 实现的。比如你自己的 Email 实现是在customprofile 中的话在打包脚本中可以指定-Dapollo_profilegithub,custom。其中github是 Apollo 必须的一个 profile用于数据库的配置custom是你自己实现的 profile。同时需要注意在 EmailConfiguration.java 中默认实现的生效条件。从当前仓库源码看默认实现的注册条件为ConditionalOnMissingBean(EmailService.class)而非简单的Profile({!custom})只要自定义实现作为一个 Bean 被容器管理Apollo 就会自动采用你的实现无需再修改 Apollo 自身的配置类。这与原文档描述的自定义 Profile 方案在效果上等价且更宽松。3.2 相关代码导读ConfigPublishListener.java监听发布事件调用 emailbuilder 构建邮件内容然后调用 EmailService 发送邮件emailbuilder 包构建邮件内容的实现EmailService.java邮件发送服务EmailConfiguration.java邮件服务注册类四、邮件模板样例以下为发布邮件和回滚邮件的模板内容样式。邮件模板为 HTML 格式发送 HTML 格式的邮件时可能需要做一些额外的处理取决于每个公司的邮件服务实现。为了减少字符数模板经过了压缩处理可自行格式化提高可读性。4.1 email.template.frameworkhtmlheadstyle typetext/css.table{width:100%;max-width:100%;margin-bottom:20px;border-collapse:collapse;background-color:transparent}td{padding:8px;line-height:1.42857143;vertical-align:top;border:1px solid #ddd;border-top:1px solid #ddd}.table-bordered{border:1px solid #ddd}/style/headbodyh3发布基本信息/h3table classtable table-borderedtrtd width10%bAppId/b/tdtd width15%#{appId}/tdtd width10%b环境/b/tdtd width15%#{env}/tdtd width10%b集群/b/tdtd width15%#{clusterName}/tdtd width10%bNamespace/b/tdtd width15%#{namespaceName}/td/trtrtdb发布者/b/tdtd#{operator}/tdtdb发布时间/b/tdtd#{releaseTime}/tdtdb发布标题/b/tdtd#{releaseTitle}/tdtdb备注/b/tdtd#{releaseComment}/td/tr/table#{diffModule}#{rulesModule}bra href#{apollo.portal.address}/config/history.html?#/appid#{appId}env#{env}clusterName#{clusterName}namespaceName#{namespaceName}releaseHistoryId#{releaseHistoryId}点击查看详细的发布信息/abrbr如有Apollo使用问题请先查阅a hrefhttp://conf.ctripcorp.com/display/FRAM/Apollo文档/a或直接回复本邮件咨询。/body/html注使用此模板需要在 portal 的系统参数中配置apollo.portal.address指向 Apollo Portal 的地址。模板占位符说明以上模板中出现的#{appId}、#{env}、#{clusterName}、#{namespaceName}、#{operator}、#{releaseTime}、#{releaseTitle}、#{releaseComment}、#{apollo.portal.address}、#{releaseHistoryId}等占位符均由 ConfigPublishEmailBuilder.java 在构建邮件时逐项替换为真实发布数据。此外该构建器还额外支持两个模板里未出现、但在自定义模板时可用的占位符#{releaseId}发布单 ID#{emergencyPublish}紧急发布标记。当发布为紧急发布时替换为红色高亮的紧急发布标签否则替换为空字符串。构建完成后未用到的模块占位符#{diffModule}、#{rulesModule}会被自动清空避免邮件中出现空的模块区域。4.2 email.template.release.module.diffh3变更的配置/h3 table classtable table-bordered tr td width10%bType/b/td td width20%bKey/b/td td width35%bOld Value/b/td td width35%bNew Value/b/td /tr #{diffContent} /table4.3 email.template.rollback.module.diffdiv brbr h3变更的配置/h3 table classtable table-bordered tr td width10%bType/b/td td width20%bKey/b/td td width35%b回滚前/b/td td width35%b回滚后/b/td /tr #{diffContent} /table br /div4.4 email.template.release.module.rulesdiv br h3灰度规则/h3 #{rulesContent} br /div4.5 发布邮件样例4.6 回滚邮件样例五、邮件发送的底层实现链路5.1 事件驱动ConfigPublishListener 的工作流程邮件通知由 ConfigPublishListener.java 统一驱动。该监听器通过EventListener订阅ConfigPublishEvent发布事件并借助PostConstruct初始化的单线程ExecutorService线程名ConfigPublishNotifydaemontrue异步执行通知任务避免阻塞发布主流程。整体处理链路为根据发布事件的类型合并发布 / 回滚 / 普通发布 / 灰度发布查询对应的ReleaseHistoryBO发布历史记录判断当前环境是否在email.supported.envs配置的范围内不在则直接跳过邮件发送根据发布操作类型选择对应的邮件构建器GRAY_RELEASE灰度发布→GrayPublishEmailBuilderNORMAL_RELEASE普通发布→NormalPublishEmailBuilderROLLBACK回滚→RollbackEmailBuilderGRAY_RELEASE_MERGE_TO_MASTER灰度全量合并到主干→MergeEmailBuilder调用EmailService.send(email)完成发送。5.2 模板渲染与 diff 生成规则邮件内容由 emailbuilder 包下的构建器完成核心逻辑集中在抽象类ConfigPublishEmailBuilder中基本信息渲染将框架模板中的 AppId、环境、集群、Namespace、发布者、发布时间、发布标题、备注等占位符替换为真实数据diff 模块渲染仅当 Namespace 的配置格式为Properties时才会在邮件中展示变更 diff 明细若 Namespace 是文件file格式diff 模块会被替换为变更内容请点击链接到Apollo上查看若本次发布没有任何配置变更diff 模块会被替换为无配置变更每个变更项按 Type / Key / Old Value / New Value 生成表格行其中 key 与 value 超过 100 个字符时会被截断并以...结尾常量VALUE_MAX_LENGTH 100用于保护邮件体不过度膨胀灰度规则模块渲染灰度发布时通过#{rulesContent}注入灰度规则内容。5.3 DefaultEmailServiceSMTP 发送的默认实现DefaultEmailService.java 是方式一的发送实现其核心逻辑为发送前先检查email.enabled未开启则直接返回通过 JavaMail 的SessionSMTPTransport建立连接使用email.config.host、email.config.user、email.config.password完成 SMTP 认证邮件正文使用自定义的HTMLDataSourcegetContentType()返回text/html即以 HTML 格式发送发送成功/失败都会记录日志失败时还会通过Tracer.logError上报监控方便排查。六、接入要点小结场景推荐方案关键配置无公司统一邮件网关方式一内置 SMTP 服务email.enabledtrueemail.config.host/user/password已有公司统一邮件网关方式二自定义EmailServiceBean实现EmailService并注册为 Spring Bean只对部分环境发邮件两种方式通用email.supported.envs指定环境列表邮件内容定制两种方式通用4 个email.template.*模板参数无论采用哪种方式都需要保证apollo.portal.address配置正确否则邮件正文中点击查看详细的发布信息的跳转链接将无法使用。配置项写入ApolloPortalDB.ServerConfig后约一分钟内实时生效无需重启 Portal 服务。【免费下载链接】apolloApollo is a reliable configuration management system suitable for microservice configuration management scenarios.项目地址: https://gitcode.com/gh_mirrors/apoll/apollo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考