定时任务配置指南

定时任务是自动化运维的重要组成部分，可以帮助你定期执行数据同步、缓存更新、报表生成等重复性工作。

本指南将介绍如何为 NEXTY.DEV 项目在 Vercel、Dokploy、Coolify 这几个主流部署平台上配置定时任务，让你的 SaaS 实现自动化管理。

准备工作

在开始配置定时任务之前，请确保完成以下准备步骤：

生成 CRON_SECRET

CRON_SECRET 是一个安全密钥，用于验证定时任务请求的合法性，防止未授权访问。

生成方法（任选其一）：

方法 A：使用 NEXTY.DEV 的 Cron Secret 生成器（推荐）

访问 https://nexty.dev/zh/tools/cron-secret-generator，免费，完全在浏览器本地生成，不会上传到任何服务器
复制生成的密钥

方法 B：使用其他在线工具

访问 https://generate-secret.vercel.app/32
复制生成的随机字符串

方法 C：使用命令行（Mac/Linux）

openssl rand -base64 32

生成后，请将该字符串添加到项目的环境变量 CRON_SECRET。

完成定时任务接口编写

定时任务的工作原理是：系统定期向你的应用发送 HTTP 请求，触发预先编写好的接口，接口内部包含具体的任务处理逻辑。因此，在配置定时任务之前，你需要：

在项目中创建定时任务接口（如: /api/cron/task1）
在接口中实现具体的业务逻辑
添加 CRON_SECRET 验证，确保只有合法请求才能触发任务

模板自带一个必须配置的定时任务 /api/cron/credits，见下一节。

内置定时任务：/api/cron/credits

从 v4.0.0 起，模板内置了 /api/cron/credits。只要你启用了订阅或积分功能，这个定时任务必须配置，否则以下三件事不会发生：

年付订阅的月度积分定投结算：年付套餐首月立即发放，剩余 11 次靠它按月滴灌
逾期未续费订阅的对账：补救丢失的续费 webhook，重放最新一张账单
PayPal 挂起捕获的对账：把 eCheck 等挂起付款推进为成功或失败

接口约定：

方法	鉴权	作用
`POST`	需要 `Authorization: Bearer $CRON_SECRET`	真正的调度入口，返回 `{ ok, at, drip, renewals, pendingCaptures }`
`GET`	不需要	仅健康检查，不结算任何东西，返回 `{ ok: true, status: 'healthy' }`

推荐频率：每分钟一次（* * * * *）。单次运行有 60 秒预算，每轮最多结算 100 条定投、20 条续费对账、20 条挂起捕获，积压会在后续几轮自动排空。接口没有跨轮次锁，慢的一轮和下一轮重叠也无害 —— 定投在订阅行锁上串行并复检，对账重放进幂等的履约层。

本地手工触发：

curl -X POST -H "Authorization: Bearer $CRON_SECRET" \
  http://localhost:3000/api/cron/credits

Vercel 平台配置

提示

Vercel 免费账号仅支持创建一个定时任务。

Vercel 使用 Vercel Cron Jobs 功能来运行定时任务。配置步骤如下：

在项目根目录创建或编辑 vercel.json 文件：

vercel.json

{
  "crons": [
    {
      "path": "/api/cron/task1",
      "schedule": "0 0 * * *"
    },
    {
      "path": "/api/cron/task2",
      "schedule": "0 2 * * 1"
    }
  ]
}

Cron 表达式说明：

0 0 * * * - 每天凌晨 0:00（UTC 时间）
0 2 * * 1 - 每周一凌晨 2:00（UTC 时间）

时区说明：Vercel Cron 使用 UTC 时间。

部署完成后，你可以在 Vercel 项目的 Settings > Cron Jobs 中可以看到已配置的定时任务。

注意：Vercel 上跑不了内置的 /api/cron/credits

Vercel Cron 只会发 GET 请求，而 /api/cron/credits 的 GET 只是健康检查。要在 Vercel 上用它，你需要自己加一层代理把调度转成带 Bearer 的 POST，或者改写该接口的鉴权方式。另外 Vercel 免费账号的定时任务频率也达不到推荐的每分钟一次。如果你的产品有年付订阅，建议改用下面的 Dokploy / Coolify 方案，或用外部调度器（如 GitHub Actions、cron-job.org）发 POST。

Dokploy 平台配置

Dokploy 提供了更灵活的定时任务配置方式，支持直接在管理面板中创建和管理。

配置步骤：

进入需要创建定时任务的服务管理面板
找到 Schedules 选项卡
点击创建新的定时任务

表单内容填写如下：

Task Name: 自定义任务名称
Schedule: Cron 表达式，如：0 0 * * *(每天凌晨0点执行)
Shell Type: 选择 Sh
Command: wget --header="Authorization: Bearer <上一步生成的 CRON_SECRET>" --post-data="" -O- https://<你的域名>/api/<定时任务接口路径>

配置内置的积分定时任务时，Schedule 填 * * * * *，Command 如下（命令在应用容器内执行，localhost:3000 直达本服务，$CRON_SECRET 从容器自身的环境变量读取，密钥既不出容器也不走公网）：

wget --header="Authorization: Bearer $CRON_SECRET" --post-data="" -qO- http://localhost:3000/api/cron/credits

部署代码后，如果想测试定时任务，可以点击面板上的执行按钮，这样会立即执行一次。

Coolify

Coolify 在应用页面的 Scheduled Tasks 里提供了同样的功能，填入相同的 Cron 表达式和上面的 wget 命令即可。

Cron 表达式参考

┌───────────── 分钟 (0 - 59)
│ ┌───────────── 小时 (0 - 23)
│ │ ┌───────────── 日期 (1 - 31)
│ │ │ ┌───────────── 月份 (1 - 12)
│ │ │ │ ┌───────────── 星期 (0 - 6) (周日=0)
│ │ │ │ │
* * * * *

示例：

0 2 * * * - 每天 2:00
0 2 * * 1 - 每周一 2:00
0 */6 * * * - 每 6 小时
0 0 1 * * - 每月 1 号 0:00