跳到主要内容

0015 后台任务队列与邮件

  • 状态:已接受(2026-10-23)
  • 相关:ADR 0012;设计文档 02 §1.1(F05、F06)、03(S02、S03、S05、S06)、04 §5.1(jobs / outbox)

背景​

M1 第三部分:邮箱验证(F06)与找回密码(F05)。Blessing Skin 在请求里同步发信,SMTP 慢则请求慢,失败时把 SMTP 错误原样返回给访客(S06);验证链接永久有效(S03),重置链接 1 小时内可无限次使用、重置后不吊销会话(S02)。

决策​

  • 数据库任务队列(jobs 表 + internal/jobs),为邮件引入,后续渲染缓存清理、文件回收等复用:
    • 生产者在同一个事务里写入业务数据与任务(transactional outbox):令牌和发送它的邮件要么都存在,要么都不存在。
    • 每个节点都运行 worker,每 5 秒轮询;业务提交后主动 Kick,邮件立即发出。认领任务用条件更新加 5 分钟租约,多副本下同一任务只在一个节点执行;节点中途崩溃,租约到期后由其它节点接手。
    • 失败按 1 分钟、5 分钟、15 分钟、1 小时退避重试,第 5 次失败或 Permanent 错误标记为 failed。完成或放弃后立即清空 payload(邮件里有一次性链接),7 天后删除记录。
  • 邮件(internal/mail):
    • 驱动 none(默认)/ smtp / log(写日志,开发用),由运行时设置选择,热切换;任务执行时才读取当前设置。
    • SMTP 支持隐式 TLS(465)、STARTTLS(587)与明文(仅本机中继),TLS 1.2 起;认证用 PLAIN,服务器只提供 LOGIN 时用 LOGIN(如 Office 365)。与 net/smtp 一样,不在未加密连接上向非本机发送密码。
    • 邮件为 multipart(纯文本 + HTML),头部按 RFC 2047 编码,站点名、标题里的换行无法注入头部;HTML 模板转义用户数据。模板有中英两种,按用户偏好、其次按请求语言选择。
    • SMTP 错误只进日志,以及管理员的"发送测试邮件"接口(同步发送,直接返回错误,便于排查);访客永远看不到。
  • 链接只用 site.url 生成,从不取请求的 Host 头(否则任何人都能让站点发出指向自己服务器的真实重置邮件,即密码重置投毒)。未设置 site.url 时,带链接的邮件视为不可用。链接不绑定邮箱地址,因此改邮箱时作废发往旧地址的所有链接,改密码时作废未使用的重置链接。
  • 邮箱验证:注册时(配置了邮件)在同一事务里签发令牌并入队邮件。链接 24 小时有效、一次性;验证页需要点击按钮(POST)才生效,邮件安全软件预取链接不会用掉它。重发每分钟 1 封、每天 5 封;新令牌签发时作废同用途的旧令牌。
  • 找回密码:
    • /auth/password/forgot 对任何邮箱都返回同样的 202(S05);需要验证码;同一地址每小时 10 次、同一邮箱每小时 3 次,对未注册的邮箱同样计数,限流本身不泄露账号是否存在。
    • 链接 30 分钟有效、一次性,只有最新一封有效。
    • 重置先用廉价查询确认令牌有效,再计算哈希;事务内换密码、作废令牌、吊销该用户全部会话(S02),并把邮箱视为已验证(链接确实送达了这个收件箱)。
  • 以上接口与登录、注册一样始终要求 CSRF 头:另一个站点不能借访客的浏览器触发它们。

备选方案​

  • Redis 队列:多一个必需组件,小站部署负担重;数据库队列对邮件这种量级足够,且能与业务写入同一事务。
  • 请求内同步发信:实现最简单,但 SMTP 慢会拖慢注册、失败无法重试,也做不到事务一致。
  • GET 链接直接验证:部分邮件安全网关会预先打开链接,用户还没点就被"用掉"。

影响​

  • 新表 jobs(迁移 20261023151731_jobs)。
  • 没有配置邮件时:注册照常,不发验证邮件;登录页不显示"忘记密码";找回密码接口返回 503。
  • 设置里的 SMTP 密码目前以明文存放在数据库(与其它设置相同),只有管理员可见;加密的密钥存储计划在 M4。