Инструкция по развёртыванию модуля Триггеров в Windows: версия 17.Х+

Версия модуля триггеров 17.Х. работает c версией системы 3.23 и выше

1. IIS 8.5.
2. Windows server 2019 и выше.
3. Один из вариантов СУБД:
   • MSSQL (тестировалось на версии 2016 Express Edition+, минимальная версия MSSQL 2019) + Microsoft SQL Server Management Studio (SSMS) соответствующей версии;
   • PostgreSQL версии 13+ (возможна установка на более раннюю версию Postgres, но тогда потребуется вносить правки в код).
4. .net 6 hosting bundle (с версии 17.25 и выше, до версии 17.22 включительно достаточно .net 5).

1. Устанавливаем ОС Windows Server.
2. Устанавливаем СУБД.
3. Устанавливаем Net 6 hosting bundle.
4. Добавляем роль IIS через графическую утилиту «Диспетчер Сервера».
5. Добавляем учетную запись пользователя в Систему, от имени которого будет работать сервис через оснастку «Локальные пользователи и группы».

Начиная с версии 17 система «модуля Триггеров» является многокомпонентной. Каждая компонента должна разворачиваться отдельно.

Версия 17.x может корректно работать только с версиями Системы ADVANTA 3.23 и выше.

• Сайт - это web-приложение, через которое осуществляется администрирование и мониторинг исполнения задач, по обработке событий триггерами. Сайт осуществляет компиляцию триггеров и сборки доступа через API к основной Системе ADVANTA после её обновления. Сайт не обрабатывает события, поэтому его жизненный цикл предусматривает, что он будет периодически выгружаться из пула активных приложений web-сервера, что не приводит к остановке работы модуля Триггеров в целом.
• Движок (Engine) - консольное приложение, которое обрабатывает события Системы ADVANTA, поступающие через шину данных. Подразумевается, что данный модуль работает непрерывно и выгружается, только если произошло обновление основной Системы ADVANTA. При выгрузке модуль отправляет команду restart для управляющего Агента.
• Агент - сервис, который может быть запущен как Windows-service или как консольное приложение. Задача данного сервиса - управлять модулями Engine, развёрнутыми в рамках одного хоста. Агент осуществляет старт Engine-консолей, согласно конфигурации, а также рестарт конкретного Engine, если от него поступила соответствующая команда в результате обновления основной Системы ADVANTA.

1. Открыть оснастку SQL Server Management Studio.
2. Создать новую базу данных. В названии указать любое значение (например triggers).
3. Создать учетную запись для базы данных модуля триггеров.
   
   • В окне «Обозреватель объектов» (Object Explorer) раскрыть «Безопасность» (Security), нажать правой кнопкой мыши на «Имена входа» (Logins) и выбрать «Создать имя» (New Login).
   • В разделе «Общие» (General):
     • В поле «Имя входа» (Login name) ввести любое значение (например triggers). Введённый логин затем понадобится указать на сервере приложения для доступа к базе данных.
     • Ввести пароль учетной записи. Введённый пароль затем понадобится указать на сервере приложения для доступа к базе данных.
     • Выставить опцию «Проверка подлинности SQL Server» (SQL Server authentication).
     • Убрать опцию «Требовать использование политики паролей» (Enforce password policy).
     • Выставить используемый язык «Язык по умолчанию» (Default language), выбрав в выпадающем меню «Русский» (Russian).
     • Выставить используемую базу данных «База данных по умолчанию», выбрав в выпадающем списке меню базу, созданную на шаге 2.1.1.2.
   • Нажать «OK».
4. Открыть созданную учетную запись. Перейти на страницу «Сопоставление пользователей» (User Mapping):
   • В окне «Пользователи, сопоставленные с этим именем входа» (User mapped to this login) в столбце «Схема» (Map) установить галочку напротив базы, созданную на шаге 2.1.1.2.
   • В окне «Членство в роли базы данных для: <выбранная база данных>» (Database role for membership for) выставить права db_owner.
     

1. Открываем pgAdmin.
2. Добавляем пользователя.
3. Создаем новую БД.
4. При первичном развёртывании или обновлении мажорной версии, необходимо обновить схему базы данных. Для этого первый запуск должен выполниться с ключом Adavanta/Database/MigrateOnStartup = true, последующие запуски могут осуществляться с любым значением данного ключа.

1. Открываем утилиту управления IIS «Диспетчер служб IIS».
   
2. Создаем новый пул для приложения:
   • имя - любое;
   • пул приложения - «Без управляемого кода»;
   • режим управляемого конвейера - «Встроенный».
3. После создания пула заходим в «Дополнительные параметры», находим пункт «Удостоверение» и меняем его на использование «Особой учетной записи», в качестве учетной записи используем созданную выше учетную запись пользователя.
4. В этом же окне «Дополнительные параметры» находим пункт «Режим запуска» и выбираем режим «Always running» - необходимо чтобы процесс всегда работал и не завершался при простое (с версии 17.х не актуально).
   
   
5. Создаем новый сайт:
   
   • имя - любое;
   • пул - выбираем только что созданный нами пул приложения;
   • физический путь - выбираем путь, где будет храниться исполняемые файлы приложения;
     
   • привязка - вводим доменное имя сайта.
6. Выбираем в списке сайтов вновь созданный сайт, заходим в контекстное меню и выбираем пункт «Редактировать разрешение», переходим на вкладку «Безопасность» и добавляем туда созданную выше учетную запись пользователя.
7. Заходим в основные настройки сайта и нажимаем «Тест настроек», должно открыться модальное окно, в котором все пункты будут отмечены зелеными индикаторами, говорящие об успешности настройки доступа сайта и файловой системы.

1. Копируем в папку, указанную в настройках сайта, исполняемый файлы из полученного архива с приложением.
2. Открываем файл appsettings.json и находим секцию ConnectionStrings, меняем в ней адрес SQL сервера и название БД.
3. Если необходима диагностика, почему не запускается приложение, необходимо в файле web.config найти секцию aspNetCore и поменять параметр stdoutLogEnabled на true.

Настройки приложения осуществляются в файле appsettings.json. Так как приложение можно запустить в различных конфигурациях, то в проекте несколько файлов типа: appsettings.ConfigurationName.json.

При получении архива для распространения с исполняемыми файлами используется файл с настройками appsettings.json.

WorkingDirectory - относительный или абсолютный путь, по которому будет размещаться рабочая папка. Значение по умолчанию: external (относительный путь).

Данный раздел настраивается в соответствии с правилами ведения журнала в .NET Core.

• RootPath – абсолютный путь по которому будет размещаться папка с логами. По умолчанию полный путь до папки с приложением.
• BasePath – относительный путь до папки, в которой будут создаваться файлы с логами. По умолчанию Logs. Конечный путь до папки с файлами логов будет сформирован объединением путей: [RootPath]\[BasePath].
• LogLevel – набор фильтров сообщений поступающих в лог. Формируется по правилам стандартного логирования в Asp.Net Core. Для полного отключения логов, необходимо внутри данной секции указать параметр “Default”: “None”.

• RuntimeUser - логин и пароль пользователя, от чьего имени будут вестись запросы в API Системы ADVANTA при исполнении триггеров (параметры Login и Password соответственно). Под этим пользователем, через API так же осуществляется запрос на извлечение данных о типах объектов.
• Host - URL адрес сервера для осуществления запросов в API Системы ADVANTA.
  
• ObjectsSyncTimeout - период синхронизации типов объектов с Системой ADVANTA. Задаётся в минутах. Параметр необязательный. Значение по умолчанию 15 (т.е. раз в 15 минут).
• ApiRequestTimeout - период ожидания ответа SOAP API Системы ADVANTA. Задаётся в секундах. Параметр необязательный. Если параметр не задан или его значение равно 0, то будет использовано значение по умолчанию равное 3600 (т.е. 3600 секунд, что равно одному часу).

• Emails - список почтовых адресов, на которые необходимо рассылать уведомления о перезапуске или сбое в работе триггеров. Список необходимо указать через любой из разделителей: запятая, точка с запятой, пробел.

Содержит настройки smtpсервера для отправки e-mail уведомлений:

• Address - адрес smtp сервера;
• Login - логин (e-mail) отправителя;
• Password - пароль отправителя;
• Port - номер порта, если требуется;
• UseSSL - требование использовать SSL (true/false) по умолчанию false.

В данном разделе указываются параметры подключения к Базе данных Системы ADVANTA к шине обмена сообщениями Rebus. Вид транспорта и строка подключения к БД ConnectionString должны быть идентичны параметрам, используемым в настройках Системы ADVANTA.

    "Rebus": {
      //Варианты транспорта: "MSSQL", "PostgreSql"
      "Transport": "PostgreSql",
 
      // пример строки подключения для транспорта "MSSQL"
      //"ConnectionString": "Data Source = SqlServerName;Database=AdvantaRebus;Trusted_Connection=True;MultipleActiveResultSets=true", 
 
      // пример строки подключения для транспорта "PostgreSql"
      "ConnectionString": "User ID=username;Password=userpwd;Host=localhost;Port=5432;Database=AdvantaRebus;", 
 
      "InputQueueName": "bus_triggers_queue", // "Bus_TriggersInputQueue" - для транспорта "MSSQL"
      "SubscriptionsTableName": "Bus_TriggersInputQueue_Subscriptions"
      "PostgreSqlMessagesTableName": "bus_triggersinputqueue" //используется только для транспорта "PostgreSql"
    }

• Transport - тип транспорта для Rebus шины сообщений. Возможные варианты: «MSSQL» и «PostgreSql». Если параметр не указан или пустой, то по умолчанию используется значение «MSSQL». Возможен так же вариант «Emulator» - используется для запуска приложения без привязки к rebus.
• ConnectionString - строка подключения к базе данных, через которую публикуются сообщения rebus.
• InputQueueName - название очереди сообщений (канала), через которую будут поступать сообщения для данного instans-а. Для MSSQL по умолчанию будет «Bus_TriggersInputQueue», для PostgreSql по умолчанию будет bus_triggers_queue.
• SubscriptionsTableName - название таблицы БД, в которую будет размещена информация о подписках. По умолчанию будет "Bus_TriggersInputQueue_Subscriptions"(должно совпадать с настройками публикующего сервиса).
• PostgreSqlMessagesTableName - название таблицы БД, через которую будет вестись обмен сообщениями в случае "PostgreSql" транспорта. По умолчанию будет использоваться "bus_triggersinputqueue" (должно совпадать с настройками публикующего сервиса). Для MSSQL параметр игнорируется, так как для MSSQL Rebus использует (и при необходимости создаёт) таблицу с именем, совпадающим с названием входящей очереди сообщений (InputQueueName).

В этом разделе указываются настройки подключения к собственной служебной Базе данных модуля Триггеров, отдельной от БД Системы ADVANTA.

  "Database": {
    //Варианты провайдеров: "MSSQL", "PostgreSql"
    "Provider": "PostgreSql",
 
    // пример строки подключения для провайдера "MSSQL"
    //"ConnectionString": "Data Source = SqlServerName;Database=AdvantaTriggers;Trusted_Connection=True;MultipleActiveResultSets=true",
 
    // пример строки подключения для провайдера "PostgreSql"
    "ConnectionString": "User ID=username;Password=userpassword;Host=localhost;Port=5432;Database=AdvataTriggers;",
    "MigrateOnStartup": "true"
  },

• Provider - определяет тип СУБД, используемой для модуля триггеры. Возможные варианты: «MSSQL» и «PostgreSql». Если параметр не указан или пустой, то по умолчанию используется значение «MSSQL». Возможен так же вариант «Memory» - в этом варианте СУБД использоваться не будет, а все будет храниться в памяти до завершения работы приложения. Данный режим удобно использовать в процессе разработки и тестирования.
• ConnectionString - строка подключения к базе данных, в которой размещаются триггеры.
• MigrateOnStartup - признак автоматической миграции структуры базы данных. Принимаемые значения true или false. Параметр необязательный. Значение по умолчанию false.

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

• InstanceName - наименование запускаемого инстанса модуля Триггеры. Данное наименование добавляется к логам и в тему e-mail уведомлений.

• Address – адрес сервера Vault, обязательный параметр. Пример значения: https:⁄⁄vault.yourcompany.ru:8200.
• RoleId – Bдентификатор (GUID) роли, обязательный параметр. Пример значения: «b52f920d-dccf-76ad-e7e0-a2d3eb23abc3».
• SecretId – Идентификатор (GUID) секрета, обязательный параметр. Пример значения: «cfa2b4f6-4a92-5ec3-5253-acf5a026ddec».
• Version – версия контейнера. Возможные варианты: «V1» или «V2», обязательный параметр.
• MountPoint – точка монтирования контейнера секретов, обязательный параметр. Пример значения: «kv-v2».
• Path – путь к секретам, обязательный параметр. Пример значения: dbPasswords.

Ссылка на секрет в Vault могут прописываться для любых значений строковых параметров в любых разделах файла конфигурации (кроме раздела HashiCorpVault) в формате: {$your_hashicorp_vault_key$}.

Пример для параметра: ConnectionString: {$triggers_db_connection$}.

1. Исполняемые файлы публикуются в подпапку Agent после публикации. Содержимое папки может быть перенесено в любую другую папку хоста.
2. По умолчанию агент сконфигурирован как windows service, для развёртывания агента как службы можно воспользоваться инструкцией компании Microsoft. Для запуска агента в консольном режиме необходимо запустить приложение Advanta.Triggers.Agent с ключом -console.
3. При старте агент будет пытаться запустить все экземпляры движков, перечисленные в разделе ModulesPaths файла appsettings.json.

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

Данный раздел настраивается в соответствии с правилами ведения журнала в .NET Core.

• RootPath - абсолютный путь по которому будет размещаться папка с логами. По умолчанию полный путь до папки с приложением.
• BasePath - относительный путь до папки, в которой будут создаваться файлы с логами. По умолчанию Logs. Конечный путь до папки с файлами логов будет сформирован объединением путей: [RootPath]\[BasePath]
• LogLevel - набор фильтров сообщений поступающих в лог. Формируется по правилам стандартного логирования в Asp.Net Core. Для полного отключения логов, необходимо внутри данной секции указать параметр Default: None.

• ModulesPaths - массив относительных или абсолютных путей, по которым размещаются рабочие папки управляемых Engine модулей.

Данный раздел файла appsettings.json мониторится агентом динамически, поэтому пути до управляемых Engine могут быть прописаны как до старта, так и после старта агента. При добавлении очередного пути, агент пытается определить есть ли Engine по этому пути. Если есть, то определяет стартовал ли Engine, если нет, то стартует его.

При удалении пути агент посылает соответствующему Engine модулю команду shutdown.

Для получения информации по текущему состоянию агента, необходимо в папку агента положить файл status без расширения. Содержимое файла не читается. После того как агент обнаружит файл, он сформирует информацию о текущем состоянии движков и создаст или обновит файл output.txt. Информация о статусе так же будет записана в лог. Файл status будет автоматически удалён.

1. Исполняемые файлы публикуются в подпапку Engine после публикации. Содержимое папки может быть перенесено в любую другую папку хоста.
2. Движок должен располагаться на том же хосте, что и сайт.
3. Движок может быть запущен вручную либо передан под управление агенту.
4. Одному сайту должен соответствовать один экземпляр работающего движка.

Настройки приложения осуществляются в файле appsettings.json. Так как приложение можно запустить в различных конфигурациях, то в проекте несколько файлов типа: appsettings.ConfigurationName.json.

При получении архива для распространения с исполняемыми файлами используется файл с настройками appsettings.json.

Для запуска движка необходимо использовать те же настройки appsettings.json, которые используются для запуска сайта.

Отличаться может только раздел Logging. В противном случае движок и сайт не смогут найти друг друга в процессе инициализации канала коммуникации по UDP протоколу.