用途:为 Vercel cron 任务、Next.js API 路由处理器和后端周期任务提供定时任务管理规范,适用于创建新 cron 任务、在 vercel.json 添加条目、编写 /api/cron/* 路由、实现后端周期任务(APScheduler、asyncio)以及审查 cron 表达式和防重叠逻辑。
主要能力:提出定时任务四原则——鉴权(每个端点校验 CRON_SECRET)、幂等(重跑结果一致)、可观测(记录开始、结束、耗时、结果)、防重叠(并发调用不破坏共享状态)。给出 Next.js 路由处理器模板、路由文件位置约定、Vercel cron 注册方式,以及数据库锁与内存标志两种防重叠模式,并附 cron_locks 表结构。后端部分介绍 FastAPI lifespan 启停后台任务与 APScheduler 集成。还包含 cron 表达式语法与常用表达式、UTC 与 AEST/AEDT 时区换算、幂等写法、结构化日志事件、连续失败告警、反模式表和新建任务检查清单。
使用方式:路由处理器先校验 Authorization 头是否为 Bearer ${process.env.CRON_SECRET},再执行任务逻辑并记录日志;新任务在 apps/web/app/api/cron/{job-name}/route.ts 创建,并在 apps/web/vercel.json 的 crons 数组注册 path 与 schedule。防重叠可用数据库锁(acquireLock/releaseLock)或 ScheduledAuditRunner 的内存 Set 标志。后端可用 create_task 启动周期函数,或用 AsyncIOScheduler 配合 CronTrigger,时区设为 Australia/Brisbane。
限制:资料未提供安装命令、依赖版本、收费与价格信息;示例中的 Supabase、logger 等为项目内既有模块,需按实际环境替换。Vercel cron 以 UTC 运行,需自行换算本地时间。