Состав приложения
Приложение Winter — это не обязательно веб-сервер. Оно собирается из компонентов, и веб среди них лишь один из пяти: рядом могут работать долгоживущие процессы, флоты воркеров под супервизией, планировщик задач и WebSocket-серверы. Любой из них может быть единственным.
Что такое компоненты и зачем
Компонент — самостоятельная часть приложения со своим способом работы: веб отвечает на запросы, процесс крутится в цикле, демон держит флот воркеров, планировщик запускает задачи по времени.
Проблема. У приложения редко бывает одна форма. Сервису с API почти всегда
нужен кто-то ещё: разгребать очередь, опрашивать оборудование, чистить старые
записи по ночам. Обычно это решается снаружи — отдельными скриптами под cron,
юнитами systemd, сторонним супервизором. И тогда одно приложение превращается в
несколько развёртываний: разные способы запуска, разные конфигурации, разные логи,
а общий код между ними приходится тащить пакетом.
Решение. Winter описывает состав приложения в самом приложении. Класс-точка
входа перечисляет атрибутами, из чего оно состоит, — и php call run поднимает
всё это вместе, под одним конфигом, с общим контейнером зависимостей и общими
логами. Понадобился воркер — это строка в манифесте, а не новое развёртывание.
Манифест
Всё объявляется атрибутами на классе приложения:
<?php
use Flytachi\Winter\Kernel\App\Attribute\EnableDaemon;
use Flytachi\Winter\Kernel\App\Attribute\EnableProcess;
use Flytachi\Winter\Kernel\App\Attribute\EnableScheduler;
use Flytachi\Winter\Kernel\App\Attribute\EnableHttp;
use Flytachi\Winter\Kernel\App\Attribute\EnableWebSocket;
use Flytachi\Winter\Kernel\WinterApplication;
require __DIR__ . '/vendor/autoload.php';
#[EnableHttp] // HTTP-сервер
#[EnableScheduler] // задачи по расписанию
#[EnableProcess(\Main\Process\SnmpPoller::class)] // один воркер
#[EnableDaemon(\Main\Process\Emails::class)] // флот воркеров
#[EnableWebSocket(\Main\ChatSocket::class, port: 8001)] // WebSocket-сервер
final class Application extends WinterApplication
{
public static function main(array $argv): never
{
parent::run($argv);
}
}Это весь файл запуска. Настройки живут в обычных классах, которые находит сканер, —
см. Внедрение зависимостей и
Настройку веб-слоя. А то, что атрибутам недоступно, —
условия, значения из окружения, внешние программы — объявляется кодом в хуке
components().
Пять компонентов
| Атрибут | Что поднимает | Повторяемый |
|---|---|---|
#[EnableHttp(port: …)] |
HTTP-сервер; по умолчанию 0.0.0.0:8000 |
нет |
#[EnableProcess(Класс)] |
Один долгоживущий процесс | да |
#[EnableDaemon(Класс)] |
Флот воркеров под супервизией | да |
#[EnableWebSocket(Класс, port: …)] |
WebSocket-сервер на своём порту | да |
#[EnableScheduler] |
Планировщик задач #[Scheduled] |
нет |
Повторяемость означает буквально это: несколько разных процессов и несколько разных демонов объявляются несколькими строками. Один и тот же класс дважды объявить нельзя — процесс работает в одном экземпляре, и приложение не стартует с подсказкой.
У всех атрибутов есть параметры супервизии: что делать, если компонент не запускается или падает, — см. Супервизия.
#[EnableProcess(\Main\Process\SnmpPoller::class)]
#[EnableProcess(\Main\Process\Heartbeat::class)]
#[EnableDaemon(\Main\Process\Emails::class)]
#[EnableDaemon(\Main\Process\Webhooks::class)]Адрес HTTP-сервера объявляется так же, как у WebSocket, — рядом с ним:
#[EnableHttp(port: 8080, host: '127.0.0.1')]. При запуске его переопределяют флаги
--http.port / --http.host, а последнее слово —
за конфигуратором веб-слоя. Прежнее имя атрибута —
#[EnableWeb]: оно устарело и работает как #[EnableHttp] без параметров.
Что компонентом не является
Три атрибута выглядят похоже, но ничего не поднимают:
| Атрибут | Что делает |
|---|---|
#[EnableAsync] |
Включает проксирование методов с #[Async] — см. Асинхронные вызовы |
#[EnableCaching] |
Включает кеширование методов с #[Cacheable] и соседними атрибутами — см. Кеширование методов |
#[EnableActuator] |
Добавляет вебу диагностические эндпоинты — см. Actuator / Health |
Запуск
Одна команда поднимает всё, что перечислено в манифесте:
php call run # рабочий режим
php call run dev # разработка: перезапуск при изменении .phpГлавный процесс — php call run, в контейнере это PID 1 — и есть приложение: он
запускает компоненты и следит за ними. Каждый компонент, HTTP-сервер в том числе,
работает в своём процессе: упавший поднимается по правилам из раздела
Супервизия, остановили приложение — остановятся все.
php call run ← приложение (PID 1)
├── winter-http: manager → Worker 0..N
├── winter-process: Heartbeat
├── winter-daemon: Emails master → worker#1, worker#2
└── …Одно приложение — один запуск
Второй php call run того же приложения из того же проекта не стартует:
Application is already running [PID 812] (since 2026-10-29 10:14:03 +05:00). Stop it before starting it again — one application runs once per project (.winter/).
В начале сообщения — полное имя класса вашего приложения. Два запуска делили бы между
собой одни и те же процессы-синглтоны. Аварийно убитый запуск (kill -9, docker kill)
повторному не мешает — см. Если приложение убито.
Приложение без веба
Убираете #[EnableHttp] — и приложение поднимается безголовым: только процессы,
демоны и планировщик.
#[EnableScheduler]
#[EnableDaemon(\Main\Process\Emails::class)]
final class Application extends WinterApplication { /* ... */ }Такое приложение по-прежнему пользуется контейнером, конфигурацией, логированием и доступом к базе — просто не слушает порт. Это обычный способ развернуть отдельный обработчик очереди или ночной регламент рядом с основным сервисом.
Пустой манифест — ошибка
Хотя бы один компонент объявить нужно. Приложение без единого #[Enable*] не
запустится и скажет об этом прямо: No components declared со списком доступных
атрибутов.
Остановка
SIGTERM (docker stop, kill <pid>) или Ctrl+C в терминале останавливают приложение
целиком. Каждый компонент фреймворка при этом получает SIGTERM, что бы ни получило
само приложение: Ctrl+C посылает приложению SIGINT, но его компоненты всё равно
останавливаются по SIGTERM — это единственный сигнал остановки, который корректно
обрабатывает каждый из них. Поэтому у процесса под приложением срабатывает
onTerminate(), а не onInterrupt().
Внешняя программа получает свой stopSignal —
по умолчанию тоже SIGTERM.
Начало и конец остановки видны в логе:
Application up: http://0.0.0.0:8000 + [Heartbeat, Emails]
Application stopping (SIGTERM): 3 component(s)
Application stopped in 125 msВ скобках — причина: SIGTERM, SIGINT или critical failure, если приложение
останавливает критичный компонент; тогда и последняя строка читается как
Application stopped (critical failure) in 2.7s. Длительность пишется в миллисекундах
до секунды и в секундах дальше. Ещё две строки на месте этих:
Application reloading.—php call run devперезапускается после изменения кода;Application finished: every component has done its work.— у приложения без веба все компоненты закончили работу сами, и оно вышло.
Каждому компоненту остановка даёт его собственный срок: процессу — его $grace
(по умолчанию 30 секунд), внешней программе — grace, HTTP-серверу — время на начатые
запросы (ожидание при остановке). Само
приложение ждёт свои компоненты не дольше 35 секунд — или на 5 секунд дольше самого
длинного из этих сроков, если он больше 30. Кто не остановился к этому времени, получает
SIGKILL, и лог говорит, чья работа оборвана:
Application stopping (SIGTERM): 3 component(s)
Application stop: not stopped within 35s — killing Emails.
Application stopped (forced) in 35.0sЕсли хоть у одного компонента $grace = 0 — ждать сколько угодно, — приложение
уважает этот выбор и своего срока не ставит.
С приоритетами уровни останавливаются друг за другом, и сроки складываются:
самый долгий срок в Low, плюс в Normal, плюс в High, плюс 5 секунд. HTTP на Low (30),
процессы на Normal (30) и база на High с grace: 60.0 дают 125 секунд — и столько же
должно быть у stop_grace_period контейнера.
Повторный сигнал остановки — второй Ctrl+C, второй kill — не ждёт: оставшиеся
компоненты сразу получают SIGKILL, в логе
Application stop: a second stop signal — killing Emails.
Сроки вложены друг в друга: компонент — 30 секунд, приложение — 35, контейнер — 40.
Последнее нужно задать самому. docker stop по умолчанию ждёт всего 10 секунд и затем
убивает контейнер целиком, так что 30 секунд компонентов не наступили бы никогда, — в
сгенерированном docker-compose.yml поэтому стоит stop_grace_period: 40s. В
Kubernetes задайте terminationGracePeriodSeconds: 40: умолчание 30 оборвёт 35-секундный
срок приложения.
Сигналы приложению
SIGHUP перезагружает всё приложение и ничего не останавливает. Его посылают
главному процессу — kill -HUP <pid>, в контейнере docker kill -s HUP <контейнер>, — и
каждый компонент перезагружается по-своему:
| Компонент | Что получает |
|---|---|
| HTTP-сервер | SIGUSR1 — плавный перезапуск воркеров: начатые запросы доделываются |
| Процесс | onReload() |
| Планировщик | заново читает расписание |
| Демон | свой onReload() и SIGHUP каждому воркеру — их onReload() |
| WebSocket | onReload() — по умолчанию ничего не делает |
Внешняя программа (script(), command()) |
ничего: SIGHUP по умолчанию завершил бы её |
В логе — Application reloading (SIGHUP): 4 component(s).
SIGUSR1 и SIGUSR2, посланные приложению, уходят только HTTP-серверу. Чтобы
вызвать onUser1() / onUser2() процесса, сигнал посылают на PID самого процесса —
его показывает php call process <Класс> status.
Если приложение убито
Компоненты работают в своих группах процессов и сами с приложением не умирают. Если
приложение убить так, что оно не успеет их остановить (kill -9, OOM killer), они
остались бы работать без присмотра: HTTP-сервер держал бы порт, и следующий
php call run не смог бы стартовать.
Поэтому приложение первым делом запускает маленький процесс-страж — в ps он виден
как winter-sentinel. Страж знает группы всех компонентов. Если приложение исчезло, не
остановив их, страж пишет в stderr строку
winter: the application (PID 812) is gone — stopping its components, посылает компонентам SIGTERM, через 30 секунд оставшимся — SIGKILL и выходит.
Блокировка приложения к этому времени свободна, и следующий php call run стартует.
Сигналы остановки страж игнорирует, так что Ctrl+C в терминале его не задевает.
В контейнере такого не бывает: вместе с PID 1 уходит весь контейнер. Если первым
погибнет сам страж, приложение работает дальше и пишет об этом предупреждение — с этого
момента после kill -9 компоненты останавливать некому.
Супервизия
Что это. Супервизор — часть приложения, которая запускает его компоненты и следит за ними: решает, перезапустить ли упавший компонент, сдаться или остановить всё приложение.
Проблема. Компонент, который не может работать, не должен ни молча лежать, ни бесконечно перезапускаться. Типичная картина без правил: воркер падает при старте из-за ошибки конфигурации, его перезапускают сотни раз в минуту, в логе — только «процесс завершился», а приложение при этом выглядит живым.
Решение. У каждого компонента два этапа жизни, и правила для них разные.
запуск ──► старт ──(готов)──► работа (часы, дни…)
│ │
упал или не успел упал
за startTimeout │
│ ▼
▼ перезапуск через 1 → 2 → 4 с,
без повторов не больше retries за 30 минутСтарт длится, пока компонент не станет готов. Упал на старте — значит, сломан, а не невезуч: повтор ничего не даст, только спрячет ошибку. Поэтому на старте повторов нет.
Работа начинается с готовности. Падение здесь — разовый сбой (оборвалось соединение,
кончилась память), и компонент перезапускается: через 1 секунду, потом через 2, через 4 —
не больше retries раз за 30 минут. Продержался 30 минут — счётчик снова с нуля.
Повтор, упавший уже на старте, считается одной из этих попыток.
Готовность фреймворк определяет сам:
| Компонент | Готов, когда |
|---|---|
| HTTP-сервер | Занял порт и запустился |
| Процесс | Начал выполнять run() — зависимости построены |
| Планировщик | Запустил цикл задач |
| WebSocket | Занял порт и принимает подключения |
| Демон | Все воркеры дошли до работы |
| Внешняя программа | Сразу после запуска — или когда проходит её проверка ready |
Параметры
| Параметр | По умолчанию | Что задаёт |
|---|---|---|
critical |
true |
Что делать, когда компонент больше не может работать: true — остановить приложение, false — оставить компонент лежать, а остальное пусть работает |
retries |
3 |
Сколько перезапусков после падения в работе за 30 минут |
startTimeout |
60 |
Сколько секунд на старт; не успел — это падение на старте. 0 — ждать сколько нужно |
priority |
Priority::Normal |
Когда компонент стартует и останавливается относительно остальных — см. Priority |
#[EnableHttp(retries: 5)]
#[EnableProcess(PriceImport::class, critical: false, startTimeout: 180)]
#[EnableScheduler(retries: 5)]
#[EnableWebSocket(ChatSocket::class, port: 8001, critical: false)]
#[EnableDaemon(Documents::class, startTimeout: 300)] // у демона нет retriesДемон не перезапускается никогда. Он сам супервизор своих воркеров и перезапускает
их по своей политике. Если упал сам демон или он сдался — ему
доступен только critical.
Критичный компонент, который больше не может работать, останавливает приложение:
остальные компоненты корректно завершаются, а php call run выходит с кодом 1. В
контейнере это видно сразу — docker ps покажет перезапуск, Kubernetes — CrashLoopBackOff.
Некритичный остаётся лежать в состоянии FAILED, а остальное приложение работает
дальше.
Что сбоем не считается
- Остановка по просьбе —
stop()из кода или консоли. Компонент остаётся остановленным, см. Управление работающим компонентом. Это так и тогда, когда тело процесса не уложилось в свойgraceи его завершили принудительно: остановка по просьбе — не падение, и компонент не перезапускается. - Остановка всего приложения.
- Процесс доделал работу:
run()вернул управление. Процесс не перезапускается и не оставляет записи о себе: вcall application statusон виден как выполненный (COMPLETED), а запустить его снова можно как любой процесс.
Отсюда правило: процесс, который должен работать всегда, не должен возвращаться из
run(). Пусть при ошибке бросает исключение — тогда это падение, и приложение его
перезапустит. Тихо вышедший из цикла процесс считается выполнившим работу.
Планировщик, WebSocket и демон работают в бесконечном цикле, который заканчивается только по остановке. Если цикл кончился сам — это падение.
Как это выглядит в логе
TickProcess is up.
TickProcess crashed: killed by signal 9; restart 1 of 3 in 1s.
TickProcess is up.
Reports failed: did not start: exit code 1. It is not critical: the application runs on without it.
Importer failed: did not start: was not ready within 60s. It is critical: the application stops.Причина падения на старте — исключение — пишется отдельной строкой рядом.
Порядок запуска и остановки
Что это. По умолчанию приложение запускает все компоненты разом и разом же их останавливает. Порядок задаётся, когда одни компоненты держатся на других.
Проблема. Допустим, база данных работает внутри приложения, как внешняя программа. Если всё стартует одновременно, HTTP-сервер начнёт принимать запросы, пока база ещё поднимается, и первые запросы получат ошибку. Миграциям некуда встать: они нужны после базы, но до сервера. А при остановке база получит сигнал вместе со всеми и может погаснуть раньше, чем закончатся запросы, которые к ней обращаются.
Решение. У каждого компонента есть приоритет, а у приложения — два метода: один выполняется между стартом базы и стартом остальных, другой — когда всё остановлено.
Priority
Приоритетов три. Чем выше приоритет, тем дольше компонент живёт: раньше стартует и позже останавливается.
| Приоритет | Стартует | Останавливается | Для чего |
|---|---|---|---|
Priority::High |
первым | последним | то, на чём держатся остальные: база, Redis, свой nginx |
Priority::Normal |
после High | между | работа приложения: процессы, демоны, планировщик. Значение по умолчанию |
Priority::Low |
когда всё готово | первым | то, что принимает трафик извне: HTTP, WebSocket |
Приоритет принимают все #[Enable*] и все методы components():
use Flytachi\Winter\Kernel\App\Priority;
#[EnableHttp(port: 8000, priority: Priority::Low)] // трафик — когда всё готово
#[EnableScheduler] // Normal
final class Application extends WinterApplication
{
protected static function components(Components $components): void
{
$components->command(['bin/postgres.sh'], name: 'postgres',
priority: Priority::High,
ready: ['pg_isready', '-q', '-h', '/run/postgresql'],
stopSignal: SIGINT,
retries: 3);
}
protected static function onStarting(): void
{
Migrations::apply(); // postgres здесь уже готов
}
}Migrations — класс вашего проекта. Как задаются ready, stopSignal и retries у
программы — в разделе Готовность, сигнал остановки, перезапуск.
Старт идёт по уровням: High → onStarting() → Normal → Low. Следующий
уровень стартует, когда все компоненты предыдущего готовы — или в состоянии, в котором
ждать больше нечего: некритичный упал, компонент работает снаружи,
программа закончила работу. Внутри уровня компоненты стартуют одновременно. Критичный
компонент, не готовый к своему startTimeout, останавливает приложение, как и без
приоритетов, — до следующих уровней дело не доходит.
Остановка идёт обратно: Low → Normal → High. Уровень получает сигнал, когда
предыдущий остановился полностью: сначала закрыли вход для трафика, потом погасили
работу, потом базу. Второй Ctrl+C по-прежнему убивает всё оставшееся сразу.
Лог называет каждый уровень:
Application starting High: postgres
postgres is up.
onStarting done in 812 ms.
Application starting Normal: Scheduler
Application starting Low: Http
…
Application stopping (SIGTERM): 3 component(s)
Application stopping Normal: Scheduler
Application stopping High: postgres
Application stopped in 1.4sВ call application status появляется колонка
PRIORITY, а у компонента, который ждёт свой уровень, — причина: waits for High to be ready или waits for onStarting.
Без приоритетов ничего не меняется
Все компоненты — Normal, если не сказано иное, HTTP-сервер тоже. Приложение, в котором
приоритет не задан и onStarting() не объявлен, стартует и останавливается разом, как
раньше, и лишних строк в логе нет.
onStarting()
Метод класса приложения, который выполняется один раз при старте: когда компоненты High готовы, но остальные ещё не запущены. Место для разовой подготовки — прежде всего миграций. Контейнер, слой базы данных и логгер в нём уже есть.
protected static function onStarting(): void
{
Migrations::apply();
}- Ошибка останавливает запуск. Исключение пишется в лог, следующие уровни не
стартуют, приложение выходит с кодом
1:onStarting failed (exit code 1): the application stops. - Выполняется в отдельном процессе. Открытое в нём — соединения, таймеры — не достаётся компонентам по наследству. Но и то, что метод запишет в статическое свойство или синглтон, до компонентов не дойдёт: результаты передают через базу, файл или кеш.
- Сигнал остановки во время
onStarting()прерывает его, и больше ничего не стартует. - Когда не выполняется: при перезагрузке (
SIGHUP) и в консольных командах. Вphp call run devон выполняется на каждом перезапуске после правки кода — то, что в нём делается, должно быть безопасно повторять. Миграции такими и бывают.
Если компонентов High нет — например, база во внешнем контейнере, — onStarting()
выполняется сразу после загрузки, до всех компонентов.
initdb — в скрипте запуска базы
pg_isready говорит только, что сервер принимает соединения, а не что база и роль уже
созданы. Подготовку каталога данных кладут в скрипт запуска, как в официальном образе
postgres, а создание базы и роли — в начало onStarting():
#!/bin/sh
[ -s "$PGDATA/PG_VERSION" ] || initdb -D "$PGDATA"
exec postgres -D "$PGDATA"Базу оставляйте критичной (так по умолчанию): если она не поднимется, миграции всё равно не пройдут.
onStopped()
Метод класса приложения, который выполняется, когда остановлено всё — компоненты, а последними и High. Выполняется в процессе самого приложения и не дольше 5 секунд: он для короткого — уведомить, убрать временные файлы.
protected static function onStopped(): void
{
Notifier::send('service stopped');
}Исключение пишется в лог (onStopped failed), но остановку не отменяет: код выхода
остаётся тем, каким был бы без него. Иначе Docker с restart: on-failure поднимал бы
контейнер после обычной остановки.
Объявление кодом
Атрибуты статичны: в них можно писать только константы. Для всего остального есть хук
components() на классе приложения.
components()
use Flytachi\Winter\Kernel\App\Components;
#[EnableHttp]
#[EnableDaemon(\Main\Process\Emails::class)]
final class Application extends WinterApplication
{
protected static function components(Components $components): void
{
// Планировщик — только на репликах-обработчиках.
if (env('APP_ROLE') !== 'web') {
$components->scheduler();
}
// Порт — из окружения.
$components->websocket(\Main\ChatSocket::class, port: (int) env('CHAT_WS_PORT', 8001));
$components
->script('scripts/legacy-sync.php', critical: false)
->command(['node', 'tools/bridge.js'], name: 'bridge');
}
}Хук вызывается при старте, после сканирования — контейнер уже готов. Объявленное в нём
складывается с атрибутами. Методы process(), scheduler(), websocket() и daemon()
принимают то же, что и одноимённые атрибуты, включая параметры супервизии. service()
добавляет сервис — базу, кеш, — который сам знает, как ему
стартовать, проверяться и останавливаться и что ему нужно в образе.
Ошибка в хуке — неверное значение, один класс дважды — остановит запуск с указанием места:
Application::components(): retries and startTimeout cannot be negative.
Внешние программы
Иногда рядом с приложением должна работать программа, к фреймворку не относящаяся: старый PHP-скрипт, утилита на другом языке, мост к стороннему сервису. Её можно отдать тому же супервизору.
script()
PHP-скрипт, который запускается отдельной программой тем же PHP, что и приложение. Это обычный PHP: фреймворк в нём не участвует.
$components->script('scripts/legacy-sync.php', args: ['--batch=500'], critical: false);Путь — от корня проекта или абсолютный. Если файла нет, приложение не стартует с
понятной ошибкой. Имя для логов по умолчанию — имя файла без .php, задать своё можно
параметром name.
command()
Любая программа, которую можно найти в PATH, с аргументами:
$components->command(['node', 'tools/bridge.js'], name: 'bridge', grace: 20.0);Скрипт и программа работают одинаково:
- запускаются в корне проекта с окружением приложения, включая переменные из
.env; - по умолчанию готовы сразу после запуска;
- по умолчанию не перезапускаются: выход с кодом
0— работа сделана, любой другой — сбой, и дальше решаетcritical; - при остановке получают
SIGTERM, а черезgraceсекунд (по умолчанию 30) —SIGKILL; - их вывод идёт в вывод приложения как есть, а с
output— в лог приложения.
Готовность, сигнал остановки, перезапуск
Программа, на которой держатся остальные — база, Redis, — нуждается в большем, чем
«запущена»: остальным надо знать, когда она готова, гасить её надо её собственным
сигналом, а упавшую — поднимать. Для этого у command() и script() есть параметры:
| Параметр | По умолчанию | Что задаёт |
|---|---|---|
priority |
Priority::Normal |
Уровень запуска и остановки |
ready |
null — готова сразу |
Как узнать, что программа готова: команда, которая завершается с 0, когда та готова (['pg_isready', '-q']), или 'tcp://хост:порт', который принимает подключение |
alive |
null — не проверяется |
Проверка, что программа после старта ещё жива, — см. alive |
stopSignal |
SIGTERM |
Каким сигналом просить остановиться: SIGINT — быстрая остановка PostgreSQL |
retries |
0 |
Сколько перезапусков после падения за 30 минут — как у процессов, с паузами 1, 2, 4 с |
startTimeout |
60 |
Сколько секунд у проверки ready; без ready не действует |
output |
null — вывод как есть |
Как превращать вывод программы в лог приложения — см. output |
$components->command(['redis-server', 'config/redis.conf'], name: 'redis',
priority: Priority::High,
ready: 'tcp://127.0.0.1:6379',
retries: 3);Проверку ready приложение спрашивает раз в полсекунды. Вывод проверочной команды
отбрасывается; команда, которая висит дольше 5 секунд, считается ответом «нет». Не
готова за startTimeout — это падение на старте: критичная программа останавливает
приложение (postgres failed: did not start: was not ready within 60s), некритичная
остаётся лежать, а следующий уровень стартует без неё.
alive
Что это. Проверка, что программа после старта всё ещё жива и отвечает. ready
спрашивают только до готовности; alive — всё время, пока программа работает.
Проблема. Процесс может зависнуть, не умирая: база перестала принимать соединения,
сервис упёрся в блокировку. Для приложения такой процесс жив — PID на месте, — и оно его
не трогает. Запросы тем временем ждут и падают по таймауту, а call application status
показывает RUNNING.
Решение. Приложение регулярно задаёт программе простой вопрос — команду или подключение к порту. Если программа много раз подряд не ответила, её считают зависшей, останавливают по ступеням и перезапускают, как упавшую.
use Flytachi\Winter\Kernel\App\Probe;
$components->command(['bin/postgres.sh'], name: 'postgres',
priority: Priority::High,
ready: ['pg_isready', '-q', '-h', '/run/postgresql', '-d', 'postgres'],
alive: Probe::command(['pg_isready', '-q', '-h', '/run/postgresql', '-d', 'postgres']),
stopSignal: SIGINT,
retries: 3);Что передать в alive
| Значение | Что проверяет |
|---|---|
null (по умолчанию) |
ничего — проверки нет |
['pg_isready', '-q'] |
команду: код 0 — жива; с настройками по умолчанию |
'tcp://127.0.0.1:6379' |
порт: принимает подключение — жива; с настройками по умолчанию |
Probe::command([...], every:, timeout:, failures:) |
команду, со своими настройками |
Probe::tcp('127.0.0.1:6379', every:, timeout:, failures:) |
порт, со своими настройками (tcp:// можно не писать) |
Параметры Probe
| Параметр | По умолчанию | За что отвечает |
|---|---|---|
every |
10 |
Раз в сколько секунд проверять. Проверки не накладываются: следующая начинается, только когда закончилась предыдущая |
timeout |
5 |
Сколько секунд ждать ответа одной проверки. Не ответила за это время — её прерывают, и это неудача |
failures |
6 |
Сколько неудач подряд значат «зависла». Одна удачная проверка обнуляет счётчик |
С этими значениями программу признают зависшей примерно через минуту без единого ответа
(failures × every = 6 × 10 с; если timeout больше every, вместо every считается
timeout).
Как это работает
- Проверки начинаются после готовности — через
everyсекунд после того, как прошлаready(или после запуска, еслиreadyнет). На старте работает толькоready. - Каждая проверка — отдельный процесс, её вывод отбрасывается; ответ — только код выхода. Проверка порта тоже идёт в своём процессе, чтобы приложение не ждало её.
- Неудача пишется в лог сразу, с номером:
postgres alive check failed (2/6): no answer in 5s.— и видна вcall application statusпод строкой программы:alive check failed 2/6. - Удачная проверка после неудач сбрасывает счётчик:
postgres answers its alive check again. failuresнеудач подряд — программа зависла:postgres is not answering (6 checks in a row): stopping it with SIGINT.
Как останавливают зависшую программу
Сначала мягко, потом строже — в пределах её grace:
| Когда | Что получает программа |
|---|---|
| сразу | свой stopSignal — например, SIGINT, быструю остановку PostgreSQL |
через grace / 2 |
SIGTERM — если ещё работает (в логе postgres still running: SIGTERM.) |
через grace |
SIGKILL (postgres still running: SIGKILL.) |
Если stopSignal и так SIGTERM, средняя ступень пропускается: SIGTERM, через grace —
SIGKILL. Чем бы программа ни закончилась — даже чистым выходом с кодом 0 на свой
сигнал, — это падение: postgres crashed: was not answering; restart 1 of 3 in 1s.
Дальше — как при любом падении: перезапуск по retries с паузами 1, 2, 4 с, а когда
попытки кончились, решает critical. Для базы, убитой SIGKILL, это значит
восстановление после аварии при следующем старте — так же, как после kill -9.
Защита от ложных срабатываний
Убить работающую программу из-за медленного ответа хуже, чем подождать. Поэтому:
- Считаются только неудачи подряд. Пик нагрузки, контрольная точка, сборка мусора дают одну-две неудачи, и первая же удачная проверка обнуляет счётчик.
- Лёгкая проверка.
pg_isreadyтолько устанавливает соединение и запросов не выполняет: долгая выгрузка, тяжёлыйCOPY, блокировки таблиц ей не мешают — занятая база на подключение отвечает. - Щедрый
timeout: 5 секунд на ответ — медленный, но живой сервер успевает. - Не проверяют, когда незачем: до готовности, во время остановки приложения, пока программа перезапускается.
- Видно заранее. Каждая неудача — строка в логе. Если проверки начали «моргать» под
нагрузкой, это видно задолго до перезапуска — поднимите
failuresилиtimeout. - По умолчанию выключено. Без
aliveпрограмму не проверяют вовсе.
Для тяжёлой базы с долгими выгрузками можно быть ещё осторожнее:
alive: Probe::command(['pg_isready', '-q', '-h', '/run/postgresql', '-d', 'postgres'],
every: 15, timeout: 10, failures: 8), // about two minutes without an answerПроверка не видит, чего не спрашивает
pg_isready скажет «жива» и базе, которая принимает соединения, но не выполняет запросы
к одной повисшей таблице. Это правильно: перезапускать базу из-за одной долгой
блокировки хуже, чем ждать. Своя, более глубокая проверка (psql -c 'select 1')
возможна, но тогда и её ложные срабатывания — на вас.
output
Что это. Разбор вывода программы в лог приложения: строка за строкой, каждая — со своим уровнем.
Проблема. Без разбора программа пишет в вывод приложения как есть. Её строки
выглядят иначе, чем строки приложения, на них не действует LOG_LEVEL, они не попадают
в JSON и в файл логов. Ошибку базы среди них не отличить от обычного сообщения.
Решение. Дать программе output — класс, который читает одну её строку и говорит,
что она значит. Дальше строка идёт через логгер приложения: каналом служит имя
программы (синим), в скобках — PID процесса, который её написал.
use FlytachiWinterKernelAppOutputLine;
use FlytachiWinterKernelAppProgramOutput;
final class RedisOutput implements ProgramOutput
{
public function line(string $line): OutputLine
{
// 12:M 15 Nov 2026 02:10:00.412 # Server initialized
if (preg_match('/^(\d+):\w \S+ \S+ \S+ \S+ ([.*#-]) (.*)$/', $line, $m) !== 1) {
return OutputLine::more($line);
}
$level = match ($m[2]) {
'.' => 'debug',
'-', '*' => 'info',
default => 'warning',
};
return OutputLine::entry($level, $m[3], pid: (int) $m[1]);
}
}$components->command(['redis-server', '--port', '6379'], name: 'redis', output: new RedisOutput());[2026-11-15 02:10:00] [INFO ] -redis- [12]: Server initialized
[2026-11-15 02:10:00] [WARN ] -redis- [12]: Memory overcommit must be enabled!Что может вернуть line():
| Вызов | Что значит |
|---|---|
OutputLine::entry($level, $message, $context, $pid) |
Строка начинает запись. Уровень — PSR-3 ('info', 'error'…); $pid — кто её написал, по умолчанию сама программа |
OutputLine::more($text, $key) |
Строка продолжает предыдущую запись: с $key — в её контекст под этим ключом, без — туда же, куда ушла строка перед ней |
OutputLine::skip() |
Строку не писать |
- Запись уходит в лог, когда начинается следующая или программа замолкает на
мгновение. Поэтому продолжения успевают к ней присоединиться: ошибка и её
STATEMENTстановятся одной записью. - Разбор не теряет вывод. Строку, на которой
line()бросил исключение, приложение пишет как есть, с уровнемINFO. line()вызывается в процессе приложения, на каждую строку. Он должен быть быстрым и не хранить состояние между вызовами.- Программа, которая пишет без остановки, супервизор не держит: за один проход он читает ограниченную порцию.
- Размер ограничен. Строка — до 128 КБ, запись вместе с продолжениями — до 3 МБ;
лишнее отрезается, а в конце записи сказано, сколько:
… (cut: 9.2 MB more). Подcall run dev— 1 МБ и 16 МБ.
Готовый разбор есть у PostgreSQL.
Только из кода
Внешние программы не управляются консолью call process: у них нет класса, а значит, и
записи состояния. Они живут ровно столько, сколько приложение.
Управление работающим компонентом
Пока приложение работает, запуском процессов распоряжается оно — из кода в любом
процессе так же, как из консоли (call process … start, call daemon … start,
call schedule start, с -d и без).
| Вызов | Что происходит |
|---|---|
Класс::stop() |
Компонент останавливается и остаётся остановленным: приложение его не перезапускает |
Класс::dispatch() |
Приложение запускает компонент — остановленный, упавший (FAILED) или выполнивший работу — с чистого листа, счётчик перезапусков обнуляется. Возвращает PID нового процесса |
Класс::relaunch() |
Перезапуск: остановить и сразу запустить. Сбоем не считается |
Класс::start() |
Для объявленного компонента — отказ ProcessManagedException: он работает в процессах приложения, а не в текущем |
InboxWatcher::stop(); // остановлен, приложение его не поднимет
$pid = InboxWatcher::dispatch(); // снова работает внутри приложения
InboxWatcher::relaunch(); // перезапуск, например после смены настроекОстановка действует только на текущий запуск приложения: после перезапуска приложения снова поднимается всё, что объявлено.
Запуск необъявленного процесса
Процесс, которого нет в составе приложения, тоже запускается через приложение — оно его подхватывает на один запуск:
- повторов нет: упал — значит упал;
- он не критичный: ни падение, ни что-то ещё не остановит приложение;
- закончил работу или остановлен — приложение о нём забывает;
- упал — виден в
call application statusкакFAILEDс причиной, пока его не запустят снова; - остановка или перезапуск приложения его не возвращает: он временный.
Объявленный компонент запускается со своими параметрами (retries, critical,
startTimeout) — как при старте приложения.
Так удобно включать то, что нужно не всегда. Например, планировщик не стоит в составе приложения, а раз в месяц его включают на пару дней:
php call schedule start # приложение подхватывает планировщик
php call app status # он в списке «Adopted»
php call schedule stop # и приложение о нём забываетИз кода так же: ReportExport::dispatch() в контроллере запускает выгрузку внутри
приложения — её видно в call application status, и она остановится вместе с приложением.
Класс::start() необъявленного процесса по-прежнему запускает его в текущем процессе:
это просьба «выполни здесь», а не «запусти в фоне».
Ещё два случая, о которых заботиться не нужно:
- Компонент уже запущен вне приложения — например, его подняли командой
call process … start -dдоcall run. Приложение не падает и не воюет с ним, а ждёт, пока тот завершится, и тогда запускает свой. - Компонент или всё приложение работает в другом окружении — запись видна через общую
папку
.winter/смонтированного проекта, но процесс в другом контейнере. Такую запись не трогают:stop()иrelaunch()вернутfalse,start()иdispatch()откажут с подсказкой выполнить команду там. Иначе рядом с приложением заработал бы второй экземпляр — например, второй планировщик, и задачи выполнялись бы дважды. Запись контейнера, убитого без остановки (docker kill, нехватка памяти) и пересозданного на том же дереве, не мешает: её блокировку никто не держит, и компонент стартует. Это видно между контейнерами одной машины; хост macOS и контейнер блокировок друг друга не видят.
Что выбрать
Пять инструментов легко перепутать, потому что все они «делают что-то в фоне». Разводятся они по вопросу «когда это должно работать».
| Нужно | Инструмент |
|---|---|
| Выполнить кусок работы, не задерживая ответ клиенту | #[Async] |
| Крутить один бесконечный цикл: слушать очередь, опрашивать устройство | Процесс |
| То же самое, но в несколько рук, с перезапуском упавших | Демон |
| Запускать по расписанию: каждые 5 минут, каждую ночь в 3:00 | Планировщик |
| Держать открытые соединения с браузерами и отправлять им сообщения сразу | WebSocket |
Разберём границы, потому что именно на них ошибаются:
#[Async] — не фоновая задача. Метод уходит в отдельную корутину и чередуется
с вызывающим кодом на ожиданиях ввода-вывода, но работа остаётся внутри того же
воркера и живёт ровно столько, сколько он: перезапуск её потеряет, на другую
машину она не уедет, очереди у неё нет. Годится, чтобы не заставлять клиента ждать;
не годится, чтобы гарантированно доставить письмо — для этого нужен процесс или
демон с очередью.
Процесс против демона. Процесс — один экземпляр, демон — несколько под супервизией, с политикой перезапуска и масштабированием. Если работа делится на независимые единицы и одного воркера мало, берите демона; если задача по своей природе одна (слушать один сокет, держать одно подключение), берите процесс.
Планировщик против процесса с sleep(). Цикл с sleep(300) внутри процесса
кажется простым решением, но с ним вы сами отвечаете за то, чтобы задача не
наложилась сама на себя, за пропуски после перезапуска и за расписание в терминах
времени суток. Планировщик всё это уже умеет.
Дальше
- Процессы — один долгоживущий воркер
- Демоны — флот воркеров с супервизией
- Планировщик — задачи по расписанию
- WebSocket — постоянные соединения с браузерами
- Асинхронные вызовы — не заставлять клиента ждать медленную операцию
- Ключевые идеи — как это исполняется в резидентном приложении