Просмотр кода страницы 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''' ===== 

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

Перед установкой непосредственно сервиса необходимо [[PVE. Установка сервисного пакета окружения|установить сервисный пакет окружения]].

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

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

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

<code>sudo systemctl enable res.service && sudo systemctl start res.service</code>

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

<code>systemctl status res.service</code>

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

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

Описание параметров приведено в таблице
{| class="wikitable"
|+
!Параметр
!По умолчанию
!Назначение
|-
|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):

  <small>proxy_set_header  Host $host;</small>

<small>  proxy_set_header  X-Forwarded-For $proxy_add_x_forwarded_for;</small>

<small>  proxy_set_header  X-Forwarded-Proto $scheme;</small>

<small>  proxy_set_header  X-Forwarded-Ssl on; # Optional</small>

<small>  proxy_set_header  X-Forwarded-Port $server_port;</small>

<small>  proxy_set_header  X-Forwarded-Host $host;</small>

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

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



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




<span style="color:red">'''ВНИМАНИЕ - раздел в доработке'''</span>



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

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

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

<code><small>dpkg -i elasticsearch-8.15.3-amd64.deb</small></code>

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

<small><code>The generated password for the elastic built-in superuser is : j9Of2HyCHcK55ElgziyW</code></small>

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

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

<code><small>/usr/share/elasticsearch/bin/elasticsearch-certutil ca --pem --out /etc/elasticsearch/certs/ca.zip;</small></code>

<code><small>cd /etc/elasticsearch/certs/;</small></code>

<code><small>unzip ca.zip;</small></code>

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

<small><code>/usr/share/elasticsearch/bin/elasticsearch-certutil cert \</code></small>

<small><code>--out /etc/elasticsearch/certs/elastic.zip \</code></small>

<small><code>--name elastic \</code></small>

<small><code>--ip 1.2.3.4, 127.0.0.1 \</code></small>

<small><code>--ca-cert /etc/elasticsearch/certs/ca/ca.crt \</code></small>

<small><code>--ca-key /etc/elasticsearch/certs/ca/ca.key \</code></small>

<small><code>--pem;</code></small>

<small><code>cd /etc/elasticsearch/certs/;</code></small>

<small><code>unzip elastic.zip</code></small>

'''Правим''' конфиг elasticsearch <small><code>/etc/elasticsearch/elasticsearch.yml</code></small>

Результат:

<small><code>cluster.name: res # '''''имя кластера - произвольно'''''</code></small>

<small><code>path.data: /var/lib/elasticsearch</code></small>

<small><code>path.logs: /var/log/elasticsearch</code></small>

<small><code>network.host: 1.2.3.4 # '''''здесь ip хоста'''''</code></small>

<small><code>http.port: 9200</code></small>

<small><code>xpack.security.enabled: true</code></small>

<small><code>xpack.security.enrollment.enabled: true</code></small>

<small><code>xpack.security.http.ssl:</code></small>

<small><code>  enabled: true</code></small>

<small><code>  key: /etc/elasticsearch/certs/elastic/elastic.key</code></small>

<small><code>  certificate: /etc/elasticsearch/certs/elastic/elastic.crt</code></small>

<small><code>  certificate_authorities: /etc/elasticsearch/certs/ca/ca.crt</code></small>

<small><code>xpack.security.transport.ssl:</code></small>

<small><code>  enabled: true</code></small>

<small><code>  verification_mode: certificate</code></small>

<small><code>  keystore.path: certs/transport.p12</code></small>

<small><code>  truststore.path: certs/transport.p12</code></small>

<small><code>cluster.initial_master_nodes: ["hostname"] # '''''здесь подставить имя хоста'''''</code></small>

<small><code>http.host: 0.0.0.0</code></small><blockquote>'''''Внимание: копировать конфиг отсюда напрямую не получится, wiki добавляет в начало строки вместо пробела «неразрывный пробел» — yaml его не воспринимает.'''''</blockquote>'''Стартуем''' сервис

<small><code>systemctl daemon-reload</code></small>

<small><code>systemctl enable elasticsearch.service</code></small>

<small><code>systemctl start elasticsearch</code></small>

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

<small><code>curl -X GET -u elastic:j9Of2HyCHcK55ElgziyW <nowiki>https://1.2.3.4:9200</nowiki> --cacert /etc/elasticsearch/certs/ca/ca.crt</code></small>

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

<code><small>dpkg -i kibana-8.15.3-amd64.deb</small></code>

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

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

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

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

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

'''Правим''' конфиг kibana <small><code>/etc/kibana/kibana.yml</code></small>

Результат

<small><code>server.port: 5601</code></small>

<small><code>server.host: 0.0.0.0</code></small>

<small><code>server.publicBaseUrl: "<nowiki>http://1.2.3.4:5601</nowiki>"</code></small>

<small><code>server.ssl.enabled: false</code></small>

<small><code>elasticsearch.hosts: ["<nowiki>https://1.2.3.4:9200</nowiki>"]</code></small>

<small><code>elasticsearch.username: "kibana_system"</code></small>

<small><code>elasticsearch.password: "gfntin_083SKBYC9V5yk"</code></small>

<small><code>elasticsearch.ssl.certificateAuthorities: /etc/kibana/certs/ca/ca.crt</code></small>

<small><code>elasticsearch.ssl.verificationMode: full</code></small>

<small><code>logging:</code></small>

<small><code>  appenders:</code></small>

<small><code>    file:</code></small>

<small><code>      type: file</code></small>

<small><code>      fileName: /var/log/kibana/kibana.log</code></small>

<small><code>      layout:</code></small>

<small><code>        type: json</code></small>

<small><code>  root:</code></small>

<small><code>    appenders:</code></small>

<small><code>      - default</code></small>

<small><code>      - file</code></small>

<small><code>pid.file: /run/kibana/kibana.pid</code></small>

<small><code>xpack.security.authc.providers:</code></small>

<small><code>  basic.basic1:</code></small>

<small><code>    order: 0</code></small>

<small><code>csp.strict: false</code></small>

<small><code>csp.warnLegacyBrowsers: false</code></small>

<small><code>csp.script_src:</code></small>

<small><code>  - unsafe-inline</code></small>

<small><code>  - self</code></small>

<small><code>  - unsafe-eval</code></small>

<small><code>server.customResponseHeaders: {"x-frame-options":"ALLOWALL"}</code></small>

'''Запускаем''' kibana <small><code>systemctl enable kibana && systemctl start kibana</code></small>

Заходим по адресу <nowiki>https://1.2.3.4:5601/</nowiki> с пользователем elastic и паролем, который создал инсталлятор elasticsearch. Если видим стартовую страничку Kibana, то Elasticsearch и Kibana готовы к работе с RES. После запуска RES установит пользователя reports с паролем reports и правом доступа к рабочим столам kibana. Рекомендуется сменить после этого пароль. Этот пользователь и пароль должен быть указан в [https://wiki.connect2ai.net/index.php/UPS._%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%B0%D0%B4%D0%BC%D0%B8%D0%BD%D0%B8%D1%81%D1%82%D1%80%D0%B0%D1%82%D0%BE%D1%80%D0%B0#%D0%9A%D0%BE%D0%BD%D1%84%D0%B8%D0%B3%D1%83%D1%80%D0%B8%D1%80%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5_%D0%BF%D0%B0%D1%80%D0%B0%D0%BC%D0%B5%D1%82%D1%80%D0%BE%D0%B2_%D1%81%D0%B5%D1%80%D0%B2%D0%B8%D1%81%D0%B0 конфиг файле ups] в разделе res.

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

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

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

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

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

<code>/opt/res/uninstall</code> 

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