تنظیم منطقه زمانی و Schedule Trigger در n8n
Schedule Trigger در n8n ممکن است چند ساعت خطا کند، چون 3 تنظیم TZ، GENERIC_TIMEZONE و منطقه زمانی workflow را میخواند. هر سه را درست تنظیم کنید.
چرا Schedule Trigger در n8n در ساعت اشتباه اجرا میشود
Schedule Trigger در n8n در ساعت اشتباه اجرا میشود، زیرا n8n منطقهٔ زمانی را از 3 محل جداگانه میخواند و اصلاح یکی از آنها فقط بخشی از مشکل را برطرف میکند. این 3 محل عبارتاند از متغیر TZ خود container، مقدار پیشفرض instance یعنی GENERIC_TIMEZONE، و منطقهٔ زمانی تنظیمشده در یک workflow مشخص. هر 3 مورد را یکبار تنظیم کنید تا همهٔ scheduleهایی که پس از آن ایجاد میکنید، در زمان مورد انتظار اجرا شوند.
ابتدا یک تصور نادرست را اصلاح کنیم. یک n8n جدید و self-hosted، scheduleها را بر اساس UTC (زمان هماهنگ جهانی) اجرا نمیکند. ساعت container برابر UTC است، زیرا image رسمی هیچ TZای تنظیم نمیکند. زمانبندی لایهٔ جداگانهای است و مقدار پیشفرض مستندشدهٔ n8n برای GENERIC_TIMEZONE، America/New_York است (تا اکتبر 2026). بنابراین، یک instance بدون تغییر، Schedule Triggerها را بر اساس زمان نیویورک اجرا میکند. به همین دلیل اختلاف زمانی گزارششده معمولاً با فاصلهٔ واقعی کاربر از UTC مطابقت ندارد. کاربری در برلین که زمان 06:00 را تعیین میکند، اجرای آن را در ساعت 12:00 به وقت محلی میبیند؛ همچنین در 11:00 طی هفتههای ماه مارس و هفتهٔ تغییر ماههای اکتبر و نوامبر اجرا میشود، زمانی که ایالات متحده از ساعت تابستانی استفاده میکند اما اروپا چنین نمیکند.
سه لایه منطقه زمانی و اولویت آنها
TZ منطقه زمانی سیستمعامل داخل کانتینر است. مستندات n8n آن را متغیری توصیف میکنند که منطقه زمانی سیستم را تنظیم میکند تا خروجی اسکریپتها و دستوراتی مانند date را کنترل کند. این متغیر تعیین میکند که date داخل کانتینر چه چیزی را چاپ کند، چه برچسب زمانی در خطوط لاگ کانتینر ثبت شود، new Date() در یک Code node چه مقداری برگرداند و هر اسکریپت shell که در آنجا اجرا میکنید چه زمانی را ببیند. این متغیر هیچ تأثیری بر زمان اجرای Schedule Trigger ندارد.
GENERIC_TIMEZONE منطقه زمانی نمونه n8n است. مستندات آن را منطقه زمانی نمونه n8n مینامند و ذکر میکنند که برای گرههای زمانبندی مانند Cron اهمیت دارد. منظور از Cron در اینجا، نحو استاندارد زمانبندی مبتنی بر زمان است و n8n آن را به عنوان گزینه Custom (Cron) در Schedule Trigger ارائه میدهد.
منطقهٔ زمانی workflow برای هر workflow بهصورت جداگانه تنظیم میشود. workflow را در canvas باز کنید، سه نقطه در گوشهٔ بالا سمت راست را انتخاب کنید، سپس Settings را باز کنید و مقدار Timezone را تغییر دهید. این مقدار، GENERIC_TIMEZONE را فقط برای همان workflow override میکند. همه تنظیمات این صفحه به build رایگان self-hosted مربوط هستند؛ بنابراین تنظیم درست scheduleها به هیچ بخش پولی وابسته نیست و قابلیتهایی که به licence key نیاز دارند فهرست کاملاً متفاوتی هستند.
برای یک Schedule Trigger، ترتیب اولویت ثابت است. n8n اگر گردشکار دارای منطقه زمانی باشد از آن استفاده میکند، در غیر این صورت از منطقه زمانی نمونه در GENERIC_TIMEZONE و در نهایت از پیشفرض داخلی خود یعنی America/New_York استفاده میکند. TZ در هیچیک از مراحل این تصمیمگیری بررسی نمیشود.
برای تاریخها در داخل گرههای شما، پاسخ به این بستگی دارد که کد از کدام ساعت پرسوجو میکند. Luxon، کتابخانه تاریخ که در پسزمینه عبارتهای n8n قرار دارد، از منطقه زمانی n8n استفاده میکند، بنابراین $now و $today از همان ترتیب اولویت گردشکار و سپس نمونه پیروی میکنند که در مورد Trigger نیز صادق است. دستور ساده JavaScript یعنی new Date() در یک Code node از سیستمعامل پرسوجو میکند، بنابراین از TZ پیروی میکند. این تفاوت، منشأ اصلی سردرگمی در این بخش است: ممکن است Trigger درست عمل کند، در حالی که تمام برچسبهای زمانی که گردشکار مینویسد، ساعتها اختلاف داشته باشند.
تنظیم هر سه مورد در فایل Compose
مقادیر TZ و GENERIC_TIMEZONE را در فایل کنار یکدیگر قرار دهید تا کسی یکی را تنظیم نکند و دیگری را فراموش کند. قطعهکد زیر بخش مربوط به منطقه زمانی در یک سرویس فعال است. مابقی فایل، شامل reverse proxy و گواهی، از یک نمونه n8n خودمیزبان روی VPS پشت HTTPS گرفته شده است.
services:
n8n:
image: docker.n8n.io/n8nio/n8n
restart: unless-stopped
ports:
- "127.0.0.1:5678:5678"
environment:
- GENERIC_TIMEZONE=Europe/Berlin
- TZ=Europe/Berlin
- N8N_RUNNERS_ENABLED=true
- N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true
volumes:
- n8n_data:/home/node/.n8n
volumes:
n8n_data:آن را با docker compose up -d اعمال کنید، نه با docker compose restart. دستور restart همان container قبلی را با محیطی که با آن ساخته شده است دوباره اجرا میکند، بنابراین تغییرات فایل روی فرآیند در حال اجرا اعمال نمیشود. دستور up -d تغییرات محیط را تشخیص داده و container را دوباره میسازد. اگر این مقادیر را بهجای درج مستقیم، در یک فایل env نگهداری میکنید، همان قانون بازسازی اعمال میشود و راهنمای مدیریت فایل env و secrets در Compose توضیح میدهد که آن فایل از کجا خوانده میشود.
از نام منطقه IANA (Internet Assigned Numbers Authority) به فرم Region/City استفاده کنید، مانند Europe/Berlin یا America/Sao_Paulo. این نامها قوانین تغییر ساعت تابستانی را برای آن مکان در بر دارند، بنابراین با تغییر ساعت محلی، اختلاف زمانی نیز تغییر میکند. نامهایی با اختلاف ثابت مانند Etc/GMT+5 هرگز با تغییر فصل تغییر نمیکنند و علامت آنها برعکس چیزی است که تصور میکنید. دستور LC_ALL=C TZ=Etc/GMT+5 date +%z را اجرا کنید تا -0500 را چاپ کند. از این نامها اجتناب کنید.
چرا تنظیم تنها یکی از آنها، مشکل را بهصورت ناقص حل میکند
تنظیم GENERIC_TIMEZONE بهتنهایی باعث میشود Schedule Trigger در ساعتی که میخواهید اجرا شود، اما هر چیزی که زمان را از سیستمعامل میخواند، همچنان روی UTC باقی بماند. یک Code node که new Date().toString() را فراخوانی میکند، یک رشته UTC برمیگرداند، خطوط لاگ کانتینر با زمان UTC ثبت میشوند و هر نام فایلی که بر اساس ساعت سیستم ساخته شود، در نیمهشب اشتباه تغییر میکند.
تنظیم TZ بهتنهایی نتیجه معکوس دارد. docker compose exec n8n date زمان محلی شما را چاپ میکند که به نظر موفقیتآمیز میرسد، در حالی که Schedule Trigger همچنان روی America/New_York است و با اختلاف شش ساعت نسبت به ساعتی که درخواست کردهاید، اجرا میشود. این نسخهای است که بیشترین زمان را هدر میدهد، زیرا بررسی اولیهای که اکثر افراد انجام میدهند، همان موردی است که اکنون درست به نظر میرسد.
اگر یک workflow timezone را تنظیم کنید و سپس GENERIC_TIMEZONE را تغییر دهید، آن workflow تغییر را نادیده میگیرد. مقدار تنظیمشده در workflow اولویت دارد و تا زمانی که شخصی تنظیمات آن workflow را باز نکند، همان مقدار باقی میماند. اگر یک workflow در ساعت عجیبی اجرا میشود در حالی که سایر workflowهای مجاور آن مشکلی ندارند، تقریباً همیشه دلیل آن همین است.
بهجای حدس زدن، ساعتها را بررسی کنید
ساعت میزبان (host) و کانتینر را مستقیماً با هم مقایسه کنید.
date
docker compose exec n8n date
docker compose exec n8n printenv TZ GENERIC_TIMEZONEپس از تنظیم TZ، دو دستور اول باید زمان یکسانی را نمایش دهند. printenv برای هر متغیر موجود، یک خط خروجی چاپ میکند؛ بنابراین مشاهده دو خط به معنای تنظیم بودن هر دو متغیر است و مشاهده یک خط نشان میدهد که وضعیت نیمهتنظیمشده است.
اکنون از داخل یک workflow، این موضوع را از خود n8n بپرسید، زیرا shell کانتینر نمیتواند به شما بگوید که منطقه زمانی (timezone) در سطح workflow چیست. یک Code node به workflow مشکلدار اضافه کنید و آن را یک بار با Execute Workflow اجرا کنید.
return [
{
json: {
n8n_time: $now.toISO(),
n8n_zone: $now.zoneName,
system_time: new Date().toString(),
},
},
];n8n_zone منطقهای است که Schedule Trigger این workflow از آن استفاده خواهد کرد؛ این مقدار قبلاً از طریق اولویت workflow نسبت به instance تعیین شده است، بنابراین مستقیماً به پرسش شما پاسخ میدهد. system_time منطقه زمانی خود کانتینر را از TZ دریافت میکند. این دستور را در همان workflow مشکلدار اجرا کنید، نه در یک workflow جدید، زیرا تنظیمات سطح workflow همراه با خودِ workflow جابهجا میشوند. اگر این دو مقدار با هم تفاوت داشتند، شما بدون باز کردن حتی یک فایل پیکربندی، مشکل را پیدا کردهاید.
عبارتهای Cron در گرهٔ Schedule Trigger
Schedule Trigger فاصلههای ثابتی از چند ثانیه تا چند ماه ارائه میکند و برای مواردی که در این بازهها قرار نمیگیرند، گزینهٔ Custom (Cron) را دارد. عبارت Cron بر اساس منطقهٔ زمانی نهاییشدهٔ workflow خوانده میشود؛ بنابراین 0 6 * * * در آن منطقه به معنای ساعت 06:00 است، نه 06:00 به وقت UTC. یک عبارت 5-فیلدی از crontab guru را میتوان بدون تغییر وارد کرد. n8n همچنین یک فیلد اختیاری برای ثانیه میپذیرد که در جدول فیلدهای مستندات، در جایگاه اول قرار دارد: ثانیه، دقیقه، ساعت، روز ماه، ماه، روز هفته.
هرگز اختلاف زمانی را دستی در عبارت وارد نکنید. نوشتن 0 4 * * * در یک instance با UTC برای رسیدن به ساعت 06:00 در برلین، در تابستان درست است اما در تمام زمستان 1 ساعت زودتر اجرا میشود، زیرا برلین در تابستان روی UTC+2 و در زمستان روی UTC+1 قرار دارد. از آخرین یکشنبهٔ ماه مارس تا آخرین یکشنبهٔ ماه اکتبر، این عبارت در ساعت 06:00 به وقت برلین اجرا میشود و در باقی سال در ساعت 05:00 اجرا خواهد شد؛ در آن دوره فقط 0 5 * * * به ساعت 06:00 میرسد. منطقهٔ زمانی را تنظیم کنید و ساعت محلی موردنظر خود را بنویسید.
تأثیر تغییر ساعت تابستانی بر وظایف زمانبندیشده در ساعت 02:30
زمان محلی روی ساعت دیواری، یک لحظهٔ تضمینشده نیست. دو بار در سال، یک ساعت ناپدید و یک ساعت تکرار میشود و هر وظیفهای که در آن ساعات زمانبندی شده باشد، تحت تأثیر قرار میگیرد. میتوانید این اتفاق را با date روی هر سیستم لینوکسی، بدون دخالت n8n، مشاهده کنید.
LC_ALL=C TZ=Europe/Berlin date -d '2027-03-28 02:30'date: invalid date '2027-03-28 02:30'این یک غلط تایپی در دستور نیست. در تاریخ 2027-03-28 ساعت برلین مستقیماً از 02:00 به 03:00 میپرد، بنابراین ساعت 02:30 محلی در آن روز وجود ندارد و date از تبدیل آن به یک لحظهٔ زمانی خودداری میکند. وظیفهای که روی 02:30 محلی تنظیم شده باشد، هیچ لحظهای برای اجرا ندارد. زمانهای مجاور مشکلی ندارند: date -d '2027-03-28 01:30' به عنوان CET و date -d '2027-03-28 03:30' به عنوان CEST تفسیر میشوند.
تغییر ساعت پاییزی تصویر آینهای این وضعیت است. در تاریخ 2027-10-31 ساعت برلین از 03:00 به 02:00 عقب کشیده میشود، بنابراین ساعت 02:30 دو بار تکرار میشود.
LC_ALL=C TZ=Europe/Berlin date -d '2027-10-31 02:30 CEST' '+%s'
LC_ALL=C TZ=Europe/Berlin date -d '2027-10-31 02:30 CET' '+%s'1824942600
1824946200دو لحظهٔ متفاوت که هر دو 02:30 محلی نامیده میشوند و 3600 ثانیه با هم فاصله دارند. وظیفهای که در آن زمان قفل شده باشد، یا دو بار اجرا میشود یا یک بار در ساعتی که کسی انتخاب نکرده است، و هیچکدام از این نتایج برای اجرای صورتحساب یا چرخش بکآپ مطلوب نیست. زمانبندی را از آن بازه خارج کنید. در اکثر مناطق اروپا و آمریکای شمالی، بازهٔ پرخطر بین 00:00 تا 03:00 محلی است.
زمانبندی زیرساخت بر اساس UTC و نمایش زمان محلی به کاربران
پاسخ استاندارد، دو وظیفهای که یک منطقه زمانی (timezone) انجام میدهد را از هم جدا میکند. ماشینها به یک بازه زمانی پایدار نیاز دارند. انسانها به ساعتی خوانا نیاز دارند.
- برای کارهایی که ناظری ندارند، منطقه زمانی گردشکار (workflow) را روی UTC تنظیم کنید. پشتیبانگیری، گرمکردن کش (cache warming)، ارسال لاگ و تولید گزارش در این دسته قرار میگیرند. در UTC، فاصله بین دو اجرا دقیقاً همان بازهای است که تعیین کردهاید، چرا که UTC فاقد تغییرات ساعت تابستانی (daylight saving) است.
- برای کارهایی که توسط انسان خوانده میشوند، زمانبندی را در UTC نگه دارید و در لحظه نمایش، آن را تبدیل کنید. یک عبارت ساده این کار را انجام میدهد:
{{ $now.setZone('Europe/Berlin').toFormat('yyyy-MM-dd HH:mm') }}زمان محلی را در بدنه پیام قرار میدهد، در حالی که محرک (trigger) همچنان پایدار باقی میماند.
همین تفکیک در خارج از n8n نیز صدق میکند. هنگامی که بخشی از اتوماسیون شما به عنوان یک سرویس و تایمر systemd روی VPS اجرا میشود، خط OnCalendar آن در منطقه زمانی سیستم خوانده میشود که خود یک ساعت چهارم با تنظیمات مستقل است. نگه داشتن تمام زمانبندها روی UTC باعث میشود به جای چهار قانون، فقط یک قانون را به خاطر بسپارید. این موضوع برای هر چیزی که یک بازه زمانی را خلاصه میکند نیز اهمیت دارد، زیرا یک گردشکار عامل هوش مصنوعی n8n که آمار دیروز را درخواست میکند، بسته به اینکه کدام منطقه زمانی تعیین شده باشد، بیسروصدا از یک بازه 24 ساعته متفاوت استفاده خواهد کرد.
حالتهای شکست و خروجیهایی که مشاهده خواهید کرد
همه چیز با شش ساعت اختلاف اجرا میشود. مقدار GENERIC_TIMEZONE هرگز تنظیم نشده است، بنابراین مقدار پیشفرض داخلی یعنی America/New_York اعمال میشود. docker compose exec n8n printenv GENERIC_TIMEZONE هیچ خروجیای چاپ نمیکند. آن را تنظیم کنید و سپس container را دوباره بسازید.
فایل Compose را ویرایش کردید اما هیچ تغییری اعمال نشد. شما دستور docker compose restart را اجرا کردید، بنابراین container محیط اصلی خود را حفظ کرد. دستور docker compose up -d را اجرا کنید و سپس با docker compose exec n8n printenv TZ تغییرات را تأیید کنید.
تریگر درست است اما زمانها اشتباه هستند. فقط GENERIC_TIMEZONE تنظیم شده است. یک new Date() در گره Code همچنان زمان UTC را از سیستمعامل میخواند. مقدار TZ را روی همان مقدار تنظیم کرده و container را دوباره بسازید.
یک ورکفلو تنظیمات instance را نادیده میگیرد. آن ورکفلو در تنظیمات خود دارای منطقه زمانی اختصاصی است که بر GENERIC_TIMEZONE اولویت دارد. بوم (canvas) را باز کنید، روی سه نقطه کلیک کرده، به بخش Settings و سپس Timezone بروید.
یک job روزانه امسال دو بار اجرا شد یا یک روز را رد کرد. ساعت زمانبندیشدهٔ آن در بازهٔ تغییر ساعت تابستانی (daylight saving) قرار دارد. ساعت اجرا را تغییر دهید یا آن ورکفلو را به UTC منتقل کنید.
FAQ
چرا تریگر زمانبندی n8n من در ساعت اشتباهی اجرا میشود؟
گردشکار (workflow) شما در حال استفاده از منطقه زمانی متفاوتی نسبت به تصور شماست. n8n اگر گردشکار دارای منطقه زمانی باشد از آن استفاده میکند، در غیر این صورت از منطقه زمانی نمونه (instance) تعریفشده در GENERIC_TIMEZONE و در نهایت از مقدار پیشفرض داخلی خود یعنی America/New_York استفاده میکند. در یک نمونه self-hosted که کسی GENERIC_TIMEZONE را تنظیم نکرده باشد، زمانبندیها بر اساس زمان نیویورک انجام میشوند، نه UTC؛ به همین دلیل است که اختلاف زمانی بهندرت با فاصله شما از UTC مطابقت دارد. دستور docker compose exec n8n printenv GENERIC_TIMEZONE را اجرا کنید. اگر خروجی خالی باشد، یعنی این مقدار هرگز تنظیم نشده است.
تفاوت بین TZ و GENERIC_TIMEZONE در n8n چیست؟
TZ منطقه زمانی سیستمعامل داخل کانتینر است. این متغیر تعیین میکند که date داخل کانتینر چه مقداری برگرداند، چه برچسبهای زمانی در خطوط لاگ کانتینر ظاهر شوند، new Date() در یک Code node چه خروجی داشته باشد و هر اسکریپتی که در آنجا اجرا میکنید چه زمانی را مشاهده کند. GENERIC_TIMEZONE منطقه زمانی نمونه n8n است و همان چیزی است که گرههای زمانبندی (schedule nodes) و عبارتهای Luxon مانند $now از آن استفاده میکنند. تنظیم یکی بدون دیگری باعث میشود یا تریگر صحیح داشته باشید اما برچسبهای زمانی اشتباه باشند، یا برچسبهای زمانی صحیح باشند اما تریگر با اختلاف ساعت اجرا شود. هر دو را روی یک مقدار یکسان تنظیم کنید.
آیا باید منطقه زمانی گردشکار را تنظیم کنم یا GENERIC_TIMEZONE را؟
مقدار GENERIC_TIMEZONE را بهعنوان پیشفرض برای کل نمونه تنظیم کنید و از تنظیمات مخصوص هر گردشکار فقط در مواردی استفاده کنید که یک گردشکار واقعاً متعلق به منطقه زمانی دیگری باشد. مقدار گردشکار بر مقدار نمونه اولویت دارد و از تغییرات بعدی در GENERIC_TIMEZONE پیروی نمیکند؛ بنابراین ردیابی یک override فراموششده در سطح گردشکار، ماهها بعد بسیار دشوار خواهد بود.
چه اتفاقی برای کاری که در ساعت 02:30 زمانبندی شده است هنگام تغییر ساعت میافتد؟
آن زمان محلی یا ناپدید میشود یا دو بار رخ میدهد. LC_ALL=C TZ=Europe/Berlin date -d '2027-03-28 02:30' مقدار date: invalid date '2027-03-28 02:30' را برمیگرداند، زیرا ساعت برلین در آن روز از 02:00 به 03:00 میپرد. در تاریخ 2027-10-31، همان زمان روی ساعت دیواری به دو لحظه با فاصله یک ساعت از هم نگاشت میشود. کارهای زمانبندیشده را خارج از بازه محلی 00:00 تا 03:00 قرار دهید، یا گردشکار را روی UTC تنظیم کنید و تبدیل به زمان محلی را فقط در جایی انجام دهید که قرار است توسط انسان خوانده شود.