Фоновые обработчики

Фоновый обработчик в Lizard (lizard.build) работает без HTTP-порта. Это может быть потребитель очереди, бот, который проверяет обновления, реконсилер или цикл опроса. Запустите его в режиме воркера, установив порт контейнера в 0, например командой lizard up --port 0. Обработчик не получает PORT, проверку готовности и публичный маршрут, поэтому он никогда не считается неисправным из-за того, что не отвечает по HTTP. Для очереди заданий используйте его вместе с Managed Redis. Чат-боты тоже работают как фоновые обработчики; см. руководства по боту Telegram и боту Discord.

Что меняет рабочий режим

Когда containerPort=0, платформа:

• Пропускает внедрение PORT — обработчик не привязывается нигде.
• Пропускает TCP-проверку готовности — нет ложноположительного статуса “unhealthy”. Старый под останавливается до запуска нового.
• Пропускает EXPOSE в синтезируемом Dockerfile.
• Пропускает регистрацию маршрута балансировщика — ничего не обслуживается. (Сгенерированный домен *.onlizard.com может всё ещё отображаться в сервисе, но он не будет отвечать.)

Включить рабочий режим

Три эквивалентных способа:

# New upload-source worker
lizard up --port 0
 
# Flip an existing service
lizard port 0 --service worker
 
# Via the config:apply path
lizard service set worker --set containerPort=0

Рабочий режим — жёсткий переключатель — для вступления в силу изменения порта требуется повторный деплой.

Проверить текущий порт

lizard port --service worker

Выводит текущий порт контейнера или worker mode, когда он 0.

Когда не стоит использовать рабочий режим

Не используйте режим воркера для обычного HTTP-сервиса, который просто медленно запускается. Режим воркера полностью отключает проверку доступности, поэтому он скроет ошибки вроде “the listener never came up”. Если ваш сервис предназначен для обслуживания трафика, оставьте реальный порт и исправьте запуск.

Запуск потребителя очереди

Используйте пример redis-worker. Он перемещает задание из списка ожидающих в список обрабатываемых, сохраняет его результат в верхнем регистре и подтверждает задание в транзакции Redis. Оставьте одну реплику: восстановление при запуске предполагает одного потребителя. Пример использует Python 3.13 и redis-py 6.4.0.

Из директории с его Dockerfile:

lizard init --name queue-example
lizard add --service worker
lizard add redis
lizard secrets set REDIS_URL='${{redis.REDIS_URL}}' --service worker
lizard up --service worker --port 0

Выполните вход с помощью lizard login, если команда сообщает, что требуется аутентификация. Используйте фактическое имя базы данных, если оно не redis. Держите ссылку в кавычках. Установите её перед загрузкой приложения.

Проверьте финальное событие деплоя, затем проверьте обработчик:

lizard port --service worker
lizard logs --service worker --json

Отправьте задание со своего компьютера. lizard run --service redis запускает локальную команду со значениями подключения аддона Redis, включая его публичный REDIS_URL:

python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
lizard run --service redis -- python jobs.py enqueue first-job
lizard run --service redis -- python jobs.py result first-job

Процесс выводит Queue worker ready, а после выполнения задания — Processed first-job. Если хвост лога пуст, опирайтесь на проверку задания; в результатах тестов зафиксирован наблюдаемый лимит логирования. Команда результата ждёт до 30 секунд и выводит {"id": "first-job", "result": "HELLO"}. Само по себе запущенный процесс не доказывает, что он может потреблять задания.

Проверка перезапуска

Для этого тестового сервиса перезапустите обработчик и отправьте ещё одно задание:

lizard restart --service worker
lizard run --service redis -- python jobs.py result first-job
lizard run --service redis -- python jobs.py enqueue after-restart
lizard run --service redis -- python jobs.py result after-restart

Если у after-restart нет результата через 30 секунд, дождитесь возвращения сервиса в running в lizard ps --json и снова выполните команду результата. Оба результата должны быть HELLO. Первый результат живёт в Redis, поэтому перезапуск обработчика не удаляет его. При запуске единственный потребитель возвращает незавершённые записи обработки в список ожидающих.

Этот демо принимает только JSON-задания, созданные jobs.py. Он не реализует очередь мёртвых писем, валидацию для недоверенных производителей или exactly-once внешние побочные эффекты. Для платежей, email или других эффектов используйте проверенную библиотеку очередей и идемпотентные обработчики. Надёжность и бэкап Redis отделены от поведения перезапуска обработчика; см. хранилище и восстановление.

Устранение неполадок

См. также

• lizard port — показать или изменить порт контейнера сервиса.
• Сервис никогда не становится здоровым — самая частая ошибка конфигурации рабочего режима.
• Управляемые аддоны — Redis, Postgres и S3 для стейтфул-нагрузок.
• Хостинг Python-приложений — Celery-обработчик — тот же образ с другой командой и без HTTP-порта.

См. результаты сценарийных тестов для проверенных версий, облачных результатов и оставшихся ограничений.

Обновлено 12 октября 2026 г.