后台任务

Web 应用如何在每个平台上每分钟执行一轮自己的周期性工作,为什么一行锁就够,以及 /setup 怎样发现它停了。

Web 应用有一些不由请求触发的工作:重试失败的履约、收尾没人轮询的 AI 任务。这些工作集中在一个函数 runScheduledJobs() 里,它把每个任务各执行一轮。平台之间的差别只在于由谁来调用它。检查自己的部署见运行后台任务。

一轮,固定的任务列表

一轮按顺序执行各个任务。某个任务抛出异常会被记为失败,后面的任务照常执行。

任务作用
credit-sweep扩展点。模板的账本没有需要过期或补发的积分,所以它报告为零;加入会过期的积分时在这里实现
billing-fulfilments按退避间隔重试订单付款或退款时失败的履约
ai-channel-tasks推进没人轮询的异步服务商任务,让它们完成并结算积分
agent-maintenance仅在安装 agent-starter 后存在:让有未完成运行的 Cloudflare Agent 容器执行一轮维护。对通过 URL 访问的 Agent 服务不做任何事

这些任务属于 Web 应用,不属于 Agent 服务。不部署 Agent 时,除 agent-maintenance 外的任务全部照常执行。Agent 服务自己的循环不执行其中任何一个。

一轮的三种触发方式

部署方式触发方开关
Node 服务(Fly.io、Railway、Docker、VPS、pnpm dev)Web 进程内的循环:启动五秒后第一轮,之后每分钟一轮JOBS_IN_PROCESS,默认开启
Cloudflare Workerwrangler.jsonc 里的 Cron Trigger "crons": ["* * * * *"],由 Worker 入口的 scheduled 处理triggers 配置块
任意系统 cron、Kubernetes CronJob 或平台调度器调用 pnpm jobs:run你的调度器

Node 构建在服务进程加载时就启动循环,所以一个还没有流量的新部署也会重试履约。pnpm dev 不会执行服务端入口,循环在第一个请求到来时启动。Worker 不是长驻进程,也不允许持有定时器,所以循环不会在那里启动。设置 JOBS_IN_PROCESS=false 会关闭循环,把调度交给 pnpm jobs:run。

一行锁保证每分钟只执行一轮

触发可以重叠:每个副本都在运行循环,同时还可能有 cron 触发。锁是 config_settings 里的一行 jobs.next_run_at,值是 ISO 时间戳。

  1. 执行方用一条带条件的更新认领这一轮:只有当 jobs.next_run_at 不在未来时才把它往后移。只有一个调用方的更新会改到这一行,其余调用方更新了零行,返回 "skipped"。
  2. 认领时把时间戳往后推五分钟。执行方中途崩溃的话,锁会在这之后过期。
  3. 一轮结束时,jobs.next_run_at 设为本轮开始后一分钟,jobs.last_run_at 设为结束时间,jobs.last_report 写入本轮的 JSON 报告。

比较的是 ISO 时间戳字符串,在 SQLite、D1 和 Postgres 上排序结果一致。认领只有一条语句,因此不需要事务。

/setup 上的心跳

/setup 不保存任务状态标记。它每次读取 jobs.last_run_at 和 jobs.last_report 并判断:

状态/setup 显示
没有任何一轮的记录未就绪。新部署会在一分钟内记下第一轮;提示一直不消失说明没有任何东西在触发
上一轮在五分钟以前未就绪,并说明是多久以前
上一轮有任务失败未就绪,并列出每个失败任务的名称和错误
上一轮时间很近且全部成功就绪

每条提示的末尾都会说明 deploy.config.json 所记录的平台是怎样触发的:Cloudflare 的 Cron Trigger、Fly.io 的 min_machines_running = 1、Railway 的 Web 服务、Docker 的 Web 容器。这一项没有可以跳转的后台页面,因为它需要在部署平台上修复。

相关文件

src/server/jobs/scheduled.ts
src/server/jobs/credit-sweep.ts
src/server/db/repositories/scheduled-jobs.repository.ts
src/server/jobs/in-process.ts
src/server-entry.ts
src/server-entry.node.ts
scripts/jobs/run.ts
src/server/jobs/heartbeat.ts
src/server/functions/setup-readiness.ts

pnpm validate:optional-agent 会在当前配置的数据库上真实执行几轮并断言这把锁:一分钟内的第二次调用被跳过,两个并发调用只执行一轮,崩溃的执行方留下的锁会被接管。

下一步