RES. Руководство администратора

Общее описание

Сервис предназначен для обеспечения доступа к отчетам kibana в интерфейсе UPS и отправки в elasticsearch статистики работы роботов SES.

Термины и определения

Report Engine Service (RES) – сервис проксирования запросов к отчетам Kibana в интерфейсе UPS. Сервис отображает все отчеты Kibana.

Требования к окружению

Для нормальной работы сервис должен быть установлен на сервере с UPS. В процессе работы сервис взаимодействует со следующими сервисами:

   • UPS – настройка осуществляется через файл /opt/ups/config.json
   • Kibana – настраивается через файл /opt/res/config.json. kibana может быть расположен на другом хосте
   • elasticsearch - настраивается через файл /opt/res/config.json. elasticsearch может быть расположен на другом хосте
   • SES – настраивается через файл /opt/res/config.json. SES может быть расположен на другом хосте

Установка RES

Дистрибутив распространяется в виде установочных пакетов для окружения и сервиса. Загрузите установочные пакеты на сервер и выполните команды для вашей системы в каталоге с пакетом.

Перед установкой непосредственно сервиса необходимо установить сервисный пакет окружения.

• Установка/обновление RES осуществляется скриптом chmod +x ./res-<версия>-<релиз>.sh && ./res-<версия>-<релиз>.sh -i с правами администратора. Список всех ключей инсталлятора можно посмотреть, запустив инсталлятор ./res-<версия>-<релиз>.sh без ключей.
• Загрузить последнюю версию продукта curl -s "https://repo.connect2ai.net/api/res/new" --user '[user]:[pass]' 2>&1 | bash или в интерактивном режиме bash -c "$(curl -s https://repo.connect2ai.net/api/res --user '[user]:[pass]' 2>&1)".
• Обновить RES /opt/res/inupdate в интерактивном режиме. Или запустить с ключом:
  • /opt/res/inupdate -b — обновить до последней beta версии;
  • /opt/res/inupdate -r — обновить до последней release версии;
  • /opt/res/inupdate -n — обновить до последней версии (неважно beta или release).
• Проверить актуальную версию продукта curl -s "https://repo.connect2ai.net/api/res/version.
• Посмотреть лог изменений curl -s "https://repo.connect2ai.net/api/res/changelog" --user '[user]:[pass]'.
• Полное описание всех команд API репозитория можно найти по ссылке https://repo.connect2ai.net/api. [user]:[pass] — это тот же логин и пароль, что и от Nextcloud.
• В папке с продуктом можно добавить 2 файла конфигурации (допускается один общий файл на все продукты в папке с окружением /opt/pve/):
  • echo -n "[user]:[pass]" > /opt/res/.userapi (это файл авторизации в API, нужен для обновления и загрузки )
  • echo -n "http://example.com:3128 [user] [password]" > /opt/res/.proxy (это файл конфигурации proxy, необходим для обновления и загрузки, при отсутствующем прямом подключении к интернету)

При обновлении следующий список файлов и папок сохраняется: .userapi, .proxy, logs, nnets, config.json, cache, pretrained, pve, data. Сервис не требует остановки и возвращается в актуальное состояние после обновления.

Не забудьте запустить сервис и включить в автозапуск в системе:

sudo systemctl enable res.service && sudo systemctl start res.service

Удостоверьтесь, что сервис стартовал:

systemctl status res.service

Разрешите доступ к портам 6157/tcp, 6170/tcp а также порту, определенном в конфиге (по умолчанию 6189/tcp) на нужном интерфейсе.

Настройка

Файл config.json

Настройка параметров сервиса res производится в файле /opt/res/config.json

Описание параметров приведено в таблице

Параметр	По умолчанию	Назначение
port	6189	Порт API интерфейса используется в UPS — настройка servers.res в конфиге UPS.
servers.ses.urls	"http://127.0.0.1:6190/ses"	Список серверов ses для получения статистики.
servers.ses.timers.connect	60	Таймаут на подключение к серверам ses. При превышении в журнал будет записана ошибка таймаута.
servers.ses.timers.read	120	Таймаут на чтение статистики с серверов ses. При превышении в журнал будет записана ошибка таймаута.
servers.ses.scores	["one", "two", "three",  "four", "five"]	Ключевые слова для поиска оценки работы.
servers.elastic.url	"https://10.2.0.30:9200"	Сервер Elasticsearch для выгрузки статистики.
servers.elastic.username	"elastic"	Пользователь elasticsearch.
servers.elastic.password	" "	Пароль пользователя elasticsearch.
servers.elastic.timers.connect	60	Таймаут на подключение к серверам Elasticsearch. При превышении в журнал будет записана ошибка таймаута.
servers.elastic.timers.read	120	Таймаут на выгрузку статистики на сервер Elasticsearch. При превышении в журнал будет записана ошибка таймаута.
servers.kibana.url	"https://10.2.0.30:5601"	Сервер kibana для получения отчетов.
servers.kibana.timers.connect	60	Таймаут на подключение к серверу Kibana. При превышении в журнал будет записана ошибка таймаута.
servers.kibana.timers.read	120	Таймаут на чтение отчетов с сервера Kibana. При превышении в журнал будет записана ошибка таймаут.а
loader.time	["05:00", "17:00"]	Ежедневное расписание загрузки статистики. Записей может быть больше если нужно чаще актуализировать статистику.
logs.path	"logs/"	Папка хранения журналов.
logs.backups	10	Максимальное количество журнальных файлов.
logs.maxSize	5242880	Максимальный размер журнального файла.

Для того чтобы рабочие столы с отчетами были доступны в UPS по https протоколу, в конфигурации реверс прокси должны быть следующие директивы (для nginx):

  proxy_set_header  Host $host;

  proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;

  proxy_set_header  X-Forwarded-Proto $scheme;

  proxy_set_header  X-Forwarded-Ssl on; # Optional

  proxy_set_header  X-Forwarded-Port $server_port;

  proxy_set_header  X-Forwarded-Host $host;

Также должен быть еще один конфиг файл который перенаправляет порт 5602 ssl на порт 5602 сервиса UPS (proxy_pass   https://UPS_IP:5602;)

В конфиге должны быть директивы для заголовков CORS и обработки OPTIONS запросов.

Установка и настройка kibana + elasticsearch

ВНИМАНИЕ - раздел в доработке

Для работы RES нужно установить и соответствующим образом настроить Elasticsearch и Kibana. Без настроенного подключения к рабочим Elasticsearch и Kibana RES не стартует и пишет в логи ошибку.

Пример установки на один хост с IP 1.2.3.4, без кластера.

Устанавливаем elasticsearch

dpkg -i elasticsearch-8.15.3-amd64.deb

Инсталлятор должен выдать

The generated password for the elastic built-in superuser is : j9Of2HyCHcK55ElgziyW

Копируем пароль — он будет использован в разделе servers.elastic.password файла конфигурации RES и для входа в веб-интерфейс Kibana.

Генерируем CA.

/usr/share/elasticsearch/bin/elasticsearch-certutil ca --pem --out /etc/elasticsearch/certs/ca.zip;

cd /etc/elasticsearch/certs/;

unzip ca.zip;

С использованием CA генерируем сертификаты для elastik

/usr/share/elasticsearch/bin/elasticsearch-certutil cert \

--out /etc/elasticsearch/certs/elastic.zip \

--name elastic \

--ip 1.2.3.4, 127.0.0.1 \

--ca-cert /etc/elasticsearch/certs/ca/ca.crt \

--ca-key /etc/elasticsearch/certs/ca/ca.key \

--pem;

cd /etc/elasticsearch/certs/;

unzip elastic.zip

Правим конфиг elasticsearch /etc/elasticsearch/elasticsearch.yml

Результат:

cluster.name: res # имя кластера - произвольно

path.data: /var/lib/elasticsearch

path.logs: /var/log/elasticsearch

network.host: 1.2.3.4 # здесь ip хоста

http.port: 9200

xpack.security.enabled: true

xpack.security.enrollment.enabled: true

xpack.security.http.ssl:

  enabled: true

  key: /etc/elasticsearch/certs/elastic/elastic.key

  certificate: /etc/elasticsearch/certs/elastic/elastic.crt

  certificate_authorities: /etc/elasticsearch/certs/ca/ca.crt

xpack.security.transport.ssl:

  enabled: true

  verification_mode: certificate

  keystore.path: certs/transport.p12

  truststore.path: certs/transport.p12

cluster.initial_master_nodes: ["hostname"] # здесь подставить имя хоста

http.host: 0.0.0.0

Внимание: копировать конфиг отсюда напрямую не получится, wiki добавляет в начало строки вместо пробела «неразрывный пробел» — yaml его не воспринимает.

Стартуем сервис

systemctl daemon-reload

systemctl enable elasticsearch.service

systemctl start elasticsearch

Проверяем с использованием пароля, сгенерированного в начале

curl -X GET -u elastic:j9Of2HyCHcK55ElgziyW https://1.2.3.4:9200 --cacert /etc/elasticsearch/certs/ca/ca.crt

Устанавливаем kibana

dpkg -i kibana-8.15.3-amd64.deb

Папка для сертификатов: mkdir -p /etc/kibana/certs/

Копируем корневой сертификат: cp -r /etc/elasticsearch/certs/ca /etc/kibana/certs/

Получим пароль для доступа из kibana в elasticsearch /usr/share/elasticsearch/bin/elasticsearch-reset-password -u kibana_system --auto

Пароль нужен будет дальше в строке elasticsearch.password: конфига kibana.

Kibana ставим в варианте http (без ssl).

Правим конфиг kibana /etc/kibana/kibana.yml

Результат

server.port: 5601

server.host: 0.0.0.0

server.publicBaseUrl: "http://1.2.3.4:5601"

server.ssl.enabled: false

elasticsearch.hosts: ["https://1.2.3.4:9200"]

elasticsearch.username: "kibana_system"

elasticsearch.password: "gfntin_083SKBYC9V5yk"

elasticsearch.ssl.certificateAuthorities: /etc/kibana/certs/ca/ca.crt

elasticsearch.ssl.verificationMode: full

logging:

  appenders:

    file:

      type: file

      fileName: /var/log/kibana/kibana.log

      layout:

        type: json

  root:

    appenders:

      - default

      - file

pid.file: /run/kibana/kibana.pid

xpack.security.authc.providers:

  basic.basic1:

    order: 0

csp.strict: false

csp.warnLegacyBrowsers: false

csp.script_src:

  - unsafe-inline

  - self

  - unsafe-eval

server.customResponseHeaders: {"x-frame-options":"ALLOWALL"}

Запускаем kibana systemctl enable kibana && systemctl start kibana

Заходим по адресу https://1.2.3.4:5601/ с пользователем elastic и паролем, который создал инсталлятор elasticsearch. Если видим стартовую страничку Kibana, то Elasticsearch и Kibana готовы к работе с RES. После запуска RES установит пользователя reports с паролем reports и правом доступа к рабочим столам kibana. Рекомендуется сменить после этого пароль. Этот пользователь и пароль должен быть указан в конфиг файле ups в разделе res.

Протоколы и порты

Сервис использует порт 6156/tcp - реверс прокси кибаны и 6189/tcp для доступа к API-интерфейсу. Порт доступа к API может быть изменен в конфигурационном файле.

Журналы работы

Для проверки состояния сервиса выполните sudo systemctl status res.

Журналы сервиса находятся в каталоге, определенном в конфигурационном файле (по умолчанию — /opt/res/logs/). Ошибки также пишутся в системный журнал, для просмотра можно воспользоваться командой sudo journalctl -u res

Удаление и обновление RES

Для удаления выполните команду:

/opt/res/uninstall

Команда удалит сервис и рабочий каталог, включая все файлы конфигурации. Для обновления запустите скрипт установки, как указано в п. 4. При этом обновление не изменяет файл /opt/res/config.json.