Перейти к содержанию

Многофункциональный веб-сервис webbi

Общие сведения

Веб-сервис webbi предназначен для решения следующих задач:

Tip

webbi входит в состав TESSA начиная с версии 4.0.

Important

По умолчанию возможность приёма команд из внешнего контура отключена. Включить её и настроить маршрут для приёма команд можно в поле Settings → Management конфигурационного файла app.json для webbi.

Important

Работа с webbi должна производиться только по протоколу HTTPS, за что должен отвечать соответствующим образом настроенный reverse proxy (IIS или nginx).

Настройка сервиса webbi

Для корректной работы webbi необходимо задать ряд обязательных параметров.

Important

Настройки, заданные в аргументах командной строки, имеют приоритет перед настройками, заданными в конфигурационном файле.

Аргументы командной строки

Аргументы командной строки и их назначение:

Аргумент Описание
-c <config> Указывает путь к файлу конфигурации в формате JSON, содержащему настройки webbi (как правило app.json). Обязательный. Если не задан, то должен быть задан аргумент -cstdin
-cstdin Указывает, что содержимое файла конфигурации в формате JSON с настройками webbi необходимо считать из стандартного потока ввода (stdin). Обязательный. Если не задан, то должен быть задан аргумент -c
-server <name> Указывает имя сервера TESSA, обслуживание которого осуществляет webbi. Только для режима технического обслуживания
-p <port> Указывает порт, который будет использован webbi для работы. По умолчанию используется порт 19857
-r <redisConnectionString> Строка с данными подключения к серверу Redis
-ri <refreshInterval> Указывает интервал обновления данных из Redis в формате <numOfSeconds>s, или <numOfMilliseconds>ms. Допустимо использовать дробные значения. Значение по умолчанию 3 секунды
-unrestricted Допускает обработку запросов от любых адресов, приходящих на прослушиваемый webbi порт. По умолчанию webbi обрабатывает запросы, поступающие только с того компьютера, на котором он запущен.

Использование данного флага может ухудшить безопасность системы. Не рекомендуется его использовать без уверенности в необходимости именно такого режима работы webbi. Флаг допустимо использовать только в изолированных системах, например, внутри docker контейнера
-msdb <connectionString> Строка подключения к БД MS SQL Server с данными системы. Используется для обогащения представлений в Redis Explorer. Если аргумент задан, то аргумент -pgdb не должен быть задан, т.к. они взаимоисключающие
-pgdb <connectionString> Строка подключения к БД PostgreSQL с данными системы в формате libpq. Используется для обогащения представлений в Redis Explorer. Если аргумент задан, то аргумент -msdb не должен быть задан, т.к. они взаимоисключающие.
⚠️ Формат строки подключения отличается от формата, используемого в app.json для npgsql
-dev Флаг включения режима разработчика.
⚠️ Используется только разработчиками при локальных запусках.
Активирует webbi в режиме Redis Explorer без авторизации.
Все остальные возможности отключены.
⛔ Запрещено использовать в продуктивном контуре, поскольку открывает неконтролируемый доступ к данным системы в Redis
-v Флаг использования многословного режима. В этом режиме на консоль будут выводится подробные диагностические сообщения
-dbg Флаг использования отладочного режима. Рекомендуется использовать только в диагностических целях для проверки работы сервера. В этом режиме будет доступна страница /info с подробной информацией о текущем состоянии webbi
-cid Полный путь к файлу с уникальным идентификатором компонента.
Если файл не указан, то при старте компонента будет создан файл .cid рядом с исполняемым файлом.
Если файл пуст, то в указанный файл будет записан уникальный идентификатор компонента
-randomize-cid Флаг необходимости дополнительно рандомизировать уникальный идентификатор компонента.
Используйте рандомизацию, чтобы гарантировать, что несколько параллельно запущенных процессов, использующих единственный файл с уникальным идентификатором, не получат одинаковый уникальный идентификатор

Tip

Рекомендуется указывать номер порта целым числом больше 10000, не кратным 10, что в большей степени поможет исключить попытку запустить webbi на уже занятом кем-то порту, например, 19857. Как правило, номера портов меньше 8000 (реже - 10000) резервируются системными службами и приложениями.

Note

Если путь к файлу с уникальным идентификатором компонента не указан в аргументе командной строки -cid, то будет использоваться значение из переменной окружения TESSA_CID в полном соответствии с правилами генерации уникального идентификатора компонента.

Аналогично, если не указан аргумент командной строки -randomize-cid, то используется значение из переменной окружения TESSA_RANDOMIZE_CID (любое непустое значение переменной означает, что флаг указан).

Конфигурационный файл

webbi использует тот же файл конфигурации app.json, что и веб-сервис TESSA. Допускается использовать любое подходящее имя файла, при условии, что содержащиеся внутри данные имеют формат JSON и указанную далее структуру.

Поле ConnectionStrings главного объекта файла, JSON объект.

Поле Описание
default Строка подключения к БД по умолчанию. Может быть либо строкой, либо массивом строк в случае подключения к БД PostgreSQL

Tip

Поле ConnectionStrings не является обязательным для webbi и может отсутствовать, или default может быть равен пустой строке. В этом случае Redis Explorer не будет обогащать представления данными системы из БД.

Поле Settings главного объекта файла, JSON объект.

Поле Описание
ServerCode Код (символьное имя) сервера TESSA
Redis Строка подключения к Redis
ResponseHeaders JSON объект с дополнительными заголовками, которые необходимо отправлять при ответе на каждый клиентский запрос. Каждое поле объекта - это имя соответствующего заголовка, а значение - его содержание
Discovery.KeysStrictSecurity Флаг включения строгой политики безопасности работы с ключами для обработки команд доверенного контура
Management JSON объект с настройками маршрута для отправки команд из внешнего контура в доверенный
Webbi JSON объект с основными настройками webbi

Поле Settings → Management, JSON объект.

Поле Описание
Enable Флаг включения маршрута приёма команд из внешнего контура в доверенный. По умолчанию маршрут выключен
Endpoint Строка с именем маршрута.
Имя должно иметь длину 10 и более символов, должно начинаться с буквы, за которой должны следовать буквы, цифры, или символы _ , -. Допускаются только буквы английского алфавита в верхнем или нижнем регистре.
Рекомендуется использовать в качестве префикса строку management.
По умолчанию используется имя management

Поле Settings → Webbi, JSON объект.

Поле Описание
Database JSON объект с настройками подключения к базе данных системы для обогащения представлений Redis Explorer. Может отсутствовать
Port Указывает порт, который будет использован webbi для работы
RefreshInterval Указывает интервал обновления данных из Redis в формате dd.hh:mm:ss, где dd - дни, hh - часы в 24 часовом формате, mm - минуты, ss - секунды (поддерживаются целые или вещественные числа)
LogsPath Строка с именем директории для хранения файлов журналов событий webbi. По умолчанию используется директория logs в рабочей директории webbi
MaintenanceConfig JSON объект с настройками управления правилами переадресации запросов. Если отсутствует, webbi не должен переключать правила переадресации запросов

Поле Settings → Webbi → Database, JSON объект.

Поле Описание
Type Указывает тип строки подключения. Допустимы значения:
ms - MS SQL Server
pg - PostgreSQL
ConnectionString Строка подключения к БД, соответствующая типу.
⚠️ Для строки подключения к к БД PostgreSQL используется формат libpq, отличающийся от формата для npgsql

Поле Settings → Webbi → MaintenanceConfig, JSON объект.

Поле Описание
Mode Режим работы. Доступные варианты: IIS, nginx. Обязательное поле
Path Путь к файлу с правилами переадресации запросов. Если путь не указан, webbi не будет переключать правила переадресации запросов
RulePrefix Префикс правил переадресации запросов для IIS. Если не указан, будут использованы все имеющиеся правила переадресации
SwitchOn Инструкция для включения режима техобслуживания. Только для nginx. Если не задана, то webbi не будет переключать правила переадресации запросов
SwitchOff Инструкция для выключения режима техобслуживания. Только для nginx. Если не задана, то webbi не будет переключать правила переадресации запросов
ReloadCommand Инструкция для перезапуска nginx. Только для nginx. Если не задана, webbi не будет перезапускать nginx

Пример файла конфигурации.

{
    ".if": [
        "linux",
        {
            "Settings": {
                "Webbi": {
                    "MaintenanceConfig" : {
                        "Mode": "nginx",
                        "Path": "/etc/nginx/conf.d/maintenance.switch",
                        "SwitchOn": "set $maintenance on;",
                        "SwitchOff": "set $maintenance off;",
                        "ReloadCommand": "sudo -n nginx -s reload"
                    }
                }
            }
        },
        "windows",
        {
            "Settings": {
                "Webbi": {
                    "MaintenanceConfig" : {
                        "Mode": "iis",
                        // Path to your TESSA web application installation
                        //"Path": "C:/inetpub/wwwroot/platform/web/web.config",
                        "Path": "C:/tessa/web/web.config",
                        "RulePrefix": "Maintenance"
                    }
                }
            }
        }
    ],



    ".include": [
        "app-*.json",
        "../web/app.json",
        "../app.json",
        "applocal-*.json"
    ],



    "Settings": {
        // Basic options
        "ServerCode": "tessa",
        "Redis": "localhost",
        "ResponseHeaders": {
            "X-Frame-Options": "sameorigin",
            "X-XSS-Protection": "1; mode=block",
            // Extra headers
            "MySuperHeader": "Webbi"
        },
        // Strict keys security
        "Discovery.KeysStrictSecurity": false,
        // Command management endpoint settings
        "Management": {
            "Enable": false,
            "Endpoint": "management"
        },
        // Webbi options
        "Webbi": {
            "Port": 19857,
            "RefreshInterval": "00.00:00:03",
            "LogsPath": "@logs",
            "MaintenanceConfig" : {
                "Mode": null,
                "Path": null,
                "RulePrefix": null,
                "SwitchOn": null,
                "SwitchOff": null,
                "ReloadCommand": null
            }
        }
    }
}

Настройка внешнего вида страниц технического обслуживания, отображаемых webbi

В webbi существуют широкие возможности по настройке внешнего вида страницы отображения данных режима технического обслуживания под нужды каждого конкретного заказчика. Далее рассмотрена структура страниц и предоставляемые возможности по их модификации.

Important

Изменения вступают в силу после перезапуска webbi.

Страницы отображаются при помощи механизма шаблонов html страниц языка Go. Сами шаблоны расположены в директории views основной директории webbi.

Файл шаблона Описание Используемые сообщения
layout.tmpl Основной шаблон макета страницы. Все остальные страницы наследуют схему его разметки Title
maintenance.tmpl Шаблон страницы технического обслуживания. Содержит информацию о причинах технического обслуживания, сроках его проведения и любые иные дополнительные сведения MaintenanceMessage
normal.tmpl Шаблон страницы нормальной работы системы. Отображается с момента переключения системы в нормальный режим, до полного введения TESSA в работу NormalMessage
about.tmpl Шаблон страницы о текущем состоянии webbi. Отображается, если webbi запущен в отладочном режиме -

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

Шаблон layout.tmpl определяет основную структуру html страницы и задаёт две области HeadTemplate и BodyTemplate для вставки содержимого каждой конкретной страницей наследником. При этом все наследники автоматически используют базовую структуру страницы (приведена далее схематично).

<!DOCTYPE html>
<html>
  <head>



    ...



    <link rel="stylesheet" href="{{ .BasePath }}assets/main.css" />



    <!--Here goes additional header content for page-->
    {{template "HeadTemplate" .}}
  </head>
  <body>
    <section id="header">
      <div class="page-header">
        <img src="{{ .BasePath }}assets/images/logo.png" />
        <p>{{ .Localize "Title" }}</p>
      </div>
    </section>
    <!--Here goes main body content for page-->
    {{template "BodyTemplate" .}}
  </body>
</html>

Important

Для корректного доступа к статическим ресурсам в ссылках используйте конструкцию, начинающуюся с {{ .BasePath }}, которая позволяет построить корректные пути к ресурсам на отображаемой странице (подробнее о ресурсах).

Как можно видеть, HeadTemplate позволяет внедрить содержимое в область заголовка страницы, например, детализировать название страницы (тег title) и задать дополнительные таблицы стилей (CSS файлы).

Шаблон BodyTemplate позволяет внедрить содержимое тела страницы. При этом видимый пользователю заголовок с логотипом и названием будет присутствовать в верху страницы.

Два этих шаблона, фактически, являются местами для вставки содержимого и определяются в шаблонах каждой конкретной страницы. Определение страницы maintenance.tmpl:

{{define "HeadTemplate"}}
<title>
  {{ .Get "ServerCode" }}
</title>
{{ end }}



{{define "BodyTemplate"}}
<section id="message">
  <!-- Design for IE 11 (desktop client) -->
  <table>
    <tr>
      <td class="td-icons">
        <svg
          class="mes-img"
          xmlns="http://www.w3.org/2000/svg"
          fill="currentColor"
          viewBox="0 0 16 16">
          ...
        </svg>
      </td>
      <td>
        {{ range .Localize "MaintenanceMessage" | paragrapher }}
        <p>{{ . }}</p>
        {{ end }}
      </td>
    </tr>
  </table>
</section>
{{ end }}

Всё содержимое страницы сводится к определению двух шаблонов в формате {{define "Имя шаблона"}} Содержимое шаблона {{ end }}. На странице можно отображать как статическую html разметку, так и локализуемые сообщения и строки.

Important

Для вывода локализованных сообщений на странице используется конструкция {{ range .Localize "Название сообщения или строки локализации" | paragrapher }}<p>{{ . }}</p>{{ end }}. Эта конструкция выводит локализованное сообщение или строку локализации с указанным именем, с учётом переноса строк. Можно использовать сокращённую форму {{ .Localize "Название сообщения или строки локализации" }}, если в локализуемой строке нет переносов строк, поскольку всё содержимое будет выведено в одну строку без учёта форматирования (переносов строк). Таким образом, можно добавлять на страницу любую локализуемую информацию.

Important

Все имена, которые используются в конструкциях вида {{ .Localize "Имя" ... }} должны быть включены либо в список сообщений, либо в список строк локализации, доступных webbi, см. Перевод системы в режим технического обслуживания.

Статические ресурсы страниц

Webbi позволяет страницам использовать статические ресурсы, которые располагаются в директории public основной директории webbi. При написании адреса ресурса на странице, public является корневой директорией (/), адреса всех ресурсов должны быть описаны относительно неё без включения имени самой директории public.

Tip

Рекомендуется все используемые ресурсы располагать в директории assets (ресурсы), группируя их по соответствующим поддиректориям.

Important

Все файлы, расположенные в директории public, будут доступны для скачивания. Размещать файлы в этой директории и её поддиректориях следует тогда, когда присутствует необходимость в этом.

На данный момент директория public содержит только директорию assets (ресурсы), данные в которой сгруппированы согласно их виду и назначению.

Директория Содержимое
icons Иконки и миниатюры изображений
images Полноразмерные изображения

Непосредственно в самой директории assets расположены каскадные таблицы стилей и файл манифеста веб-приложения.

Установка в Windows (IIS)

Для установки webbi в ОС Windows необходимо выполнить следующие шаги:

  • Установить и настроить необходимые модули:
  • Настроить webbi.
  • Настроить веб-приложение TESSA (web).

Important

В Windows webbi работает под управлением IIS.

Установка и настройка модулей

Модуль URL Rewrite добавляет поддержку возможности переопределения запросов для сайта и/или приложения, а Application Request Routing добавляет возможность задействовать обратный прокси сервер при выполнении запроса.

Данная функциональность необходима для переадресации запросов с основного сервера TESSA на webbi при переходе в режим технического обслуживания.

Important

Порядок установки модулей крайне важен. Сначала следует установить URL Rewrite версии 2.1 и лишь затем Application Request Routing версии 3.0, т.к. последний зависит от первого. Установка в другом порядке может привести к неработоспособности связки этих модулей.

Important

Если уже установлены предыдущие версии данных модулей, рекомендуется удалить их и установить указанные версии. В противном случае корректность работы не гарантируется.

Необходимо убедиться, что модули установлены и доступны в диспетчере служб IIS.

Далее необходимо включить модуль Application Request Routing для переадресации запросов. В противном случае переадресация не будет работать. В диспетчере служб IIS необходимо открыть настройки модуля Application Request Routing Cache двойным щелчком левой кнопки мыши.

В открывшемся диалоге в разделе действий в подразделе Proxy необходимо нажать на ссылку Server Proxy Settings....

В открывшемся диалоге установить флаг Enable proxy. Остальные настройки можно оставить без изменений.

Нажать на ссылку Применить, чтобы изменения вступили в силу.

На этом установка и настройка необходимых для IIS модулей завершена.

Настройка webbi

Для удобства управления рекомендуется устанавливать webbi как приложение, работающее под управлением IIS. Этот процесс рассмотрен далее.

Important

Приложение webbi должно работать на том же сервере, где работает веб-приложение TESSA.

Note

При желании, можно установить webbi как службу Windows (подробнее об этом можно прочитать по ссылке, шаг 5). Однако данный вариант установки менее удобен при обслуживании, чем установка webbi как приложения IIS, поэтому здесь он не рассматривается.

Настройка пула приложений

Вначале необходимо создать новый не управляемый пул в Пулах приложений IIS.

Пул должен иметь следующие настройки.

Tip

Если требуется, можно использовать другую схему именования.

Для данного пула рекомендуется использовать ту же учётную запись, которая была задана при установке веб-приложения TESSA (как правило, tessa). Для этого необходимо выделить пул и открыть его Дополнительные параметры.

Чтобы установить учётную запись, нужно нажать на кнопку ....

В открывшемся диалоге выбрать пункт Особая учетная запись, далее нажать на кнопку Установить... и в открывшемся окне указать нужную учетную запись (в формате имя домена\имя учетной записи и пароль). В результате требуемая запись будет установлена:

Tip

Вне зависимости от того, какая конкретная учётная запись привязана к пулу, последовательность шагов по настройке останется такой, как описана далее, с той лишь разницей, что необходимо будет использовать имя установленной учётной записи.

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

  • параметр Режим запуска должен быть равен AlwaysRunning;
  • параметр Тайм-аут простоя (в минутах) должен быть равен 0;
  • параметр Максимальное число рабочих процессов должен быть равен 1 (по умолчанию).

На этом настройка пула завершена.

Настройка доступа к файловой системе

Important

Для переключения запросов к веб-приложению TESSA на webbi необходимо, чтобы у учётной записи, от имени которой работает пул, был доступ на запись к файлу web.config в директории с веб-приложением TESSA.

Необходимо настроить учётной записи, от имени которой работает пул, доступ на запись файла web.config приложения TESSA.

Чтобы определить в какой директории расположено веб-приложение TESSA следует в контекстном меню данного приложения выбрать пункт Управление приложением → Дополнительные параметры.

Базовый путь к приложению указан в значении поля Физический путь. В рассматриваемом случае это C:\inetpub\wwwroot\tessa\web.

В целевой директории необходимо открыть свойства файла web.config.

Перейти на вкладку Безопасность и нажать кнопку Изменить.

В открывшемся окне нажать кнопку Добавить.

В открывшемся окне выбора в поле Размещение выбрать домен или локальную машину и ввести имя учётной записи, от которой запущен пул приложений, в данном примере это tessa. Проверить имя кнопкой Проверить имена.

После проверки имён, имя должно выглядеть как показано на рисунке (имя должно быть подчёркнуто Имя домена или локальной машины\tessa). Далее нажать на кнопку OK в диалоге.

Необходимо предоставить текущей учётной записи полный доступ к файлу и применить изменения, нажав на кнопку OK.

В первом диалоге отображаются установленные разрешения. В нём необходимо нажать кнопку OK и применить изменения.

Теперь у приложения webbi, работающего под управлением соответствующего пула IIS, есть необходимые разрешения, требуемые для включения переадресации запросов на себя, в то время как основное приложение TESSA переведено в режим технического обслуживания и недоступно для пользователей.

Настройка приложения

Самым простым способом создания приложения webbi является копирование соответствующего каталога из архива установки TESSA в целевую директорию, в которой находится директория web (в случае стандартной установки это C:\inetpub\wwwroot\tessa).

Добавление виртуального каталога

Tip

Если директория webbi появилась в менеджере IIS в результате предыдущего шага, добавление виртуального каталога пропускается. Далее выполняется преобразование каталога в приложение.

Если директория webbi не появилась в менеджере IIS, необходимо добавить ссылку на неё. Выбрать директорию tessa в составе сайта (в данном случае Default Web Site) и в контекстном меню выбрать пункт Добавить виртуальный каталог.

Указать имя виртуального каталога webbi и путь, соответствующий директории, который был создан на предыдущем шаге. Применить настройки, нажав на кнопку OK.

Преобразование каталога в приложение

Далее необходимо сделать из каталога приложение. Для этого нужно выбрать каталог и в контекстном меню выбрать пункт Преобразовать в приложение.

В открывшемся диалоге активировать настройку Включить предварительную загрузку и настроить пул приложений на созданный ранее (webbi), нажав на кнопку Выбрать.

В появившемся диалоге выбрать нужный пул webbi и нажать кнопку OK, чтобы подтвердить выбор.

В исходном окне также нажать кнопку OK.

Настройка доступа к управлению переводом в режим технического обслуживания

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

За перевод команды отвечает специальный маршрут switch.

Ограничение осуществляется путём задания списка IP адресов (v4), которым разрешён доступ к команде. По умолчанию, разрешён доступ только с локального компьютера, на котором установлен IIS.

Ниже описывается настройка данного правила.

Необходимо выбрать приложение webbi и далее в группе IIS выбрать модуль Переопределение URL-адресов. Двойным щелчком левой кнопки мыши открыть настройки правил модуля.

Правило для управления доступом называется disable switch. Двойным кликом открыть это правило.

В открывшемся редакторе правила перейти к группе Условия. Для изменения правила фильтрации выбрать первую строку и нажать на кнопку Изменить.

Например, чтобы настроить доступ к команде для клиентов с адресами в диапазоне 195.167.0.100 - 195.167.0.255, помимо дефолтного 127.0.0.1, необходимо в существующее условие добавить регулярное выражение |195.167.0.1\d+. Чтобы проверить правильность регулярного выражения можно использовать встроенный инструмент проверки, для этого нужно нажать на кнопку Проверить. Для завершения настройки и применения нового условия нужно нажать OK.

Tip

В качестве условия выступает регулярное выражение со стандартным синтаксисом.

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

Эту же настройку можно выполнить прямым редактированием файла web.config для webbi.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
    </handlers>
    <!-- В атрибуте arguments указываются аргументы командной строки. -->
    <aspNetCore processPath=".\webbi.exe" arguments="-c app.json" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" forwardWindowsAuthToken="true" requestTimeout="00:10:00" startupTimeLimit="3600" hostingModel="OutOfProcess">
      <environmentVariables>
        <!-- В атрибуте value можно указать номер порта для управляемого IIS приложения. -->
        <environmentVariable name="ASPNETCORE_PORT" value="19857" />
      </environmentVariables>
    </aspNetCore>
    <rewrite>
      <rules>
        <rule name="disable switch" enabled="true" stopProcessing="true">
          <match url="^switch([/\?].*)?$" />
          <action type="CustomResponse" statusCode="403" statusReason="Forbidden: Access is denied." statusDescription="You do not have permission to view this directory or page using the credentials that you supplied." />
          <conditions>
            <!-- В атрибуте pattern указывается список IP адресов с которых разрешён доступ к маршруту /switch для перевода системы в режим технического обслуживания. Список заполняется в виде регулярного выражения. -->
            <add input="{REMOTE_ADDR}" pattern="(::1|127.0.0.1|195.167.0.1\d+)" negate="true" />
          </conditions>
        </rule>
      </rules>
    </rewrite>
  </system.webServer>
</configuration>

Условие со списком разрешённых адресов находится в узле configuration → system.webServer → rewrite → rules → rule (name="disable switch") → conditions → add, атрибут pattern. Поскольку файл открыт после применения правила в графическом пользовательском интерфейсе, соответствующее значение уже содержится в данных атрибута: (::1|127.0.0.1|195.167.0.1\d+).

Следует также обратить внимание на два других важных момента.

Аргументы запуска webbi настраиваются в узле configuration → system.webServer → aspNetCore, атрибут arguments.

Порт для работы webbi под управлением IIS указывается в узле configuration → system.webServer → aspNetCore → environmentVariables → environmentVariable (name="ASPNETCORE_PORT"), атрибут value.

На этом настройку приложения webbi для IIS можно считать завершённой.

Настройка веб-приложения TESSA

В этом разделе описана настройка правил переадресации запросов от приложения TESSA web к webbi при переходе системы в режим технического обслуживания. Каждое правило можно задать в диспетчере IIS в настройках модуля URL Rewrite, так же, как настраивались правила для webbi. Далее рассмотрен второй вариант настройки правил прямым редактированием файла web.config.

Необходимо открыть файл web.config веб-сервиса TESSA. Часть, относящаяся к настройке правил переадресации запросов, находится в узле configuration → system.webServer → rewrite. Перенести её в свой файл. Он должен выглядеть следующим образом.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <system.webServer>
    <!-- Секция с правилами переадресации запросов. Скопируйте её в свой файл web.config -->
    <rewrite>
      <!-- Правила переадресации -->
      <rules>
        <!-- Переадресация запроса проверки работоспособности. -->
        <rule name="MaintenanceHealthCheckRule" enabled="false" stopProcessing="true">
          <match url="^hcheck$" />
          <action type="Rewrite" url="https://localhost/tessa/webbi/hcheck" />
        </rule>



        <!-- Переадресация запросов на доступ к статическим данным страницы со сведениями о режиме технического обслуживания. -->
        <rule name="MaintenanceAssetsRule" enabled="false" stopProcessing="true">
          <match url="^(.*/)?assets/(.*)" />
          <action type="Rewrite" url="https://localhost/tessa/webbi/assets/{R:2}" />
        </rule>



        <!-- Переадресация всех запросов на страницу со сведениями о режиме технического обслуживания. -->
        <rule name="MaintenanceRule" enabled="false" stopProcessing="true">
          <match url="(.*)" />
          <action type="Rewrite" url="https://localhost/tessa/webbi/" />
        </rule>
      </rules>
    </rewrite>
    <!-- Конец секции с правилами переадресации. -->



    <!-- Эта часть должна быть взята из вашего оригинального файла и не требует изменений. Изменения здесь могут повлечь к утрате работоспособности приложения. -->
    <handlers>
      <add name="aspNetCore" path="*" verb="*" modules="AspNetCoreModuleV2" resourceType="Unspecified" />
    </handlers>
    <aspNetCore processPath="%LAUNCHER_PATH%" arguments="%LAUNCHER_ARGS%" stdoutLogEnabled="false" stdoutLogFile=".\logs\stdout" forwardWindowsAuthToken="true" requestTimeout="00:10:00" startupTimeLimit="3600" hostingModel="InProcess">
      <environmentVariables />
    </aspNetCore>
    <httpProtocol>
      <customHeaders>
        <remove name="X-Powered-By" />
      </customHeaders>
    </httpProtocol>
    <security>
      <requestFiltering allowDoubleEscaping="true">
        <requestLimits maxAllowedContentLength="4294967295" maxUrl="10999" maxQueryString="2097151" />
      </requestFiltering>
    </security>
  </system.webServer>
</configuration>

Important

Порядок следования правил в узле rewrite важен! Изменение порядка приведёт к некорректной работе переадресации.

В данном случае задано три правила переадресации.

Правило Описание
MaintenanceHealthCheckRule Переадресация запроса проверки работоспособности. Данное правило является обязательным и не должно меняться. Позволяет определить доступность и нормальное функционирование webbi
MaintenanceAssetsRule Переадресация запросов на доступ к статическим данным страницы со сведениями о режиме технического обслуживания. Как правило, страница с описанием времени осуществления технического обслуживания содержит различные иконки, изображения и CSS стили. Это правило требуется для их корректной загрузки. В противном случае пользователю будет отображён только HTML текст без надлежащего форматирования и других статических ресурсов
MaintenanceRule Переадресация всех запросов на страницу со сведениями о режиме технического обслуживания. Обязательное правило. Должно быть последним в списке правил, т.к. перехватывает все запросы и прекращает дальнейшую обработку правил переадресации

Important

Имена всех правил доступа начинаются с префикса Maintenance, именно он указывается файле в app.json для webbi: Settings → Webbi → MaintenanceConfig → RulePrefix. Если вы выберете иную схему именования, не забудьте поменять указанную настройку в файле app.json для webbi, иначе webbi не сможет переключить правила переадресации запросов.

Important

Во всех правилах переадресации использован базовый адрес https://localhost/. Здесь должно быть указано имя используемого сайта (домена). Например, адрес правила MaintenanceRule https://localhost/tessa/webbi/ для домена tessa.ru должен выглядеть https://tessa.ru/tessa/webbi/. Для всех правил должны быть настроены корректные адреса.

После ручного редактирования управлять правилами переадресации может быть удобнее из диспетчера IIS. Для этого нужно выбрать приложение web, далее в группе IIS выбрать Переопределение URL-адресов и двойным щелчком левой кнопки мыши открыть управление правилами.

Описанные выше правила переадресации выделены рамкой.

На этом настройка поддержки режима техобслуживания для Windows завершена.

Установка в Linux (nginx)

Для обеспечения поддержки работы TESSA в режиме технического обслуживания под управлением nginx необходимо выполнить следующие шаги:

  • Настроить конфигурационные файлы nginx.
  • Настроить работу webbi в качестве сервиса (службы, демона) операционной системы.
  • Настроить доступ к файлу maintenance.switch в директории nginx/conf.d.
  • Настроить доступ к выполнению определённых команд (опционально при выполнении следующего пункта, иначе обязательно).
  • Опционально настроить сервис webbi-reloader, автоматизирующий перезапуск nginx при изменении файла с флагом режима технического обслуживания.

Здесь предполагается, что TESSA и nginx уже установлены и настроены в используемой операционной системе.

Настройка конфигурационных файлов nginx

Настройка конфигурационных файлов nginx необходима, чтобы запросы к веб-сервису TESSA перенаправлялись сервису webbi, когда система переведена в режим технического обслуживания. Необходимо открыть файл конфигурации nginx, который при стандартной установке расположен по пути /etc/nginx/conf.d/default и внести в него правки, чтобы он выглядел примерно следующим образом.

Important

Не следует копировать приведённое содержимое целиком. Необходимо внести изменения в соответствующие части существующего файла, т.к. базовые настройки могут отличаться от приведённых далее, что приведёт к потере работоспособности.

Tip

Рекомендуется вносить правки в том порядке, в котором они указаны далее. ... означает предыдущее (существующее) содержимое файла. Если ... указано до новой части, то новая часть вставляется после существующей, если ... указано после новой части, то новая часть вставляется в файл до существующей части. Нужно найти в файле ближайшую часть текста, что указана и внести соответствующие правки.

# для протокола https
server {
    # maintenance mode switch flag
    include conf.d/maintenance.switch;



    # здесь всё, что было раньше, до блока "location /"
    ...



    location / {
        # Важно, чтобы эта часть была первой, до существующего содержимого!
        # maintenance mode switch
        if ($maintenance = on) {
          rewrite ^(.*)$ / break;
          #send all to webbi
          proxy_pass https://localhost:1020;
          break;
        }



        # здесь всё, что было раньше внутри блока "location /"
        ...



    }



    # новое содержимое
    # route for static resources
    location ~* (.*/assets)/(.+) {
        # maintenance mode switch
        if ($maintenance = on) {
            rewrite /assets/(.+)$ /assets/$1 break;
            proxy_pass https://localhost:1020;
            break;
        }
    }
}



# новое содержимое
# maintenance mode: proxy for webbi
server {
    # если порт уже занят, нужно указать другой
    listen 1020 ssl;
    listen [::]:1020 ssl;



    # ВАЖНО! Используйте те же настройки SSL, что и для базового сервиса
    # Начало блока настроек SSL
    ssl_certificate /etc/pki/tls/certs/localhost.crt;
    ssl_certificate_key /etc/pki/tls/private/localhost.key;



    ssl_protocols TLSv1.2;
    ssl_ciphers HIGH:!aNULL:!MD5;
    # Конец блока настроек SSL



    location / {
        proxy_pass http://localhost:19857;
    }



    location ~* /assets/(.+) {
        proxy_pass http://localhost:19857;
        break;
    }



    location ~* /switch {
        limit_except POST {
            deny all;
        }
        # here you configure allowed IP addresses.
        allow 127.0.0.1;
        deny all;
        proxy_pass http://localhost:19857;
    }
}

Important

Если используются другие настройки для базового сервиса TESSA, их нужно применить. Если при настройке webbi решено использовать другой порт, необходимо внести изменения в настройке прокси сервера для webbi (maintenance mode: proxy for webbi).

Important

webbi должен иметь доступ к файловой системе с настройками для nginx.

Tip

Части, относящиеся к режиму технического обслуживания, помечены в файле комментариями # maintenance.

Tip

Подробнее про создание сертификата и ключа для SSL описано в инструкции по установке TESSA на Linux.

При настройке прав доступа к маршруту /switch необходимо настроить список IP адресов, которым разрешён доступ к этой команде.

Для использования возможностей переадресации запросов в nginx в директории /etc/nginx/conf.d/ требуется создать файл maintenance.switch со следующим содержимым:

set $maintenance off;

Файл содержит признак, находится ли система в режиме технического обслуживания, который используется для переадресации запросов к сервису webbi.

Important

Необходимо изменить настройки доступа к файлу maintenance.switch. Для этого нужно выполнить команду sudo chmod 644 maintenance.switch.

Important

Необходимо изменить владельца файла maintenance.switch, если webbi и/или webbi-reloader работают от имени другого пользователя. Например, для смены владельца на учётную запись tessa необходимо выполнить команду sudo chown tessa maintenance.switch.

Настройка работы webbi в качестве сервиса операционной системы

Первое, что необходимо сделать, это скопировать каталог webbi из директории linux, расположенной в директории основного дистрибутива, в директорию, в которой расположен веб-сервис TESSA. Если выполнялись пункты стандартной инструкции, то базовый путь /home/tessa/tessa/.

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

sudo chmod 755 webbi

Данная команда устанавливает флаг “Исполняемый” для файла webbi.

Important

Если TESSA расположена на одной физической машине, а nginx на другой, то webbi необходимо скопировать на ту машину, на которой установлен nginx. Также в этом случае необходимо скопировать файл app.json из директории web в директорию webbi. Без этого система не будет работать в нужном режиме.

Important

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

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

sudo stat /sbin/init

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

Настройка службы webbi для systemv

Рассмотрим, как настроить службу webbi для системы управления службами systemv.

Необходимо перейти в директорию /etc/init.d/ и создать в ней файл webbi следующего содержимого:

#!/bin/sh
### BEGIN INIT INFO
# Provides:          webbi - platform paired web server for maintenance mode
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Stop/start webbi
### END INIT INFO



PATH=/sbin:/usr/sbin:/bin:/usr/bin



if [ -L $0 ]; then
    SCRIPTNAME=`/bin/readlink -f $0`
else
    SCRIPTNAME=$0
fi



NAME="webbi"
DAEMONUSER="tessa"
DAEMONDIR="/home/$DAEMONUSER/tessa/webbi"
DAEMON="$DAEMONDIR/webbi"
DAEMON_ARGS="-c app.json"
LOGDIR="/home/$DAEMONUSER/tessa/logs/"
LOGFILE="$LOGDIR/webbi.log"
PIDFILE="/var/run/webbi.pid"



# Exit if the package is not installed
[ -x "$DAEMON" ] || exit 0



. /lib/init/vars.sh



. /lib/lsb/init-functions



do_start()
{
    log_daemon_msg "Starging system $NAME daemon"
    su - $DAEMONUSER -c "mkdir -p '$LOGDIR'"
    su - $DAEMONUSER -c "rm -f '$LOGFILE'"
    start-stop-daemon --start --name "$NAME" --user $DAEMONUSER \
        --background --make-pidfile --pidfile "$PIDFILE" \
        --stdout "$LOGFILE" --stderr "$LOGFILE" \
        --chdir "$DAEMONDIR" \
        --exec "$DAEMON" -- $DAEMON_ARGS
    RETVAL="$?"
    log_end_msg $?
    return "$RETVAL"
}



do_stop()
{
    # Return
    #   0 if daemon has been stopped
    #   1 if daemon was already stopped
    #   2 if daemon could not be stopped
    #   other if a failure occurred
    log_daemon_msg "Stopping system $NAME daemon"
    start-stop-daemon --stop --quiet --oknodo --retry=5 --pidfile "$PIDFILE"
    RETVAL="$?"
    log_daemon_msg $?
    rm -f $PIDFILE
    return "$RETVAL"
}



case "$1" in
    start)
        [ "$VERBOSE" != no ] && log_daemon_msg "Starting " "$NAME"
        do_start
        case "$?" in
            0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
            2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
        esac
        ;;
    stop)
        [ "$VERBOSE" != no ] && log_daemon_msg "Stopping " "$NAME"
        do_stop
        case "$?" in
            0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
            2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
        esac
        ;;
  restart)
        log_daemon_msg "Restarting $DESC" "$NAME"
        do_stop
        case "$?" in
            0|1)
                do_start
                case "$?" in
                    0) log_end_msg 0 ;;
                    1) log_end_msg 1 ;; # Old process is still running
                    *) log_end_msg 1 ;; # Failed to start
                esac
                ;;
            *)
                # Failed to stop
                log_end_msg 1
                ;;
        esac
        ;;
    status)
        status_of_proc -p "$PIDFILE" "$DAEMON" "$NAME" && exit 0 || exit $?
        ;;
    *)
        echo "Usage: $SCRIPTNAME {start|stop|restart|status}" >&2
        exit 3
        ;;
esac



exit $RETVAL

Tip

Найти этот файл можно в архиве в директории init.d.

Tip

Для создания и редактирования файла допускается использовать команду sudo nano /etc/init.d/webbi, или команду вызова другого текстового редактора от имени пользователя с повышенными привилегиями.

Important

Переменные скрипта DAEMONUSER, DAEMONDIR, LOGDIR зависят от установки webbi. В случае необходимости запуска от другого пользователя необходимо указать его имя в DAEMONUSER. В случае установки webbi в директорию, отличную от /home/$DAEMONUSER/tessa/, изменить переменные DAEMONDIR, LOGDIR таким образом, чтобы они соответствовали директории установки webbi.

Important

Необходимо ознакомиться с документацией start-stop-daemon для вашей операционной системы. В некоторых версиях вместо двух аргументов --stdout и --stderr используется один --output. В этом случае нужно скорректировать соответствующую часть функции do_start (--stdout "$LOGFILE" --stderr "$LOGFILE" заменить на --output "$LOGFILE").

Необходимо задать права на исполнение данного сервиса.

sudo chmod 755 /etc/init.d/webbi

Добавление сервиса в автозапуск.

  • Наиболее надёжный способ: 
    sudo ln -s /etc/init.d/webbi /etc/rc0.d/S01webbi
  • Если доступна команда chkconfig: 
    sudo chkconfig --add /etc/init.d/webbi
  • Если доступна команда update-rc.d: 
    sudo update-rc.d webbi defaults
  • Если доступна команда rc-update: 
    sudo rc-update add webbi default

Управление сервисом.

  • Запуск: 
    sudo service webbi start
  • Останов: 
    sudo service webbi stop
  • Перезапуск: 
    sudo service webbi restart
  • Получение сведений о текущем состоянии: 
    sudo service webbi status

Настройка службы webbi для systemd

Рассмотрим, как настроить службу webbi для системы управления службами systemd.

В директории /etc/systemd/system/ создать файл webbi.service со следующим содержимым:

[Unit]
Description=Webbi - platform paired web server for maintenance mode



[Service]
WorkingDirectory=/home/tessa/tessa/webbi
ExecStart=/home/tessa/tessa/webbi/webbi -c app.json
Restart=always
RestartSec=10
SyslogIdentifier=webbi
User=tessa



[Install]
WantedBy=multi-user.target

Tip

Этот файл можно найти в архиве в директории systemd.

Important

Переменные файла конфигурации User, WorkingDirectory, ExecStart зависят от установки webbi. В случае необходимости запуска от другого пользователя, необходимо указать его имя в User. В случае установки webbi в директорию, отличную от /home/tessa/tessa/, необходимо изменить переменные WorkingDirectory, ExecStart таким образом, чтобы они соответствовали директории установки webbi.

Настроить автозапуск сервиса webbi и запустить его, выполнив команду:

sudo systemctl enable webbi

Tip

Здесь webbi соответствует имени сервиса webbi.service без расширения .service.

Управление сервисом.

  • Запуск: 
    sudo systemctl start webbi
  • Останов: 
    sudo systemctl stop webbi
  • Перезапуск: 
    sudo systemctl restart webbi
  • Получение сведений о текущем состоянии: 
    sudo systemctl status webbi

Настройка прав доступа к выполнению команд управления nginx

В стандартном режиме работы webbi предполагается, что она сама будет перезапускать nginx командой nginx -s reload после переключения в режим технического обслуживания. В большинстве случаев её выполнение нужно осуществлять от имени пользователя с повышенными правами (команда sudo).

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

sudo visudo

В конец файла добавить строку следующего вида, где tessa - это имя пользователя, от имени которого будет работать webbi (указанное в настройках сервиса).

tessa ALL = (ALL) NOPASSWD: /usr/sbin/nginx

Tip

Если webbi запускается от имени суперпользователя, данных настроек производить не следует. Также необходимо отредактировать строку ReloadCommand в app.json webbi следующим образом: "ReloadCommand": "nginx -s reload".

Note

Если после настройки прав на выполнение команд nginx от имени суперпользователя система продолжает требовать ввод пароля, можно попробовать разрешить запуск nginx без пароля для группы суперпользователей, хотя это и не рекомендуется: 

%sudo ALL=(ALL) NOPASSWD: /usr/sbin/nginx
Если данная настройка также не помогла, необходимо обратиться к руководству операционной системы по настройке запуска команд от имени суперпользователя без ввода пароля.

Настройка сервиса webbi-reloader, автоматизирующего перезапуск nginx

Этот раздел описывает настройку автоматического перезапуска nginx при изменении файла maintenance.switch без участия webbi.

Для автоматического отслеживания изменений в файлах необходимо установить пакет inotify-tools следующей командой:

sudo apt install inotify-tools

Необходимо удалить текст команды перезапуска из файла app.json для webbi: "ReloadCommand":"".

"Settings": {
    "Webbi": {
        "MaintenanceConfig": {
            "Mode": "nginx",
            "Path": "/etc/nginx/conf.d/maintenance.switch",
            "SwitchOn": "set $maintenance on;",
            "SwitchOff": "set $maintenance off;",
            // Здесь пустая строка.
            "ReloadCommand": ""
        }
    }
}

Создать в директории /etc файл nginx-reloader.sh следующего содержания:

#!/bin/bash



watchPath=$1



while true
do
  inotifywait --exclude .swp -e create -e modify -e delete -e move $watchPath
  sudo -n nginx -t
  if [ $? -eq 0 ]
  then
    echo "Detected Nginx config change"
    echo "Executing: nginx -s reload"
    sudo -n nginx -s reload
  fi
done

Tip

Этот файл можно найти в архиве.

Important

Если данный файл будет выполняться от имени суперпользователя, необходимо удалить префиксы sudo -n во всех командах вызова nginx.

Чтобы сделать файл исполняемым, необходимо выполнить следующую команду:

sudo chmod 755 /etc/nginx-reloader.sh

Important

webbi-reloader необходимо настроить для той же системы управления сервисами, для которой настроена TESSA.

Настройка службы webbi-reloader для systemv

Чтобы настроить службу webbi-reloader для системы управления службами systemv, нужно перейти в директорию /etc/init.d/ и создать в ней файл webbi-reloader следующего содержимого:

#!/bin/sh
### BEGIN INIT INFO
# Provides:          webbi nginx maintenance switch file watching and nginx reloading
# Default-Start:     2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Stop/start webbi maintenance watchers
### END INIT INFO



PATH=/sbin:/usr/sbin:/bin:/usr/bin



if [ -L $0 ]; then
    SCRIPTNAME=`/bin/readlink -f $0`
else
    SCRIPTNAME=$0
fi



NAME="webbi-reloader"
DAEMONUSER=tessa
DAEMON="/etc/nginx-reloader.sh"
DAEMON_ARGS="/etc/nginx/conf.d/maintenance.switch"
PIDFILE="/var/run/webbi-reloader.pid"



# Exit if the package is not installed
[ -x "$DAEMON" ] || exit 0



. /lib/init/vars.sh



. /lib/lsb/init-functions



do_start()
{
    log_daemon_msg "Starging system $NAME daemon"
    start-stop-daemon --start --name "$NAME" --user $DAEMONUSER --background --make-pidfile --pidfile "$PIDFILE" --exec "$DAEMON" -- $DAEMON_ARGS
    RETVAL="$?"
    log_end_msg $?
    return "$RETVAL"
}



do_stop()
{
    # Return
    #   0 if daemon has been stopped
    #   1 if daemon was already stopped
    #   2 if daemon could not be stopped
    #   other if a failure occurred
    log_daemon_msg "Stopping system $NAME daemon"
    start-stop-daemon --stop --quiet --oknodo --retry=5 --pidfile "$PIDFILE"
    RETVAL="$?"
    log_daemon_msg $?
    rm -f $PIDFILE
    return "$RETVAL"
}



case "$1" in
    start)
        [ "$VERBOSE" != no ] && log_daemon_msg "Starting " "$NAME"
        do_start
        case "$?" in
            0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
            2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
        esac
        ;;
    stop)
        [ "$VERBOSE" != no ] && log_daemon_msg "Stopping " "$NAME"
        do_stop
        case "$?" in
            0|1) [ "$VERBOSE" != no ] && log_end_msg 0 ;;
            2) [ "$VERBOSE" != no ] && log_end_msg 1 ;;
        esac
        ;;
  restart)
        log_daemon_msg "Restarting $DESC" "$NAME"
        do_stop
        case "$?" in
            0|1)
                do_start
                case "$?" in
                    0) log_end_msg 0 ;;
                    1) log_end_msg 1 ;; # Old process is still running
                    *) log_end_msg 1 ;; # Failed to start
                esac
                ;;
            *)
                # Failed to stop
                log_end_msg 1
                ;;
        esac
        ;;
    status)
        status_of_proc -p "$PIDFILE" "$DAEMON" "$NAME" && exit 0 || exit $?
        ;;
    *)
        echo "Usage: $SCRIPTNAME {start|stop|restart|status}" >&2
        exit 3
        ;;
esac



exit $RETVAL

Tip

Этот файл можно найти в архиве в директории init.d.

Important

В случае необходимости запуска от другого пользователя, необходимо указать его имя в DAEMONUSER. Необходимо учесть, что этот пользователь должен иметь права на чтение директории /etc/nginx/conf.d/ и на перезапуск nginx.

Задать права на исполнение данного сервиса.

sudo chmod 755 /etc/init.d/webbi-reloader

Добавить сервис в автозапуск.

  • Наиболее надёжный способ: 
    sudo ln -s /etc/init.d/webbi-reloader /etc/rc0.d/S01webbi-reloader
  • Если доступна команда chkconfig: 
    sudo chkconfig --add /etc/init.d/webbi-reloader
  • Если доступна команда update-rc.d: 
    sudo update-rc.d webbi-reloader defaults
  • Если доступна команда rc-update: 
    sudo rc-update add webbi-reloader default

Управление сервисом.

  • Запуск: 
    sudo service webbi-reloader start
  • Останов: 
    sudo service webbi-reloader stop
  • Перезапуск: 
    sudo service webbi-reloader restart
  • Получение сведений о текущем состоянии: 
    sudo service webbi-reloader status

Настройка службы webbi-reloader для systemd

Чтобы настроить службу webbi-reloader для системы управления службами systemd, нужно создать в директории /etc/systemd/system/ файл webbi-reloader.service со следующим содержимым:

[Unit]
Description=Webbi nginx maintenance switch watcher



[Service]
ExecStart=/etc/nginx-reloader.sh "/etc/nginx/conf.d/maintenance.switch"
Restart=always
RestartSec=10
SyslogIdentifier=webbi-reloader
User=tessa



[Install]
WantedBy=multi-user.target

Tip

Этот файл можно найти в архиве в директории systemd.

Important

В случае необходимости запуска от другого пользователя, необходимо указать его имя в User. Необходимо учесть, что этот пользователь должен иметь права на чтение директории /etc/nginx/conf.d/ и на перезапуск nginx.

Настроить автозапуск сервиса webbi-reloader и запустить его, выполнив команду:

sudo systemctl enable webbi-reloader

Tip

Здесь webbi-reloader соответствует имени сервиса webbi-reloader.service без расширения .service.

Управление сервисом.

  • Запуск: 
    sudo systemctl start webbi-reloader
  • Останов: 
    sudo systemctl stop webbi-reloader
  • Перезапуск: 
    sudo systemctl restart webbi-reloader
  • Получение сведений о текущем состоянии: 
    sudo systemctl status webbi-reloader

Описание webbi REST API

  • Общие маршруты:

    • GET /info - страница с диагностической информацией, только в режиме отладки;
    • GET /info-json - общие данные о webbi;
    • GET /hcheck - проверка работоспособности.

  • Маршруты режима технического обслуживания:

    • GET /check - проверка возможностей переключения в режим техобслуживания;
    • GET /mode - текущий статус режима техобслуживания;
    • POST /switch - включить/выключить режим техобслуживания;
    • ALL /* - страница с сообщением о техническом обслуживании.

  • Маршруты приёма и обработки команд из внешнего контура, если настройка задана в конфигурационном файле:

    Tip

    В командах далее {management} - строка, заданная в конфигурационном файле.

    Important

    Чтобы webbi смог обработать запросы данной группы, необходимо чтобы парный публичный ключ от приватного ключа, которым подписан передаваемый JWT был известен webbi. В противном случае, запрос будет отклонён, даже если приватный ключ валиден.

    Подробнее об управлении ключами можно прочитать в документации по мониторингу компонентов.

  • Маршруты Redis Explorer:

    • GET /explorer - страница веб-приложения Redis Explorer;
    • POST /explorer/api/login - проверка возможности аутентификации;
    • GET /explorer/api/tree - получить данные для отображения древовидной структуры навигации;
    • GET /explorer/api/view - получить данные представления для узла дерева;
    • DELETE /explorer/api/item - удалить узел или элемент данных представления.

GET /info страница с диагностической информацией

Страница диагностической информации.

Important

Страница доступна только при запуске webbi в режиме отладки.

Ответы

Код Формат Описание
200 text/html Страница диагностической информации
503 text/plain Текст с описанием ошибки

При нормальном выполнении выводится следующая страница:

Поле Описание
Program Имя, версия и дата сборки приложения
Component identifier (CID) Уникальный идентификатор компонента
OS Сведения об операционной системе, под управлением которой работает приложение
Host name Имя компьютера, на котором работает приложение
CPUs count Доступное количество ядер
Server Code Код сервера TESSA, поддержку которого осуществляет приложение
Port Номер порта, используемого приложением
Data refresh interval Интервал обновления данных из Redis
Maintenance Сведения о текущем режиме технического обслуживания: on - включен, off - выключен
Redis state Сведения о текущем состоянии доступности Redis для приложения: Healthy - доступен, Unhealthy - недоступен
Redis initialized Сведения о том, что данные системы в Redis полностью инициализированы: Yes - TESSA установила флаг, что все данные записаны в Redis, No - флаг отсутствует или отличается от ожидаемого
Can publish component info Признак достаточности данных в Redis для публикации webbi информации о себе как о компоненте системы
Work mode Сведения о режиме работы приложения: Standalone - независимая работа, Managed by IIS - работа приложения под управлением IIS
Switching mode Установленный режим работы для переключения правил reverse proxy сервера при переводе системы в состояние технического обслуживания:
- none - режим не задан, webbi не будет переключать настройки reverse proxy;
- iis - задан режим работы IIS, webbi будет переключать правила IIS;
- nginx - задан режим работы nginx, webbi будет переключать правила nginx
Switching rules file is known Признак того, что путь к файлу правил для reverse proxy задан в настройках webbi
Can switch Информация о том, возможно ли переключение системы в режим технического обслуживания
Management enabled Информация о том, что приём внешних команд управления компонентами включен
Management endpoint Информация о пути, по которому будет осуществляться приём внешних команд управления компонентами.
В случае, если приём команд включен, в данном блоке будет выведена ссылка, иначе - текст

Important

Отладочный режим следует использовать только при первичной настройке webbi или при возникновении каких-либо проблем, чтобы не раскрывать чувствительную информацию о системе, делающую её менее безопасной.

GET /info-json общая информация о webbi

Возвращает общую информацию о версии webbi и ОС, на которой осуществлён запуск.

Ответы

Код Формат Описание
200 application/json JSON объект с краткой информацией о webbi
503 text/plain Текст с описанием ошибки

При нормальном выполнении выводится JSON объект со следующей структурой:

Поле Описание
Name Стока с именем программы webbi
Version Строка с номером версии
BuildDate Строка с датой сборки
OS Строка с именем ОС, на которой запущена программа

Пример ответа: 

{
    "Name": "webbi",
    "Version": "4.1 preview",
    "BuildDate": "2024-09-18",
    "OS": "windows"
}

GET /hcheck проверка работоспособности

Возвращает текстовый ответ с состоянием работоспособности приложения.

Ответы

Код Формат Описание
200 text/plain Текущее состояние работы
503 text/plain Текст с описанием ошибки

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

  • Healthy - компонент работоспособен, нормальная работа;
  • Unhealthy - компонент не работоспособен, требуется перезапуск.

Tip

Необходимо использовать этот маршрут для проверок работоспособности компонента типа health check в среде, в которой запускается сервис webbi. Например, systemd в ОС Linux или Docker.

GET /check проверка возможностей переключения в режим техобслуживания

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

Ответы

Код Формат Описание
200 text/plain Результат проверки
503 text/plain Текст с описанием ошибки

При нормальном выполнении выводится строка ok.

GET /mode получить текущий статус режима техобслуживания

Возвращает информацию о текущем статусе режима технического обслуживания.

Ответы

Код Формат Описание
200 application/json JSON объект с информацией о статусе режима технического обслуживания
503 text/plain Текст с описанием ошибки

При нормальном выполнении выводится JSON объект со следующей структурой:

Поле Описание
maintenance Флаг с признаком, находится ли система в режиме технического обслуживания

POST /switch переключение режима техобслуживания

Позволяет перевести систему в режим технического обслуживания и вывести из него.

Параметры

JSON объект следующей структуры в теле запроса:

Поле Описание
maintenance Строка с предписанием в какое состояние необходимо перевести систему:
on - включить режим технического обслуживания
off - выключить режим технического обслуживания
messages JSON объект, поля которого являются именами используемых сообщений в режиме технического обслуживания, а их значения - содержимым этих сообщений. В сообщениях разрешается использовать константы локализации (в форме $LocalizationAlias, тогда это должно быть единственным значением текста сообщения) и плейсхолдеры констант локализации (в форме {$LocalizationAlias}). В форме с плейсхолдерами разрешено включать более одного плейсхолдера и специальных символов форматирования (перенос строк \n и т.п.). Допускается указывать пустое тело сообщения
localization JSON объект, поля которого являются именами констант локализации в формате [<lang>:]<LocalizationAlias>, а их значения - текстом на соответствующем языке. Здесь lang - языковой код в формате ISO 639-1 (например, en для английского, ru для русского и т.п.), LocalizationAlias - имя константы локализации (используемой в сообщениях Messages). Код языка и : может быть опущен, в этом случае константа считается мультиязыковой или универсальной и будет использоваться для локализации любого языка. Таким образом, можно задать одну универсальную константу и, в случае необходимости, задать уточняющие константы для других языков

Important

Обязательным является только поле maintenance.

Ответы

Код Формат Описание
200 text/plain Сообщение об успехе переключения
400 text/plain Текст с описанием ошибки
503 text/plain Текст с описанием ошибки

При нормальном выполнении выводится строка ok.

Important

Поскольку данный маршрут меняет состояние системы, доступ к нему должен быть ограничен в соответствующих настройках reverse proxy. В противном случае работа системы может быть саботирована.

POST /{management} передать команду в доверенный контур

Передаёт команду из внешнего контура в доверенный.

Important

Чтобы webbi смог передать команду в доверенный контур, необходимо чтобы парный публичный ключ от приватного ключа, которым подписана команда, был известен webbi. В противном случае команда будет отклонена, даже если приватный ключ валиден.

Подробнее об управлении ключами можно прочитать в документации по мониторингу компонентов.

Параметры

JWT объект команды в теле запроса.

Ответы

Код Формат Описание
200 application/json JSON объект с идентификаторами целевых компонентов для команды
400 text/plain Текст с описанием ошибки

При нормальном выполнении выводится JSON объект со следующей структурой:

Поле Описание
Targets Массив строк, каждая из которых является идентификатором компонента

GET /{management}?cmd={rq} запрос статуса выполнения переданной команды

Возвращает статус выполнения ранее переданной команды.

Параметры

rq - JWT объект запроса результата выполнения команды следующей структуры.

Поле Описание
ID Строковой идентификатор команды

Important

Запрос должен быть подписан тем же ключом, что и команда, и этот ключ должен быть известен webbi.

Ответы

Код Формат Описание
200 application/json JSON объект с результатами обработки команды
403 text/plain Текст с описанием ошибки

При нормальном выполнении выводится JSON объект со следующей структурой:

Поле Описание
Responses Массив JSON объектов, каждый из которых является результатом обработки команды компонентом

POST /{management}/locks запрос данных о блокировках объектов в системе

Возвращает информацию о наличии в системе блокировок с заданными параметрами.

Параметры

JWT объект со следующей структурой в теле запроса.

Поле Описание
ServerCode Идентификатор кода сервера приложений TESSA, информация по блокировкам которого запрашивается
LockGroups Массив строк с именами групп блокировок. Опциональный

Ответы

Код Формат Описание
200 application/json JSON объект с информацией по блокировкам
403 text/plain Текст с описанием ошибки

При нормальном выполнении выводится JSON объект, ключом которого является имя группы блокировки, а значением - массив идентификаторов заблокированных объектов в этой группе.

DELETE /{management}/locks снять блокировки с объектов в системе

Снимает блокировки с заданных объектов системы.

Параметры

JWT объект со следующей структурой в теле запроса.

Поле Описание
ServerCode Идентификатор кода сервера приложений TESSA, информация по блокировкам которого запрашивается
LockGroups Массив строк с именами групп блокировок. Опциональный
LockIds Массив строк идентификаторов заблокированных объектов. Опциональный

Ответы

Код Формат Описание
200 text/plain Результат выполнения операции
403 text/plain Текст с описанием ошибки

При нормальном выполнении выводится строка ok.

POST /{management}/components получить информацию о компонентах системы

Возвращает информацию о компонентах системы.

Параметры

JWT объект со следующей структурой в теле запроса.

Поле Описание
LoadPlugins Флаг необходимости предоставления информации о плагинах chronos

Ответы

Код Формат Описание
200 application/json JSON объект с описанием компонентов
403 text/plain Текст с описанием ошибки

При нормальном выполнении выводится JSON объект со следующей структурой:

Поле Описание
Components Массив JSON объектов, каждый из которых является описанием компонента
Plugins Массив JSON объектов, каждый из которых является описанием состояния работы плагина chronos
RedisTime Строка, содержащая текущую дату и время Redis

GET /explorer страница веб-приложения Redis Explorer

Выводит главную страницу SPA приложения Redis Explorer.

Ответы

Код Формат Описание
200 text/html Страница с сообщением о техническом обслуживании

При нормальном выполнении выводится страница логина:

POST /explorer/api/login проверка возможности аутентификации

Выполняет проверку аутентификации пользователя с переданными параметрами.

Параметры

JWT токен авторизации в заголовке Authorization.

Ответы

Код Формат Описание
200 text/plain
401 text/plain Текст с описанием ошибки

GET /explorer/api/tree получить данные для отображения древовидной структуры навигации

Возвращает данные для построения дерева навигации в Redis Explorer.

Параметры

JWT токен авторизации в заголовке Authorization.

Ответы

Код Формат Описание
200 application/json JSON объект данных дерева
401 text/plain Текст с описанием ошибки

При нормальном выполнении выводится JSON объект со следующей структурой:

Поле Описание
id Идентификатор узла
name Имя узла
delete Признак допустимости удаления узла
children Массив дочерних узлов

GET /explorer/api/view?id={itemId} получить данные представления для узла дерева

Возвращает данные представления узла с идентификатором itemId в Redis Exploder.

Параметры

JWT токен авторизации в заголовке Authorization.

Ответы

Код Формат Описание
200 application/json JSON объект данных дерева
401 text/plain Текст с описанием ошибки

При нормальном выполнении выводится JSON объект с одной из следующих структур, в зависимости от данных узла:

Поле Описание
message Текст выводимого сообщения
Поле Описание
title Заголовок представления
viewType Идентификатор типа представления
canDelete Флаг допустимости удаления данных представления
dataType Тип данных значения
value Значение
Поле Описание
title Заголовок представления
viewType Идентификатор типа представления
canDelete Флаг допустимости удаления данных представления
cols JSON объект с описанием колонок таблицы
rows Массив JSON объектов строк данных таблицы

DELETE /explorer/api/item удалить узел или элемент данных представления

Удаляет узел или элемент данных представления.

Параметры

JWT токен авторизации в заголовке Authorization. JSON объект запроса удаления данных следующей структуры в теле сообщения:

Поле Описание
id Идентификатор элемента
parentId Идентификатор родительского элемента

Ответы

Код Формат Описание
200 application/json -
400 text/plain Текст с описанием ошибки

ALL /* страница с сообщением о техническом обслуживании

Выводит страницу с сообщением о техническом обслуживании для всех остальных запросов, локализованную для запрашиваемого языка.

Ответы

Код Формат Описание
200 text/html Страница с сообщением о техническом обслуживании

При нормальном выполнении выводится страница:

Режим технического обслуживания

Начиная с версии TESSA 4.0 в системе введена поддержка автоматизированного перехода в режим технического обслуживания и выхода из него.

Эти функции выполняет специальный компонент - веб-сервис webbi (доступен для Windows и Linux), входящий в поставку системы и расположенный рядом с основным web-сервисом TESSA (web), находящимся в одноимённой директории.

Webbi работает постоянно, параллельно и не зависимо от web-сервиса TESSA, принимает и обрабатывает все запросы, адресованные сервису, когда он физически недоступен.

Important

webbi обеспечивает перевод в режим техобслуживания только того веб-сервиса TESSA, ServerCode которого указан в конфигурационном файле.

Если без использования webbi при недоступности web-сервиса TESSA возвращалась ошибка с крайне общим и неконкретизированным описанием “Сервер не отвечает/недоступен”, то с использованием webbi, будет выведена настроенная дизайнером, брендированная для каждого решения, содержащая фирменный логотип, цвета и корпоративный шаблон html страница с информацией о причинах и продолжительности технического обслуживания. Это существенно повышает удобство использования приложений пользователями, их информированность и, как следствие, позволяет уменьшить количество обращений в службу технической поддержки с вопросами о сбое в работе системы. Webbi позволяет оповещать пользователей о проводимых технических работах в штатном режиме.

Important

Работа с webbi должна производиться только по протоколу HTTPS, за что должен отвечать соответствующим образом настроенный reverse proxy (IIS или nginx).

Important

При настройке webbi для работы под управлением IIS для нормальной работы модуля ARR необходимо, чтобы использованный сертификат для SSL был подписан доверенным корневым центром сертификации. В случае локальной разработки - был помещён в соответствующий раздел сертификатов локального компьютера.

Перевод системы в режим технического обслуживания

Для перевода системы в режим технического обслуживания допустимо использовать одну из следующих команд tadmin:

Important

Перед использованием команд перевода системы в режим технического обслуживания рекомендуется выполнить вызов команд диагностики работы webbi.

Команда проверки работоспособности webbi:

curl https://localhost/tessa/webbi/hcheck

При нормальном режиме работы будет выведено healthy.

Команда проверки правильности настроек правил переключения в режим технического обслуживания для reverse proxy:

curl https://localhost/tessa/webbi/check

При нормальном режиме работы будет выведено ok.

Tip

Загрузить последнюю версию curl можно с её официального сайта.

Tip

При использовании самоподписанного сертификата для подавления ошибок curl можно использовать флаг -k или --insecure.

Ниже рассмотрено использование каждой из перечисленных команд.

Important

Для работы команд SendCommand и SendCommandClient требуется наличие соответствующих ключей с правами перевода системы в режим технического обслуживания. При этом приватный ключ должен быть доступен tadmin, а публичный известен webbi.

Important

Для работы команды SendCommandClient также требуется, чтобы в webbi был включен режим приёма внешних команд (Settings → Management → Enable в файле app.json).

Перевод системы в режим технического обслуживания при помощи команды SendCommand

Команда перевода системы в режим технического обслуживания tadmin SendCommand:

tadmin SendCommand Maintenance -k:admin.key -kp:admin -pp:c=switch-on "-pp:m:NormalMessage=$NormalMessage" "-pp:m:MaintenanceMessage={$MaintenanceMessage}\n{$CustomMessage} 15:00 27/02/2023" "-pp:m:MyMessage=Whatever\nI'd like to write\nin multiple\nlines" "-pp:m:A=" -nologo

Используемые аргументы (подробнее здесь):

  • -k - путь к приватному ключу с правами перевода системы в режим технического обслуживания;
  • -kp - пароль от приватного ключа;
  • -pp:c - задаёт выполняемую команду;
  • -pp:m: - позволяет определить сообщения для различных режимов работы, которые могут использоваться на страницах. Аргумент позволяет задать одно и более сообщений в формате <messageName>=<messageText>. Если ничего не указать после =, то тело соответствующего сообщения будет заменено на пустую строку, что (практически) эквивалентно его подавлению при выводе;
  • -nologo - предотвращает отображение сообщения по авторским правам и номеру версии.

Important

В Linux необходимо экранировать символ $ при помощи символа \ (т.е. использовать запись \$) или использовать вместо двойных кавычек (") одинарные ('). Т.к. это влияет на интерпретацию аргументов -m, содержащих конструкции вида $SomeMessageOrLocalizationString. Это же справедливо и для Windows, если в качестве командной строки используется PowerShell.

В результате выполнения команды отобразится текст примерно следующего содержания:

wet-island-DjxdNv OK: Maintenance mode on

Это говорит о нормальном выполнении команды. В случае наличия ошибок будет выведена соответствующая информация.

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

Перевод системы в режим технического обслуживания при помощи команды SendCommandClient

Команда перевода системы в режим технического обслуживания tadmin SendCommandClient:

tadmin SendCommandClient Maintenance -k:admin.key -kp:admin -wa:https://localhost/tessa/webbi -wm:management -wt:42 -pp:c=switch-on "-pp:m:NormalMessage=$NormalMessage" "-pp:m:MaintenanceMessage={$MaintenanceMessage}\n{$CustomMessage} 15:00 27/02/2023" "-pp:m:MyMessage=Watever\nI'd like to write\nin multiple\nlines" "-pp:m:A=" -u:admin -p:admin -nologo

Используемые аргументы (подробнее здесь):

  • -k - путь к приватному ключу с правами перевода системы в режим технического обслуживания;
  • -kp - пароль от приватного ключа;
  • -wa - задаёт адрес сервера webbi;
  • -wm - маршрут, по которому webbi принимает внешние команды;
  • -wt - задаёт таймаут ожидания ответа при выполнении команды;
  • -pp:c - задаёт выполняемую команду;
  • -pp:m: - позволяет определить сообщения для различных режимов работы, которые могут использоваться на страницах. Аргумент позволяет задать одно и более сообщений в формате <messageName>=<messageText>. Если ничего не указать после =, то тело соответствующего сообщения будет заменено на пустую строку, что (практически) эквивалентно его подавлению при выводе;
  • -u, -p - стандартные аргументы для задания пользователя и пароля для доступа к веб-сервису TESSA;
  • -nologo - предотвращает отображение сообщения по авторским правам и номеру версии.

Important

По умолчанию указанная команда выбирает строки локализации из библиотек локализации при помощи сервиса локализации. Поэтому для её выполнения необходим полностью работоспособный веб-сервис TESSA.

Important

В Linux необходимо экранировать символ $ при помощи символа \ (т.е. использовать запись \$) или использовать вместо двойных кавычек (") одинарные ('). Т.к. это влияет на интерпретацию аргументов -m, содержащих конструкции вида $SomeMessageOrLocalizationString. Это же справедливо и для Windows, если в качестве командной строки используется PowerShell.

В результате выполнения команды отобразится текст примерно следующего содержания:

wet-island-DjxdNv OK: Maintenance mode on

Это говорит о нормальном выполнении команды. В случае наличия ошибок будет выведена соответствующая информация.

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

Перевод системы в режим технического обслуживания можно выполнить и без необходимости взаимодействия с веб-сервисом TESSA в, так называемом изолированном или автономном режиме. Для этого используется флаг -pp:i.

tadmin SendCommandClient Maintenance -k:admin.key -kp:admin -wa:https://localhost/tessa/webbi -wm:management -wt:42 -pp:c=switch-on "-pp:m:NormalMessage=$NormalMessage" "-pp:m:MaintenanceMessage={$MaintenanceMessage}\n{$CustomMessage} 15:00 27/02/2023" "-pp:m:MyMessage=Watever\nI'd like to write\nin multiple\nlines" "-pp:m:A=" -pp:i -nologo

В этом случае не требуется указывать параметры подключения к TESSA.

Important

При использовании изолированного режима необходимо, чтобы все строки локализации, использующиеся в сообщениях, были получены из автономных источников. Подробнее об источниках см. далее.

Если необходимо использовать сообщения по умолчанию, что не рекомендуется, т.к. при переводе в режим технического обслуживания хорошим тоном является указание не только причин, но и продолжительности недоступности системы, можно воспользоваться командой в её кратчайшей форме:

tadmin SendCommandClient Maintenance -k:admin.key -kp:admin -wa:https://localhost/tessa/webbi -wm:management -wt:42 -pp:c=switch-on -pp:i -nologo

Important

Все ограничения изолированного режима сохраняются. Шаблоны сообщений считываются из файла app.json утилиты tadmin.

Источники локализации

При переводе системы в режим технического обслуживания для формирования библиотеки локализации, используемой при локализации сообщений, используются следующие источники.

Источник Порядок Описание Класс поставщик данных
Файл app.json утилиты tadmin 10 Строки локализации, расположенные в секции Settings → Maintenance → Localization. Не переопределяют уже имеющиеся в итоговой библиотеке строки ConfigurationMaintenanceLocalizationStrategy
Сервис локализации TESSA 100 Строки локализации, получаемые из стандартных библиотек локализации TESSA. Не используется в изолированном режиме. Не переопределяет уже имеющиеся в итоговой библиотеке строки LocalizationServiceMaintenanceLocalizationStrategy

Рассмотрим данные конфигурационного файла app.json утилиты tadmin, используемые при переводе системы в режим технического обслуживания. Они должны быть расположены в секции Settings → Maintenance.

Поле Описание
Localization.DefaultLanguage Содержит буквенный языковой код (ISO 639-1) для языка, используемого по умолчанию при локализации сообщений. Может отсутствовать, тогда будет использоваться значение en
Localization.Prefix Префикс для поиска строк локализации в библиотеке локализации. Будет присоединён к именам констант локализации, используемых в сообщениях (см. поле Messages). Может отсутствовать, тогда нужно указывать полные имена строк локализации
Messages JSON объект, поля которого являются именами используемых сообщений в режиме технического обслуживания, а их значения - содержимым этих сообщений. В сообщениях разрешается использовать константы локализации (в форме $LocalizationAlias, тогда это должно быть единственным значением текста сообщения) и плейсхолдеры констант локализации (в форме {$LocalizationAlias}). В форме с плейсхолдерами разрешено включать более одного плейсхолдера и специальных символов форматирования (перенос строк \n и т.п.). Допускается указывать пустое тело сообщения
Localization JSON объект, поля которого являются именами констант локализации в формате [<lang>:]<LocalizationAlias>, а их значения - текстом на соответствующем языке. Здесь lang - языковой код в формате ISO 639-1 (например, en для английского, ru для русского и т.п.), LocalizationAlias - имя константы локализации (используемой в сообщениях Messages). Код языка и : может быть опущен, в этом случае константа считается мультиязыковой или универсальной и будет использоваться для локализации любого языка. Таким образом, можно задать одну универсальную константу и, в случае необходимости, задать уточняющие константы для других языков

Рекомендуется, чтобы файл конфигурации был самодостаточным, то есть все константы локализации, используемые для сообщений (Messages) были определены в блоке локализации (Localization).

Пример файла конфигурации.

{
    "Settings": {
        "Maintenance": {
            "Localization.DefaultLanguage": "en",
            "Localization.Prefix": "Common_Maintenance_",
            "Messages": {
                "Title": "$TitleAlias",
                "MaintenanceMessage": "{$HeaderAlias}\n{$Maintenance}",
                "NormalMessage": "{$Normal}"
            },
            "Localization": {
                "TitleAlias": "TESSA - The fastest document management system",
                "ru:TitleAlias": "ТЕССА - Самая быстрая система электронного документооборота",
                "Header": "Attention!",
                "ru:Header": "Внимание!",
                "Maintenance": "Server is under planned maintenance.",
                "ru:Maintenance": "Сервер находится на плановом техническом обслуживании.",
                "Normal": "Server is properly working.",
                "ru:Normal": "Сервер находится в режиме штатной работы."
            }
        }
    }
}

Tip

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

Tip

Перечень зарезервированных сообщений приведён в этом разделе документации.

Можно добавить свой источник локализации, например, из CSV файла и встроить его в указанную цепочку, задав соответствующий порядок.

Чем меньше порядок, тем приоритетнее источник. Также при реализации собственного источника можно управлять возможностью переопределения источником собственных строк локализации в итоговой библиотеке, что позволяет строить гибкие и настраиваемые цепочки.

Important

В изолированном режиме большая часть стандартного API недоступно. Необходимо учитывать это при разработке собственных источников локализации.

Выход из режима технического обслуживания

Для вывода системы из режима технического обслуживания в режим нормального функционирования допустимо использовать одну из следующих команд tadmin:

Вывод системы из режима технического обслуживания при помощи команды SendCommand

Вывод системы из режима технического обслуживания командой tadmin SendCommand:

tadmin SendCommand Maintenance -k:admin.key -kp:admin -pp:c=switch-off -nologo

Используемые аргументы (подробнее здесь):

  • -k - путь к приватному ключу с правами перевода системы в режим технического обслуживания;
  • -kp - пароль от приватного ключа;
  • -pp:c - задаёт выполняемую команду;
  • -nologo - предотвращает отображение сообщения по авторским правам и номеру версии.

В результате выполнения команды отобразится текст примерно следующего содержания:

wet-island-DjxdNv OK: Maintenance mode off

Это говорит о нормальном выполнении команды. В случае наличия ошибок будет выведена соответствующая информация.

Вывод системы из режима технического обслуживания при помощи команды SendCommandClient

Вывод системы из режима технического обслуживания командой tadmin SendCommandClient:

tadmin SendCommandClient Maintenance -k:admin.key -kp:admin -wa:https://localhost/tessa/webbi -wm:management -wt:42 -pp:c=switch-off -nologo

Используемые аргументы (подробнее здесь):

  • -k - путь к приватному ключу с правами перевода системы в режим технического обслуживания;
  • -kp - пароль от приватного ключа;
  • -wa - задаёт адрес сервера webbi;
  • -wm - маршрут, по которому webbi принимает внешние команды;
  • -wt - задаёт таймаут ожидания ответа при выполнении команды;
  • -pp:c - задаёт выполняемую команду;
  • -nologo - предотвращает отображение сообщения по авторским правам и номеру версии.

В результате выполнения команды отобразится текст примерно следующего содержания:

wet-island-DjxdNv OK: Maintenance mode off

Это говорит о нормальном выполнении команды. В случае наличия ошибок будет выведена соответствующая информация.

Приём и обработка команд из внешнего контура

Данный режим работы позволяет использовать webbi как шлюз между внешним и доверенным контурами. По умолчанию, данный режим выключен. Для его включения необходимо установить значение true в поле Settings → Management → Enable конфигурационного файла app.json для webbi. Также можно настроить маршрут для приёма команд в поле Settings → Management → Endpoint.

Important

Часть команд webbi обрабатывает самостоятельно, а часть передаёт для обработки в доверенный контур, подробнее в разделе REST API.

Redis Explorer просмотр и управление данными системы в Redis

TESSA активно использует Redis для хранения своих данных. Для удобства просмотра и управления ими был разработан Redis Explorer. По сути он дополняет возможности Tessa Admin, но в части Redis.

Important

Redis Explorer является административным приложением и доступ к нему также стоит ограничивать средствами reverse proxy.

Поддерживается два режима отображения данных:

  • логический (по умолчанию) - данные группируются в логические узлы, для каждого узла существует представление, могут использоваться данные из БД, если подключение к ней задано;
  • физический - отображаются только ключи Redis, данные для промежуточных узлов отсутствуют, группировка лексикографическая по части пути.

Поскольку управление данными является чувствительной задачей, то доступ ограничивается при помощи аутентификации пользователей.

Для использования Redis Explorer у администратора должен быть действующий приватный ключ со скоупом remote-redis-management, а у webbi парный к нему публичный. В противном случае доступ будет запрещён.

Tip

Для использования Redis Explorer при локальной разработке предназначен ключ -dev, который запустит webbi в режиме Redis Explorer, при этом аутентификация будет отключена, а сразу после запуска будет открыта новая вкладка браузера со страницей Redis Explorer на которой сразу отображён основной экран, минуя экран аутентификации.

При стандартном запуске на странице Redis Explorer будет отображён экран аутентификации.

Для аутентификации необходимо указать приватный ключ и пароль от него.

Tip

Поле выбора приватного ключа поддерживает drag-n-drop, поэтому приватный ключ можно просто “перетащить” в это поле.

Important

Пароль и ключ не запоминаются и не передаются по сети куда-либо, а лишь используются для удостоверения права пользователя на работу с Redis Explorer-ом, т.е. для подписи соответствующего JWT.

В случае наличия ошибок, соответствующая информация будет выведена на в нижней части диалога.

При успешной аутентификации, будет осуществлён переход на основной экран управления данными в режиме отображения логической структуры.

Экран разделён на 3 области:

  1. заголовок с кнопкой выхода Logout;
  2. область навигации по дереву данных с меню доступных действий;
  3. область представления с отображением данных и меню доступных действий.

Tip

При нажатии на кнопку Logout или обновлении страницы средствами браузера или соответствующими горячими клавишами будет произведён выход и возврат к экрану авторизации.

Меню области навигации содержит следующие действия:

  • поиск - для поиска узлов по части имени и фильтрации дерева данных;

    Tip

    Режим поиска и фильтрации активируется после 2-го введённого символа. В случае быстрой печати, поиск активируется после первой значимой паузы (более 0.5 секунды).

  • свернуть всё, кроме текущего узла - сворачивает все узлы дерева, кроме текущего активного узла его предков и потомков;

  • обновить - обновляет данные дерева навигации;
  • удалить - удаляет выбранный узел и все его дочерние узлы;
  • переключение между логическим и физическим представлением.

Меню области представления содержит следующие действия:

  • поиск - для поиска данных по части имени и фильтрации табличных данных;

    Tip

    Режим поиска и фильтрации активируется после 2-го введённого символа. В случае быстрой печати, поиск активируется после первой значимой паузы (более 0.5 секунды).

  • обновить - обновляет данные представления;

  • удалить - удаляет выбранные элементы.

    Tip

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

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

  • выбрать/снять выбор со всех строк - флаг в заголовке таблицы;

    Important

    Выбор осуществляется только для отображаемых на данной странице строк таблицы.

  • выбрать/снять выбор с одной конкретной строки - щелчок левой кнопкой мыши по любому месту строки за исключением колонки с флагом;

  • добавить/убрать выбор со строки - щелчок левой кнопкой мыши по флагу в строке.

При изменении количества отображаемых на странице данных (в случае если данных больше чем отображается), полный выбор станет частичным.

Tip

Количество выбранных строк отображается в левом нижнем углу таблицы.

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

Данные любой ячейки, кроме ячейки с флагами, можно сортировать по возрастанию и убыванию.

Режим отображения физической структуры данных

Режим отображения физической структуры данных предназначен для просмотра ключей в том виде, в котором они хранятся в Redis, без логической группировки данных и их обогащения из БД. Он максимально прост и соответствует представлению любого другого менеджера данных Redis с графическим пользовательским интерфейсом.

Представления для промежуточных узлов отсутствуют.

Никакого дополнительного декодирования данных не производится.

Длинные значения ячеек укорачиваются, при этом у них появляется кнопка открытия диалога с полным текстом ячейки.

Режим отображения логической структуры данных

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

Tip

Так, данные о сессиях пользователей физически хранятся в строковых ключах, но в логическом представлении они сгруппированы в логическом узле session в табличном виде.

В случае задания подключения к БД TESSA, отображаемые данные обогащаются:

  • в представлении сессий выводятся данные о пользователе;
  • в дереве и представлениях операций выводятся не идентификаторы типов, а их имена.

На верхнем уровне внедрены 4 виртуальных узла для группировки всех данных Redis:

  • channels - для отображения каналов, открытых в момент обращения в Redis. Эти данные доступны только в режиме логического представления, поскольку каналы не являются ключами;
  • instances - данные, относящиеся к развёрнутым экземплярам TESSA;
  • monitoring - данные подсистемы мониторинга;
  • others - все остальные данные, как правило неклассифицированные или неполные данные экземпляров, у которых отсутствует ключевой признак initialized.

Узел instances

В данных экземпляров instances отображаются все развёрнутые экземпляры системы.

Tip

Если база данных Redis используется для локальной разработки, то данное представление позволит с лёгкостью удалить все неиспользуемые экземпляры, например, оставшиеся от тестовых запусков.

Узел с именем экземпляра позволяет управлять данными этого экземпляра.

Tip

При локальной разработке и обновлении данных решения, данные в Redis остаются неизменными. Для того, чтобы система при старте сама инициализировала данные в Redis заново, вместо удаления всех ключей, связанных с экземпляром, достаточно удалить ключ initialized.

В узле locks данных экземпляра содержатся данные по всем существующим в системе блокировкам. Можно как посмотреть для каких объектов они взяты, так и снять блокировки целиком или частично.

Tip

В представлении приводится подробная расшифровка по типу и состоянию блокировки.

Tip

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

Узел monitoring

В узле monitoring сгруппированы все данные системы, относящиеся к подсистеме мониторинга.

  • Узел discovery содержит основные данные по компонентам системы, сгруппированные по экземплярам.

    Он содержит следующие узлы:
    • Узел chronos содержит детализированные данные по работе плагинов chronos. Полную информацию можно посмотреть в диалоге детализации, открывающемуся при нажатии на соответствующую иконку в ячейке с данными.
    • Узел components содержит детализированные данные по работе компонентов системы.
    • В случае наличия данных о плагинах (узел chronos), в дерево добавляется виртуальный узел plugins, детализирующий информацию о работе плагинов, собирая её из узлов chronos и components.
    • Узел settings содержит детализированные данные по настройкам работы механизма обновления информации о компонентах.
    • Узел timestamps содержит данные о последнем обновлении каждого из компонентов.
    • Узел tokens содержит служебные данные о токенах компонентов, используемые для обнаружения и устранения коллизий.
  • Узел keys содержит детализированные данные обо всех зарегистрированных в Redis публичных ключах подсистемы мониторинга.
  • Узел scripts содержит детализированные данные о служебных скриптах системы.
Back to top