功能与集成
定时任务 (Cron)
每日 Cron 是全系统的对账兜底——它跑什么、为什么这样设计、怎么加你自己的任务。
Cloudflare Workers 的 Cron Triggers
在 wrangler.jsonc 里声明,到点调用 Worker 的 scheduled 处理器——不需要额外服务器。
模板配了每日 03:00 UTC 一趟,入口在 src/worker.ts#scheduled。
设计原则:事件驱动尽力而为,Cron 负责最终一致
所有实时链路(webhook、better-auth hooks)都是 best-effort——网络抖动、进程重启都可能漏掉 一次同步。模板的做法不是把实时链路做"绝对可靠"(做不到),而是让每日 Cron 把状态对齐: 每一步都幂等,漏一天补一天,重复跑无害。给自己加任务时建议沿用这个思路——事件驱动求快, Cron 求对。
每日一趟都跑什么
按 src/worker.ts#scheduled 里的顺序:
| 任务 | 做什么 | 跳过条件 |
|---|---|---|
| 维护清理 | 过期 session/verification、陈旧限流行(maintenance/cleanup.ts) | — |
| 孤儿组织清扫 | 删号后残留的空组织;持活跃座位订阅的跳过并告警(那行是对账 Stripe 的唯一线索) | — |
| 座位对账 | 组织成员数与 Stripe 订阅 quantity 对齐(实时同步靠 organizationHooks,这里兜底) | 未配 Stripe |
| Referral 补结 | 结算时"还没有组织"而跳过的奖励在这里追上(按 ref 幂等) | — |
| Drip 邮件 | D0/D3/D7 生命周期邮件,claim-before-send 幂等 | 未配 RESEND_API_KEY(不能白烧 claim) |
| 席位交付对账 | 确认已接受的仓库邀请、重发 7 天过期的邀请;表外 collaborator 只告警绝不动手 | 未配 GitHub 交付 |
| 审计保留期 | 清理超过 180 天的审计行(append-only 表的唯一删除路径) | — |
细节分别见 组织与团队、增长、 License 与代码交付、安全包。
加你自己的任务
- 频率改
wrangler.jsonc→triggers.crons(cron 表达式数组,可配多条;多条时可在scheduled里按controller.cron分流)。 - 逻辑追加到
src/worker.ts#scheduled。每步独立try/catch或保证幂等,别让一个任务 的异常放弃后面所有任务。
Cron 也受 Workers 的 CPU 时间限制。大批量数据处理建议分页、限量(模板里的清理任务都带 batch 上限),更重的活考虑 Queues。
本地测试
pnpm dev(vite)不会触发 scheduled。两个办法:
- 单元测试直接调用被 cron 使用的纯函数(模板的 workers 池测试就是这么覆盖对账逻辑的);
- 或用
wrangler dev --test-scheduled起本地 Worker,再curl "http://localhost:8787/__scheduled?cron=0+3+*+*+*"手动触发一趟。