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 (зависит от того, какой способ доступа вы используете).
Значением для USM_POLLER_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 USM_POLLER_SATELLITE_ID=id_вашего_satellite \ erpuserside/usm_poller:3.18