Аргументы запуска компонентов 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_*.
Связанные материалы
-
Главные файлы настроек — конфигурация в
/etc/webim; -
Логирование в Chat Backend и Логирование в Admin Backend — формат и слияние
logging.json; -
Масштабирование Admin Backend — многонодовый режим;
-
Мониторинг Webim Server через Prometheus — сбор метрик;
-
Рекомендации по настройке мониторинга — контроль процессов и портов;
-
Speller и Data Storager — переменные окружения и эксплуатация микросервисов.