运行后台任务

确认定时任务在你的平台上运行,手动执行一轮,并在 /setup 提示它停止时知道该做什么。

履约重试和未完成的 AI 任务由一轮定时任务处理,它应该每分钟执行一次。多数部署下它已经在运行。本文说明如何确认这一点、如何手动执行一轮,以及 /setup 提示轮次停止时如何处理。锁和心跳的原理见后台任务。

准备工作

  • 一个已部署的项目,或数据库已迁移的本机项目。
  • 拥有 config.read 的管理员账号,用来打开 /setup。
  • 知道项目部署在哪个平台:deploy.config.json 的 platform 字段,见部署模型。

确认你的平台在执行任务

找到触发方

平台由什么触发检查什么
CloudflareWorker 的 Cron Triggerwrangler.jsonc 保留 "triggers": { "crons": ["* * * * *"] },且已部署的 Worker 列出了这个触发器
Fly.ioWeb 进程内的循环fly.toml 保留 min_machines_running = 1;停掉的机器什么也不会执行
RailwayWeb 服务内的循环Web 服务在运行
DockerWeb 容器内的循环容器在运行:docker compose ps
本机同一个循环,由 pnpm dev 收到的第一个请求启动打开任意页面一次

在 Node 平台上,除非设置了 JOBS_IN_PROCESS=false,循环默认开启。

决定是否改用外部 cron

没有特别理由就保留进程内循环。需要把调度移出 Web 进程时(例如 Web 机器会缩容到零),在 Web 应用的环境里设置 JOBS_IN_PROCESS=false,再让调度器每分钟执行一次下面的命令,数据库变量与 Web 应用保持一致:

pnpm jobs:run

循环和 cron 同时存在也是安全的。锁行保证每一轮只有一个执行方执行,其余的跳过。

手动执行一轮

在 .env 指向目标数据库的检出目录里运行:

pnpm jobs:run

它会打印这一轮的报告,有任务失败时退出码非零:

{
  "startedAt": "2026-11-17T08:00:00.000Z",
  "finishedAt": "2026-11-17T08:00:00.412Z",
  "jobs": [
    { "name": "credit-sweep", "ok": true, "counts": { "expiredUsers": 0, "granted": 0 } },
    { "name": "billing-fulfilments", "ok": true, "counts": { "attempted": 0, "succeeded": 0 } },
    { "name": "ai-channel-tasks", "ok": true, "counts": { "polled": 0 } }
  ]
}

如果打印的是 "skipped",说明最近一分钟内已有别的执行方拿走了这一轮。这是正常现象,等一分钟再执行。安装了 agent-starter 的项目还有第四个任务 agent-maintenance。

读懂 /setup 上的警告

打开 /setup,找到定时任务这一项。每次加载页面时,页面都根据最近一次记录的轮次重新计算这一项的状态。

这一项的提示含义处理
No scheduled round has been recorded数据库建好之后还没有执行过任何一轮新部署等一分钟。一直不消失说明上表中的触发方缺失
The last scheduled round ran N minutes ago超过五分钟没有新的一轮检查你所在平台的触发方,提示里会指出。恢复之前,履约重试和 AI 任务轮询都在等待
The last round had failures某个任务抛出了异常读提示里的任务名和错误,修复原因,再运行 pnpm jobs:run 查看该任务的结果
Last round less than a minute ago, every job succeeded轮次在正常执行无需处理

某个任务失败不会影响同一轮里的其它任务,下一轮还会再试。

验证任务在运行

  • /setup 的定时任务一项为就绪,上一轮距今不超过几分钟。
  • 两分钟后刷新 /setup,上一轮的时间已更新。
  • config_settings 中 jobs.last_run_at 是一个很近的 ISO 时间戳,jobs.last_report 是那一轮的报告。
  • pnpm validate:optional-agent 通过。发布前,pnpm smoke:node(先 pnpm build:node)或 pnpm smoke:worker(先 pnpm build)会在一次性数据库上启动构建产物,并检查确实记录了一轮。

下一步