upstash-qstash

Upstash QStash - 无服务器消息队列与定时任务专家

技能概述

Upstash QStash 专家助您构建无需管理基础设施的可靠消息传递系统 —— HTTP 进，HTTP 出，中间由 QStash 保证可靠送达。

适用场景

1. Serverless 环境下的定时任务

在 Vercel、Cloudflare Workers 等 serverless 平台需要定时执行任务时，QStash 提供开箱即用的 cron 调度能力，无需维护任何服务器。

2. 可靠的 Webhook 与 HTTP 回调

当您需要确保第三方 API 调用或 webhook 通知一定送达时，QStash 自动处理重试、去重和失败回调。

3. 延迟消息与任务调度

需要将任务推迟几分钟、几小时甚至几天执行的场景，QStash 的延迟调度功能让消息按您设定的时间精准投递。

核心功能

消息发布与投递

通过简单的 HTTP 请求发送消息，QStash 负责将消息可靠地投递到目标 URL，支持 URL 组批量分发、消息去重和自定义延迟。

Serverless Cron 调度

设置类似 crontab 的定时规则，QStash 会按计划定期调用您的 HTTP 端点，完美适配 serverless 架构的长期任务需求。

签名验证与回调

自动为每个请求生成可验证的签名，确保消息来源可信。支持成功回调和失败回调，让您实时掌握投递状态。

常见问题

Upstash QStash 是什么？

QStash 是 Upstash 提供的无服务器消息队列服务，基于 HTTP 协议工作。您只需发送 HTTP 请求到 QStash，它会负责将消息可靠地投递到您指定的目标 URL，自动处理重试、去重和调度，无需您管理任何基础设施。

如何使用 QStash 发送定时消息？

使用 QStash API 或 SDK 发送请求时，只需在请求头或 body 中设置 delay 参数（单位为秒）或 cron 表达式即可。例如设置 delay: 3600 会在一分钟后投递消息，设置 cron: "0 9 * * *" 则会每天早上 9 点投递。

怎么验证 QStash 的 webhook 签名？

QStash 会在每个请求的 Upstash-Signature 头中携带签名。您需要在服务端使用您的 QStash 签名密钥，对该请求的 body 和 URL 进行签名计算，然后比对签名是否一致。请务必验证签名以防止伪造请求。

QStash 可以调用内网/localhost 接口吗？

不可以。QStash 运行在 Upstash 的基础设施上，只能访问公网可访问的 HTTP(S) 端点。开发测试时可以使用 ngrok、localtunnel 等隧道工具将本地服务暴露到公网。

如何处理消息投递失败？

QStash 会自动重试失败的投递。您也可以在发送消息时配置 failureCallbackUrl，当消息最终失败时，QStash 会向该 URL 发送失败通知。建议在回调接口中记录失败日志并进行人工干预。

QStash 免费额度是多少？

QStash 提供免费层，包含每日一定数量的请求配额和并发限制。具体额度可能随时间调整，请查阅 Upstash 官方文档获取最新定价信息。