运行后台任务
确认定时任务在你的平台上运行,手动执行一轮,并在 /setup 提示它停止时知道该做什么。
履约重试和未完成的 AI 任务由一轮定时任务处理,它应该每分钟执行一次。多数部署下它已经在运行。本文说明如何确认这一点、如何手动执行一轮,以及 /setup 提示轮次停止时如何处理。锁和心跳的原理见后台任务。
准备工作
- 一个已部署的项目,或数据库已迁移的本机项目。
- 拥有
config.read的管理员账号,用来打开/setup。 - 知道项目部署在哪个平台:
deploy.config.json的platform字段,见部署模型。
确认你的平台在执行任务
找到触发方
| 平台 | 由什么触发 | 检查什么 |
|---|---|---|
| Cloudflare | Worker 的 Cron Trigger | wrangler.jsonc 保留 "triggers": { "crons": ["* * * * *"] },且已部署的 Worker 列出了这个触发器 |
| Fly.io | Web 进程内的循环 | fly.toml 保留 min_machines_running = 1;停掉的机器什么也不会执行 |
| Railway | Web 服务内的循环 | Web 服务在运行 |
| Docker | Web 容器内的循环 | 容器在运行: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)会在一次性数据库上启动构建产物,并检查确实记录了一轮。