Информация для разработчиков и администраторов ALEPIZ

Описание системы

ALEPIZ написан на языке JavaScript. С серверной стороны используется nodejs. Для распараллеливания вычислений используются дочерние процессы и потоки. Процессы взаимодействуют между собой через протокол TCP/IP.

В качестве базы данных используется встраиваемая база sqlite. Для работы с базой данных используется модуль nodejs - better-sqlite3. В качестве основы для Web сервера используется модуль nodejs - express. Для формирования пользовательского интерфейса используется Materialize и JQuery.

Разработка

  • Изменение или получение данных об объектах, счетчиках, действиях, задачах осуществляется через подключение и использование библиотек API из файлов в каталоге проекта rightsWrappers\. Описание содержимого файлов находится ниже. Документация по API находится внутри файлов с исходным кодом
  • Описание разработки действий находится на странице помощи Actions\Action editor .
  • Описание разработки сборщиков находится на странице помощи Actions\Collector editor
  • Описание разработки лаунчеров находится на странице помощи Actions\Launcher editor
  • Описание разработки средств связи находится на странице помощи Actions\Communication editor
  • Функции и описание для разработки функций находится в файле проекта lib\calcFunction.js
  • Функции и для разработки функций обработки исторических данных находится в файле проекта models_history\historyFunctions.js
  • Для смены СУБД конфигурации объектов и их свойств, счетчиков, задач и пользователей в ALEPIZ перепишите все функции в каталоге models_db\*.js
  • Для смены СУБД для работы с историческими данными перепишите функции работы с БД в models_history\historyStorageServer.js

Процессы ALEPIZ

Для работы ALEPIZ запускаются серверные процессы, внутри которых работают потоки. Ниже дано описание процессов и потоков.

  • alepiz.js - основной процесс, используется для отслеживания работы процесса alepizRunner.js
    • alepizRunner.js - процесс, запускающий и следящий за работой:
      • процессов ALEPIZ:
        • historyServer.js - сервер обслуживания исторических данных
        • actionServer.js - сервер запуска действий
        • activeCollectorServer.js - серверы для получения и обработки данных из активных или выделенных сборщиков
      • и потоков ALEPIZ:
        • log.js - сервер логирования
        • dbServer.js - сервер БД для внешних интеграций с конфигурацией ALEPIZ
        • dbBackup.js - сервер резервного копирования
        • actionServer.js - сервер обслуживания задач
        • webServer.js - Веб сервер
        • debugCounters.js - сервер отладки счетчиков

Базы данных

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

  • База с конфигурацией системы db.db
  • База с историческими данными и трендами storage.db
  • База с событиями events.db
  • Клиентские сессии session.db

База с конфигурацией системы: DB.DB

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

  • Объекты и свойства
    • objects - список объектов и параметры объектов
    • interactions - взаимодействия объектов
    • objectsProperties - свойства объектов
  • Счетчики и переменные
    • counters - список счетчиков и параметры счетчиков
    • countersGroups - группы счетчиков
    • countersUnits - единицы измерения
    • countersParameters - параметры для сборщиков
    • countersUpdateEvents - события для обновления счетчиков
    • variables - переменные из исторических данных
    • variablesExpressions - вычисляемые переменные
  • objectsCounters - связь между объектами и счетчиками
  • Задачи
    • tasks - список задач и параметры задач
    • tasksParameters - параметры для действий
    • tasksActions - действия, используемые в задачах
    • tasksGroups - группы для задач
    • taskRunConditions - условия для автоматического выполнения задач
    • taskRunConditionsOCIDs - связь условий задач со счетчиками, подключенными к объектам, от которых зависит выполнение задач
  • Права
    • rightsForActions - права на действия
    • rightsForObject - права на объекты
    • taskGroupsRoles - права на группа задач
  • Пользователи и роли
    • users - список пользователей
    • userRoles - связи между пользователями и ролями
    • roles - список ролей
    • userCommunication - адреса для связи с пользователями
    • userCommunicationPriorities - приоритеты для средств связи
    • userCommunicationPriorityDescription - описание приоритетов средств связи

База с историческими данными: HISTORY.DB

База служит для хранения исторических данных и трендов. Исторические данные могут хранится в виде чисел или строковых значений. Остальные типы данных будут преобразованы к этим двум типам. У одного объекта могут храниться оба типа данных. ALEPIZ автоматически определяет тип данных, преобразует и сохраняет данные в требуемую таблицу. По возможности ALEPIZ преобразует данные из строкового формата в числовой. Логические значения true и false преобразовываются в числовые 1 и 0.

Тренды могут быть применены только к числовым данным. Тренды это среднее арифметическое для данных одного объекта, собранных в течение определенного для этого тренда времени. Существует несколько трендов, ориентированных на разные интервалы времени с усреднением за 10, 30 и 60 минут. Они служат для быстрого построения графиков и таблиц с данными за большой период времени. Время хранения трендов и исторических данных отличается и настраивается для каждого счетчика с помощью действия Counter settings параметрами Keep history и Keep trends.

Объектами в исторической базе данных является единица, для которой собираются исторические данные. В терминах базы с конфигурацией ALEPIZ, объектами являются элементы из таблицы objectsCounters, т.е. это связанные друг с другом элементы типа Objects и Counters. База с историческими значениями и база с конфигурацией системы не связаны между собой через механизмы SQLITE. Связь осуществляется на программном уровне. Для ускорения получения данных из БД используется встроенный алгоритм кэширования исторических данных в памяти. В ALEPIZ реализованы функции очистки базы с историческими значениями:

  • Система очистки удаленных из ALEPIZ объектов removeZombie
  • Система очистки исторических данных и трендов houseKeeper
Система очистки удаленных из ALEPIZ объектов removeZombie

Процедура очистки удаленных объектов запускается на старте и потом периодически вместе с houseKeeper. Она удаляет объекты, которых не существует в ALEPIZ. За счет связей внутри базы с историческими данными вместе с объектами удаляются и сами данные.

Система очистки исторических данных и трендов Housekeeper

Процедура очистки исторических данных запускается периодически, через интервал времени, установленный в параметре cacheServiceInterval. Housekeeper удаляет исторические данные старше, чем указано в параметрах счетчика для хранения исторических данных (Keep history). Данные из трендов будут удалены в соответствии с настройкой счетчика для хранения трендов (Keep trends)

Ниже приведен список таблиц и предназначение для каждой таблицы

  • objects - Список идентификаторов объектов (objectsCounters.id) и требуемое количество данных, хранимых для объекта в кэше
  • numbers - числовые данные
  • strings - строковые данные
  • trends10min - тренды c усреднением данных за 10 мин
  • trends30min - тренды с усреднением данных за 30 мин
  • trends60min - тренды с усреднением данных за 60 мин
  • config - хранит информацию о том, где остановился процесс Housekeeper для того, чтобы после рестарта ALEPIZ продолжить работу с места остановки.

Количество таблиц с трендами и их периодичность может быть настроено в models_history\historyStorage.js: var trendsTimeIntervals = [10, 30, 60]; Если база с историческими данными непустая, при изменении периодичности необходимо вручную удалить таблицы с трендами, которые больше не используются.

База с событиями: EVENTS.DB

База с событиями используется сборщиком event-generator и действием Dashboard. Она содержит информацию о событиях, произошедших в инфраструктуре, подсказки по обработке событий и комментарии ним. Ниже приведен список таблиц и предназначение для каждой таблицы

  • events - список произошедших событий и их параметры
  • disabledEvents - временно отключенные события
  • comments - комментарии к событиям
  • hints - подсказки по событиям

Клиентские сессии: SESSION.DB

База служит для хранения клиентских сессий и куков. База используется Web сервером ALEPIZ и содержит одну таблицу sessions.

Структура проекта

Каталоги проекта делят проект на логические блоки. Ниже приводится их описание:

  • .distr - каталог содержит файлы для формирования установочного пакета
  • actions - в каталоге находятся действия
  • bin - каталог содержит обслуживающие скрипты для обслуживания и запускаемый файл alepiz.js
  • collectors - в каталоге находятся сборщики
  • communication - в каталоге находятся модули для различных средств связи
  • config - каталог с файлами конфигурации системы
  • DB - каталог с базами данных
  • launchers- в каталоге находятся лаунчеры для запуска действий
  • lib - основной каталог с кодом ALEPIZ
  • logs - каталог с лог файлами
  • models_db - каталог, содержащий файлы с программным кодом, описывающим интерфейс к базе с конфигурацией системы db.db. При необходимости можно сменить СУБД, переписав функции в js файлах в этом каталоге
  • models_history - каталог, содержащий сервер и API, для взаимодействие с базой с историческими данными: HISTORY.DB. При необходимости можно сменить СУБД, переписав функции в файле historyStorageServer.js
  • node_modules - модули nodejs, используемые в проекте
  • private - каталог для ключей HTTPS сервера и шифрования cookies.
  • public - каталог с файлами для работы для формирования пользовательского интерфейса ALEPIZ
  • rightsWrappers - каталог с API для работы с базой конфигурации системы db.db
  • routers - программный код с маршрутизаторами Web сервера
  • server - сервер для обработки данных, полученных счетчиками
  • serverActions - сервер управления действиями
  • serverDB - сервер для работы с конфигурацией ALEPIZ, используется для внешних интеграций
  • serverDebug - сервер для отладки процесса расчета переменных для счетчиков
  • serverTask - сервер для отслеживания условий автоматического запуска задач
  • serverWeb - Веб сервер для взаимодействия с ALEPIZ
  • utils - утилиты для обслуживания системы
  • views - каталог с шаблонами pug для работы пользовательского интерфейса ALEPIZ и страницами помощи

lib - библиотеки ALEPIZ

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

  • actionConf.js - получение конфигураций для действий
  • alepizRunner.js
  • browserLog.js - обслуживание пользовательского интерфейса работы системы логирования действий (всплывающее окно снизу при выполнении действия)
  • calc.js - ядро для вычисления функций и выражений в различных модулях ALEPIZ
  • calcFunctions.js - функции для вычислительного ядра (не исторические).
  • collectors.js - управление сборщиками: получение, сохранение, проверка параметров, удаление.
  • communication.js - API для работы со встроенными средствами связи
  • conf.js - интерфейс для работы с файлами конфигурации в формате JSON
  • dbBackup.js - клиент-серверная подсистема для резервного копирования баз SQLITE
  • encrypt.js - функции шифрования
  • exitHandler.js - обработчик исключений и остановок процессов и потоков
  • help.js - работа со справочной информацией
  • installService.js - установщик сервиса ALEPIZ
  • IPC.js - клиент-серверная система взаимодействия между компонентами ALEPIZ по протоколу TCP/IP
  • log.js - клиент-серверная подсистема логирования ALEPIZ
  • proc.js - подсистема запуска, остановки и взаимодействия между процессами ALEPIZ
  • profiling.js - библиотека, помогающая профилировать код
  • recode.js - библиотека для перекодировки текста между разными кодовыми страницами
  • runInThread.js - библиотека для запуска и работы с потоками
  • runInThreadChild.js - клиентская часть библиотеки работы с потоками, которая запускается как поток и служит для подключения программного кода, который необходимо запустить в потоке
  • tasks - работа с задачами
  • threads.js - еще одна библиотека для запуска и работы с потоками
  • user - работа с пользователями

rightsWrappers - API для работы с объектами, счетчиками, действиями, пользователями и задачами

API служит для получения и записи данных при работе с объектами счетчиками, действиями, пользователями и задачами. API использует функции из models_db, не взаимодействуя напрямую с БД. Кроме получения и записи данных так же осуществляется проверка прав доступа к объектам и действиям. Для этого во все функции передается имя пользователя. API так же осуществляет проверку корректности всех переданных параметров. В исходных файлах js даны комментарии, которые помогут использовать данное API. Предназначение файлов следующее:

  • actions - проверка прав на взаимодействие объектов и пользователя с действиями
  • counterSaveDB - сохранение и удаление счетчиков (для действия Counter settings)
  • countersDB - запрос данных о счетчиках
  • objectsDB - сохранение и запрос данных об объектах, связях со счетчиками и взаимодействиях между объектами
  • objectsPropertiesDB - сохранение и запрос данных при работе со свойствами объектов
  • tasksDB - сохранение и запрос данных при работе с задачами.

models_db - работа с базой конфигурации системы SQLITE

Код ориентирован только на работу с БД. В нем не производится проверок корректности передаваемых, параметров, обработки ошибок и пр. Код написан так, чтобы с минимальными затратами по ресурсам можно было изменить СУБД на любую другую. В каталоге modifiers находятся модули, которые вносят изменения в БД. В корневом каталоге модули предназначены только для выполнения запросов на получение информации из БД. Предназначение файлов следующее:

  • createDB - каталог с файлами, содержащими код по созданию таблиц БД, если не каких-то таблиц не существует
  • actionsDB.js - получение и сохранение настроек пользовательского интерфейса для действий.
  • connect-sqlite3.js - обслуживание сессии web сервера - работа с session.db
  • modifiers/counterDB.js - сохранение изменений в счетчиках (для действия Counter editor)
  • countersDB.js - получение данных о счетчиках
  • countersGroupsDB.js - обслуживание и получение данных о группах счетчиков
  • countersUnitsDB.js - обслуживание и получение данных о единицах измерения
  • db.js - в зависимости от настроек переключает взаимодействие с БД настроек ALEPIZ через сервер БД или напрямую, через файловые операции.
  • dbWrapper.js - преобразует функции best-sqlite в формат, совместимый с сервером БД.
  • objectsDB.js - обслуживание и получение данных об объектах
  • objectsFilterDB.js - фильтрация, поиск объектов, взаимодействие объектов в системном меню Objects
  • objectsPropertiesDB.js - обслуживание и получение данных о свойствах объектов
  • tasksDB.js - обслуживание и получение данных о задачах
  • transactions.js - организация работы с использованием транзакций, очереди транзакций
  • usersDB.js - обслуживание и получение данных о пользователях
  • usersRolesRightsDB.js - работа с ролями пользователей, кеширование ролей

models_history - сервер для работы с историческими данными

Сервер для работы с историческими данными состоит из:

  • Основного процесса history, обрабатывающего запросы и распределяющего их между дочерними потоками БД. Он так же занимается организацией кэширования данных
  • Потоков historyStorageServer, обслуживающих запросы на запись в файлы БД. Для резервирования может быть использовано несколько файлов БД.
  • Потоков historyStorageServer, выполняющих запросы к БД на получение данных. Количество дочерних процессов равно количеству ядер CPU или устанавливается настройками.

Предназначение файлов следующее:

  • historyClient.js - API для взаимодействия с сервером обслуживания исторических данных
  • historyServer.js - основной исполняемый файл сервера обработки исторических данных
  • historyCache.js - код, обслуживающий кэш БД и взаимодействующий с процессами, выполняющими запросы к БД
  • historyStorage.js - внутреннее API для работы с файлом БД с историческими данными
  • historyStorageServer.js - потоки, непосредственно выполняющие файловые операции для получения или сохранения исторических данных в БД.
  • historyFunctions.js - функции для обработки исторических данных.
  • historyFunctionsGet.js - получение данных для функций обработки данных.
  • historyHousekeeper.js - система для удаления старой информации из БД.
  • historyParameters.js - параметры сервера по умолчанию.