Использование Redis

В данном разделе рассматривается использование NoSQL СУБД Redis в типовом решении.

Note

Данная СУБД используется в качестве персистентного хранилища данных, данные в котором сохраняются между перезапусками сервера Redis. Этот подход отличается от использования Redis как кэша в оперативной памяти, который очищается при перезапуске сервера.

Note

В процессе обслуживания системы можно остановить все сервисы (web-сервисы, webbi, Chronos и др.), после чего полностью очистить базу Redis. Содержимое будет воссоздано при запуске одним из рабочих процессов web-сервиса по данным в реляционной БД TESSA. Поэтому выполнять резервные копии базы Redis не требуется.

Поскольку сервер Redis может использоваться для хранения данных нескольких экземпляров TESSA, то для разделения данных по экземплярам и их уникальной идентификации каждый ключ начинается с префикса - кода сервера (ServerCode).

Tip

Это не рекомендуется для production-инсталляций, но может использоваться при разработке и тестировании.

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

Например, в ключе формата {serverCode}:locks, {serverCode} является подстановочным значением, а locks - литеральным.

Important

Во всех ключах подстановочная строка {serverCode} содержит код сервера ServerCode.

Important

Для просмотра и управления данными системы в Redis рекомендуется использовать Redis Explorer.

Рассмотрим используемые в системе ключи.

Группа “Техническое обслуживание”

Формат ключа	Тип данных Redis	Описание
{serverCode}:mode	string	Содержит целочисленный код работоспособности системы. Если ключ отсутствует или содержит значение 0 - система работает в нормальном (штатном) режиме. Если ключ содержит значение 1 - система находится на плановом техническом обслуживании. Все пользовательские операции с ней в данный момент недоступны
{serverCode}:messages	hash	Содержит сообщения для отображения пользователю с поддержкой строк локализации. Ключ - имя сообщения. Значение - текст сообщения с поддержкой строк локализации. Пример: Maintenance: {$MaintenanceMessage}\nSome other text.
{serverCode}:localization	hash	Содержит строки локализации для отображения пользователю (в основном в составе сообщений). Ключ - строка формата [{langCode}:]{name}, где {langCode} - код языка в соответствии со стандартом ISO 639; {name} - имя строки локализации. Код языка может отсутствовать, в этом случае строка локализации считается универсальной для всех языков. Значение - текст строки на указанном языке или универсальный текст для всех языков. Пример: Greeting: Hello! ru:Greeting: Привет!

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

Группа “Блокировки объектов”

Все ключи данной группы имеют формат {serverCode}:locks:{objectPrefix}. Здесь:

• locks - зарезервированная часть ключа, обозначающая, что он относится к блокировкам;
• {objectPrefix} - непустой префикс ключа, обозначающий разновидность блокируемых объектов.

Блокировки объектов осуществляются при помощи наиболее общих интерфейсов IObjectLockingStrategy и IObjectTransactionLockingStrategy, первый из которых позволяет проводить базовые операции по взятию и снятию блокировки, второй - учитывает наличие транзакций.

Note

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

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

Формат ключа	Тип данных Redis	Описание
{serverCode}:locks:cards	hash	Содержит информацию по блокировкам карточек системы. Ключ - ID: Guid карточки. Значение - счётчик блокировок и ожиданий. Используется при работе системы с карточками. За работу с блокировками карточек отвечает интерфейс ICardLockingStrategy
{serverCode}:locks:wfe-processes	hash	Содержит информацию по блокировкам процессов Workflow Engine. Ключ - ID: Guid процесса. Значение - счётчик блокировок и ожиданий. Используется при работе системы с Workflow Engine. За работу с блокировками процессов Workflow Engine отвечает интерфейс IWorkflowEngineLockScope
{serverCode}:locks:wfe	hash	Содержит информацию по блокировкам объектов синхронизации Workflow Engine. Ключ - Name: String объекта синзронизации. Значение - счётчик блокировок и ожиданий. Используется при работе системы с Workflow Engine. За работу с блокировками объектов синхронизации Workflow Engine отвечает интерфейс IWorkflowEngineLockScope
{serverCode}:locks:kr-permissions	hash	Содержит информацию по блокировкам правил доступа. Ключ - не важен, всегда используется пустое значение Guid.Empty 00000000-0000-0000-0000-000000000000. Значение - счётчик блокировок и ожиданий. Используется при работе системы с правилами доступа. За работу с блокировками правил доступа отвечает интерфейс IKrPermissionsLockStrategy
{serverCode}:locks:kr-stage-templates	hash	Содержит информацию по блокировкам шаблонов этапов маршрутов и групп шаблонов этапов. Ключ - не важен, всегда используется пустое значение Guid.Empty 00000000-0000-0000-0000-000000000000. Используется при работе системы с маршрутами. За работу с блокировками шаблонов этапов отвечает интерфейс IKrStageTemplateLockStrategy
{serverCode}:locks:acl:{ruleID}	hash	Содержит информацию по блокировкам расчётов ACL для синхронизации параллельных расчётов. {ruleID} - идентификатор правила ACL. Ключ - ID: Guid карточки, для которой производится расчёт правила. Значение - счётчик блокировок и ожиданий. Используется при работе системы с ACL. За работу с блокировками расчётов правил ACL отвечает интерфейс IAclLockStrategy
{serverCode}:locks:nested-roles:{contextID}	hash	Содержит информацию по созданию вложенных ролей. {contextID} - идентификатор контекста создания вложенной роли. Ключ - ID: Guid основной роли. Значение - счётчик блокировок и ожиданий. Используется при работе системы с вложенными ролями. За работу с блокировками создания вложенных ролей отвечает интерфейс INestedRoleLockStrategy
{serverCode}:locks:smart-roles:{generatorID}	hash	Содержит информацию по созданию умных ролей. {generatorID} - идентификатор генератора умной роли. Ключ - ID: Guid владельца умной роли. Значение - счётчик блокировок и ожиданий. Используется при работе системы с умными ролями. За работу с блокировками создания умных ролей отвечает интерфейс ISmartRoleLockStrategy
{serverCode}:locks:user-security"	hash	Содержит информацию по обновлению данных безопасности пользователей. Ключ - ID: Guid пользователя. Значение - счётчик блокировок и ожиданий. Используется при обновлении системой данных о безопасности. За работу с данными о безопасности отвечает интерфейс IUserSecurityLockingStrategy
{serverCode}:locks:forums	hash	Содержит информацию по блокировкам операции отправки уведомлений о новых сообщениях в форумах. Ключ - не важен, всегда используется значение 333EE6B8-6468-4E0E-9AC0-C73DB83919DC. Значение - счётчик блокировок и ожиданий. Используется при отправке уведомлений о новых сообщениях в форумах. За работу с блокировками операций отвечает интерфейс IOperationLockingStrategy
{serverCode}:locks:calendar	hash	Содержит информацию по блокировкам операции пересчёта календаря. Ключ - не важен, всегда используется значение F3BD681E-861D-4820-8FA5-B2443B20DBBA. Значение - счётчик блокировок и ожиданий. Используется при пересчёте календаря. За работу с блокировками операций отвечает интерфейс IOperationLockingStrategy
{serverCode}:locks:roles	hash	Содержит информацию по блокировкам операции пересчёта ролей (в т.ч. пересчёт замещений, расчёт динамических ролей и генераторов метаролей, а также синхронизация AD/LDAP). Ключ - не важен, всегда используется значение DE7D7A67-FA4B-4C80-A7F2-B9E45095F6C8. Значение - счётчик блокировок и ожиданий. Используется при пересчёте состава ролей. За работу с блокировками операций отвечает интерфейс IOperationLockingStrategy
{serverCode}:locks:dashboards:{dashboardTypeID}	hash	Содержит информацию по блокировкам дашбордов. {dashboardTypeID} - идентификатор типа дашборда. Ключ - ID: Guid пользователя. Значение - счётчик блокировок и ожиданий. За работу с блокировками отвечает интерфейс IDashboardLockingStrategy
{serverCode}:locks:normalization	hash	Содержит информацию по блокировкам, используемых при наполнении справочников нормализации. Ключ - ID: Guid идентификатор справочника нормализации. Значение - счётчик блокировок и ожиданий. За работу с блокировками операций отвечает интерфейс INormalizationLockingStrategy
{serverCode}:locks:file-cache	hash	Содержит информацию по блокировкам, которые используются при работе с кэшем файлов. Ключ - не важен, всегда используется значение 730E24FD-52EE-4BFC-9CE0-9DAF3283FABE. Значение - счётчик блокировок и ожиданий. Используется при очистке кэша файлов. За работу с блокировками операций отвечает интерфейс IOperationLockingStrategy
{serverCode}:locks:only-office	hash	Содержит информацию по блокировкам, которые используются при параллельном редактировании OnlyOffice. Ключ - ID: Guid идентификатор операции параллельного редактирования OnlyOffice. Значение - счётчик блокировок и ожиданий. За работу с блокировками отвечает интерфейс IOnlyOfficeLockingStrategy
{serverCode}:locks:file-converter-cache	hash	Содержит информацию по блокировкам, которые используются при записи в кэш конвертации файлов. Ключ - ID: Guid идентификатор версии исходного файла, для которого выполнялась конвертация. Значение - счётчик блокировок и ожиданий. За работу с блокировками отвечает объект FileConverterCache

Вывод установленных блокировок

Для вывода блокировок используются консольные команды tadmin PrintLocks и PrintLocksClient.

Команда tadmin PrintLocks без аргументов напрямую подключится к Redis (строка подключения указана по ключу "Redis" в app.json утилиты tadmin) и выведет все имеющиеся в системе блокировки с указанием вида объектов:

tadmin PrintLocks

cards   bddf302b-ae6e-48f7-b2ea-639113081477
cards   cddf302b-ae6e-48f7-b2ea-639113081478
roles   dddf302b-ae6e-48f7-b2ea-639113081474
roles   eddf302b-ae6e-48f7-b2ea-639113081475
roles   fddf302b-ae6e-48f7-b2ea-639113081476

Tip

Перед вызовом команд, напрямую подключающихся к Redis, необходимо проверить значение настройки "ServerCode" в конфигурационном файле app.json утилиты tadmin, чтобы оно соответствовало аналогичной настройке для сервисов web и chronos.

Или надо передать её значение явно аргументом -sc:server_code.

Чтобы вывести только блокировки по определённым видам объектов, перечислите их аргументами команды (в примере выводятся блокировки по карточкам и ролям):

tadmin PrintLocks cards roles

Также через команду tadmin PrintLocksClient возможно выполнить запрос, используя механизмы управления компонентами посредством Management endpoint сервиса webbi, что подходит для production-инсталляций, где прямое подключение к Redis может быть недоступно для администратора.

tadmin PrintLocksClient -wa:https://tessa-server/webbi -k:path/to/key_file.key -kp:key_password

Note

Если выводится ошибка о том, что система находится в режиме обслуживания, то укажите аргумент -wm:maintenance, содержащий путь до Management endpoint сервиса webbi.

Удаление блокировок

Для удаления блокировок используются команды tadmin DeleteLocks и DeleteLocksClient.

Команда tadmin DeleteLocks без аргументов напрямую подключится к Redis (строка подключения указана по ключу "Redis" в app.json утилиты tadmin) и удалит все имеющиеся в системе блокировки.

tadmin DeleteLocks

Important

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

Удаление блокировок для объектов с определёнными идентификаторами с указанием вида объектов возможно следующим вызовом (в примере удаляются блокировки для карточек с указанными идентификаторами):

tadmin DeleteLocks cards -id:bddf302b-ae6e-48f7-b2ea-639113081477 -id:cddf302b-ae6e-48f7-b2ea-639113081478

Также через команду tadmin DeleteLocksClient возможно выполнить запрос, используя механизмы управления компонентами посредством Management endpoint сервиса webbi, что подходит для production-инсталляций, где прямое подключение к Redis может быть недоступно для администратора.

tadmin DeleteLocksClient -wa:https://tessa-server/webbi -k:path/to/key_file.key -kp:key_password

Note

Если выводится ошибка о том, что система находится в режиме обслуживания, то укажите аргумент -wm:maintenance, содержащий путь до Management endpoint сервиса webbi.

---

Для удаления блокировок также допустимо использование утилиты redis-cli, которая напрямую подключается к Redis и может выполнять на нём любые команды.

Так, если Redis установлен в подсистеме WSL (для ОС Windows) с использованием дистрибутива Ubuntu (установка из Microsoft Store), то очистить все блокировки на карточки из командной строки можно вызовом:

ubuntu run redis-cli DEL tessa:locks:cards

Здесь tessa - значение настройки "ServerCode" из файла app.json для сервисов web и chronos.

Для Linux достаточно вызвать команду без ubuntu run:

redis-cli DEL tessa:locks:cards

Important

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

Для снятия блокировки с определённой карточки по её идентификатору используется вызов в подсистеме WSL, где в кавычках передаётся идентификатор карточки (для каждой карточки - отдельный вызов):

ubuntu run redis-cli HDEL tessa:locks:cards "bddf302b-ae6e-48f7-b2ea-639113081477"

Для Linux достаточно вызвать команду без ubuntu run:

redis-cli HDEL tessa:locks:cards "bddf302b-ae6e-48f7-b2ea-639113081477"

Группа “Активные операции”

Данная группа содержит ключи, относящиеся к выполнению операций, доступных в представлении Администратор -> Служебные -> Активные операции и в API IOperationRepository, плагинами Chronos, рабочими процессами web-сервиса, утилитой tadmin и другими.

Формат ключа	Тип данных Redis	Описание
{serverCode}:operations:progress	hash	Содержит информацию по прогрессу выполнения операции плагинами Chronos, рабочими процессами web-сервиса, утилитой tadmin и другими. Ключ - ID: Guid идентификатор операции. Значение - прогресс выполнения операции, вещественное число в диапазоне [0.0; 100.0]. Используется для отображения прогресса активных операций. За работу с прогрессом операций отвечает интерфейс IOperationProgressStrategy
{serverCode}:operations:queue:{operationTypeID}	sorted set	Содержит информацию о запланированных плагинами Chronos, рабочими процессами web-сервиса, утилитой tadmin и другими операциях. Здесь {operationTypeID} - идентификатор типа операции. Ключ - ID: Guid идентификатор запланированной операции. Счёт (score) - вещественное число двойной точности, содержащее количество миллисекунд, прошедших с 1970-01-01T00:00:00.000Z до времени начала операции и отвечающее за сортировку запланированных операций. Используется для выполнения запланированных операций. За работу с запланированными операциями отвечает интерфейс IOperationQueueStrategy

Группа “Сессии”

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

Формат ключа	Тип данных Redis	Описание
{serverCode}:session:{sessionId}	string	Содержит флаг активности сессии с идентификатором {sessionId}. Управление флагом осуществляет ISessionActivityProvider
{serverCode}:last-activity	hash	Содержит данные о последней активности сессий. Ключ - ID: Guid идентификатор сессии. Значение - дата и время последней активности в формате ISO 8601. Пример: 284ae07a-31db-4cff-9108-ae131daeb8a9: 2023-04-13T09:51:40.9252258Z Используется в плагине SessionsActivityUpdater Chronos. Управление данными о последней активности осуществляет ISessionActivityProvider
{serverCode}:2fa:{attemptId}	string	Содержит данные о попытке входа пользователя в систему и при использовании двухфакторной аутентификации. Управление данными осуществляет ITwoFactorAuthRepository
{serverCode}:2fa:{typeID}:{userID}	string	Содержит информацию о попытке входа пользователя в систему в рамках конкретного типа при использовании двухфакторной аутентификации. Управление данными осуществляет ITwoFactorAuthRepository

Группа “Служебные”

Формат ключа	Тип данных Redis	Описание
{serverCode}:initialized	string	Содержит целочисленный флаг, означающий состояние инициализированности системы. Устанавливается при запуске системы в IRedisInitializer. Если ключ отсутствует - инициализации не производилось и при запуске сервера все необходимые данные будут помещены в Redis. Если ключ содержит значение 0 - система находится в состоянии инициализации. Если ключ содержит значение 1 - система полностью инициализирована. Если ключ содержит любое другое значение - недопустимое значение, ключ нужно удалить
{serverCode}:web-scheduler-cid	string	Содержит уникальный идентификатор компонента системы, который является текущим планировщиком плагинов. Используется при включении обработки плагинов на веб-сервисе (см. раздел Настройка обработки фоновых операций)

Группа “Мониторинг”

Формат ключа	Тип данных Redis	Описание
scripts	hash	Содержит разделяемые lua скрипты для Redis, используемые всеми компонентами системы. Ключ - string имя скрипта. Значение - string текст lua скрипта
keys	hash	Содержит публичные ключи, используемые для подписи отправляемых компонентам команд. Ключ - string - уникальный идентификатор ключа. Значение - string JWT публичного ключа
commands	hash	Содержит команды, отправленные компонентам системы. Ключ - Guid уникальный идентификатор команды. Значение - string JWT команда
commands:{commandID}	hash	Содержит результаты обработки команды с уникальным идентификатором commandID компонентами системы. Ключ - string уникальный идентификатор компонента системы. Значение - string JSON результат обработки команды
discovery:components	hash	Содержит данные о компонентах системы. Ключ - string уникальный идентификатор компонента системы. Значение - string JSON информация о компоненте системы
discovery:timestamps	hash	Содержит данные о последней активности компонентов системы. Ключ - string уникальный идентификатор компонента системы. Значение - long время последней активности компонента, как число секунд стандартного времени UNIX
discovery:tokens	hash	Содержит служебные данные для обнаружения и предотвращения коллизий компонентов системы. Ключ - string уникальный идентификатор компонента системы. Значение - int псевдослучайное число в диапазоне [1000; 10000) получаемое компонентом при его запуске
discovery:settings	hash	Содержит настройки для проведения служебных операций с данными компонентов, например периодической очистки. Ключ - string уникальный идентификатор служебной настройки. Значение - string значение настройки
discovery:chronos	hash	Содержит информацию о состоянии работы плагинов chronos. Ключ - string уникальный идентификатор плагина chronos внутри компонента chronos. Значение - string JSON информация о состоянии работы плагина chronos

Группа “Нормализация”

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

Формат ключа	Тип данных Redis	Описание
{serverCode}:normalization:{dictionaryAlias}	hash	Содержит кэшируемые данные справочника нормализации с алиасом (уникальным именем) {dictionaryAlias}. Ключ - идентификатор справочника (в зависимости от типа ключа, определённого при регистрации справочника, может иметь тип Guid, long или string). Значение - string строковое значение справочника для соответствующего ключа. Пример: 3db19fa0-228a-497f-873a-0250bf0a4ccb: Admin Управление кэшируемыми данными справочников нормализации осуществляет объект RedisNormalizationSource, создаваемый по объекту с настройками RedisNormalizationOptions