Сервис бандлирования статического контента

PDF
Сложный

Статический контент — *.js-файлы и *.css-файлы, которые находятся в файловой системе Creatio и используются для отображения интерфейса приложения в браузере. *.js-файлы могут содержать код клиентских модулей или другую информацию в виде JavaScript-кода. Статический контент имеет ряд особенностей, которые описаны в статье Файловый контент пакетов. По умолчанию использование статического контента в приложении включено, что позволяет повысить производительность приложения.

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

Способы оптимизации времени загрузки страницы приложения:

  • Минификация — уменьшает размер *.css, *.js и *.html-файлов. В процессе сжатия все комментарии к коду, переносы строк, лишние отступы и пробелы удаляются. Уменьшает размер исходного файла на 10-20 %.
  • Бандлирование (генерация bundle-файлов) — оптимизирует работу приложения путем объединения всех однотипных файлов статического контента в один bundle-файл. Уменьшает количество запросов страницы.

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

Составляющие сервиса бандлирования:

  • ContentService — сервис, который взаимодействует с файлами приложения Creatio для выполнения минификации и бандлирования. Размещается независимо от приложения Creatio.
  • ContentWatcher — утилита, которая взаимодействует с файлами приложения Creatio и с ContentService для обеспечения своевременности выполнения минификации и бандлирования.

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

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

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

Требования для корректной работы сервиса бандлирования:

  • Бесперебойная работа ContentService и ContentWatcher.
  • Наличие у ContentService и ContentWatcher доступа к статическому контенту.
  • Возможность доступа из ContentService к ContentWatcher по протоколу HTTP.
  • Корректная настройка конфигурации ContentService и ContentWatcher.

Для приложений, развернутых on-site, необходимо выполнить предварительную настройку сервиса. Для cloud-приложений сервис бандлирования настроен по умолчанию.

ContentService 

ContentService — сервис, который взаимодействует с файлами приложения Creatio для выполнения минификации и бандлирования статического контента. Размещается независимо от приложения Creatio.

Конечные точки ContentService 

Конечные точки ContentService
Конечная точка
Описание
Метод
/
Проверка работоспособности сервиса бандлирования.
GET
/process-content
Основная конечная точка. Включает генерацию минифицированных bundle-файлов. Изменяет конфигурационный файл _ContentBootstrap.js.
POST
/clear-bundles
Отключает генерацию минифицированных bundle-файлов и удаляет bundle-файлы. Изменяет конфигурационный файл _ContentBootstrap.js.
POST
/minify-content
Минифицирует статический контент.
POST

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

Конечная точка / не принимает параметров. Другие конечные точки принимают различные параметры, которые передаются в теле запроса в формате JSON.

Параметры конечных точек ContentService
Параметр
Конечные точки
Описание
ContentPath required Все конечные точки. Путь к каталогу со статическим контентом.
OutputPath Все конечные точки.

Путь к каталогу, в который сохраняются сгенерированные сервисом бандлирования файлы (например, bundle-файлы).

  • Для конечной точки /minify-content значение текущего параметра соответствует значению параметра ContentPath.
  • Для конечных точек /process-content и /clear-bundles значение текущего параметра соответствует значению параметра ContentPath, к которому добавлен суффикс /bundles.
SchemasBundlesRequireUrl /process-content URL, который используется в конфигурационном файле RequireJs для загрузки браузером бандлированных и/или минифицированных файлов. Обязательный параметр при изменении значения по умолчанию параметра OutputPath на другое значение.
MinifyJs /process-content Флаг, который указывает на необходимость выполнения минификации *.js-файлов. По умолчанию — true.
MinifyConfigs /process-content Флаг, который указывает на необходимость выполнения минификации сгенерированных конфигурационных файлов RequireJs. По умолчанию — true.
ApplyBundlesForSchemas /process-content Флаг, который указывает на необходимость выполнения бандлирования *.js-файлов статического контента схем. По умолчанию — true.
ApplyBundlesForResources /process-content Флаг, который указывает на необходимость выполнения бандлирования *.js-файлов ресурсов схем. По умолчанию — true.
Force /clear-bundles Флаг, который указывает на необходимость удаления bundle-файлов. По умолчанию — false (конфигурирует Creatio на использование небандлированного статического контента).

Настройка ContentService 

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

Настройки ContentService
Настройка
Описание
Logging Управление уровнями логирования.
UseParallelism Управление параллелизмом. По умолчанию — false.
UseCancellation Управление автоматической отменой операций.
ShutdownFinalizationDelay Управление временем (в миллисекундах) дополнительного ожидания для безопасного завершения сервиса бандлирования.
BundleGeneration Управление бандлированием. Содержит настройки DictionaryPath, IgnoredFileNamePatterns, BundleMinLength.
DictionaryPath Путь к словарю. Настройка содержится в блоке BundleGeneration.
IgnoredFileNamePatterns Управление игнорированием файлов. Настройка содержится в блоке BundleGeneration.
BundleMinLength Пороговое значение размера (в количестве символов/байтах) создаваемого bundle-файла. Если размер bundle-файла при выполнении бандлирования превысил указанное значение, то его генерация прекращается и создается следующий bundle-файл. По умолчанию — 204800 (генерирует bundle-файлы размером 200-250 Кбайт). Настройка содержится в блоке BundleGeneration.
InfluxDbConnectionString Строка подключения к InfluxDb. Подробнее читайте в Метрики InfluxDb.
InfluxDbConnectionTimeout Таймаут (в миллисекундах) подключения к InfluxDb. По умолчанию — 5000.

Параллелизм используется для ускорения минификации и бандлирования. За использование параллелизма отвечает настройка UseParallelism. Если параллелизм включен, то операции обработки файлов разбиваются на независимые блоки. В зависимости от инфраструктуры это позволяет значительно ускорить работу сервиса бандлирования. Параллелизм значительно увеличивает нагрузку на CPU, а также на сеть и/или дисковую подсистему.

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

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

При стандартной остановке (например, по нажатию Ctrl + C в консоли или остановке пула через IIS) сервис бандлирования прекращает получение новых запросов, а также пытается безопасно завершить уже начатую обработку. Вариант безопасного завершения, который использует сервис, зависит от значения настройки UseCancellation.

Варианты безопасного завершения:

  • Если включена настройка UseCancellation, то прекращается выполнение задач, которые возможно отменить.
  • Если отключена настройка UseCancellation или выполнение задачи отменить невозможно, то ожидается выполнение начатых задач.

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

Словарь — порядок выполнения бандлирования схем. Используется для оптимизации формирования bundle-файлов. Схемы, которые отсутствуют в словаре, попадают в bundle-файлы в алфавитном порядке. Путь к файлу BundlesDictionary.txt словаря указывается в настройке DictionaryPath блока BundleGeneration. Файл BundlesDictionary.txt предварительно генерируется и поставляется вместе с ContentService. Для приложений, которые были значительно кастомизированы, рекомендуется сгенерировать пользовательский словарь.

Чтобы сгенерировать пользовательский словарь:

  1. Скачайте *.zip-архив с утилитой FileListGetter. *.zip-архив доступен по ссылке. Обратите внимание, что для работы утилиты необходим пакет .NET Framework версии 4.7.2 или выше в приложении, для которого планируется сгенерировать пользовательский словарь.
  2. Откройте страницу приложения, для которой планируется сгенерировать словарь.
  3. Откройте инструменты разработчика и перейдите на вкладку Network. Подробнее об инструментах разработчика читайте в статье Front-end отладка.
  4. Обновите страницу для загрузки файлов статического контента.
  5. Нажмите правой кнопкой мыши на области загруженных файлов и сохраните *.har-файл в каталог HarFiles утилиты FileListGetter.
  6. Повторите шаги 1-4 для всех страниц приложения, для которых планируется сгенерировать словарь.
  7. Скопируйте файл BundlesDictionary.txt в каталог Output утилиты FileListGetter.
  8. Запустите файл утилиты FileListGetter.exe.

В результате файл BundlesDictionary.txt каталога Output содержит пользовательский словарь.

Игнорирование файлов позволяет определить файлы, которые не должны учитываться при выполнении бандлирования. За игнорирование файлов отвечает настройка IgnoredFileNamePatterns блока BundleGeneration.

Файлы, которые необходимо игнорировать при бандлировании:

  • Файлы статического контента, которые не являются корректными RequireJS-модулями. Для этих файлов не реализована возможность загрузки браузером из bundle-файлов.
  • Конфигурационные файлы статического контента, которые загружаются особенным образом и не должны попадать в bundle-файлы.

ContentWatcher 

ContentWatcher — утилита, которая взаимодействует с файлами приложения Creatio и с ContentService для обеспечения своевременности выполнения минификации и бандлирования.

Действия, которые выполняет ContentWatcher:

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

ContentWatcher отслеживает изменения файла _MetaInfo.json, который изменяется в момент изменения статического контента. После этого ContentWatcher отправляет ContentService уведомление о необходимости выполнения бандлирования. ContentWatcher может отслеживать изменения любых файлов и отправлять уведомление по любому URL. Для корректной работы связки Creatio — ContentWatcherContentService необходимо выполнить конфигурирование ContentWatcher.

ContentWatcher позволяет отслеживать нескольких приложений Creatio.

Настройки ContentWatcher
Настройка
Описание
Общие настройки
ContentServiceUrl required

URL конечной точки для вызова при обнаружении изменений. Используйте шаблон URL-адреса конечной точки, который представлен ниже.

Шаблон URL-адреса конечной точки
http://[Адрес ContentService]/process-content
DefaultFileFilter Паттерн для фильтрации файлов, изменения которых планируется отслеживать. По умолчанию — _MetaInfo.json. Используется, если для приложения Creatio не указана настройка FileFilter.
ConfigurationRefreshInterval Длительность интервала (в миллисекундах), с которым сервис бандлирования считывает настройки для приложений Creatio. По умолчанию — 300000, что эквивалентно пяти часам. При обнаружении изменений в настройках для сайтов эти изменения применяются без прерывания работы ContentWatcher.
InfluxDbConnectionString Строка подключения к InfluxDb. Подробнее читайте в Метрики InfluxDb.
InfluxDbConnectionTimeout Таймаут (в миллисекундах) подключения к InfluxDb. По умолчанию — 5000.
Настройки для on-site приложения
ContentWorkers required Блок настроек для каждого приложения Creatio, которое обслуживает ContentWatcher.
Name required Пользовательское название, которое может использоваться для определения текущего приложения Creatio в логах.
Directory required Путь к каталогу, изменения в котором необходимо отслеживать. Т. е. путь к каталогу \conf текущего приложения Creatio, который содержит файл _MetaInfo.json.
FileFilter Паттерн для фильтрации файлов, изменения которых планируется отслеживать. Не используется, если для приложения Creatio указана настройка DefaultFileFilter.
ContentWorkerArguments required Параметры в формате "ключ-значение", которые необходимо передавать в ContentService при обнаружении изменений. Для корректной работы ContentService укажите объект с ключом СontentPath и значением, в котором указан путь к каталогу \conf\content.

 

Если ContentWatcher и ContentService разворачиваются на Linux (в том числе в Docker) и файловая система Creatio встраивается в файловую систему ContentWatcher и ContentService , то в настройках Directory и СontentPath укажите пути к каталогам, в которые встроена файловая система Creatio. Например, если каталог \conf приложения Creatio встроен в контейнер по пути /app/content/, то в настройке Directory укажите /app/content/, а в настройке СontentPath/app/content/content.

Пример конфигурационного файла (on-site приложение)
{
    "ContentServiceUrl": "http://host.docker.internal:29572/process-content",
    "ConfigurationRefreshInterval": "86400000",
    "DefaultFileFilter": "_MetaInfo.json",
    "ContentWorkers": [
        {
            "Name": "Site 1",
            "Directory": "/path_to_creatio_conf_folder/",
            "ContentWorkerArguments": [
                {
                    "key": "ContentPath",
                    "value": "/path_to_creatio_conf_folder/content"
                }
            ]
        }
    ]
}

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

Метрики InfluxDb 

ContentWatcher и ContentService позволяют записывать метрики успешных и неуспешных операций в InfluxDb. Документация InfluxDb доступна на официальном сайте InfluxDb. Соединение с InfluxDb настраивается в файле appsettings.json с помощью значений параметров строки подключения InfluxDbConnectionString.

Пример строки подключения InfluxDbConnectionString
"InfluxDbConnectionString": "url=http://1.2.3.4:5678; db=content; user=User1; password=QwErTy; version=v_1_3"

Параметры строки подключения InfluxDbConnectionString представлены в таблице ниже.

Параметры строки подключения InfluxDbConnectionString
Настройка
Описание
url required Адрес сервера InfluxDb.
db Имя базы данных, в которую планируется записывать метрики. По умолчанию — content.
user Имя пользователя для соединения с сервером InfluxDb. По умолчанию — пустая строка.
password Пароль для соединения с сервером InfluxDb. По умолчанию — пустая строка.
version Версия сервера InfluxDb. По умолчанию — Latest. Возможные значения: Latest, v_1_3, v_1_0_0, v_0_9_6, v_0_9_5, v_0_9_2, v_0_8_x.

Метрики InfluxDb, которые записывают ContentService и ContentWatcher, представлены в таблице ниже.

Метрики InfluxDb
Метрика
Описание
Метрики, которые записывает ContentService
service_processing_duration Длительность обработки контента.
service_error Ошибки, которые получены при выполнении бандлирования, удалении временных каталогов, очистке bundle-файлов.
Метрики, которые записывает ContentWatcher
watcher_notifying_duration Длительность оповещения ContentService.
watcher_error Ошибки, которые получены при загрузке настроек, мониторинге, оповещении ContentService.

Развернуть сервис бандлирования статического контента 

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

Для разворачивания сервиса бандлирования необходим сервер под управлением Linux OS (рекомендуем использовать стабильные версии Ubuntu или Debian), с установленной и настроенной стабильной версией Docker. С этого сервера необходимо разрешить выполнение запросов к хранилищу образов Docker Hub. Сервер служит хост-машиной для составляющих сервиса бандлирования.

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

  1. Скачайте *.zip-архив с файлами конфигурации сервисов. *.zip-архив доступен по ссылке.
  2. Разархивируйте архив в произвольный каталог (например, \opt\services).

    Структура конфигурации сервисов:

    • \etc\content-watcher\appsettings.json — конфигурационный файл ContentWatcher.
    • docker-compose.yml — конфигурационный файл утилиты docker-compose.
    • *.env — файл с переменными окружения для запуска компонентов.
  3. В файле .\docker-compose\*.env укажите параметры:

    • ContentServicePort — порт, на котором будет работать ContentService.
    • ContentPath — каталог с сайтами/контентом сайтов, который встроен в контейнер.
  4. В файле .\docker-compose\etc\content-watcher\appsettings.json настройте перечень сайтов для отслеживания ContentWatcher.
  5. В каталог, в котором развернуты конфигурационные файлы (например, \opt\services), загрузите необходимые docker-образы сервисов.

    Команда для загрузки необходимых docker-образов сервисов
    docker-compose pull
    

    В результате выполнения команды из официального сайта Docker Hub загружены необходимые docker-образы сервисов.

    Действия, которые необходимо выполнить для загрузки docker-образов сервисов, если на сервере запрещен доступ в интернет:

    1. На машине с открытым доступом вручную скачайте все необходимые образы вручную (см. конфигурационный файл docker-compose.yml).
    2. На целевую машину перенесите скачанные docker-образы в виде файлов.

      Команда для переноса скачанных docker-образов сервисов
      docker export/import
      
  6. Запустите сервисы.

    Команда для запуска сервисов
    docker-compose up -d 
    

    В результате сервисы запущены.

  7. Проверьте корректность разворачивания сервиса бандлирования. Для этого выполните GET-запрос по адресу, который приведен ниже.

    {IP-адрес сервера}: {CONTENT_SERVICE_PORT}
    
    17.17.17.7:9999
    

    IP-адрес сервера — IP-адрес сервера, на котором установлены сервисы.

    CONTENT_SERVICE_PORT — порт, на котором работает ContentService. Совпадает с портом, который указан в файле .\docker-compose\*.env на шаге 2.

    В результате выполнения команды получен ответ Service is running.