持久任务与就绪检查

已与 starter 提交 e632762 同步。

当某项工作必须在浏览器请求结束后继续完成时，请使用本页，例如发送邮件、发放积分、删除对象或完成隐私请求。模板内置轻量的 PostgreSQL 持久队列，多数团队无需先运维 Redis 队列或独立 worker 服务即可上线。

决定如何运行和监控后台工作

• Vercel 使用受认证的五分钟 Cron drain；VM、容器或 Kubernetes 使用已提供的独立 Worker。平台调度器也可运行一次性 pnpm jobs:run --production。
• 中低吞吐时保留 PostgreSQL 队列。Worker 与 Cron 共用领取、重试、维护和可观测性服务。Worker 的 JOB_WORKER_HANDLER_TIMEOUT_MS 与 JOB_WORKER_DRAIN_DEADLINE_MS 默认分别为 20 秒和 40 秒；延长提供器预算时需验证中止行为，且必须低于五分钟租约。使用 Worker 不需要更换队列存储。
• /api/health 回答“进程能否响应”，/api/ready 回答“该版本是否可以接收生产流量”，不要混用。

可以上线的标准： 测试任务能被领取；强制失败会重试并最终可见；重叠的 Cron 不会产生重复效果；readiness 失败和 failed 队列增长会触发告警。

为什么任务必须持久化

Serverless 实例可能在响应返回后立刻冻结。必须完成的工作——邮件、积分发放、对象删除、账号导出与删除——会写入 jobs 表，而不是交给 queueMicrotask 或未等待的 Promise。

当前任务包含欢迎/支付/邀请/预约邮件、注册积分、Slack 事件、存储删除、账号导出、导出过期、账号删除、营销邮件投递，以及五积分图像生成工作流。

安全入队

await enqueueJob("welcome_email", { email, name, userUuid }, {
  dedupeKey: `welcome:${userUuid}`,
  subjectUserUuid: userUuid
});

dedupeKey 保证入队幂等。Subject UUID 让隐私流程能够取消或清理待处理任务。Handler 自身也必须幂等，因为 provider 可能已接受请求而 worker 尚未收到响应。

选择一种默认 Runner

Admin 的 /jobs 页面显示状态、次数、等待时间、主体和安全错误信息，不暴露 payload JSON。admin_rw 可带审计说明重试失败的幂等任务或取消独立通知；积分、存储、生命周期和活动任务必须通过所属工作流取消。

Runner 行为

GET /api/cron/jobs 由 Authorization: Bearer $CRON_SECRET 保护。vercel.json 每五分钟调用一次；在其他平台必须自行调度。

Runner 使用 FOR UPDATE SKIP LOCKED 每次领取一个任务，允许 Cron 并发运行；租约为五分钟；单 handler 上限 20 秒，整次 drain 40 秒；默认最多尝试五次，从 30 秒开始指数退避；完成记录保留 14 天。它还会清理过期上传预留并扫描卡住的 Stripe 事件。

CRON_SECRET 必须与 BETTER_AUTH_SECRET 不同，且不能让 Cron 端点无保护暴露。

存活与就绪

GET 或 HEAD /api/health 只检查进程存活，不访问依赖。

GET /api/ready 检查生产环境配置、数据库和迁移、Redis 分布式限流以及队列状态。数据库、迁移、Redis 或必需配置失败会返回 503；队列失败只把报告标为 degraded，不会把 Web 服务摘除。

平台频繁探活使用 /api/health；部署完成和接收流量前使用 /api/ready。

运维清单

1. 设置至少 32 随机字节的 CRON_SECRET。
2. 确认调度器每五分钟调用。
3. 监控 cron.jobs 结构化日志。
4. 对 readiness 非 200 和 failed 队列增长告警。
5. Job payload 只做向后兼容的增量修改。

下一步： 在接收生产流量前，把 runner、调度器与 readiness 检查纳入部署与安全流程。