定时任务（Cron）

什么是定时任务？

定时任务是您项目中的常规 HTTP 处理程序，FloopFloop 会按照 您配置的定期计划调用它——每 5 分钟、每小时、每天午夜， 随您配置。典型用途：轮询交易所的市场数据、刷新缓存、 发送每日摘要邮件、评估策略并下单。

每次触发都是对您项目中 /api/cron/* 路由的一个POST 请求，带有项目范围的持有者令牌，您在执行 任何工作前需要验证该令牌。

编写处理程序

您的处理程序是一个普通的 Next.js POST 路由。在执行任何工作前， 请对照 process.env.FLOOP_CRON_TOKEN 验证持有者令牌—— 任何其他请求都应收到 401：

// src/app/api/cron/rebalance/route.ts
import { NextRequest, NextResponse } from "next/server";

export const dynamic = "force-dynamic";

export async function POST(request: NextRequest) {
  const expected = `Bearer ${process.env.FLOOP_CRON_TOKEN ?? ""}`;
  if (request.headers.get("authorization") !== expected) {
    return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
  }

  // Do your work here — query data, call APIs, etc.
  return NextResponse.json({ ok: true });
}

FLOOP_CRON_TOKEN 环境变量由 FloopFloop 管理——它在 构建时内置到您项目的运行时中，不会出现在 Secrets UI 中。

任务的注册方式

定时任务由模板声明，而不是手动添加。模板会在其根目录附带 一个 floop.crons.json 文件：

{
  "jobs": [
    {
      "name": "evaluate-strategy",
      "cron": "*/5 * * * *",
      "path": "/api/cron/evaluate-strategy",
      "enabled": true
    }
  ]
}

在您第一次成功部署后，FloopFloop 会读取此清单并为您的项目注册 任务。注册是幂等的——重新部署相同的模板不会重复任务或重置任何 运行历史。

如果您的应用需要不同的计划，请在聊天中请求 FloopFloop 更新模板的floop.crons.json；新的执行频率将在下次部署后生效。

运行状态

每次触发都会记录状态：ok、error 或 timeout。 从您的处理程序返回非 2xx HTTP 状态以将运行标记为错误——响应正文 （最多 500 个字符）将作为错误消息被捕获，以便调试。

限制与约束

• 每个项目最多 10 个定时任务。 在 floop.crons.json中声明超过 10 个条目的模板，超出部分将在注册时被拒绝。
• 最小间隔 1 分钟。 亚分钟级别的 cron 表达式 将在注册时被拒绝。
• 每次触发 30 秒的请求超时。 如果您的处理程序 花费时间更长，调度器会记录 timeout 并继续。
• 仅在您的项目已部署且处于活跃状态时触发——新创建的项目和 已暂停的项目会被静默跳过，并在重新激活后自动恢复。
• 路径必须匹配 /api/cron/<name>—— 此限制将 cron 触发与您的公开路由隔离开来。