Back to Details

crontap-replace-vercel-cron

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Replace Vercel Cron

替换 Vercel Cron

Keep Vercel as the runtime and move only the clock. Crontap calls the deployed route over HTTPS.
保留 Vercel 作为运行时环境，仅迁移“时钟”。Crontap 通过 HTTPS 调用已部署的路由。

Prerequisites

前置条件

Before using the required tools, check whether they are available. If any are missing, stop and offer the user exactly two choices:
  1. Connect Crontap MCP at 
    https://mcp.crontap.com/mcp
    . MCP access works on every Crontap tier.
  2. Configure 
    $CRONTAP_CLIENT_ID
    and 
    $CRONTAP_API_KEY
    for the raw API. Raw API access requires Ultra.
Do not silently choose a path or continue until the user selects one.
  • Read the existing 
    vercel.json
    cron path and expression.
  • Confirm the production hostname and route method.
  • Protect the route with a dedicated secret header.
  • Make the handler idempotent before cutover.
在使用所需工具前，先检查它们是否可用。如果有任何缺失，请停止操作，并且只向用户提供以下两个选择：
  1. 在 
    https://mcp.crontap.com/mcp
    连接 Crontap MCP。所有 Crontap 套餐均支持 MCP 访问。
  2. 为原始 API 配置 
    $CRONTAP_CLIENT_ID
    和 
    $CRONTAP_API_KEY
    。原始 API 访问需要 Ultra 套餐。
不要在未告知用户的情况下擅自选择方案，也不要在用户选择之前继续操作。
  • 读取现有 
    vercel.json
    中的 cron 路径和表达式。
  • 确认生产主机名和请求方法。
  • 使用专用的 secret header 保护该路由。
  • 在切换前让处理程序具备幂等性。

Cutover workflow

切换流程

  1. Add or verify route authentication in the Vercel application.
  2. Test the protected production route with a controlled request.
  3. Choose a cutover time and explain the brief overlap or gap risk.
  4. Remove or disable the 
    vercel.json
    schedule.
  5. Create the matching Crontap schedule immediately.
  6. Verify the resolved timezone, next runs, and first history entry.
  7. Keep a rollback plan: pause Crontap, restore the Vercel cron, then deploy.
Do not leave both clocks enabled. Two schedulers can create duplicate side effects even when both are operating correctly.
  1. 在 Vercel 应用中添加或验证路由身份验证。
  2. 使用受控请求测试受保护的生产路由。
  3. 选择切换时间，并说明短暂重叠或间隔风险。
  4. 移除或禁用 
    vercel.json
    中的调度。
  5. 立即创建匹配的 Crontap 调度。
  6. 验证解析后的时区、下次运行时间和首条历史记录。
  7. 保留回滚方案：暂停 Crontap，恢复 Vercel cron，然后部署。
不要同时启用两个调度器。即使两者都正常工作，两个调度器也可能会产生重复副作用。

MCP examples

MCP 示例

Create the replacement:
json
{
  "tool": "create_schedule",
  "arguments": {
    "url": "https://app.example.com/api/cron/daily-report",
    "cron": "0 9 * * 1-5",
    "timezone": "UTC",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer <secret-from-secure-store>"
    },
    "label": "Vercel daily report"
  }
}
Pause for rollback or maintenance:
json
{
  "tool": "pause_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}
Resume the same configuration:
json
{
  "tool": "resume_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}
Confirm the selected ID before pause or resume.
创建替代调度：
json
{
  "tool": "create_schedule",
  "arguments": {
    "url": "https://app.example.com/api/cron/daily-report",
    "cron": "0 9 * * 1-5",
    "timezone": "UTC",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer <secret-from-secure-store>"
    },
    "label": "Vercel daily report"
  }
}
暂停以进行回滚或维护：
json
{
  "tool": "pause_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}
恢复相同配置：
json
{
  "tool": "resume_schedule",
  "arguments": {
    "scheduleId": "<schedule-id>"
  }
}
暂停或恢复前，请确认所选的 ID。

Protected route pattern

受保护路由模式

Compare the request authorization header with a server-only environment variable. Return 401 before performing work when it does not match. Do not use a secret in the query string or route path.
If the route queues work, persist the logical schedule period as an idempotency key before enqueueing. Return success only after the queue accepts the job.
将请求的 authorization header 与仅服务器端可见的环境变量进行比较。不匹配时，在执行工作之前返回 401。不要在查询字符串或路由路径中使用 secret。
如果路由将任务加入队列，请在入队前将逻辑调度周期作为幂等键持久化。只有在队列接受任务后才返回成功。

REST fallback

REST 回退方案

REST creation requires Ultra API access:
bash
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://app.example.com/api/cron/daily-report",
    "interval": "0 9 * * 1-5",
    "timezone": "UTC",
    "verb": "GET",
    "headers": {
      "Authorization": "Bearer <secret-from-secure-store>"
    },
    "label": "Vercel daily report"
  }'
Use MCP for non-Ultra accounts.
通过 REST 创建需要 Ultra API 访问权限：
bash
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://app.example.com/api/cron/daily-report",
    "interval": "0 9 * * 1-5",
    "timezone": "UTC",
    "verb": "GET",
    "headers": {
      "Authorization": "Bearer <secret-from-secure-store>"
    },
    "label": "Vercel daily report"
  }'
对于非 Ultra 账户，请使用 MCP。

Verification

验证

  • Confirm the old Vercel schedule is absent from the deployed configuration.
  • Confirm only one Crontap schedule targets the route.
  • Verify a 401 without the secret and success with the secret.
  • Inspect the first real run and the application-level side effect.
  • 确认已部署的配置中不再包含旧的 Vercel 调度。
  • 确认只有一个 Crontap 调度指向该路由。
  • 验证无 secret 时返回 401，有 secret 时成功。
  • 检查首次真实运行和应用层面的副作用。

Safety and plan limits

安全与方案限制

  • Never paste the production route secret into the skill, repository, or chat.
  • Pause before restoring the old scheduler during rollback.
  • Preserve the original cadence's UTC semantics unless the user explicitly chooses a local IANA timezone.
  • On a cap or cadence error, present the returned four-option ladder and smallest viable option.
  • 切勿将生产路由 secret 粘贴到 skill、代码仓库或聊天中。
  • 回滚并恢复旧调度器之前，先暂停调度。
  • 除非用户明确选择本地 IANA 时区，否则保留原始调度频率的 UTC 语义。
  • 达到上限或出现频率错误时，展示返回的四选项阶梯以及最小可行选项。

Troubleshooting

故障排查

  • A Vercel 401 means the configured schedule header and route secret differ.
  • A 404 often means the route is not deployed on the hostname being called.
  • Duplicate output means both clocks are active or endpoint idempotency failed.
  • A timeout may require durable queueing instead of long synchronous work.
  • Vercel 返回 401，表示已配置的调度 header 与路由 secret 不一致。
  • 返回 404，通常表示路由尚未部署到被调用的主机名上。
  • 输出重复，表示两个调度器同时处于启用状态或端点幂等性处理失败。
  • 请求超时，可能需要使用持久化队列，而不是执行长时间同步工作。

References

参考资料