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

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

Аргументы задают то, что должно быть известно процессу **до** чтения конфигурационных файлов: адрес и порт прослушивания, имя узла в кластере, имя подключения к **Redis**, путь к дополнительной конфигурации логирования. Остальные настройки **Chat Backend**, **Admin Backend**, **History Backend**, **Image Robot** задаются в файлах из `/etc/webim` — см. [Главные файлы настроек](https://webim.ru/kb/devops/main-ini-configuration.html). **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 завершает процесс |

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

Способ передачи аргументов зависит от варианта установки: для DEB-пакетов это unit-файлы systemd (например, `webim-tornado` и `webim-admin-backend`) или конфигурация `supervisord`, для [Docker](https://webim.ru/kb/devops/hosted-deployment/docker.html) — команда запуска контейнера. После изменения аргументов компонент нужно перезапустить.

## Chat Backend

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

| Аргумент | По умолчанию | Назначение                                                                                                                                                                                                            |
|----------|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `--port` | `8260` | TCP-порт, на котором компонент принимает запросы.                                                                                                                                                                     |
| `--upstream_timeout` | `40` | Тайм-аут обработки запроса, секунды. По его истечении запрос завершается без ответа от обработчика.                                                                                                                   |
| `--logging_config` | не задан | Путь к дополнительному файлу `logging.json`. Файл **объединяется** с конфигурацией из дистрибутива, а не заменяет её. Подробности — в статье [Логирование в Chat Backend](https://webim.ru/kb/devops/logging-configuration-for-chat-backend.html). |
| `--prometheus_port` | не задан | Порт HTTP-сервера метрик. Если аргумент не указан, сервер метрик не запускается. См. [Мониторинг через Prometheus](https://webim.ru/kb/devops/monitoring/prometheus.html).                                                                         |
| `--redis_connection` | не задан | Имя подключения к **Redis** из секции `connections` (см. [Конфигурация Redis](https://webim.ru/kb/devops/main-ini-configuration.html#redis)). Обязательный параметр. Без него **Chat Backend** не стартует.                      |
| `--node_name` | не задан | Устаревший, не подлежит использованию.                                                                                                                                                                                |
| `--cluster_config` | не задан | Устаревший, не подлежит использованию.                                                                                                                                                                                |
| `--profiler_filename` | не задан | Путь к файлу для дампа профиля. Если аргумент не указан, профилирование недоступно.                                                                                                                                   |
| `--profiling` | `true` | Состояние профилировщика на старте. Действует только вместе с `--profiler_filename`.                                                                                                                                  |

### Профилирование { #cb-profiling }

Профилирование включается только при заданном `--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](https://webim.ru/kb/devops/logging-configuration-for-admin-backend.html). |
| `--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`.                                                                                                         |

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

### Переменные окружения { #ab-env }

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

### Многонодовый режим { #ab-multinode }

Для многонодового режима обязательны **оба** аргумента — `--cluster-name` и `--redis-connection`; их значения должны быть одинаковыми на всех экземплярах **Admin Backend**. Полная процедура описана в статье [Масштабирование Admin Backend](https://webim.ru/kb/devops/scaling/admin-backend-scaling.html).

### Пример

```
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-порт, на котором компонент принимает запросы. |

!!! Note "N.B."
    Порт `9090` по умолчанию занимают и другие компоненты — например, воркеры [Data Storager](https://webim.ru/kb/devops/services/data-storager.html) публикуют на нём метрики. Если компоненты размещены на одном узле без сетевой изоляции, назначьте им разные порты.

Пример:

```
image_robot --host=192.0.2.3 --port=9095
```

## Speller

**Speller** — микросервис проверки орфографии. Архитектура, сеть и полный список переменных окружения — в статье [Speller](https://webim.ru/kb/devops/services/speller.html).

Аргументы командной строки **не разбираются**. Точка входа `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` рядом с точкой входа.

!!! Warning "Внимание"
    Порт `8000` по умолчанию занимает и HTTP-процесс [Delta Proxy](#delta-proxy). Если оба сервиса стоят на одном узле без сетевой изоляции, назначьте им разные значения `API_WEB_PORT`.

## Data Storager

**Data Storager** (ранее **es-storager**) — набор процессов, которые переносят историю диалогов и статистику из баз **Webim** в поисковый кластер и **ClickHouse**. Полное описание архитектуры, переменных окружения и эксплуатационных команд — в статье [Data Storager](https://webim.ru/kb/devops/services/data-storager.html).

У сервиса нет единого `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 { #ds-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. |

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

    Эксплуатационные команды (`health`, `refresh`, `populate` и другие) описаны в статье [Data Storager](https://webim.ru/kb/devops/services/data-storager.html) и к старту воркера не относятся.

### Переменные, влияющие на запуск { #ds-env }

| Переменная | По умолчанию                 | Назначение                                                                                                                                                                                                                                                            |
|------------|------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `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](https://webim.ru/kb/devops/services/data-storager.html).

### Примеры

Один 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
```

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

    Порт `9090` по умолчанию занимает и [Image Robot](#image-robot). Порт `8000` — [Speller](#speller) и HTTP-процесс [Delta Proxy](#delta-proxy). На одном узле без изоляции порты нужно разнести.

## Delta Proxy

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

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

| Процесс | Точка входа | Как запускается |
|---------|-------------|-----------------|
| 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](#ds-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
```

!!! Warning "Внимание"
    HTTP API по умолчанию слушает порт `8000` — тот же, что у [Speller](#speller). Consumer дополнительно занимает `FAUST_WEB_PORT` и `FAUST_PROMETHEUS_PORT`. Значения должны быть заданы в `.env` поставки и не пересекаться с другими процессами на узле.

## Аргументы логирования Tornado { #tornado-logging }

Аргументы ниже доступны в **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` | Величина интервала при ротации по времени. |

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

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

  * [Главные файлы настроек](https://webim.ru/kb/devops/main-ini-configuration.html) — конфигурация в `/etc/webim`;

  * [Логирование в Chat Backend](https://webim.ru/kb/devops/logging-configuration-for-chat-backend.html) и [Логирование в Admin Backend](https://webim.ru/kb/devops/logging-configuration-for-admin-backend.html) — формат и слияние `logging.json`;

  * [Масштабирование Admin Backend](https://webim.ru/kb/devops/scaling/admin-backend-scaling.html) — многонодовый режим;

  * [Мониторинг Webim Server через Prometheus](https://webim.ru/kb/devops/monitoring/prometheus.html) — сбор метрик;

  * [Рекомендации по настройке мониторинга](https://webim.ru/kb/devops/monitoring/monitoring-setup-recommendations.html) — контроль процессов и портов;

  * [Speller](https://webim.ru/kb/devops/services/speller.html) и [Data Storager](https://webim.ru/kb/devops/services/data-storager.html) — переменные окружения и эксплуатация микросервисов.

---

Источник: https://webim.ru/kb/devops/launch-arguments.html
