Xiuno 实现邮件通知与短信网关全攻略

52JinY 助手

做过几次 Xiuno 的二开与部署后，我对“消息触达”这块一直有个朴素标准：稳定、可观测、可回退。邮件通知与短信网关对接，看似只是发条消息，踩过的坑多了才知道细节才是成败关键。下面按实战流程梳理思路与要点，帮助你少走弯路。

先说邮件通知。Xiuno 原生支持 SMTP，但默认配置偏保守。企业环境建议直接用成熟服务商（如企业邮箱或 SendGrid、阿里云企业邮），因为退信处理和信誉度对到达率影响很大。配置上三点：一是端口与加密协议要对应，465 对应 SSL，587 对应 STARTTLS，别混；二是发件人域名要做 DKIM/DMARC/SPF，哪怕是小站点，也能显著降低进垃圾箱概率；三是连接与超时参数适度放宽，公有云延迟偶发抖动，过短超时会造成“间歇性失败”。上线前用多家收件箱（QQ/163/Gmail/Outlook）做 A/B 验证，观察投递路径与分类结果。

再谈触发策略。论坛里典型事件包括新回复、被@、私信、系统公告。别把所有事件都直接触发外部通知——先做一个“节流”和“合并”策略，比如15分钟内聚合多条为一封摘要，避免把活跃用户轰炸到退订。另外给用户提供精细化开关：站内信必开，邮件/短信按事件类型自选，并且允许静默时段（比如夜间不发短信，只发邮件排队到早晨再推）。

短信网关的选择，核心看三点：覆盖率与到达率、价格与计费粒度、API 的幂等与限流策略。国内用阿里云短信、腾讯云、华为云都行；海外站点需要考虑 Twilio、Vonage 等。无论选谁，都要先打通模板审核与签名，很多新人卡在“测试能发，正式发不出”，本质是模板签名未通过或变量不匹配。变量策略上，短信字数宝贵，建议只发关键事件的最短文案，并在尾部附上短链跳回帖子。短链尽量自建域名，第三方公共短链容易被运营商风控。

对接实现建议用“队列+重试”的架构，而不是在请求线程里直发。Xiuno 里可以在事件触发处只写一条任务到队列表（或接入 Redis 队列），由独立的 worker 消费并调用 SMTP/短信 API。这样可以控制并发、做指数退避重试，并记录完整日志。日志至少要落四类信息：请求参数脱敏、响应码、耗时、消息唯一 ID（便于给供应商报障）。幂等性用“事件ID+用户ID+渠道”做去重键，避免重复扣费或重复投递。

关于模板与多语言。邮件用 HTML 模板，注意暗色模式与移动端适配，主按钮足够醒目；短信只保留关键信息，不要折腾格式。多语言可以在用户偏好里存语言码，渲染时选择对应模板文件。若站点体量不大，先做中文模板，英文 fallback 到简洁版即可，别一开始就过度工程化。

监控与告警是常被忽视的一环。至少建两条监控：发送成功率（5分钟窗口和24小时窗口）与延迟分布（P50/P95）。当成功率连续两个窗口低于阈值，自动降级策略生效：短信改发邮件、或暂停某家通道切换到备份供应商。别忘了退订与频控：每个渠道都必须提供易用的退订路径，和全局频控阈值（例如每天最多3条短信、10封邮件），这既是合规，也是用户体验的底线。

最后给出一条小而实用的上线清单：完成域名的 SPF/DKIM/DMARC；准备至少两家短信供应商与一套统一模板变量；实现队列与重试、幂等、限流；打通全链路日志与日/周报；准备用户可见的通知偏好页与退订通道；用真实账号跑一周灰度，检查到达率、投诉率与成本。做到这些，Xiuno 的邮件与短信触达基本就算稳了。