Демоны
Демон — это несколько воркеров одной логики под присмотром. Упавшего перезапустят с нарастающей задержкой, зависшего убьют и заменят, а число рабочих рук можно менять на ходу — вручную или по нагрузке.
Что такое демон и зачем
Демон — компонент из двух частей: мастера-супервизора и флота одинаковых воркеров, которыми он управляет.
Проблема. Процесс решает задачу «работать непрерывно», но остаётся один. Как только работы становится больше, чем успевает один воркер, всплывают вопросы, которых у одиночки не было:
- запустить пять копий — как? Пять классов-близнецов или пять юнитов
systemd? - один упал — кто заметит и поднимет? И что, если он падает в цикле — как не положить систему бесконечными перезапусками?
- один завис на сетевом вызове навсегда — он ведь формально жив,
psего видит; - ночью работы вдвое меньше — как убрать лишних, не оборвав тех, кто занят?
Каждый ответ по отдельности несложен, но вместе это уже супервизор, который вам не хочется писать.
Решение. Winter даёт его готовым. Вы описываете тело одного воркера и говорите, сколько их нужно; мастер следит за флотом: форкает, считает падения, выдерживает паузы перед перезапуском, убивает зависших, добавляет и убирает воркеров по вашему сигналу.
Быстрый старт
Наследуйте Daemon, опишите работу в workerRun() и укажите число реплик:
<?php
namespace Main\Process;
use Flytachi\Winter\DI\Attribute\Autowired;
use Flytachi\Winter\Kernel\Process\Stereotype\Daemon;
class Emails extends Daemon
{
#[Autowired] private OutboxRepository $outbox;
#[Autowired] private Mailer $mailer;
protected int $replicas = 4; // четыре воркера
protected function workerRun(): void
{
while ($this->isRunning()) {
$letter = $this->outbox->takeNext();
if ($letter === null) {
$this->sleep(1);
continue;
}
$this->markBusy();
try {
$this->mailer->send($letter);
$this->outbox->markSent($letter->id);
} finally {
$this->markIdle();
}
}
}
}Объявляем в манифесте:
#[EnableDaemon(\Main\Process\Emails::class)]
final class Application extends WinterApplication { /* ... */ }Или запускаем отдельно:
php call daemon main.process.Emails start -d
php call daemon main.process.Emails status | [================================= Daemon =================================]
| [ Daemon Status ]
| Main.Process.Emails ......................................... [Daemon ● RUNNING]
| - - - - - - - - - - - - - - - - - - - - - - -
| PID 51204
| State RUNNING
| Activity BUSY
| Started 2026-08-20 16:18:40 +00:00
| Uptime 6h 12m
| Workers 4
| Restarts 1
| - - - - - - - - - - - - - - - - - - - - - - -
| [ Workers (4) ]
| SLOT PID STATE ACT UPTIME RESTARTS
| #0 51210 running busy 6h 12m 0
| #1 51211 running idle 6h 12m 0
| #2 51212 running busy 6h 12m 0
| #3 52890 running idle 41m 1
| [ Daemon Status ]
| [================================= Daemon =================================]Тело воркера — `workerRun()`, а не `run()`
Метод run() у демона объявлен final: он занят самим супервизором. Работу
описывайте в workerRun() — это тело одного воркера, и выполняется оно уже в
дочернем процессе, а не в мастере.
Внутри доступно всё, что есть у процесса: isRunning(), sleep(), markBusy(),
markIdle(), spawn(), activity(), touch(), готовый $this->logger. Демон
наследует Процесс целиком — полный список в разделе
Что ещё доступно внутри.
Воркер отдельным классом
Если тело воркера уже описано самостоятельным процессом, workerRun() можно не
писать — укажите класс:
class Emails extends Daemon
{
protected int $replicas = 4;
protected ?string $workerClass = \Main\Process\SendWorker::class;
}Так удобно, когда один и тот же воркер должен уметь запускаться и в одиночку, и
флотом. Тело обязано быть задано одним из двух способов: без workerRun() и
без $workerClass демон уйдёт в бесконечный цикл падений.
Настройки
| Свойство | По умолчанию | Что задаёт |
|---|---|---|
$replicas |
1 |
Базовое число воркеров |
$workerClass |
null |
Класс воркера, если тело не описано в workerRun() |
$grace |
30.0 |
Сколько секунд ждать завершения работы воркера перед SIGKILL |
$livenessTimeout |
0.0 |
Сторож: убить воркера, молчащего дольше этого; 0 — выключен |
$concurrency |
0 |
Предел одновременных spawn()-задач внутри воркера |
`$grace` действует на каждого воркера
Умолчание то же, что у обычного процесса, — 30 секунд, как
terminationGracePeriodSeconds в Kubernetes: один застрявший воркер не должен держать
остановку всего флота. Ноль означает «ждать вечно» — ставьте его, только если работу
нельзя обрывать ни при каких условиях.
Минимальное число реплик — единица: $replicas = 0 будет поднято до 1. Свести
флот к нулю можно только динамически, через desiredReplicas().
Перезапуск упавших
Воркеров перезапускает демон, демона — никто
Всё, что ниже, — про воркеров внутри демона. Сам демон приложение не перезапускает:
если он сдался (исчерпал maxRestarts) или упал, решает параметр critical —
остановить приложение или оставить демона лежать. Демон, чьи воркеры так и не
поднялись за startTimeout, считается не стартовавшим — см.
Супервизия.
Что делать с умершим воркером, решает политика перезапуска.
use Flytachi\Winter\Kernel\Process\Daemon\{RestartPolicy, RestartMode};
protected function restart(): RestartPolicy
{
return new RestartPolicy(
mode: RestartMode::ON_FAILURE,
maxRestarts: 0,
backoff: 1.0,
);
}| Параметр | По умолчанию | Что задаёт |
|---|---|---|
mode |
ON_FAILURE |
Когда перезапускать |
maxRestarts |
0 |
Предел перезапусков на весь флот; 0 — без предела |
backoff |
1.0 |
Базовая пауза перед перезапуском, в секундах |
Три режима, названные по соглашению Kubernetes и systemd — если вы описывали там рестарт-политику, семантика та же:
| Режим | Поведение |
|---|---|
ALWAYS |
Перезапускать при любом выходе — воркер обязан жить, пока демона не остановят |
ON_FAILURE |
Перезапускать только после сбоя; штатное завершение считается окончательным |
NEVER |
Не перезапускать: одна попытка — и всё |
Каждое падение воркера пишется в лог с причиной и решением:
worker#1 (PID 38) crashed: killed by signal 9; restarting in 1s.
worker#3 (PID 52) crashed: exit code 1; not restarted (restart policy).
worker#2 (PID 61) crashed: exit code 255; restart limit reached.not restarted (restart policy) — политика не заменяет воркера (NEVER);
restart limit reached — исчерпан maxRestarts, и демон останавливает флот. Номер в
worker#N — тот же, что в ps: слот #0 — это worker#1.
Нарастающая пауза
Перезапуск не мгновенный: пауза удваивается с каждым падением этого воркера и упирается в потолок 30 секунд. При базовой паузе в секунду это даёт
1 → 2 → 4 → 8 → 16 → 30 → 30 → …
Смысл в том, чтобы воркер, падающий из-за недоступной базы, не превратился в бесконечный цикл форков и не мешал системе восстановиться.
`maxRestarts` считается на весь флот и гасит демона целиком
Это не «сколько раз перезапускать каждого воркера», а сколько перезапусков
допустимо всего. Достигнув предела, супервизор не просто перестаёт поднимать
конкретный слот — он останавливает весь демон, переводя его в состояние FAILED
с записью в лог уровня critical.
Умолчание 0 (без предела) для большинства случаев верное: демон должен пережить
временную недоступность зависимостей. Предел ставьте, когда лучше упасть заметно,
чем работать вечно вхолостую.
Сторож зависаний
Упавшего воркера видно, зависшего — нет: процесс жив, ps его показывает, работа
стоит. Для этого есть отдельный механизм:
protected float $livenessTimeout = 120.0;Каждый воркер регулярно подаёт признак жизни. Если признака нет дольше указанного времени, мастер убивает воркера принудительно, и дальше он идёт обычным путём падения — с паузой и перезапуском.
Не убейте здорового
Признак жизни подаётся, когда воркер отдаёт управление — на ожидании базы, сети или паузе. Долгая работа без ввода-вывода (тяжёлый расчёт) выглядит для сторожа так же, как зависание.
Ставьте $livenessTimeout заведомо больше самой долгой непрерывной операции, а
внутри такой операции подавайте признак сами:
$this->touch();
Масштабирование
Число воркеров может меняться на ходу. Переопределите desiredReplicas() — он
опрашивается регулярно, и его ответ становится целью:
protected function desiredReplicas(): int
{
$depth = $this->outbox->pendingCount();
return match (true) {
$depth > 10_000 => 20,
$depth > 1_000 => 10,
$depth > 0 => 4,
default => 1,
};
}Возвращать можно и ноль — тогда флот свернётся полностью и развернётся, когда работа появится.
Почему флот меняется не сразу
Ответ desiredReplicas() — это сигнал, а не команда. Супервизор сглаживает
его, чтобы случайный всплеск не дёргал флот туда-сюда:
use Flytachi\Winter\Kernel\Process\Daemon\ScalingPolicy;
protected function scaling(): ScalingPolicy
{
return new ScalingPolicy(
scaleInterval: 1.0,
scaleUpDelay: 0.0,
scaleDownStabilization: 60.0,
cooldown: 3.0,
scaleStep: 0,
);
}| Параметр | По умолчанию | Что задаёт |
|---|---|---|
scaleInterval |
1.0 |
Как часто опрашивать desiredReplicas() |
scaleUpDelay |
0.0 |
Сколько спрос должен держаться, прежде чем расширять флот; 0 — сразу |
scaleDownStabilization |
60.0 |
Сколько низкий спрос должен держаться, прежде чем сокращать |
cooldown |
3.0 |
Минимум между двумя действиями по масштабированию |
scaleStep |
0 |
Максимум воркеров за одно действие; 0 — без ограничения |
Модель намеренно несимметрична: вверх быстро, вниз осторожно. Всплеск нагрузки нужно обслужить немедленно, а вот убирать воркеров из-за минутного затишья — плохая идея: через минуту их придётся поднимать заново.
Сокращение уважает занятость: при прочих равных первыми уходят простаивающие
воркеры, а занятому дают доработать в пределах $grace.
Общая работа на несколько воркеров
Главное отличие демона от процесса в повседневной работе — воркеров несколько, и они лезут за работой одновременно. Фреймворк их запускает и стережёт, но не координирует: как поделить работу, решаете вы.
Наивная выборка выдаст одну задачу всем
Такой код в теле воркера выглядит правильно и ломается сразу:
$letter = $this->db->query('SELECT * FROM outbox WHERE sent = 0 LIMIT 1');
Четыре воркера выполнят его почти одновременно, получат одну и ту же строку — и
письмо уйдёт четыре раза. Ошибка не проявится при replicas: 1, поэтому её обычно
привозят в продакшен вместе с масштабированием.
Задачу нужно захватывать атомарно: пометить своей и получить обратно в одном действии, чтобы между «выбрал» и «занял» не вклинился сосед.
Самый переносимый приём — пометить строку условным обновлением и убедиться, что обновилась именно она:
-- 1. пытаемся занять: помечаем ровно одну свободную строку своим маркером
UPDATE outbox
SET claimed_by = :worker, claimed_at = NOW()
WHERE id = (SELECT id FROM outbox WHERE claimed_by IS NULL ORDER BY id LIMIT 1);
-- 2. забираем то, что заняли именно мы
SELECT * FROM outbox WHERE claimed_by = :worker AND claimed_at IS NOT NULL LIMIT 1;В PostgreSQL и MySQL 8 то же самое короче — выборкой с пропуском занятых строк:
SELECT * FROM outbox
WHERE claimed_by IS NULL
ORDER BY id LIMIT 1
FOR UPDATE SKIP LOCKED;Маркером удобно брать номер слота или PID воркера: тогда по зависшим задачам видно, кто их занял.
Очередь пишете вы
Winter не предоставляет очередь — ни таблицы, ни брокера. OutboxRepository из
примеров ваш; обычно это таблица с колонками состояния и захвата, поверх которой вы
пишете «взять», «завершить» и «вернуть». Про обращение к базе — на странице
Конструктор запросов.
Задача, взятая воркером, должна уметь вернуться: если процесс убили посреди работы, маркер захвата останется висеть. Обычно это лечат отдельной задачей планировщика, которая освобождает записи, захваченные слишком давно.
Номер воркера — не для деления работы
Воркер может узнать свой номер слота — Process::current()->slot. Он пригодится в
логах и метриках, чтобы отличать воркеров друг от друга:
$this->logger->info('batch done', ['slot' => Process::current()->slot]);Но делить по нему работу заранее — «воркер №0 берёт чётные записи, №1 нечётные» — не стоит. Номера живут ровно до первого падения: упавшего воркера заменят, флот может вырасти или сжаться, а разрезание, привязанное к числу реплик, после каждого такого события станет неверным — часть работы достанется двоим, часть никому.
Поэтому делить работу нужно через общее состояние, а не по позиции: атомарный захват из очереди, как выше, либо захват целого куска — если единица работы крупная.
-- воркер занимает не задачу, а целый раздел работы
UPDATE shards
SET owner = :pid, taken_at = NOW()
WHERE id = (SELECT id FROM shards
WHERE owner IS NULL OR taken_at < NOW() - INTERVAL '5 minutes'
ORDER BY id LIMIT 1);Второе условие — про истёкший срок — здесь обязательно: если воркер умрёт, его раздел должен вернуться в работу, а не остаться занятым навсегда.
Хуки жизненного цикла
Все четыре необязательны и вызываются в мастере.
| Хук | Когда |
|---|---|
onWorkerStart(int $slot, int $pid) |
Воркер запущен в слоте |
onWorkerExit(int $slot, int $pid, bool $crashed) |
Воркер завершился; $crashed — был ли это сбой |
onScale(int $from, int $to) |
Размер флота изменился |
tick() |
Периодически, примерно раз в scaleInterval — удобно снимать метрики |
protected function onWorkerExit(int $slot, int $pid, bool $crashed): void
{
if ($crashed) {
$this->metrics->increment('emails.worker_crashed');
}
}
protected function tick(): void
{
$this->metrics->gauge('emails.queue_depth', $this->outbox->pendingCount());
}Исключение внутри хука перехватывается и логируется — сломанный хук не уронит супервизор.
Хуки выполняются в супервизоре, а не в воркере. Отличить его помогает
Daemon::supervising(): в супервизоре он возвращает класс демона, во всех остальных
местах — null. Process::current() в супервизоре, наоборот, null: своего тела у него
нет, работу делают воркеры.
Daemon::supervising(); // 'Main\Process\Emails' в супервизоре, null в воркерах и в вебеОбращаться к базе из хуков можно — как в примере с tick() выше. Перед каждым форком
воркера супервизор закрывает свои соединения с базой и Redis, поэтому воркер их не
наследует и не может оборвать; супервизор переподключится сам при следующем запросе.
Единственное, чего делать нельзя, — оставлять в хуке открытую транзакцию. Соединение с
транзакцией закрыть нельзя, а форк с ним оборвал бы её, поэтому воркер не запускается,
пока транзакция не закрыта: супервизор повторяет попытку раз в секунду и пишет каждую в
лог как ошибку.
Перезагрузка по SIGHUP
SIGHUP демону — перезагрузка, а не остановка. Мастер вызывает свой onReload() и
передаёт SIGHUP каждому живому воркеру, а там срабатывает onReload() тела воркера —
того же класса демона или класса из $workerClass. Отличить, где выполняется хук, помогает
тот же Daemon::supervising().
protected function onReload(): void
{
if (Daemon::supervising() !== null) {
$this->logger->info('мастер: перечитываю настройки флота');
return;
}
$this->logger->info('воркер: сбрасываю свои кеши');
}Демон под php call run получает SIGHUP от приложения: kill -HUP <PID приложения>
перезагружает все компоненты — см.
Сигналы приложению. Воркер, который ещё
поднимается, такие сигналы игнорирует, пока не поставит свои обработчики: по умолчанию
SIGHUP завершил бы его.
Состояния воркеров
В выводе status у каждого слота своё состояние. Оно помогает понять, что
происходит с флотом прямо сейчас.
| Состояние | Что значит |
|---|---|
starting |
Форкнут, ждём первого признака жизни |
running |
Работает |
retiring |
Получил команду завершиться и доделывает работу |
killing |
Не уложился в $grace, отправлен SIGKILL |
restarting |
Неожиданно умер, выдерживает паузу перед перезапуском |
retired |
Умер, и политика решила не заменять его |
Номер слота стабилен: перезапуск возвращает воркера в тот же слот, поэтому
#2 в логах всегда означает одного и того же участника флота.
Как флот выглядит в ps
Мастер и воркеры называют себя так, чтобы всё дерево находилось одним grep:
ps -eo pid,command | grep winter-daemon12825 winter-daemon: StableDaemon master
12826 winter-daemon: StableDaemon worker#1
12827 winter-daemon: StableDaemon worker#2Номер в имени — единица плюс номер слота: слот #0 из таблицы status
показывается в ps как worker#1. Имя берётся из $processTitle, а если он не
задан — из короткого имени класса, как и у обычного процесса.
Управление из кода
Демон наследует у процесса ту же статическую поверхность управления, поэтому запускать, останавливать и опрашивать флот можно прямо из приложения.
| Метод | Что делает |
|---|---|
start(): void |
Поднимает супервизор в текущем процессе, не возвращая управление |
dispatch(?string $output = '/dev/null'): int |
Поднимает супервизор в фоне, возвращает его PID |
status(bool $usage = false): ?DaemonStatus |
Состояние флота или null, если демон не запущен |
stop(): bool |
Мягко останавливает весь флот |
relaunch(): bool |
Перезапускает: остановить и снова запустить; false, если не удалось |
Пока работает приложение, stop(), dispatch() и relaunch() идут через него: stop()
оставляет демона остановленным, dispatch() запускает его снова внутри приложения,
relaunch() просит приложение перезапустить его — сбоем это не считается. Подробно —
Управление работающим компонентом.
use Main\Process\Emails;
$pid = Emails::dispatch(); // супервизор ушёл в фон
Emails::stop(); // остановить весь флотКак и у процесса, start() блокирует вызывающего — из веба используйте
dispatch().
Состояние флота
status() возвращает не просто состояние мастера, а снимок всего флота: к обычным
полям процесса добавляются два.
| Поле | Тип | Что содержит |
|---|---|---|
$restarts |
int |
Сколько перезапусков было всего с момента старта |
$workers |
WorkerStatus[] |
По записи на каждый занятый слот |
У каждого воркера доступно:
| Поле | Тип | Что содержит |
|---|---|---|
$slot |
int |
Номер слота — стабилен между перезапусками |
$pid |
int |
Идентификатор процесса воркера |
$state |
SlotState |
running, starting, restarting и остальные |
$activity |
Activity |
IDLE или BUSY |
$startedAt |
int |
Когда этот воркер был запущен |
$restarts |
int |
Сколько раз перезапускался именно этот слот |
Это позволяет строить собственные проверки и панели, не разбирая вывод консоли:
use Flytachi\Winter\Kernel\Process\Activity;
$status = Emails::status();
if ($status === null) {
Emails::dispatch(); // флот не поднят — поднимем
return;
}
$busy = array_filter(
$status->workers,
fn($w) => $w->activity === Activity::BUSY,
);
// все воркеры заняты дольше минуты — повод присмотреться
if (count($busy) === count($status->workers)) {
$this->alerts->fire('Emails: весь флот занят');
}Снимок можно вернуть как есть
DaemonStatus и WorkerStatus сериализуются в JSON сами, поэтому объект состояния
годится в качестве ответа контроллера без ручной сборки.
Управление из консоли
php call daemon list # все демоны и размер их флотов
php call daemon main.process.Emails # супервизор в текущем терминале
php call daemon main.process.Emails start -d # в фоне
php call daemon main.process.Emails stop # мягкая остановка всего флота
php call daemon main.process.Emails restart # остановить и запустить снова
php call daemon main.process.Emails status # состояние + таблица воркеров
php call daemon main.process.Emails status -v # плюс расход ресурсов мастераОстановка идёт в два шага
Первый сигнал останавливает флот мягко: новые задачи не берутся, занятые воркеры
доделывают начатое в пределах $grace. Повторный сигнал завершает всех немедленно.
Примеры
Флот фиксированного размера
Самый частый случай: работы стабильно много, автомасштабирование не нужно.
<?php
namespace Main\Process;
use Flytachi\Winter\DI\Attribute\Autowired;
use Flytachi\Winter\Kernel\Process\Stereotype\Daemon;
class Webhooks extends Daemon
{
#[Autowired] private WebhookRepository $hooks;
#[Autowired] private HttpClient $http;
protected int $replicas = 8;
protected float $grace = 20.0;
protected float $livenessTimeout = 90.0;
protected function workerRun(): void
{
while ($this->isRunning()) {
$hook = $this->hooks->takeNext();
if ($hook === null) {
$this->sleep(1);
continue;
}
$this->markBusy();
try {
$this->http->post($hook->url, $hook->payload);
$this->hooks->markDelivered($hook->id);
} catch (\Throwable $e) {
$this->hooks->retryLater($hook->id);
$this->logger->warning('webhook failed', ['id' => $hook->id]);
} finally {
$this->markIdle();
}
}
}
}Три момента, без которых флот работает хуже: markBusy() не даёт остановить
воркера посреди доставки и сбрасывает состояние между задачами; retryLater() в
catch возвращает задачу в очередь; $livenessTimeout ловит зависшие HTTP-вызовы.
Автомасштабирование по глубине очереди
<?php
namespace Main\Process;
use Flytachi\Winter\DI\Attribute\Autowired;
use Flytachi\Winter\Kernel\Process\Daemon\ScalingPolicy;
use Flytachi\Winter\Kernel\Process\Stereotype\Daemon;
class Imports extends Daemon
{
#[Autowired] private ImportQueue $queue;
protected int $replicas = 2; // базовый размер
protected float $grace = 120.0; // импорт нельзя рвать на середине
protected function desiredReplicas(): int
{
return min(16, max(2, (int) ceil($this->queue->pendingCount() / 50)));
}
protected function scaling(): ScalingPolicy
{
return new ScalingPolicy(
scaleUpDelay: 5.0, // всплеск должен продержаться 5 с
scaleDownStabilization: 300.0, // сокращаем только после 5 минут затишья
scaleStep: 4, // не больше 4 воркеров за раз
);
}
}Настройки здесь под конкретную задачу: импорт долгий, поэтому сокращаться нужно неспешно, а прирост ограничен шагом, чтобы не выдать базе разом шестнадцать подключений.
Обратите внимание, что workerRun() здесь нет — значит, тело берётся из
$workerClass. Если его тоже не задать, демон будет падать при каждом форке.
Один воркер, но с присмотром
Демон осмысленен и с единственной репликой: вы получаете перезапуск после падений и сторож зависаний, которых у обычного процесса нет.
class SnmpPoller extends Daemon
{
protected int $replicas = 1;
protected float $livenessTimeout = 60.0;
protected function restart(): RestartPolicy
{
return new RestartPolicy(mode: RestartMode::ALWAYS, backoff: 5.0);
}
protected function workerRun(): void { /* ... */ }
}ALWAYS здесь уместнее умолчания: опросчик не должен завершаться штатно вообще,
и если он вышел — значит что-то не так, и его нужно поднять в любом случае.
Дальше
- Процессы — примитивы тела воркера: цикл, паузы, единицы работы
- Состав приложения — где объявляется
#[EnableDaemon] - Планировщик — когда работа привязана ко времени
- Логирование — куда пишет супервизор
- Actuator / Health — наблюдение за приложением снаружи