Croner: расписания задач в Node.js — cron, часовые пояса и 9 примеров
Девять сценариев расписаний: конструктор cron, зоны и DST, живые таймеры, protect, ошибки, worker и несколько копий. Исходники и практика Windows/Linux.

Croner: запускать полезную работу по расписанию
У сервиса почти всегда появляются действия, которые нужно выполнять без нажатия пользователя: утром подготовить отчёт, вечером сверить данные, раз в несколько минут обновить интеграцию, ночью убрать временные файлы. Сначала такую работу запускают вручную. Затем возникают забытые запуски, слишком частые повторения и непонятные правила времени. Croner позволяет описать расписание прямо в JavaScript и связать его с функцией приложения.
В этой статье собрана мастерская с девятью сценариями. Можно менять cron-выражение, видеть ближайшие даты в разных часовых поясах, исследовать переходы летнего времени и запустить короткий настоящий таймер. Отдельный пример Node.js создаёт учебные отчёты, пишет журнал и корректно завершает процесс. Исходники доступны целиком, с закреплёнными зависимостями и командами Windows и Linux.
После знакомства у вас будет не только строка cron. Вы сможете объяснить, когда должна сработать задача, что произойдёт при долгой обработке, где записать ошибку и как разместить процесс на VPS. Эти вопросы определяют практическую пригодность расписания: удачный одиночный запуск ещё не говорит о поведении сервиса в течение месяца.
Где применять: отчёты, интеграции и обслуживание
В CRM расписание удобно для ежедневной сводки по заявкам и сделкам. В интернет-магазине — для сверки каталога с поставщиком или подготовки выгрузки. Во внутреннем кабинете — для обновления агрегированных показателей, которые дорого пересчитывать при каждом открытии страницы. В системе документов — для проверки просроченных заданий и формирования списка напоминаний.
Обслуживание тоже может быть периодическим: помечать истёкшие сессии, пересчитывать статистику, удалять только собственные временные файлы старше выбранного срока. Само действие должно иметь чёткие границы. Планировщик не определяет, какие файлы безопасно удалить и какое письмо разрешено отправить. Такие решения остаются в прикладной функции и её проверках.
Начните с описания результата: «к 09:00 московского времени доступен отчёт за предыдущий завершённый день». Затем определите входные данные, допустимую задержку и поведение при повторе. Если формулировка звучит как «каждые пять минут что-нибудь обновить», полезно уточнить её до конкретной операции. Так проще выбрать расписание, журнал, механизм повторов и способ проверки результата.
Croner, системный cron, setInterval и очередь
Croner работает внутри процесса JavaScript. Функция может использовать уже созданный клиент базы, настройки приложения и общий код. Системный cron запускает команды средствами операционной системы и живёт отдельно от Node.js. setInterval отсчитывает интервалы, но сам по себе не описывает календарное правило вроде понедельника в определённой зоне. Эти инструменты подходят для разных условий эксплуатации.
Очередь решает другую задачу: хранит задания и передаёт их обработчикам. Расписание отвечает на вопрос «когда создать работу», очередь — «как доставить и обработать созданную работу». Для небольшой некритичной очистки достаточно одного процесса. Для важного отчёта разумно по расписанию создавать долговечное задание, а обработку поручать отдельному worker.
Выбирайте по последствиям простоя. Если пропуск одного обновления допустим и следующий запуск всё исправит, архитектура может быть простой. Если каждый период должен быть обработан, сохраняйте состояние периодов и задания. Доступность процесса и сохранность работы — разные свойства, поэтому автоматический перезапуск службы не заменяет очередь.
import { Cron } from 'croner';
const job = new Cron('0 9 * * MON-FRI', { timezone: 'Europe/Moscow' }, async () => {
await buildDailyReport(); // ваша прикладная операция
});
Версии, установка и устройство проекта
Мастерская использует Croner 11.0.1, Bootstrap 5.3.9 и esbuild 0.28.2. Версии зафиксированы в package.json, а точное дерево зависимостей — в package-lock.json. Для повторения используйте npm ci: так устанавливается проверенный набор, а случайное обновление зависимости не меняет поведение календаря во время обучения.
Код разделён по назначению. core.mjs вычисляет даты и создаёт ограниченный опыт. scenarios.mjs содержит исходные параметры девяти примеров. app.mjs связывает формы с библиотекой. worker.mjs — самостоятельный серверный процесс. В tools находятся сборка, локальный HTTP-сервер и создание записей реального выполнения. Такая структура позволяет перенести нужную часть без копирования всей демонстрационной страницы.
Готовая папка public уже содержит собранный JavaScript и локальный CSS. Для просмотра не требуется сторонний CDN. Исходники открываются внутри мастерской и входят в ZIP. Собственный код распространяется под MIT; зависимости сохраняют свои лицензии. Перед переносом в рабочий проект обновления следует проверять отдельно, особенно при смене основной версии Croner.
Файл: package.json
{
"name": "aen-croner-workshop", "version": "1.0.0", "private": true, "type": "module",
"scripts": {"build":"node tools/build.mjs", "test":"node --test test/*.test.mjs", "worker":"node src/worker.mjs", "record":"node tools/record.mjs", "serve":"node tools/server.mjs"},
"dependencies":{"croner":"11.0.1","bootstrap":"5.3.9"},
"devDependencies":{"esbuild":"0.28.2"}, "engines":{"node":">=22"}
}
Мини-мастерская: девять сценариев для самостоятельного опыта
Выберите сценарий в верхнем списке. Каждый пункт объясняет прикладную задачу и подставляет подходящие параметры. Поля остаются редактируемыми: можно задать свою строку, зону и опорную дату. Под результатом доступна выгрузка JSON с исходными параметрами и рассчитанными моментами. После изменения ввода старый расчёт очищается, чтобы его нельзя было принять за актуальный.
Ниже расположен отдельный живой опыт. Он не запускается автоматически и ограничен пятью вызовами и десятью секундами. Здесь можно сравнить быструю функцию с долгой, включить protect и вызвать учебное исключение. Журнал показывает фактические события текущей вкладки. Блок записей Node.js помечен отдельно: он показывает сохранённое реальное выполнение исходников, а не процесс на сервере сайта.
Удобный маршрут: сначала посмотрите будни, затем сравните зоны, исследуйте DST и только после этого включите таймер. Так календарная логика не смешивается с длительностью обработки. Если встроенная область тесна, откройте мастерскую в отдельной вкладке. На телефоне карточки результата располагаются вертикально, длинный код прокручивается внутри своего блока.
Пример 1. Как читать пять и шесть полей cron
Обычная строка из пяти полей задаёт минуту, час, день месяца, месяц и день недели. Звёздочка означает любое допустимое значение. Шаг, диапазон и перечисление позволяют описать регулярность без ручного набора дат. В мастерской исходное выражение запускает синхронизацию каждые пятнадцать минут с понедельника по пятницу в диапазоне часов с девяти до восемнадцати.
Диапазон часов включает весь последний час. Поэтому правило 9-18 содержит и 18:45. Если нужен последний запуск строго в 18:00, одно такое выражение не соответствует требованию: используйте отдельные правила или проверку бизнес-окна. Важно сверять календарь с человеческим описанием, а не только с отсутствием ошибки парсера.
Шесть полей добавляют секунды в начало. Именно такой вариант используется в коротком опыте, чтобы не ждать минуту. Переносить секундное выражение в обычный системный crontab без проверки нельзя. Формат и поддерживаемые расширения зависят от конкретного планировщика. Конструктор показывает несколько ближайших результатов, поэтому ошибку смысла легче заметить до запуска реальной операции.
// Каждые 15 минут, в часы 09–18, с понедельника по пятницу
'*/15 9-18 * * MON-FRI'
// Каждые 5 секунд — шесть полей
'*/5 * * * * *'
// В 07:30 ежедневно
'30 7 * * *'
Пример 2. Отчёт по рабочим дням
Выберите «Отчёт по будням». Опорная дата установлена на пятницу после московских девяти утра. Следующий результат — понедельник. Это простая проверка, которая помогает увидеть разницу между календарными днями и интервалом в двадцать четыре часа. Для еженедельной сводки можно оставить один день, а для нескольких дней перечислить их через запятую.
MON-FRI означает дни недели, а не официальный производственный календарь. Праздник в понедельник не отменит запуск, а рабочая суббота не появится автоматически. Если это важно для бизнеса, проверяйте специальный календарь внутри обработчика или заранее формируйте задания на разрешённые даты. Источник такого календаря и правила обновления должны быть частью проекта.
Период отчёта рассчитывайте отдельно от момента запуска. Отчёт, запущенный утром понедельника, может относиться к пятнице, выходным или предыдущей календарной неделе — это бизнес-решение. Передавайте выбранный период в функцию явно и сохраняйте его в результате. Тогда повторный запуск после сбоя не начнёт незаметно обрабатывать другой день.
const rows = schedule({
pattern: '0 9 * * MON-FRI',
timezone: 'Europe/Moscow',
anchor: '2026-11-20T07:00:00Z',
count: 3
});
// Первый UTC-момент: 2026-11-23T06:00:00.000Z
Пример 3. Часовой пояс — часть данных расписания
В распределённом сервисе нельзя полагаться только на локальную зону сервера. Один и тот же контейнер может оказаться на другом хосте, а разработчик — в другом регионе. Если пользователь выбрал ежедневные 09:00, храните вместе с cron именованную зону, например Europe/Moscow. Иначе после переноса приложения человеческий смысл расписания может измениться.
Кнопка сравнения берёт одну строку и одну опорную дату, затем вычисляет ближайший запуск для пяти зон. Под местным временем указан точный UTC-момент. Это удобно при настройке кабинетных уведомлений: пользователь видит привычные часы, а журнал и база могут сопоставлять события в общей временной шкале.
Смещение вроде UTC+3 и именованная зона отвечают на разные задачи. Для регионов с сезонными изменениями фиксированное смещение не описывает весь год. Используйте IANA-название и проверяйте правила выбранной зоны. В форме мастерской список намеренно ограничен несколькими понятными вариантами; в продукте можно предложить более широкий список с поиском и текущим смещением.
new Cron('0 9 * * *', { timezone: 'Europe/Moscow' });
new Cron('0 9 * * *', { timezone: 'UTC' });
new Cron('0 9 * * *', { timezone: 'Europe/Berlin' });
Пример 4. DST: отсутствующий и повторяющийся час
Сезонный перевод часов создаёт два неудобных случая: местное время может отсутствовать либо повториться. В сценарии DST задано 02:30 в Europe/Berlin и фиксированная дата рядом с переходом. Нажмите кнопки весны и осени, посмотрите UTC и местные подписи. Вы наблюдаете результат настоящей закреплённой библиотеки, поэтому эксперимент можно повторить в Node.js.
В Croner 11 поведение различается для фиксированного времени и интервальных правил. Согласно документации, фиксированное несуществующее время переносится на первый допустимый момент после разрыва; при повторении часа фиксированная задача выполняется в первое вхождение. Интервальные выражения продолжают проходить повторяющийся час, а отсутствующие моменты пропускают. Не переносите это описание автоматически на другие cron-реализации.
Для расчётов оплаты, сроков и отчётных периодов DST требует отдельного решения. Длительность суток может отличаться от двадцати четырёх часов, поэтому прибавление фиксированного количества миллисекунд не всегда даёт следующий местный день. Если бизнес опирается на календарные даты, храните календарную дату отдельно от UTC-времени выполнения и проверяйте переходы в тестах.
schedule({
pattern: '30 2 * * *', timezone: 'Europe/Berlin',
anchor: '2027-03-28T00:00:00Z', count: 2
});
// 2027-03-28T01:00:00.000Z — 03:00 после разрыва
// 2027-03-29T00:30:00.000Z — обычные 02:30
Официальное описание синтаксиса и DST
День месяца и день недели: ИЛИ по умолчанию
Выражение с одновременно ограниченными днём месяца и днём недели легко прочитать неправильно. По умолчанию Croner объединяет эти поля через ИЛИ. Строка с первым числом и понедельником срабатывает первого числа месяца, а также по понедельникам. Она не означает исключительно понедельник, который совпал с первым числом.
Флажок domAndDow в мастерской включает пересечение условий. Установите строку из примера, рассчитайте результат, затем включите флажок и рассчитайте снова. Ближайшая дата заметно сдвинется. Это полезный опыт для ежемесячных отчётов, регламентных работ и расписаний с ограничениями сразу по нескольким календарным полям.
В интерфейсе продукта лучше показывать человеку понятное объяснение выбранного режима. Одной строки cron может быть недостаточно для администратора, который меняет расписание раз в полгода. Список ближайших дат и явная подпись «И» или «ИЛИ» снижают вероятность ошибки. При сохранении стоит записывать режим вместе с выражением и зоной.
const common = { timezone:'Europe/Moscow' };
new Cron('0 9 1 * MON', common); // первое число ИЛИ понедельник
new Cron('0 9 1 * MON', { ...common, domAndDow:true }); // оба условия
Пример 5. Живой таймер, пауза и продолжение
В пятом сценарии обработчик длится двести миллисекунд. Нажмите начало опыта и посмотрите события. Пауза прекращает будущие срабатывания расписания, но уже начатая функция может завершиться. Продолжение возобновляет планирование. Общий предел времени опыта сохраняется даже на паузе, чтобы демонстрация не оставляла скрытый долгоживущий таймер.
Остановка окончательная для конкретного экземпляра Croner. Для нового опыта создаётся новый объект. Это отличается от паузы и важно для интерфейса: кнопка продолжения после stop не должна обещать невозможное действие. В мастерской доступность кнопок следует состоянию опыта, а журнал сохраняет причину завершения.
Браузерный таймер полезен для обучения и локальных действий страницы. Он не обеспечивает надёжный серверный запуск: вкладку можно закрыть, устройство уснёт, браузер ограничит фоновые задачи. Для регулярной обработки данных переносите ту же идею в отдельный Node.js-процесс. Публичная мастерская специально не создаёт серверные задания по нажатию посетителя.
const job = new Cron('* * * * * *', { maxRuns:5 }, () => {
console.log('Фактический запуск', new Date().toISOString());
});
job.pause();
job.resume();
job.stop(); // после этого нужен новый экземпляр
Пример 6. Долгая работа и защита protect
Представьте синхронизацию, которая иногда выполняется дольше своего интервала. Новый запуск приходит, пока предыдущий ещё обращается к API. Без ограничения одновременно работают несколько экземпляров обработчика. Они могут читать одинаковые записи, создавать лишнюю нагрузку и записывать результат в неожиданном порядке. В мастерской это видно по пиковому числу активных вызовов.
Выберите длительность 1,4 секунды при секундном расписании. Сначала включите protect, затем повторите опыт без него. Защита пропускает перекрывающееся срабатывание и вызывает наблюдаемый обработчик события блокировки. Пропуск не превращается в отложенное задание, поэтому нельзя обещать, что каждый секундный момент будет обработан позже.
Обработчик должен возвращать Promise всей работы. Если внутри запустить асинхронную операцию и немедленно выйти, планировщик может считать функцию завершённой раньше фактического результата. Это типичная ошибка при интеграциях. Используйте async/await и включайте в возвращаемую цепочку чтение, преобразование и запись, завершение которых определяет конец операции.
Файл: src/core.mjs
const job = new Cron(pattern.trim(), { timezone, domAndDow });
try {
const formatter = new Intl.DateTimeFormat('ru-RU', { timeZone: timezone, dateStyle: 'full', timeStyle: 'long' });
return job.nextRuns(count, start).map((date, i) => ({ number: i + 1, utc: date.toISOString(), local: formatter.format(date), timezone }));
} finally { job.stop(); }
}
function sleep(ms, signal) {
return new Promise(resolve => {
if (signal.aborted) return resolve(false);
const finish = ok => { clearTimeout(timer); signal.removeEventListener('abort', cancel); resolve(ok); };
const cancel = () => finish(false);
const timer = setTimeout(() => finish(true), ms);
signal.addEventListener('abort', cancel, { once: true });
});
}
// A bounded real scheduler. Stopping the Cron instance alone does not cancel an in-flight callback.
export function createTrial({ protect = true, duration = 1400, maxRuns = 5, failAt = 0, emit = () => {}, deadlineMs = 10000 } = {}) {
if (![200, 1400, 2400].includes(duration) || !Number.isInteger(maxRuns) || maxRuns < 1 || maxRuns > 8 || deadlineMs < 1000 || deadlineMs > 15000) throw new Error('Недопустимые параметры опыта.');
let runs = 0, active = 0, peak = 0, closed = false, deadline;
const controller = new AbortController();
let settle;
const done = new Promise(resolve => { settle = resolve; });
const events = [];
const report = (type, details = {}) => {
const event = { type, at: new Date().toISOString(), runs, active, peak, ...details };
events.push(event); emit(event);
};
const job = new Cron('* * * * * *', {
maxRuns,
protect: protect ? () => report('blocked') : false,
catch: error => { report('error', { message: error.message }); finishIfIdle(); }
}, async instance => {
const id = ++runs; active++; peak = Math.max(peak, active);
report('start', { id, scheduled: instance.currentRun()?.toISOString() });
try {
const completed = await sleep(duration, controller.signal);
if (!completed || closed) return;
if (id === failAt) throw new Error('Учебный временный сбой');
report('complete', { id });
} finally { active--; finishIfIdle(); }
});
Пример 7. Исключения, catch и неуспешная операция
В сценарии ошибки второй вызов выбрасывает исключение. Оно попадает в catch, записывается в журнал, а последующие календарные запуски продолжаются. Это позволяет наблюдать сбой, но не означает повтор той же бизнес-операции. Например, следующий ежедневный отчёт уже может относиться к другому периоду. Отсутствующий результат за вчера нужно учитывать отдельно.
Полезно разделять временную ошибку, неправильные входные данные и неисправимое состояние. Сетевой таймаут иногда оправдывает повтор с задержкой. Неверный идентификатор клиента требует исправления данных. Ошибка доступа обычно не исчезает от частого повторения. Политику определяет приложение; catch служит точкой наблюдения и передачи информации.
В журнал записывайте идентификатор операции, период, начало, длительность и класс ошибки. Не выводите туда токены и содержимое приватных документов. В демонстрации ошибка учебная и не обращается к внешнему сервису. В рабочем проекте важные неуспешные операции должны быть видны оператору, а не только оставаться строкой среди тысяч успешных сообщений.
new Cron('*/5 * * * *', {
timezone:'UTC',
protect:true,
catch: error => logger.error({ message:error.message }, 'report failed')
}, async () => {
await createReportForExplicitPeriod();
});
Проверка ввода и актуальность результата
Строку из пользовательской формы нужно проверять до создания постоянного расписания. Мастерская ограничивает длину выражения, количество возвращаемых дат и список зон. Опорная дата задаётся в ISO 8601 с явным Z или смещением. Ошибка отображается рядом с формой, предыдущие строки удаляются, экспорт отключается. Таким образом посетитель не скачает старый успешный ответ после неудачной попытки.
В приложении ограничения должны соответствовать продукту. Если клиенту разрешены только ежедневные отчёты, не нужно открывать секундные запуски. Ограничьте частоту, число активных расписаний и доступные операции. Сам синтаксически правильный cron ещё не доказывает, что действие допустимо и полезно. Проверка прав и квот остаётся серверной обязанностью.
При редактировании существующего расписания покажите текущую версию, будущие даты и момент вступления изменений в силу. Если несколько сотрудников меняют одну настройку, потребуется защита от потери правок. Для сохранения в базе передавайте нормализованные параметры и номер версии; не полагайтесь на скрытые поля интерфейса как на доверенный источник.
Файл: src/core.mjs
export function schedule({ pattern, timezone = 'Europe/Moscow', anchor, count = 8, domAndDow = false }) {
if (typeof pattern !== 'string' || pattern.length > 120 || !pattern.trim()) throw new Error('Введите cron-выражение до 120 символов.');
if (!zones.includes(timezone)) throw new Error('Выберите поддерживаемый часовой пояс.');
if (!Number.isInteger(count) || count < 1 || count > 20) throw new Error('Количество запусков: от 1 до 20.');
if (typeof anchor !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?(?:Z|[+-]\d{2}:\d{2})$/.test(anchor)) throw new Error('Опорная дата нужна в ISO 8601 с Z или смещением, например 2026-11-17T00:00:00Z.');
const [year, month, day, hour, minute, second] = anchor.slice(0, 19).split(/[-T:]/).map(Number);
const daysInMonth = new Date(Date.UTC(year, month, 0)).getUTCDate();
if (month < 1 || month > 12 || day < 1 || day > daysInMonth || hour > 23 || minute > 59 || second > 59) throw new Error('Такой календарной даты или времени не существует.');
const start = new Date(anchor);
if (!Number.isFinite(+start) || start.getUTCFullYear() < 2020 || start.getUTCFullYear() > 2035) throw new Error('Опорная дата должна находиться между 2020 и 2035 годами.');
const job = new Cron(pattern.trim(), { timezone, domAndDow });
try {
const formatter = new Intl.DateTimeFormat('ru-RU', { timeZone: timezone, dateStyle: 'full', timeStyle: 'long' });
return job.nextRuns(count, start).map((date, i) => ({ number: i + 1, utc: date.toISOString(), local: formatter.format(date), timezone }));
} finally { job.stop(); }
}
Пример 8. Настоящий worker Node.js и учебные отчёты
В исходниках находится самостоятельный worker. Он создаёт каталог runtime/reports и записывает синтетический отчёт в отдельный JSON-файл. В консоль выводятся структурированные события ready, report, stopping и stopped. По умолчанию процесс завершает работу после трёх отчётов; есть также предел времени. Это позволяет безопасно проверить запуск без оставленного навсегда фонового процесса.
Для длительной работы включается RUN_CONTINUOUS=1, а выражение и зона передаются через окружение. Перед изменением примера под свою задачу замените учебные числа обращением к вашему хранилищу и определите идентификатор результата. Текущие имена демонстрационных файлов показывают независимые запуски, но не являются бизнес-защитой от повторного отчёта за один период.
Раздел записей в мастерской получен реальным запуском этого файла. Можно сравнить команды, последовательность событий и исходник. Запись не имитирует выполнение на хостинге сайта: для своего процесса скачайте архив и выполните команды ниже. Такая граница полезна читателю, который хочет воспроизвести результат, а не только посмотреть анимацию.
Файл: src/worker.mjs
import { Cron } from 'croner';
import { mkdir, writeFile } from 'node:fs/promises';
import { resolve } from 'node:path';
const production = process.env.RUN_CONTINUOUS === '1';
const pattern = process.env.SCHEDULE || (production ? '0 7 * * MON-FRI' : '* * * * * *');
const timezone = process.env.TIMEZONE || 'Europe/Moscow';
const directory = resolve('runtime/reports');
await mkdir(directory, { recursive: true });
let active = Promise.resolve(), run = 0, stopping = false, timeout;
const log = (event, fields = {}) => console.log(JSON.stringify({ at:new Date().toISOString(), event, ...fields }));
const job = new Cron(pattern, { timezone, protect:true, catch:error => log('error',{message:error.message}) }, () => {
active = (async () => {
const number=++run;
const id=`demo-${Date.now()}-${number}`;
const report={id,generatedAt:new Date().toISOString(),orders:12,total:54000,currency:'RUB'};
await writeFile(resolve(directory,`${id}.json`),JSON.stringify(report,null,2),{flag:'wx'});
log('report',{id,number});
if (!production && number>=3) queueMicrotask(() => shutdown('demo-limit'));
})();
return active;
});
async function shutdown(reason) {
if(stopping)return;
stopping=true; job.stop(); clearTimeout(timeout); log('stopping',{reason});
try { await active; log('stopped',{reports:run}); } catch(error) { log('shutdown-error',{message:error.message}); process.exitCode=1; }
}
process.on('SIGINT',()=>void shutdown('SIGINT'));
process.on('SIGTERM',()=>void shutdown('SIGTERM'));
if(!production)timeout=setTimeout(()=>void shutdown('deadline'),8000);
log('ready',{pattern,timezone,next:job.nextRun()?.toISOString(),production});
Windows: запуск в PowerShell
Установите поддерживаемую версию Node.js LTS и распакуйте архив в отдельный каталог. Откройте PowerShell именно в каталоге проекта: там должны находиться package.json и package-lock.json. Сначала установите зависимости и запустите тесты, затем создайте записи и соберите браузерную часть. Локальный сервер слушает только 127.0.0.1, поэтому он предназначен для проверки на вашем компьютере.
В отдельном окне можно запустить worker. Обычный учебный режим завершится самостоятельно. Для непрерывного опыта переменные задаются через $env:, а Ctrl+C инициирует завершение. После опыта удалите временные переменные из текущей оболочки, чтобы следующий запуск случайно не получил прежнее расписание.
Windows-проверка подтверждает выполнение JavaScript и поведение библиотеки, но не превращает systemd unit в Windows-службу. Если задача должна постоянно работать на рабочем Windows-компьютере, нужен подходящий менеджер службы и отдельно проверенный жизненный цикл. Для типового VPS ниже приведён Linux-вариант, где процесс запускается выделенным пользователем.
npm ci
npm test
npm run record
npm run build
npm run serve
# Откройте http://127.0.0.1:8574
$env:RUN_CONTINUOUS = '1'
$env:SCHEDULE = '*/5 * * * * *'
$env:TIMEZONE = 'Europe/Moscow'
node src/worker.mjs
# Остановите Ctrl+C
Remove-Item Env:RUN_CONTINUOUS, Env:SCHEDULE, Env:TIMEZONE
Linux: локальный запуск и повторение проверок
На Linux используется тот же исходный проект и lockfile. Команды npm одинаковы, меняется синтаксис переменных окружения. Для короткой проверки переменные можно указать перед одной командой: они не останутся в последующих запусках оболочки. Отдельный тестовый сценарий в архиве выполняет реальные таймеры и проверяет завершение worker по SIGTERM.
В этой работе Linux-проверка выполнена в изолированном контейнере с Node.js 24.22.2. Контейнер использует собственный временный каталог и не изменяет настройки рабочего сервера. Он подтверждает расчёт дат, защиту от перекрытия, обработку исключения, записи отчётов и сигнал завершения. Проверка контейнера не выдаётся за развёртывание на VPS или проверку конкретного systemd-хоста.
Если вы запускаете проект на сервере вручную через SSH, закрытие сеанса может прекратить процесс. Для постоянной работы используйте менеджер служб. Также заранее определите каталог данных, права доступа и срок хранения отчётов. Иначе даже исправный планировщик со временем заполнит диск накопившимися результатами.
npm ci
npm test
npm run record
npm run build
RUN_CONTINUOUS=1 SCHEDULE='*/5 * * * * *' TIMEZONE=Europe/Moscow node src/worker.mjs
VPS: отдельная служба systemd
Для постоянного процесса создайте отдельного системного пользователя и разместите код в /opt/aen-croner. Сам код и зависимости должны принадлежать администратору, а службе достаточно доступа на чтение. Запись разрешается только в runtime. В шаблоне включены ограничения systemd, которые помогают отделить рабочие данные от остальной файловой системы.
Проверьте фактический путь Node командой command -v node. В примере используется /usr/bin/node; установка через пользовательский менеджер версий может дать другой путь и другой доступ. Перед стартом выполните systemd-analyze verify для unit, затем daemon-reload, enable и start. Состояние смотрите через systemctl status, журнал — через journalctl.
Шаблон не был применён к вашему production-серверу и требует проверки под конкретную ОС. Если добавляется доступ к сети, базе или секретам, задавайте его адресно. Не запускайте весь процесс от root ради записи отчёта. После изменения расписания перезапустите службу управляемо и проверьте ближайший запуск в журнале.
Файл: deploy/aen-reports.service
[Unit]
Description=AEN Croner report scheduler
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=aen-reports
Group=aen-reports
WorkingDirectory=/opt/aen-croner
Environment=NODE_ENV=production
Environment=RUN_CONTINUOUS=1
Environment="SCHEDULE=0 7 * * MON-FRI"
Environment=TIMEZONE=Europe/Moscow
ExecStart=/usr/bin/node /opt/aen-croner/src/worker.mjs
Restart=on-failure
RestartSec=5
KillSignal=SIGTERM
TimeoutStopSec=30
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/opt/aen-croner/runtime
[Install]
WantedBy=multi-user.target
sudo systemd-analyze verify /etc/systemd/system/aen-reports.service
sudo systemctl daemon-reload
sudo systemctl enable --now aen-reports.service
sudo systemctl status aen-reports.service
sudo journalctl -u aen-reports.service -n 50 --no-pager
Остановка: расписание и уже начатая работа
Метод stop прекращает будущие срабатывания, но не умеет автоматически отменить произвольный сетевой запрос или Promise внутри вашей функции. Поэтому завершение нужно проектировать на двух уровнях: остановить планировщик и затем закончить либо отменить текущую операцию. В worker выбран вариант ожидания текущей записи файла. В коротком браузерном опыте учебное ожидание поддерживает AbortController.
На сервере менеджер службы обычно посылает SIGTERM и ждёт ограниченное время. Если обработка может продолжаться час, стандартного ожидания будет недостаточно. Нужны контрольные точки, сохранение состояния, безопасный повтор или более короткие задания в очереди. Принудительное завершение посередине операции может оставить частично записанный результат.
Проверяйте этот путь отдельно: начните реальную работу, отправьте сигнал и убедитесь, что новые вызовы не появляются, а текущая операция завершается по выбранной политике. В Linux-проверке исходников подтверждена последовательность stopping с причиной SIGTERM и финальное stopped. Она полезнее предположения, что завершение процесса обязательно пройдёт так же, как обычный запуск.
process.on('SIGTERM', () => void shutdown('SIGTERM'));
process.on('SIGINT', () => void shutdown('SIGINT'));
// shutdown сначала вызывает job.stop(), затем ожидает active Promise.
Пример 9. Несколько копий приложения
Когда приложение масштабируется до двух процессов или серверов, каждый экземпляр может создать собственное расписание. Оба честно соблюдают protect, потому что он действует внутри одного объекта, и оба выполняют одну бизнес-операцию. В записи мастерской два настоящих Croner дают суммарно четыре вызова. Это наглядно показывает границу локальной защиты.
Самый простой вариант — выделить одну активную службу планирования. При требованиях к отказоустойчивости понадобится координация: лидер, распределённая блокировка с корректным сроком действия или внешняя система расписаний. Но даже такая координация не освобождает обработчик от идемпотентности: повтор может возникнуть после сбоя между выполнением действия и фиксацией результата.
Идентификатор бизнес-операции должен отражать смысл, например клиент, тип отчёта и период. Уникальное ограничение в базе помогает обнаружить повтор. При этом запись «занято» сама требует политики истечения и восстановления после аварии. Не обещайте exactly-once на основании одной настройки protect: это свойство всей цепочки и её побочных эффектов.
const first = createTrial({ protect:true, duration:200, maxRuns:2 });
const second = createTrial({ protect:true, duration:200, maxRuns:2 });
const [a,b] = await Promise.all([first.done,second.done]);
console.log(a.runs + b.runs); // 4, а не 2
Расписание плюс очередь: когда связать с BullMQ
Для долгой генерации документа удобно разделить создание задания и обработку. Croner определяет момент и период отчёта, затем producer записывает задание в долговечную очередь. Worker получает задание независимо от процесса расписания, сообщает прогресс и применяет ограниченную политику повторов. Пользователь кабинета видит состояние подготовки и может скачать результат после завершения.
Важно продумать сбой между вычислением периода и постановкой задания. Если процесс упал до записи в очередь, одного будущего запуска может быть недостаточно. Храните список требуемых периодов и сверяйте, какие результаты уже созданы. Очередь хранит принятые задания, но не знает о тех, которые producer ещё не успел отправить.
На сайте уже есть подробные материалы о BullMQ и Symfony Lock. Они помогают построить следующую ступень: повторяемые операции, наблюдаемое состояние и работа нескольких процессов. Croner в такой схеме остаётся понятным календарным входом, а доставка и обработка получают собственные проверяемые механизмы.
Как встроить настройку расписаний в интерфейс сервиса
Пользователю полезнее видеть действие и ожидаемый результат, чем пустое поле со строкой cron. Предложите готовые варианты: по будням утром, каждый час, раз в неделю. Рядом покажите часовой пояс, ближайшие даты и объяснение периода отчёта. Расширенный режим со строкой cron можно оставить для тех, кому действительно нужны нестандартные правила.
В карточке расписания покажите последний успешный запуск, следующую дату, длительность и ссылку на результат. Ошибка должна отличаться от отсутствия запуска: это разные ситуации для оператора. Кнопки ручного запуска и временной паузы полезны, если сервер проверяет права и не допускает неконтролируемого повторения тяжёлой операции.
При изменении зоны или выражения пересчитайте предпросмотр и явно попросите сохранить настройку. В мастерской изменение полей очищает прежний результат по той же причине. На мобильном устройстве расположите настройки и итог вертикально, а технический журнал сверните в раскрываемый блок. Первым экраном должна быть польза и состояние задачи, а подробности — доступны по мере необходимости.
Наблюдение, проверки и границы надёжности
В проекте проверены календарные переходы, явная зона, различие И/ИЛИ, ошибка ввода и конкретный весенний DST. Живые тесты измеряют перекрытие, protect, исключение, паузу, отмену и два независимых экземпляра. Windows и Linux прошли по пять составных тестов; worker создаёт три учебных отчёта, а Linux-проверка дополнительно подтверждает обработку SIGTERM.
Тесты календаря не зависят от сегодняшней даты: опорные моменты зафиксированы. Это делает результат воспроизводимым через месяц. Живые таймеры проверяются по событиям и диапазонам поведения, а не по требованию попасть в миллисекунду. Система общего назначения не обещает жёсткое реальное время, особенно при нагрузке или приостановке процесса.
Для эксплуатации добавьте метрики последнего успешного запуска, количества ошибок и длительности. Настройте предупреждение, если важный отчёт не появился к допустимому сроку. Отсутствие исключения в логах не доказывает, что задача вообще запускалась. Проверка полезного результата должна соответствовать исходному требованию бизнеса, с которого началась настройка расписания.
Файл: test/core.test.mjs
test('weekend gap and explicit zone',()=>{assert.equal(schedule(base)[0].utc,'2026-11-23T06:00:00.000Z');assert.equal(schedule({...base,timezone:'UTC'})[0].utc,'2026-11-20T09:00:00.000Z');});
test('invalid input cannot return stale success',()=>{for(const bad of [{pattern:'70 * * * *'},{count:100},{timezone:'invalid'},{anchor:'tomorrow'},{anchor:'2027-02-30T00:00:00Z'},{anchor:'2027-04-31T00:00:00Z'},{anchor:'2027-11-17T24:00:00Z'}])assert.throws(()=>schedule({...base,...bad}));});
test('DOM/DOW OR and AND are observably distinct',()=>{const x={...base,pattern:'0 9 1 * MON',anchor:'2026-11-17T00:00:00Z',count:1};assert.equal(schedule(x)[0].utc,'2026-11-23T06:00:00.000Z');assert.equal(schedule({...x,domAndDow:true})[0].utc,'2027-02-01T06:00:00.000Z');});
test('fixed DST spring job executes after gap',()=>{const rows=schedule({...base,pattern:'30 2 * * *',timezone:'Europe/Berlin',anchor:'2027-03-28T00:00:00Z',count:2});assert.equal(rows[0].utc,'2027-03-28T01:00:00.000Z');assert.equal(rows[1].utc,'2027-03-29T00:30:00.000Z');});
Исходники и официальные материалы
В архив входят браузерная мастерская, Node.js worker, тесты, сценарий Linux-проверки, unit systemd и README с командами для обеих платформ. Исходники в просмотрщике берутся из тех же файлов, поэтому можно сопоставлять объяснение и исполняемый код. Для первого собственного проекта начните с одного отчёта, явной зоны и безопасного учебного результата, затем добавляйте хранение и очередь по необходимости.
При обновлении Croner сначала повторите тесты ваших календарных границ и завершения процесса. Особенно внимательно проверьте переходы зон, поведение пропущенных запусков и правила перекрытия. Документация закреплённой версии и собственные тестовые даты помогают сохранить ожидаемое поведение при развитии приложения.
Официальные источники ниже описывают синтаксис, параметры, методы и жизненный цикл Node.js. Практический пример в этой статье связывает их с одной законченной задачей: создать расписание, увидеть будущие даты, выполнить работу, заметить ошибку и управляемо остановить процесс. Этого достаточно, чтобы осмысленно перенести инструмент в свой сервис.


