Litestar Fullstack SAQ 任务队列实战:Redis 驱动的异步邮件发送与 OAuth Token 刷新

原创2026-11-14 09:30:091,872 阅读

Litestar Fullstack SAQ 任务队列实战:Redis 驱动的异步邮件发送与 OAuth Token 刷新

Litestar Fullstack 是一个基于 React、Vite、SQLAlchemy 与 Docker 的全栈参考应用,其中使用 SAQ(Simple Async Queue)任务队列 + Redis 实现了异步邮件发送和OAuth Token 定时刷新两大后台能力。本文带你快速读懂它的任务队列架构:队列如何配置、定时任务如何注册、邮件如何与请求解耦、worker 如何独立部署,帮你掌握生产级异步任务的设计思路。

为什么需要 SAQ 任务队列?

在 Web 应用中,有些工作不适合塞在 HTTP 请求里同步执行:

  • 📧 发送邮件:SMTP 网络调用慢且可能失败,会拖慢注册/找回密码等接口的响应时间;
  • 🔄 刷新 OAuth Token:Google、GitHub 的 access token 有效期有限,需要定时批量刷新,与任何一次请求都无关;
  • 🧹 清理过期数据:邮件验证 token、重置密码 token、refresh token 需要定期清库。

SAQ 是一个轻量的异步任务队列,以 Redis 作为 broker:API 服务只负责"投递任务",独立的 worker 进程负责"消费执行",天然支持水平扩展与故障隔离。

快速上手:一键启动本地环境

项目通过 make 命令管理基础设施。启动本地 Redis 等基础设施:

make start-infra

本地开发时,项目默认使用 console 邮件后端,邮件直接打印到 stdout;也可以用 Mailpit 做可视化收件箱:

make mailpit   # 打开 http://localhost:18025 查看收到的邮件

队列配置:一个 dataclass 搞定 Redis 与 Cron

整个 SAQ 系统的核心配置在 SaqSettings 中,要点如下:

配置项 环境变量 默认值 说明
Redis 地址 SAQ_REDIS_URL redis://localhost:16379/0 队列 broker 连接串
worker 进程数 SAQ_PROCESSES 1 启动几个 worker 进程
单进程并发 SAQ_CONCURRENCY 10 每个进程并行执行的 job 数
Web 管理 UI SAQ_WEB_ENABLED true 可视化查看队列与任务
随应用启停 SAQ_USE_SERVER_LIFESPAN true worker 随 Litestar 应用自动启停

get_config() 方法创建了一个名为 background-tasks 的队列,并注册了两个 CronJob 定时任务(见 settings.py):

定时任务 cron 表达式 执行频率
cleanup_auth_tokens 清理过期 token 0 * * * * 每小时整点
refresh_oauth_tokens 刷新 OAuth token */15 * * * * 每 15 分钟

插件注册同样简洁:get_saq_plugin 采用惰性加载,避免在构建阶段就连接 Redis。

异步邮件发送:事件驱动的解耦设计

邮件发送并没有直接写在某个控制器里,而是走 事件监听器 模式。以注册流程为例(见 listeners.py):

  1. 用户创建成功后触发 user_created 事件;
  2. 监听器创建邮件验证 token;
  3. 调用 AppEmailService.send_verification_email() 渲染模板并发信。

邮件服务 AppEmailService 封装了模板加载、变量替换与 HTML/纯文本双格式生成,覆盖验证邮件、欢迎邮件、重置密码、团队邀请等场景,模板源文件在 src/js/templates/src/emails/。

通过 EMAIL_BACKEND 环境变量即可切换发送渠道:

  • console:打印到控制台(开发默认)
  • memory:内存存储(测试用)
  • smtp:走 SMTP 服务器
  • resend:走 Resend API(生产推荐)

💡 这种"事件 → 监听器 → 服务"的分层让控制器保持干净,也方便替换发送渠道而不动业务代码。

定时任务详解:OAuth Token 自动刷新

这是 SAQ 队列里最实用的后台任务。核心实现在 refresh_oauth_tokens:

  • 每 15 分钟扫描一次数据库,找出 10 分钟内即将过期(REFRESH_WINDOW_MINUTES = 10)且持有 refresh_token 的 OAuth 账户;
  • 用 httpx-oauth 客户端逐个调用 Google / GitHub 的刷新接口;
  • 刷新成功后写回新的 access_token、过期时间与 scope;
  • 失败只记录 warning 并计数,不影响其他账户,最终返回 {"processed", "refreshed", "skipped", "failed"} 统计结果。

另一个任务 cleanup_auth_tokens 每小时清理过期的邮件验证 token、重置密码 token 和 refresh token,保持数据库精简。

Worker 可观测性:结构化日志与生命周期钩子

app/lib/worker.py 定义了四个生命周期钩子(on_startup / on_shutdown / before_process / after_process),为每个 job 记录:

  • ⏱ 排队时长、总运行时长(pickup_time_ms、total_runtime_ms)
  • 📊 job 状态(COMPLETE / FAILED / ABORTED)与错误信息

配合 structlog,任何任务失败都能快速定位到具体 job id 与函数名。

生产部署:API 与 Worker 分离

生产环境中 worker 与 API 服务解耦运行:

这种"API 只投递、worker 专职消费"的架构,意味着发信高峰期可以直接扩容 worker 副本,而不影响接口可用性。

小结

Litestar Fullstack 通过 SAQ + Redis 实现了教科书级的异步任务实践:

  1. ✅ 队列、cron、并发等配置集中在 SaqSettings,环境变量驱动;
  2. ✅ 邮件走事件监听器 + 模板化服务,与 HTTP 请求彻底解耦;
  3. ✅ OAuth token 刷新、token 清理等定时任务按 cron 自动执行,失败有完整日志;
  4. ✅ 生产部署时 worker 独立扩缩容,API 与后台负载互不干扰。

如果你想在自己的 Litestar 项目中引入任务队列,完全可以参考这套"配置集中化 + 事件解耦 + worker 独立部署"的模式,从单个 background-tasks 队列起步即可。

登录后查看全文
litestar-fullstack