Usm poller (as satellite)

Описание

Начиная с версии USERSIDE 3.18 для взаимодействия с телекоммуникационным оборудованием используются специальные службы usm_poller, запускаемые в нескольких копиях на серверах оператора для увеличения доступности, отказоустойчивости и распределения нагрузки между серверами. Между ядром USERSIDE и этими службами передаются специальные сообщения, содержащие сетевые задания, которые через брокер сообщений RabbitMQ распределяются между всеми службами usm_poller и таким же образом через брокер службы сообщают ядру USERSIDE о результатах работы. Использование более подходящих для сетевого взаимодействия инструментов, а также внесенная в систему асинхронность позволяет использовать ранее недоступные протоколы связи, ускорить многие сценарии взаимодействия по существующим протоколам и не заставлять пользователя ждать результата в открытом окне браузера.

С учетом особенностей запуска служб usm_poller создается возможность использования этих поллеров вместо пркси-модулей usm_satellite, которые использовались в USERSIDE версиях 3.13-3.17 для проксирования команд взаимодействия с оборудованием между ядром USERSIDE и недоступным по сети оборудованием по протоколу HTTP-API. Для этого в модули usm_poller была добавлена простая настройка, идентифицирующая конкретный экземпляр usm_poller как "сателлит".

Начиная с версии USERSIDE 3.18 в качестве "сателлита" на удалённых узлах используется модуль usm_poller.

Требования

Для запуска usm_poller на удалённом узле связи требуется наличие Docker и Compose plugin v2

Установка и настройка

Установка Docker и Compose plugin

В большинстве поддерживаемых операционных систем достаточно запуска команды:

curl -fsSL get.docker.com | sh

Эта команда установит Docker Engine и Compose Plugin последних версий на большинстве поддерживаемых операционных систем. Если для вашей системы это невозможно, команда выдаст рекомендации по ручной установке. Вы также можете обратиться к официальной инструкции по установке на сайте проекта Docker. Обратите внимание на то, что версия DockerIO, которая поставлялась с некоторыми дистрибутивами Linux, считается устаревшей и не подходит. Одновременно с этим, версия Docker Desktop, предназначенная для десктопных операционных систем, поддерживается и вы сможете также использовать и ее, но предпочтение лучше отдать Docker Engine (серверной версии Docker).

Если вам необходимо запускать команды к Docker без использования sudo, то добавьте своего пользователя в группу docker следующими командами:

sudo gpasswd -a $USER docker
newgrp docker

Теперь проверьте, что все установилось корректно, выполнив команды:

docker version
docker compose version

Организация связи поллера с брокером

При использовании usm_satellite сервером являлся сам модуль, в то время как клиентом являлось ядро Userside, которое выполняло HTTP-API запросы к usm_satellite.

Теперь сервером для всех потребителей сообщений является брокер RabbitMQ, не зависимо от того, отправляет приложение сообщение либо его принимает. Это означает, что удалённый сервер, на котором устанавливается usm_poller в качестве сателлита, должен иметь доступ по сети к брокеру RabbitMQ, установленному на сервере с Userside (либо на каком-то отдельном сервере, если в этом была необходимость). В то же время удаленный сервер теперь вообще может не иметь открытых портов, что повышает его безопасность.

Для подключения к брокеру RabbitMQ по умолчанию используется TCP-порт 5672 (протокол AMQP). Мы рекомендуем открыть доступ к этому порту из внешней сети только с известных вам IP-адресов, коим является IP-адрес удаленного сервера-сателлита, на котором вы запускаете usm_poller.

Если вы используете и USERSIDE в Docker-бандле, то раскомментируйте строку в ports сервиса rabbitmq, отвечающую за трансляцию порта 5672 (подписан в комментариях как AMQP) и перезапустите Docker-бандл.

Также альтернативой порту 5672 (AMQP) может быть порт 5671 (AMQPS), который по умолчанию не используется. Вы можете настроить AMQPS (TLS) самостоятельно в дополнение к порту 5672 (AMQP). Инструкции по настройке TLS можно получить в официальной документации RabbitMQ.

Т.к. сообщения, передаваемые между брокером RabbitMQ и его потребителями передаются в открытом виде, рекомендуемым вариантом организации связи является использование туннелирования с шифрованием между узлами RabbitMQ и удалённым сервером с usm_poller.

Запуск Docker-контейнеров usm_poller

Рекомендуемым способом запуска является использование плагина compose. В этом случая вся конфигурация контейнера прописывается в специальном compose-файле, что облегчает последующую эксплуатацию.

Вы можете создать compose-файл где угодно, но чтобы не потерять его расположение в будущем, рекомендуем расположить его, например, в /opt/usm_poller. Создайте каталог:

sudo mkdir -p /opt/usm_poller

Затем создайте файл с именем compose.yaml в этом каталоге и следующим содержимым (обратите внимание на отступы - они имеют значение):

services:
  poller:
    image: erpuserside/usm_poller:3.18
    restart: unless-stopped
    environment:
      US_AMQP_DSN: amqp://имя_пользователя:пароль@адрес_хоста_rabbitmq:5672/%2f
      USM_POLLER_SATELLITE_ID: id_вашего_satellite
    deploy:
      replicas: 1

Для работы с USERSIDE 3.18 используется образ erpuserside/usm_poller:3.18. Версия образа должна совпадать с версией используемого в ядре USERSIDE.

Значением для US_AMQP_DSN является URL-строка, которую вы можете скопировать из файла .env, расположенного в корневом каталоге с USERSIDE: /var/www/userside, но вместо IP-адреса RabbitMQ, указанного там, вам нужно указать тот IP-адрес, по которому доступен сервер RabbitMQ (зависит от того, какой способ доступа вы используете).

Значением для US_SATELLITE_ID является идентификатор "сателлита", который вы можете взять со страницы: Настройка - Основная - Оборудование - Настройка сателлитов.

Сохраните файл composer.yaml и запустите для теста следующим образом:

docker compose up

Вы должны увидеть, как загружается образ, затем происходит запуск Docker-контейнера usm_poller и подключение к серверу RabbitMQ по протоколу AMQP. Если подключение к RabbitMQ серверу произошло корректно, то остановите работу контейнера сочетанием Ctrl+C, измените количество реплик (значение replicas) до 5 и запустите контейнеры в фоновом режиме:

docker compose up -d

Если пяти копий контейнера будет мало, увеличьте это значение. Чтобы определить, достаточно ли контейнеров, откройте WEB-консоль RabbitMQ используя протокол http, адрес домена вашего userside и порт 15672. Например, вот так: http://userside.mycompany.com:15672 и затем перейдите на страницу Queues. Найдите там очередь с именем usm_poller-sat-7 (где 7 — это идентификатор сателлита), откройте ее и понаблюдайте за заполнением очереди. Смысл заключается в том, чтобы поллеры успевали забирать задания в пределах нормального для вас времени. В идеале, очередь должна быть практически пустой всегда (задания сразу же отдаются свободному поллеру), либо количество сообщений должно доходить до нуля (количество поллеров достаточно). Не стоит увеличивать количество реплик просто так — это приведет к ненужному накладному расходу ресурсов и в итоге может даже отрицательно сказаться на производительности, если ресурсов системы будет не хватать.

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

docker compose restart

Посмотреть состояние контейнеров можно командой:

docker compose ps

Чтобы остановить все контейнеры, используйте команду:

docker compose stop

Чтобы обновить версию Docker-образа в пределах его версии (это желательно делать после каждого обновления USERSIDE), нужно сначала остановить контейнеры, затем обновить образы и затем снова запустить их в фоне:

docker compose stop
docker compose pull
docker compose up -d

Если вам кажется, что что-то работает не так как нужно, посмотрите логи контейнеров командой:

docker compose logs poller

Либо же можно добавить опцию -f чтобы наблюдать follow за логами в реальном времени.

Запустить один контейнер можно и без использования compose, выполнив всего лишь одну команду (состоящую из нескольких строк). Однако такой способ хоть и является более простым, все же не так удобен для последующей эксплуатации:

docker run --detach \
  --restart unless-stopped \
  --name usm_poller \
  --env US_AMQP_DSN=amqp://имя_пользователя:пароль@адрес_хоста_rabbitmq:5672/%2f \
  --env US_SATELLITE_ID=id_вашего_satellite \
  erpuserside/usm_poller:3.18