پرش به مطلب اصلی

Cron Jobs (زمان‌بندی)

🖼️
صفحه مدیریت Cron Jobs در داشبوردplaceholder — تصویر را اینجا جایگزین کنید

Cron Jobs به شما امکان می‌دهد دستورات را در زمان‌های مشخص به‌طور خودکار در محیط اپ خود اجرا کنید.

موارد کاربرد​

  • پشتیبان‌گیری خودکار: هر شب ساعت ۲ بامداد یک نسخه پشتیبان از دیتابیس بگیرید.
  • پاک‌سازی دوره‌ای: هر هفته فایل‌های موقت یا لاگ‌های قدیمی را حذف کنید.
  • ارسال گزارش: هر روز ساعت ۸ صبح گزارش آماری ایمیل شود.
  • جمع‌آوری متریک: هر ۱۵ دقیقه داده‌های تجزیه‌وتحلیل را به‌روزرسانی کنید.

پیش‌نیازها​

  • یک اپلیکیشن در حال اجرا در ابرکلیک
  • دسترسی به CLI یا API ابرکلیک

ایجاد Cron Job از طریق CLI​

abrclick cron create <app-slug> \
  --name "backup-db" \
  --schedule "0 2 * * *" \
  --command "npm run backup"

پارامترها:

  • <app-slug> — شناسه اپ (الزامی)
  • --name <name> — نام Cron Job (الزامی)
  • --schedule <cron-expr> — عبارت cron استاندارد ۵ فیلدی (الزامی)
  • --command <cmd> — دستور اجرا (الزامی)

خروجی:

✓ Cron Job backup-db ایجاد شد
  ID: cron-abc123
  زمان‌بندی: 0 2 * * * (هر روز ساعت ۲ بامداد)

ایجاد Cron Job از طریق API​

Endpoint: POST /v1/crons

Body:

{
  "appId": "app-xyz789",
  "name": "backup-db",
  "schedule": "0 2 * * *",
  "command": "npm run backup"
}

Response:

{
  "data": {
    "id": "cron-abc123",
    "appId": "app-xyz789",
    "name": "backup-db",
    "schedule": "0 2 * * *",
    "command": "npm run backup",
    "enabled": true,
    "createdAt": "2026-07-20T10:00:00Z"
  }
}

فرمت زمان‌بندی Cron​

عبارت cron شامل ۵ فیلد است:

┌───── دقیقه (0 - 59)
│ ┌───── ساعت (0 - 23)
│ │ ┌───── روز ماه (1 - 31)
│ │ │ ┌───── ماه (1 - 12)
│ │ │ │ ┌───── روز هفته (0 - 7) (یکشنبه = 0 یا 7)
│ │ │ │ │
* * * * *

مثال‌های رایج​

زمان‌بندیتوضیح
0 3 * * *هر روز ساعت ۳ صبح
0 */6 * * *هر ۶ ساعت یکبار
*/15 * * * *هر ۱۵ دقیقه
0 0 * * 0هر یکشنبه نیمه‌شب
30 2 1 * *اول هر ماه ساعت ۲:۳۰ بامداد
0 9 * * 1-5روزهای هفته ساعت ۹ صبح
نکته

از ابزارهای آنلاین مانند crontab.guru برای تست عبارت cron استفاده کنید.

مثال واقعی — پاک‌سازی لاگ‌های قدیمی​

۱. ایجاد اسکریپت در پروژه​

// scripts/cleanup-logs.js
const fs = require('fs');
const path = require('path');

const logsDir = path.join(__dirname, '../logs');
const maxAge = 7 * 24 * 60 * 60 * 1000; // 7 روز

fs.readdirSync(logsDir).forEach(file => {
  const filePath = path.join(logsDir, file);
  const stat = fs.statSync(filePath);
  if (Date.now() - stat.mtime.getTime() > maxAge) {
    fs.unlinkSync(filePath);
    console.log(`حذف شد: ${file}`);
  }
});

console.log('پاک‌سازی لاگ‌ها انجام شد.');

۲. افزودن اسکریپت به package.json​

{
  "scripts": {
    "cleanup": "node scripts/cleanup-logs.js"
  }
}

۳. ایجاد Cron Job​

abrclick cron create my-app \
  --name "cleanup-logs" \
  --schedule "0 3 * * *" \
  --command "npm run cleanup"

مشاهده لیست Cron Jobs​

از طریق CLI​

abrclick cron list

خروجی:

┌──────────────┬────────────────┬──────────────────┬─────────┐
│ ID           │ Name           │ Schedule         │ Enabled │
├──────────────┼────────────────┼──────────────────┼─────────┤
│ cron-abc123  │ backup-db      │ 0 2 * * *        │ ✓       │
│ cron-def456  │ cleanup-logs   │ 0 3 * * *        │ ✓       │
└──────────────┴────────────────┴──────────────────┴─────────┘

از طریق API​

Endpoint: GET /v1/crons

مشاهده جزئیات یک Cron Job​

از طریق CLI​

abrclick cron info cron-abc123

از طریق API​

Endpoint: GET /v1/crons/:id

Response:

{
  "data": {
    "id": "cron-abc123",
    "appId": "app-xyz789",
    "name": "backup-db",
    "schedule": "0 2 * * *",
    "command": "npm run backup",
    "enabled": true,
    "lastRun": "2026-07-20T02:00:00Z",
    "nextRun": "2026-07-21T02:00:00Z"
  }
}

ویرایش Cron Job​

از طریق CLI​

abrclick cron update cron-abc123 \
  --schedule "0 4 * * *" \
  --command "npm run backup:full"
اطلاع

فقط فیلدهایی که مشخص کنید تغییر می‌کنند. بقیه دست‌نخورده باقی می‌مانند.

از طریق API​

Endpoint: PATCH /v1/crons/:id

Body:

{
  "schedule": "0 4 * * *",
  "command": "npm run backup:full"
}

اجرای فوری (یک‌بار اکنون)​

گاهی می‌خواهید یک Cron Job را بدون انتظار برای زمان‌بندی بعدی اجرا کنید.

از طریق CLI​

abrclick cron run cron-abc123

خروجی:

✓ Cron Job backup-db اکنون اجرا شد
  Job Name: manual-abc123-1642684800

از طریق API​

Endpoint: POST /v1/crons/:id/run

Response:

{
  "data": {
    "jobName": "manual-abc123-1642684800",
    "status": "running"
  }
}

مشاهده تاریخچه اجرا​

از طریق CLI​

abrclick cron runs cron-abc123

خروجی:

┌────────────────────────────┬──────────┬────────────────────┐
│ Job Name                   │ Status   │ Started At         │
├────────────────────────────┼──────────┼────────────────────┤
│ backup-db-1642684800       │ success  │ 2026-07-20 02:00   │
│ backup-db-1642598400       │ success  │ 2026-07-19 02:00   │
│ backup-db-1642512000       │ failed   │ 2026-07-18 02:00   │
└────────────────────────────┴──────────┴────────────────────┘

از طریق API​

Endpoint: GET /v1/crons/:id/runs

Response:

{
  "data": [
    {
      "jobName": "backup-db-1642684800",
      "status": "success",
      "startedAt": "2026-07-20T02:00:00Z",
      "finishedAt": "2026-07-20T02:05:12Z"
    }
  ]
}

مشاهده لاگ یک اجرا​

از طریق CLI​

abrclick cron logs cron-abc123 backup-db-1642684800

از طریق API​

Endpoint: GET /v1/crons/:id/runs/:jobName/logs

Response:

{
  "data": {
    "logs": "شروع پشتیبان‌گیری...\nاتصال به دیتابیس...\n✓ پشتیبان‌گیری انجام شد.\n"
  }
}

حذف Cron Job​

از طریق CLI​

abrclick cron delete cron-abc123

از طریق API​

Endpoint: DELETE /v1/crons/:id

متغیرهای محیطی در Cron Jobs​

Cron Jobs دسترسی کامل به متغیرهای محیطی اپ دارند. اگر در اپ خود DATABASE_URL تنظیم کرده‌اید، دستور cron نیز به آن دسترسی دارد.

مثال:

abrclick cron create my-app \
  --name "db-backup" \
  --schedule "0 2 * * *" \
  --command "pg_dump \$DATABASE_URL > backup.sql"
اطلاع

متغیرهای محیطی به‌صورت خودکار در زمان اجرا تزریق می‌شوند. نیازی به تنظیم جداگانه نیست.

رفع خطاهای رایج​

خطا: invalid cron expression​

علت: فرمت زمان‌بندی اشتباه است.
راه‌حل: مطمئن شوید عبارت cron شامل ۵ فیلد است. از crontab.guru برای تست استفاده کنید.

خطا: command not found​

علت: دستور در محیط اپ موجود نیست.
راه‌حل: مطمئن شوید دستور در package.json scripts تعریف شده یا باینری آن نصب است.

خطا: app not found​

علت: appId اشتباه است یا اپ حذف شده.
راه‌حل: لیست اپ‌ها را با abrclick apps list بررسی کنید.

Cron Job اجرا نمی‌شود​

علت: اپ متوقف (stopped) است یا Cron Job غیرفعال شده.
راه‌حل:

  • وضعیت اپ را بررسی کنید: abrclick apps info <app-slug>
  • مطمئن شوید Cron Job فعال است: abrclick cron info <cron-id>

لاگ خطا می‌دهد اما Cron Job اجرا شده​

علت: دستور با exit code غیرصفر تمام شده.
راه‌حل: لاگ را با abrclick cron logs <cron-id> <job-name> بررسی و خطا را رفع کنید.

API endpoints کامل​

روشمسیرتوضیح
POST/v1/cronsایجاد Cron Job
GET/v1/cronsلیست تمام Cron Jobs
GET/v1/crons/:idجزئیات Cron Job
DELETE/v1/crons/:idحذف Cron Job
POST/v1/crons/:id/runاجرای فوری یک‌بار
GET/v1/crons/:id/runsتاریخچه اجرا
GET/v1/crons/:id/runs/:jobName/logsلاگ یک اجرا

مطالب مرتبط​