Menu

Cron Job Configuration Guide

cronジョブは自動運用に欠かせない要素であり、データ同期、キャッシュ更新、レポート生成などの反復的なタスクを定期的に実行するのに役立ちます。

このガイドでは、主流のデプロイプラットフォームであるVercel・Dokploy・CoolifyでNextyプロジェクトのcronジョブを設定する方法を紹介し、SaaSの自動管理を可能にします。

準備

cronジョブの設定を開始する前に、以下の準備手順を完了してください：

  1. CRON_SECRETの生成

CRON_SECRETは、cronジョブリクエストの正当性を検証し、不正なアクセスを防ぐために使用されるセキュリティキーです。

生成方法（いずれかを選択）：

方法A：NextyのCron Secretジェネレーターを使用（推奨）

  1. https://nexty.dev/ja/tools/cron-secret-generatorにアクセス。無料で、ブラウザ内だけで生成され、サーバーには一切送信されません
  2. 生成されたシークレットをコピー

方法B：他のオンラインツールを使用

  1. https://generate-secret.vercel.app/32にアクセス
  2. 生成されたランダム文字列をコピー

方法C：コマンドライン（Mac/Linux）を使用

openssl rand -base64 32

生成後、この文字列をプロジェクトの環境変数CRON_SECRETに追加してください。

  1. cronジョブエンドポイントの実装を完了

cronジョブの動作原理は、システムが定期的にアプリケーションへHTTPリクエストを送信し、特定のタスク処理ロジックを含む事前に作成されたエンドポイントをトリガーすることです。そのため、cronジョブを設定する前に以下が必要です：

  • プロジェクト内にcronジョブエンドポイントを作成（例：/api/cron/task1）
  • エンドポイントに具体的なビジネスロジックを実装
  • 正当なリクエストのみがタスクをトリガーできるようCRON_SECRET検証を追加

ボイラープレートには必ず設定すべき定期実行タスク /api/cron/credits が同梱されています。詳細は次のセクションを参照してください。

組み込みの定期実行タスク：/api/cron/credits

v4.0.0 以降、ボイラープレートには /api/cron/credits が同梱されています。サブスクリプションまたはクレジット機能を有効にする場合、この定期実行タスクの設定は必須です。設定しないと、次の 3 つが実行されません。

  • 年額サブスクリプションの月次クレジット・ドリップ決済：年額プランは初月を即時付与し、残り 11 回はこのタスクが毎月配分します
  • 更新遅延サブスクリプションの照合：失われた更新 Webhook を補償し、最新の請求書を再実行します
  • PayPal 保留中キャプチャの照合：eCheck などの保留中決済を成功または失敗へ前進させます

エンドポイントの仕様：

メソッド認証役割
POSTAuthorization: Bearer $CRON_SECRET が必要実際のスケジューリング入口。{ ok, at, drip, renewals, pendingCaptures } を返します
GET不要ヘルスチェックのみ。何も決済せず { ok: true, status: 'healthy' } を返します

推奨頻度：毎分 1 回（* * * * *）。1 回の実行は 60 秒の予算を持ち、1 ティックあたり最大 100 件のドリップ、20 件の更新照合、20 件の保留中キャプチャを処理します。滞留分は後続のティックで自動的に解消されます。ティック間のロックはなく、遅いティックが次のティックと重なっても無害です —— ドリップ決済はサブスクリプションの行ロックで直列化され、その下で再チェックし、照合は冪等なフルフィルメント層に再実行されるためです。

ローカル開発での手動実行：

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

Vercelプラットフォームの設定

注目すべき点

Vercelの無料アカウントでは、cronジョブを1つのみ作成できます。

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時（UTC時間）
  • 0 2 * * 1 - 毎週月曜日午前2時（UTC時間）

タイムゾーンに関する注意：Vercel CronはUTC時間を使用します。

デプロイ後、VercelプロジェクトのSettings > Cron Jobsで設定されたcronジョブを確認できます。

注意：組み込みの /api/cron/credits はそのままでは Vercel で動きません

Vercel Cron は GET リクエストしか送らず、GET /api/cron/credits はヘルスチェックにすぎません。Vercel で利用するには、スケジュールを Bearer ヘッダー付きの POST に変換するプロキシを自前で挟むか、エンドポイントの認証方式を書き換える必要があります。また、Vercel の無料アカウントでは推奨頻度である毎分 1 回に到達できません。年額サブスクリプションを販売する場合は、下記の Dokploy / Coolify の構成を選ぶか、外部スケジューラー（GitHub Actions、cron-job.org など）から POST を送ることをおすすめします。

Dokployプラットフォームの設定

Dokployは、管理パネルで直接作成および管理できる、より柔軟なcronジョブ設定方法を提供しています。

設定手順：

  1. cronジョブを作成する必要があるサービス管理パネルに入る
  2. Schedulesタブを見つける
  3. 新しいcronジョブを作成するためクリック
dokploy schedules
dokploy schedules

フォームに以下のように入力してください：

  • Task Name：任意のタスク名
  • Schedule：cron式、例：0 0 * * *（毎日深夜0時に実行）
  • Shell Type：Shを選択
  • Command：wget --header="Authorization: Bearer <前の手順で生成したCRON_SECRET>" --post-data="" -O- https://<あなたのドメイン>/api/<cronジョブエンドポイントのパス>

組み込みのクレジット定期実行タスクを設定する場合は、Schedule に * * * * * を指定し、以下のコマンドを使用します。コマンドはアプリコンテナ内で実行されるため、localhost:3000 が本サービスに直接到達し、$CRON_SECRET はコンテナ自身の環境変数から読み込まれます。シークレットはコンテナの外に出ず、公衆インターネットも経由しません：

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

コードのデプロイ後、cronジョブをテストしたい場合は、パネル上の実行ボタンをクリックして即座に実行できます。

dokploy schedules

Coolify

CoolifyではアプリケーションページのScheduled Tasksで同等の機能を提供しています。同じcron式と上記のwgetコマンドを入力してください。

cron式リファレンス

┌───────────── 分（0 - 59）
│ ┌───────────── 時（0 - 23）
│ │ ┌───────────── 日（1 - 31）
│ │ │ ┌───────────── 月（1 - 12）
│ │ │ │ ┌───────────── 曜日（0 - 6）（日曜日=0）
│ │ │ │ │
* * * * *

例：

  • 0 2 * * * - 毎日午前2時
  • 0 2 * * 1 - 毎週月曜日午前2時
  • 0 */6 * * * - 6時間ごと
  • 0 0 1 * * - 毎月1日午前0時