Как организовать корректный graceful shutdown воркеров в PHP, чтобы завершить начатые задачи без потерь?

Question

Graceful shutdown — это завершение воркера без резкого прерывания текущей задачи. Для этого воркер должен уметь ловить сигналы (SIGTERM, SIGINT), прекращать принимать новые сообщения и корректно завершать обработку текущего. После завершения работы нужно подтвердить или вернуть сообщение в очередь. В PHP это реализуется через pcntl-сигналы, флаги остановки и аккуратное управление циклом обработки.

YeaHub · Accepted Answer

Как реализовать корректный graceful shutdown воркеровGraceful shutdown необходим, чтобы гарантировать отсутствие потерь сообщений и корректное завершение фоновых задач.1. Проблема резкого завершенияЕсли воркер убить:текущая задача оборвётсясообщение останется "висеть"бизнес-логика может быть частично выполненаданные могут оказаться в неконсистентном состоянииТребуется аккуратное завершение.2. Основные шаги graceful shutdown1. Ловля сигналовВ PHP используют расширение pcntl:phppcntl_async_signals(true);

$shouldStop = false;

pcntl_signal(SIGTERM, function() use (&$shouldStop) {
    $shouldStop = true;
});
2. Прекращение принятия новых сообщенийЦикл обработки должен проверять флаг:phpwhile (!$shouldStop) {
    $msg = $queue->get(); // блокирующий вызов по возможности обернуть
    process($msg);
}
3. Завершение текущей задачиПосле получения сигнала:не брать новые сообщениязавершить текущую обработкуподтвердить или откатить сообщениеВажно: не завершать воркер мгновенно.3. Подтверждение сообщенийЕсть 2 варианта:успешная обработка → ackошибка → nack/requeueЭто гарантирует отсутствие потерь.4. Управление блокирующими вызовамиЕсли воркер блокируется на чтении:нужно использовать таймаутыили неблокирующие вызовыили поток с heartbeat5. Тайм-аут на завершениеGraceful shutdown не должен длиться бесконечно.Обычно:30–60 секундзатем воркер завершает выполнение принудительно6. Пример мини-реализацииphppcntl_async_signals(true);

$stop = false;
pcntl_signal(SIGTERM, fn() => $stop = true);

while (true) {
    if ($stop) break;

$msg = $channel->basic_get('queue');

if ($msg) {
        try {
            handle($msg);
            $channel->basic_ack($msg->delivery_info['delivery_tag']);
        } catch (Throwable $e) {
            $channel->basic_nack($msg->delivery_info['delivery_tag'], requeue: true);
        }
    }

usleep(50000);
}

echo "Worker stopped gracefully
";
7. Дополнительные аспектылогировать факт получения сигналаотдавать SIGKILL только после timeoutиспользовать supervisor, systemd или Kubernetes lifecycle hooksдля контейнеров — корректная работа с PID18. ВыводGraceful shutdown — обязательный элемент для надёжных воркеров. Он включает ловлю сигналов, остановку принятия новых задач, завершение текущих задач и корректное подтверждение сообщений. Это предотвращает потерю данных и обеспечивает прогнозируемое поведение сервисов.