Команда cfg
cfg разворачивает и поддерживает конфигурацию проекта: файл .env, секрет
WINTER_KEY, Docker-обвязку и автодополнение оболочки. Это первое, что запускается
при создании проекта, и то, к чему возвращаются при настройке окружения.
Что такое 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):
php call cfg initПоследовательность: патч composer.json (перезапись name и description,
очистка authors, удаление keywords и scripts) → создание .env → генерация WINTER_KEY.
cfg key — секретный ключ
| Флаг | Действие |
|---|---|
key -g |
Сгенерировать/перегенерировать ключ (64 hex = 32 байта) и записать в .env |
key -s |
Показать текущий ключ |
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-обвязка
php call cfg dockerСоздаёт Dockerfile, docker-compose.yml и .dockerignore. Dockerfile собирается на
готовом образе flytachi/winter: в нём уже
Swoole, драйверы баз и Redis, opcache, пользователь winter и запуск приложения, — а
проект добавляет только свой vendor/ и код:
# 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:
php call cfg docker -fВнутри контейнера приложение запускается как call application start и становится
PID 1: docker stop останавливает все его компоненты штатно.
Время на остановку
Штатной остановке нужно время: каждый компонент получает до 30 секунд, приложение ждёт
их до 35 — подробно в Остановке. docker stop же по
умолчанию ждёт всего 10 секунд и затем убивает контейнер целиком, так что начатая работа
обрывалась бы на десятой секунде. Поэтому в 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 его только публикует:
ports:
- "8000:8000"Левое число — порт на машине, его можно менять как угодно. Правое должно совпадать с портом в коде. WebSocket со своим портом публикуется так же, отдельной строкой.
Расширения PHP
В образе уже есть pdo_pgsql и pgsql, pdo_mysql, redis (phpredis), bcmath,
pcntl и opcache. Если нужно другое — ставится в Dockerfile проекта, от root, после
чего образ возвращается к пользователю winter. В шаблоне это готовый
закомментированный пример:
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 |
Установить с перезаписью |
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 нет
домашней папки, а установка пропала бы при пересоздании контейнера.
Дальше
- Установка — где
cfg initв цепочке старта - Конфигурация —
.envи классы-конфигураторы - Консоль — обзор — все команды