crontap-supabase-edge-function-cron

调度 Supabase Edge Function

使用 Supabase pg_cron 执行仅限 SQL 的数据库维护。如果定期执行的任务是 HTTP Edge Function，且需要使用外部调度器，请采用此模式。

前提条件

使用所需工具前，请先检查它们是否可用。如果有任何工具不可用，请停止并向用户提供且仅提供以下两个选项：

1. 连接 Crontap MCP：https://mcp.crontap.com/mcp。所有 Crontap 套餐均支持 MCP 访问。
2. 为原始 API 配置 $CRONTAP_CLIENT_ID 和 $CRONTAP_API_KEY。原始 API 访问需要 Ultra。

在用户做出选择前，不要擅自选择路径或继续操作。

• 创建调度前，先部署函数。
• 确保函数对同一个逻辑周期具有幂等性。
• 使用专用的服务端 cron 密钥保护函数。
• 切勿将 Supabase 服务角色密钥发送给 Crontap。

函数安全模式

读取专用标头或 bearer 值，并在执行任何操作前将其与仅限服务端使用的环境变量进行比较。如果函数禁用了 Supabase 网关 JWT 验证，则必须进行此应用层检查。

限制函数响应的大小。对于耗时较长的工作，应将任务持久化加入队列，并且仅在队列接受任务后返回成功。

工作流

1. 部署 Edge Function 并配置其 cron 密钥。
2. 在受控环境中分别使用和不使用密钥手动调用该函数。
3. 确认预期的状态码和幂等性行为。
4. 使用已部署的 HTTPS URL 创建 Crontap 调度。
5. 验证解析后的执行频率和首次保留的运行记录。

MCP 示例

{
  "tool": "create_schedule",
  "arguments": {
    "url": "https://project-ref.supabase.co/functions/v1/nightly-cleanup",
    "text": "every day at 02:00",
    "timezone": "UTC",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer <cron-secret-from-secure-store>",
      "Content-Type": "application/json"
    },
    "body": {
      "source": "crontap"
    },
    "label": "Supabase nightly cleanup"
  }
}

使用 Supabase 项目 URL 中的实际项目引用。不要将密钥放入函数 URL 或 JSON 请求正文中。

REST 备用方案

REST 需要 Ultra API 访问权限：

curl --fail-with-body https://api.crontap.com/v1/schedule \
  -X POST \
  -H "ClientId: $CRONTAP_CLIENT_ID" \
  -H "ApiKey: $CRONTAP_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "url": "https://project-ref.supabase.co/functions/v1/nightly-cleanup",
    "interval": "0 2 * * *",
    "timezone": "UTC",
    "verb": "POST",
    "headers": {
      "Authorization": "Bearer <cron-secret-from-secure-store>",
      "Content-Type": "application/json"
    },
    "data": {"source": "crontap"},
    "label": "Supabase nightly cleanup"
  }'

条件允许时，优先使用 MCP。

验证

• 不带 cron 密钥的请求会在产生任何副作用前返回 401。
• 带有密钥的请求会返回预期的成功状态。
• 对同一逻辑周期发送两次请求，只会产生一个持久化副作用。
• Crontap 历史记录中的结果与同一时刻的 Supabase 函数日志相符。

安全与套餐限制

• 不要将 SUPABASE_SERVICE_ROLE_KEY 用作调度凭据。
• 将函数限定为范围最小的定期操作。
• 如果 Supabase 项目可能暂停，请记住：外部时钟可以暴露故障，但无法让不可用的项目执行任务。
• 如果 Crontap 拒绝该执行频率或容量，请提供返回的四档选项，以及满足需求的最小选项。

故障排查

• Supabase 401 表示网关或函数授权拒绝了该请求。
• Supabase 404 通常表示项目引用、函数 slug 或部署环境有误。
• 如果返回 2xx 但未执行任务，请检查应用日志和幂等性记录。
• 超时问题最好通过持久化入队解决，而不是采用激进的重试策略。

参考资料

• Crontap Agent Skills 目录
• Supabase cron 作业
• Supabase Edge Function cron 作业
• Cron 故障排查
• 实时 REST API 参考