CLI · Winter Console

Команда cfg

cfg разворачивает и поддерживает конфигурацию проекта: файл .env, секрет WINTER_KEY, Docker-обвязку и автодополнение оболочки. Это первое, что запускается при создании проекта, и то, к чему возвращаются при настройке окружения.

Субкоманды init · key · env · docker · completionПервый запуск cfg init

Что такое cfg и зачем

cfg — команда управления конфигурацией проекта.

Проблема. Новый проект нужно привести в рабочее состояние: создать .env, сгенерировать секретный ключ, при желании — Docker-файлы и автодополнение. Делать это руками — легко забыть шаг.

Решение. cfg собирает эти операции в субкоманды, а cfg init выполняет базовую настройку одной командой. Об этом и раздел.

Субкоманды

Субкоманда Назначение
init Патчит composer.json, создаёт .env, генерирует ключ, кладёт stub-мету
key Управление WINTER_KEY
env Управление файлом .env
docker Генерация Docker-файлов
completion Установка/печать автодополнения оболочки

cfg init

Приводит проект в рабочее состояние (вызывается автоматически при composer create-project):

bash
php call cfg init

Последовательность: патч composer.json (перезапись name и description, очистка authors, удаление keywords и scripts) → создание .env → генерация WINTER_KEY.

cfg key — секретный ключ

Флаг Действие
key -g Сгенерировать/перегенерировать ключ (64 hex = 32 байта) и записать в .env
key -s Показать текущий ключ
bash
php call cfg key -g   # новый WINTER_KEY

Нужен .env

key -g предупредит и прервётся, если .env отсутствует — сначала создайте его (cfg env -i).

cfg env — файл окружения

Флаг Действие
env -i Создать .env из шаблона (пропускает, если существует)
env -s Напечатать загруженный $_ENV
env -s --file Напечатать сырое содержимое .env

cfg docker — Docker-обвязка

bash
php call cfg docker

Создаёт Dockerfile, docker-compose.yml и .dockerignore. Dockerfile собирается на готовом образе flytachi/winter: в нём уже Swoole, драйверы баз и Redis, opcache, пользователь winter и запуск приложения, — а проект добавляет только свой vendor/ и код:

Dockerfile
# syntax=docker/dockerfile:1

FROM composer:2 AS vendor
WORKDIR /app
COPY composer.json composer.lock ./
RUN composer install --no-dev --no-interaction --optimize-autoloader --ignore-platform-reqs

FROM flytachi/winter:8.5
COPY --from=vendor --chown=winter:winter /app/vendor ./vendor
COPY --chown=winter:winter . .
ENTRYPOINT ["winter-entrypoint"]

Режим выбирается переменной при запуске:

Запуск Режим
docker compose up Рабочий: opcache включён, наблюдателя нет
DEV=true docker compose up Разработка: перезапуск по изменению файлов, opcache выключен

Файлы, которые уже есть в проекте, команда не трогает и помечает EXISTS — их наверняка правили, и повторный запуск не должен это стереть. Перезаписать — флаг -f:

bash
php call cfg docker -f

Внутри контейнера приложение запускается как call application start и становится PID 1: docker stop останавливает все его компоненты штатно.

Время на остановку

Штатной остановке нужно время: каждый компонент получает до 30 секунд, приложение ждёт их до 35 — подробно в Остановке. docker stop же по умолчанию ждёт всего 10 секунд и затем убивает контейнер целиком, так что начатая работа обрывалась бы на десятой секунде. Поэтому в docker-compose.yml срок увеличен с запасом:

docker-compose.yml
    stop_grace_period: 40s

Сроки вложены друг в друга: компонент — 30, приложение — 35, контейнер — 40 секунд. В Kubernetes то же задаёт terminationGracePeriodSeconds: 40 в спецификации пода: его умолчание 30 оборвёт 35-секундный срок приложения. Если поднимаете $grace компонента выше 30, срок приложения растёт вместе с ним (самый длинный $grace плюс 5 секунд), и срок контейнера нужно поднять так же. С приоритетами уровни останавливаются друг за другом и их сроки складываются: HTTP на Low, процессы на Normal и база на High с grace: 60.0 — это 30 + 30 + 60 + 5 = 125 секунд, и stop_grace_period должен быть не меньше.

Порты

Порт приложение объявляет в коде — #[EnableHttp(port:)], по умолчанию 8000, — а docker-compose.yml его только публикует:

docker-compose.yml
    ports:
    - "8000:8000"

Левое число — порт на машине, его можно менять как угодно. Правое должно совпадать с портом в коде. WebSocket со своим портом публикуется так же, отдельной строкой.

Расширения PHP

В образе уже есть pdo_pgsql и pgsql, pdo_mysql, redis (phpredis), bcmath, pcntl и opcache. Если нужно другое — ставится в Dockerfile проекта, от root, после чего образ возвращается к пользователю winter. В шаблоне это готовый закомментированный пример:

Dockerfile
FROM flytachi/winter:8.5

USER root
RUN apk add --no-cache icu-libs \
  && apk add --no-cache --virtual .intl-deps $PHPIZE_DEPS icu-dev \
  && docker-php-ext-install -j"$(nproc)" intl \
  && apk del .intl-deps
USER winter
  • --virtual — компилятор и заголовки ставятся под общим именем и снимаются одной командой, в образ не попадают; остаётся только библиотека (icu-libs).
  • $PHPIZE_DEPS — набор для сборки расширений из базового образа PHP.
  • USER winter в конце — обязателен: приложение и консоль в контейнере должны работать не от root.

Файлы проекта копируются с --chown=winter:winter: приложение пишет в .winter/ и logs/, а RUN chown здесь не сработает — образ работает не от root.

docker-compose.yml монтирует проект в контейнер (volumes: ./:/app/) — это для разработки. На сервере строку volumes обычно убирают, и код с vendor/ берутся из образа. Монтируете и на сервере — на Linux папка проекта должна быть доступна на запись uid 1000 (chown -R 1000:1000 <папка проекта>), иначе приложение не стартует и скажет, какую папку не может записать.

cfg completion — автодополнение

Флаг Действие
(без флага) Напечатать скрипт в stdout
-i Установить
-if Установить с перезаписью
bash
php call cfg completion -i

Оболочка определяется по $SHELL: zsh → ~/.zsh/completions/_call (добавляет fpath в ~/.zshrc), иначе bash → ~/.bash_completion.d/call.

Дополняются ./call и call; php call — нет: оболочка ищет дополнение по имени команды, а здесь команда — php.

В контейнере ставить не нужно

В образе flytachi/winter bash и автодополнение уже есть: docker exec -it <контейнер> bash (в Portainer — /bin/bash), и ./call <Tab> работает сразу. -i в контейнере не поможет: у пользователя winter нет домашней папки, а установка пропала бы при пересоздании контейнера.

Дальше