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。