Перейти к содержанию

Аргументы запуска компонентов Webim Server

Статья описывает аргументы командной строки, с которыми запускаются серверные компоненты Webim Server. Материал предназначен для администраторов и DevOps-инженеров hosted-клиентов, которые самостоятельно управляют запуском компонентов.

Аргументы задают то, что должно быть известно процессу до чтения конфигурационных файлов: адрес и порт прослушивания, имя узла в кластере, имя подключения к Redis, путь к дополнительной конфигурации логирования. Остальные настройки Chat Backend, Admin Backend, History Backend, Image Robot задаются в файлах из /etc/webim — см. Главные файлы настроек. Speller, Data Storager и Delta Proxy настраиваются через .env и не принимают аргументов вида --logging-config.

Компоненты и точки входа

Компонент Точка входа Порт по умолчанию
Chat Backend python/source/server.py 8260
Admin Backend src/apps/admin_backend/main.py 6001
History Backend src/apps/history_backend/main.py 9003
Image Robot src/apps/image_robot/image_robot/main.py 9090
Speller api.py 8000
Data Storager producer.py, subscriber_*.py, stats.py, dashboard_realtime.py HTTP 8000, метрики 9090
Delta Proxy delta-server/api.py, delta-server/delta_consumer.py HTTP 8000

Общие правила

В компонентах применяются разные способы передачи параметров запуска.

Chat Backend Admin Backend, History Backend, Image Robot Speller, Data Storager, Delta Proxy
Способ tornado.options argparse переменные окружения (.env); у Faust-процессов дополнительно CLI Faust
Синтаксис только --аргумент=значение --аргумент значение или --аргумент=значение KEY=value в .env или в окружении процесса
Дефис и подчёркивание равнозначны: --logging_config и --logging-config — один и тот же аргумент значим: пишите точно так, как указано в таблице имена переменных фиксированы
Справка --help --help у Faust-процессов: faust --help и faust worker --help
Неизвестный аргумент нештатное поведение нештатное поведение неизвестная переменная окружения игнорируется; неизвестный аргумент Faust завершает процесс

Внимание

В компонентах на tornado.options значение отделяется только знаком =. Запись через пробел (--port 8260) приведёт к ошибке Option 'port' requires a value и процесс не стартует.

Способ передачи аргументов зависит от варианта установки: для DEB-пакетов это unit-файлы systemd (например, webim-tornado и webim-admin-backend) или конфигурация supervisord, для Docker — команда запуска контейнера. После изменения аргументов компонент нужно перезапустить.

Chat Backend

Запускается точкой входа server.py. Аргументы разбираются через tornado.options, поэтому дополнительно доступны стандартные аргументы логирования Tornado.

Аргумент По умолчанию Назначение
--port 8260 TCP-порт, на котором компонент принимает запросы.
--upstream_timeout 40 Тайм-аут обработки запроса, секунды. По его истечении запрос завершается без ответа от обработчика.
--logging_config не задан Путь к дополнительному файлу logging.json. Файл объединяется с конфигурацией из дистрибутива, а не заменяет её. Подробности — в статье Логирование в Chat Backend.
--prometheus_port не задан Порт HTTP-сервера метрик. Если аргумент не указан, сервер метрик не запускается. См. Мониторинг через Prometheus.
--redis_connection не задан Имя подключения к Redis из секции connections (см. Конфигурация Redis). Обязательный параметр. Без него Chat Backend не стартует.
--node_name не задан Устаревший, не подлежит использованию.
--cluster_config не задан Устаревший, не подлежит использованию.
--profiler_filename не задан Путь к файлу для дампа профиля. Если аргумент не указан, профилирование недоступно.
--profiling true Состояние профилировщика на старте. Действует только вместе с --profiler_filename.

Профилирование

Профилирование включается только при заданном --profiler_filename. Аргумент --profiling задаёт лишь начальное состояние: во время работы профилировщик включают и выключают запросом к административному эндпоинту, и при выключении текущий профиль сохраняется в отдельный файл со штампом времени.

Профилирование заметно увеличивает накладные расходы, поэтому в промышленной эксплуатации включайте его только на время диагностики.

Пример

Обычный запуск с нестандартным портом и метриками:

chat_backend --port=8264 --prometheus_port=9200 --redis_connection=main_redis --logging_config=/etc/webim/chat_backend_logging.json

Admin Backend

Аргументы разбираются через argparse; стандартные аргументы логирования Tornado здесь недоступны.

Аргумент По умолчанию Назначение
--host localhost Адрес прослушивания.
--port 6001 TCP-порт, на котором компонент принимает запросы.
--logging-config не задан Путь к дополнительному файлу конфигурации логирования. Файл объединяется с logging.json из корня приложения. Подробности — в статье Логирование в Admin Backend.
--cluster-name не задан Имя кластера. Непустое значение включает многонодовый режим; значение должно совпадать на всех экземплярах.
--redis-connection не задан Имя подключения к Redis из секции connections.
--kafka-connection не задан Имя подключения к Apache Kafka из секции connections. Если аргумент не указан, интеграция с Kafka не инициализируется.
--uvloop выключено Использовать цикл событий uvloop вместо стандартного.
--no-uvloop — Явно отключить uvloop. Поведение по умолчанию; аргумент нужен, чтобы переопределить --uvloop в шаблонах запуска.
--no-account-name-label метка включена Экспериментальный флаг: убирает метку account_name из метрик Prometheus. Снижает кардинальность метрик на инсталляциях с большим числом аккаунтов.
--php-root значение WEBIM_PHP_ROOT Корневой каталог файлов статики. Устаревший аргумент, используйте переменную окружения WEBIM_PHP_ROOT.

Внимание

По умолчанию Admin Backend слушает только localhost. Если перед компонентом стоит прокси или балансировщик на другом узле, задайте --host явно.

Переменные окружения

Переменная Назначение
WEBIM_PHP_ROOT Корневой каталог файлов статики. Заменяет устаревший аргумент --php-root. Если не задана ни переменная, ни аргумент, Admin Backend не стартует.
WEBIM_SHARED_CONFIGS Каталог общих конфигурационных файлов.

Многонодовый режим

Для многонодового режима обязательны оба аргумента — --cluster-name и --redis-connection; их значения должны быть одинаковыми на всех экземплярах Admin Backend. Полная процедура описана в статье Масштабирование Admin Backend.

Пример

admin_backend --host=192.0.2.1 --port=6002 --cluster-name=prod --redis-connection=main_redis --logging-config=/etc/webim/admin_backend_logging.json

History Backend

Компонент отдаёт историю диалогов по HTTP. Аргументы разбираются через argparse.

Аргумент По умолчанию Назначение
--host 0.0.0.0 Адрес прослушивания (DNS-имя или IP-литерал).
--port 9003 TCP-порт, на котором компонент принимает запросы.
--redis-connection не задан Имя подключения к Redis из секции connections. Обязательный параметр. Без него History Backend не стартует.

Пример:

history_backend --host=192.0.2.2 --port=9008 --redis-connection=main_redis

Image Robot

Компонент отдаёт пиктограммы и прочие изображения по HTTP(s). Аргументы разбираются через argparse.

Аргумент По умолчанию Назначение
--host localhost Адрес прослушивания (DNS-имя или IP-литерал).
--port 9090 TCP-порт, на котором компонент принимает запросы.

N.B.

Порт 9090 по умолчанию занимают и другие компоненты — например, воркеры Data Storager публикуют на нём метрики. Если компоненты размещены на одном узле без сетевой изоляции, назначьте им разные порты.

Пример:

image_robot --host=192.0.2.3 --port=9095

Speller

Speller — микросервис проверки орфографии. Архитектура, сеть и полный список переменных окружения — в статье Speller.

Аргументы командной строки не разбираются. Точка входа api.py сама вызывает Uvicorn и читает адрес и порт из .env. Запись вида python api.py --port 8001 игнорируется.

Параметр Где задаётся По умолчанию Назначение
API_BIND_IP .env 0.0.0.0 Адрес прослушивания HTTP-API.
API_WEB_PORT .env 8000 (в шаблоне, не в коде) TCP-порт HTTP-API. На нём же доступны /metrics. Обязательный параметр.
ENV_FILE окружение процесса .env Путь к файлу переменных окружения. Единственный способ указать конфигурацию при запуске, не меняя рабочий каталог.
DEBUG .env False Включает автоперезагрузку Uvicorn. В промышленной среде оставляйте выключенным.

Уровень логирования в коде зафиксирован (INFO) и не задаётся аргументом вроде --logging-config. Логи пишутся в стандартный вывод процесса.

Пример

ENV_FILE=/etc/webim/speller.env python api.py

В поставке процесс обычно стартует как poetry run python api.py из каталога сервиса, а переменные читаются из .env рядом с точкой входа.

Внимание

Порт 8000 по умолчанию занимает и HTTP-процесс Delta Proxy. Если оба сервиса стоят на одном узле без сетевой изоляции, назначьте им разные значения API_WEB_PORT.

Data Storager

Data Storager (ранее es-storager) — набор процессов, которые переносят историю диалогов и статистику из баз Webim в поисковый кластер и ClickHouse. Полное описание архитектуры, переменных окружения и эксплуатационных команд — в статье Data Storager.

У сервиса нет единого main.py с таблицей --host / --port. Запускаются несколько процессов, каждый со своей точкой входа.

Процесс Точка входа Как запускается Порты
producer producer.py faust -A producer -l info worker метрики PROMETHEUS_PORT
subscriber-chats subscriber_chats.py faust -A subscriber_chats -l info worker метрики PROMETHEUS_PORT
subscriber-stats subscriber_stats.py faust -A subscriber_stats -l info worker метрики PROMETHEUS_PORT
subscriber-report-stats subscriber_report_stats.py faust -A subscriber_report_stats -l info worker метрики PROMETHEUS_PORT
subscriber-chat-states subscriber_chat_states.py faust -A subscriber_chat_states -l info worker метрики PROMETHEUS_PORT
subscriber-periods subscriber_periods.py faust -A subscriber_periods -l info worker метрики PROMETHEUS_PORT
dashboard-realtime dashboard_realtime.py faust -A dashboard_realtime -l info worker метрики PROMETHEUS_PORT
stats.py stats.py python stats.py HTTP STATS_BIND_IP:STATS_WEB_PORT

HTTP-приложение stats.py устроено так же, как Speller: аргументы командной строки не читаются, адрес и порт берутся из .env.

Аргументы CLI Faust

Воркеры запускаются командой Faust. Разбор аргументов — через Click, поэтому допустимы и --аргумент значение, и --аргумент=значение.

Аргумент По умолчанию Назначение
-A / --app обязателен Модуль приложения: producer, subscriber_chats, subscriber_stats и другие из таблицы выше.
-l / --loglevel WARN у Faust Уровень логов самого Faust: crit, error, warn, info, debug. В поставках обычно info.
--datadir / -D каталог Faust Каталог служебных данных воркера. Указывается до команды worker. На одном хосте у разных процессов каталоги должны различаться.
worker — Команда запуска фонового воркера. Без неё процесс не начинает обработку топика.
--web-port / -p 6066 Порт встроенного HTTP-сервера Faust (служебный, не путать с метриками Prometheus).
--web-bind / -b 0.0.0.0 Адрес, на котором слушает встроенный HTTP-сервер Faust.
--without-web выключено Не поднимать встроенный HTTP-сервер Faust.

N.B.

С помощью -l устанавливается уровень и формат всех логов после старта воркера. Уровень и формат логов до старта воркера и в stats.py задаются переменными LOGGING_LEVEL и LOGGING_FORMAT в .env. Аргумента --logging-config у Data Storager нет.

Эксплуатационные команды (health, refresh, populate и другие) описаны в статье Data Storager и к старту воркера не относятся.

Переменные, влияющие на запуск

Переменная По умолчанию Назначение
ENV_FILE .env Путь к файлу переменных окружения. Поддерживают producer, subscriber_chats, subscriber_chat_states, subscriber_periods, dashboard_realtime и stats.py. Процессы subscriber_stats и subscriber_report_stats читают только .env из рабочего каталога.
STATS_BIND_IP 0.0.0.0 Адрес прослушивания stats.py.
STATS_WEB_PORT 8000 HTTP-порт stats.py (/health, /metrics, при включении — отчётный API). Обязательный параметр.
PROMETHEUS_PORT 9090 (в шаблоне, не в коде) Порт метрик каждого Faust-воркера. Если несколько воркеров на одном хосте, назначьте им разные значения. Обязательный параметр.
LOGGING_LEVEL INFO (в шаблоне, не в коде) Уровень логов приложения. Обязательный параметр.
LOGGING_FORMAT строка logging (в шаблоне, не в коде) Формат логов приложения. Обязательный параметр.

Остальные переменные (Kafka, Redis, базы, поисковый кластер, отчётный контур) задают работу сервиса, а не сам способ старта — см. Data Storager.

Примеры

Один producer и один consumer истории:

faust -A producer -l info worker
faust -A subscriber_chats -l info worker

Два воркера на одном хосте с разнесёнными портами метрик:

PROMETHEUS_PORT=9090 faust -A producer -l info worker --web-port=6066
PROMETHEUS_PORT=9091 faust -A subscriber_chats -l info worker --web-port=6067

HTTP-приложение отчётов:

ENV_FILE=/etc/webim/storager.env python stats.py

Внимание

producer — ровно один экземпляр на контур. Не запускайте отдельный producer на каждый consumer.

Порт 9090 по умолчанию занимает и Image Robot. Порт 8000 — Speller и HTTP-процесс Delta Proxy. На одном узле без изоляции порты нужно разнести.

Delta Proxy

Delta Proxy доставляет операторскому интерфейсу инкрементальные обновления (дельты) через HTTP API и фоновый consumer, который пишет события из Apache Kafka в Redis. Компонент не входит в основной пакет Webim Server; его выдаёт техническая поддержка.

Два процесса, две точки входа.

Процесс Точка входа Как запускается
HTTP API delta-server/api.py python api.py
Consumer delta-server/delta_consumer.py faust -A delta_consumer -l info worker

HTTP API устроен так же, как Speller: аргументы командной строки не разбираются, адрес и порт читаются из .env. Consumer — Faust-приложение; к нему применимы те же аргументы CLI Faust, что и у Data Storager.

Параметр Процесс По умолчанию Назначение
API_BIND_IP HTTP API 0.0.0.0 Адрес прослушивания HTTP API.
API_WEB_PORT HTTP API 8000 TCP-порт HTTP API. На нём же доступны /metrics.
ENV_FILE HTTP API .env Путь к файлу переменных окружения. Consumer читает .env из рабочего каталога (переменная ENV_FILE на него не действует).
DEBUG HTTP API False Автоперезагрузка Uvicorn. В промышленной среде оставляйте выключенным.
FAUST_BIND_IP Consumer нет в шаблоне Адрес встроенного HTTP-сервера Faust.
FAUST_WEB_PORT Consumer нет в шаблоне Порт встроенного HTTP-сервера Faust.
FAUST_PROMETHEUS_PORT Consumer нет в шаблоне Порт метрик Prometheus consumer-а.
KAFKA_URL Consumer нет в шаблоне Адрес брокера Apache Kafka в формате Faust, например kafka://kafka.example.local:9092.
REDIS_CACHE_LOCATION оба обязателен Строка подключения к Redis. Без неё ни один из процессов не стартует.
AGG_DELTAS_TOPIC_NAME Consumer нет в шаблоне Топик агрегированных дельт.
AGENT_DELTAS_TOPIC_NAME Consumer нет в шаблоне Топик дельт по операторам.

Уровень логирования обоих процессов зафиксирован в коде (INFO). Аргумента --logging-config нет.

Пример

ENV_FILE=/etc/webim/delta-proxy.env python api.py
faust -A delta_consumer -l info worker

Внимание

HTTP API по умолчанию слушает порт 8000 — тот же, что у Speller. Consumer дополнительно занимает FAUST_WEB_PORT и FAUST_PROMETHEUS_PORT. Значения должны быть заданы в .env поставки и не пересекаться с другими процессами на узле.

Аргументы логирования Tornado

Аргументы ниже доступны в Chat Backend как часть tornado.options:

Аргумент По умолчанию Назначение
--logging info Уровень логирования: debug, info, warning, error или none. При значении none Tornado не настраивает логирование.
--log_to_stderr авто Выводить логи в stderr. По умолчанию используется stderr, если не задан --log_file_prefix.
--log_file_prefix не задан Префикс пути к файлам логов. Для нескольких процессов на одном узле значения должны различаться.
--log_file_max_size 100000000 Максимальный размер файла лога до ротации, байты.
--log_file_num_backups 10 Количество хранимых файлов ротации.
--log_rotate_mode size Режим ротации: size или time.
--log_rotate_when midnight Тип интервала при ротации по времени: S, M, H, D, W0–W6 или midnight.
--log_rotate_interval 1 Величина интервала при ротации по времени.

Внимание

В Chat Backend эти аргументы применяются первыми, а сразу после старта поверх них накатывается конфигурация из logging.json. Настройки, заданные в logging.json, перекрывают заданные аргументами. Поэтому для Chat Backend управляйте логированием через --logging_config, а не через --logging и --log_file_*.

Связанные материалы