Litestar Fullstack SAQ 任务队列实战:Redis 驱动的异步邮件发送与 OAuth Token 刷新
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):
- 用户创建成功后触发
user_created事件; - 监听器创建邮件验证 token;
- 调用
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 服务解耦运行:
- 🐳 Docker:独立镜像 Dockerfile.worker,以
app workers run启动,并在 Compose 中设置SAQ_USE_SERVER_LIFESPAN=false(见 docker-compose.yml),由 worker 容器独立消费队列; - ☸️ Kubernetes:worker-deployment.yaml.j2 + worker-hpa.yaml.j2 提供独立 Deployment 与 HPA 自动扩缩容(示例中 2~10 副本);
- 🚂 Railway:deploy.sh 会自动创建并配置独立的 worker 服务。
这种"API 只投递、worker 专职消费"的架构,意味着发信高峰期可以直接扩容 worker 副本,而不影响接口可用性。
小结
Litestar Fullstack 通过 SAQ + Redis 实现了教科书级的异步任务实践:
- ✅ 队列、cron、并发等配置集中在 SaqSettings,环境变量驱动;
- ✅ 邮件走事件监听器 + 模板化服务,与 HTTP 请求彻底解耦;
- ✅ OAuth token 刷新、token 清理等定时任务按 cron 自动执行,失败有完整日志;
- ✅ 生产部署时 worker 独立扩缩容,API 与后台负载互不干扰。
如果你想在自己的 Litestar 项目中引入任务队列,完全可以参考这套"配置集中化 + 事件解耦 + worker 独立部署"的模式,从单个 background-tasks 队列起步即可。