Текущая версия на 11:00, 21 сентября 2021

Этот файл продублирован на svn

Для сервисов ИБИС есть похожий документ см Службы_MIS3._Разработка

Общие требования

Структура файлов

• каждая служба живет в своем каталоге
• имена каталогов в ВЕРХНЕМ регистре
• все имена файлов в нижнем регистре
• имя исполняемого файла службы должно заканчиваться на _srv
• имя службы должно начинаться с kis без "_srv" в конце!
• имя исполняемого файла по управлению службой должно заканчиваться на _ctl
• настройка подключения к БД должна храниться в файле kis.ini
• настройки службы должны храниться в <имяслужбы>.ini файле рядом с исполнимыми файлами. см. [Конфигурационные файлы KIS](Конфигурационныефайлы_KIS "wikilink")

Пример расположения служб

KIS_SRV
 ├─KIS_MQTT
 │  ├──kis_mqtt_srv.exe
 │  ├──kis_mqtt_ctl.exe
 │  ├──kis.ini
 │  │  kis_mqtt.ini
 │  │  kis_mqtt.ini.example
 │  │  readme.md
 │  └──LOG - Папка с логами
 └─KIS_EHR_CONNECTOR
    ├──kis_ehr_connector_srv.exe
    ├──kis_ehr_connector_ctl.exe
    ├──kis.ini
    ├──kis_ehr_connector.ini
    ├──kis_ehr_connector.ini.example
    ├──readme.md
    └──LOG

Именования файлов

• _srv.exe севрис
• _ctl.exe управляющая программ
• _app.EXE в виде отдельного приложения (на этапе разработки)

Все исполняемые файлы (*.exe) должны содержать актуальную информацию о версии (номер версии должен совпадать с номером ревизии SVN на котором этот exe собран)

Имя службы windows

Имя службы должно быть латинскими буквами в нижнем регистре (с подчеркиваниями) без "_srv" в конце. Примеры названий служб:

• kis_mqtt
• kis_ehr_connector
• kis_pg_rest
• kis_supp
• kis_simi_epic

Взаимодействие с postgresql

Аутентификация в БД

• каждая служба должна работать под своим уникальным пользователем (для того чтобы можно было мониторить работу службы со стороны БД)
• имя пользователя должно быть
  • большими буквами
  • совпадать с именем службы
  • заканчиваться на "SRV"

логин пароль храним в открытом виде в файле ini (<имя службы>.ini)

• [Postgresql]
  • user
  • password
  • password_crypt

application_name в сессии postgresql

Любая сессия должна себя идентифицировать установив application_name в формате <имя файла> (версия). Например:

 kis_mqtt.exe (1.0.0.1)

Ниже пример кода:

procedure TdmMain.conAfterConnect(Sender: TObject);
var
  S : String;
begin
  S := ExtractFileName(FSrvInfo.AppExe);
  S :=  S+  ' (' + FSrvInfo.FileVer + ')';
  con.ExecSQL('SET  application_name = ''' + S + ''''); // устанваливаем переменную application_name (pg_stat_activity)
end;

Требования к работоспособности при потере соединения

• Служба должна корректно отрабатывать ошибки, связанные с потерей соединения с БД и пытаться восстановить соединение самостоятельно.

Размер work_mem

для сессии которая слушает pg_listen (и только для нее) нужно проставить

set session work_mem='64kB'

Зависимость от другого ПО

• служба не должна зависеть от стороннего ПО, такого как
  • вебсерверы (IIS, APACH)
  • Net framework
  • клиент БД

Диагностика работы службы

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

WEB API

Здесь описаны методы http, которые должна реализовать служба, чтобы можно было мониторить состояние службы. Эти методы будут вызвать сторонние приложения (админка kis_z, или другие сторонние программы) для отображения статуса работы службы

GET /checkstatus

Метод возвращает 1 в теле ответа, если сервис работает правильно

GET /info

возвращает json, в котором есть настройки, текущий статус сервера (версия сервиса, есть подключение к БД и т.п.) Пример

 {"FileVer": "1.0.0.6",
    "StartDT": "2018-10-17T16:08:16.867+03:00",
    "AppExe": "C:\\KIS_SRV\\KIS_MQTT_SRV\\kis_mqtt_srv.exe",
    "DBInfo": {
        "ConnectStr": "192.168.1.16:7432\/emiac1",
        "ConnectStatus": "connected",
        "lastMessageRecivedDT": "2019-02- 04T08:20:58.302+03:00",
        "MeessageCount": 35024,
        "ListenState": "Active"
    },
    "MQTTInfo": {
        "ConnectStr": "192.168.1.16:1883",
        "ConnectStatus": "active",
        "ClientID": "V5nZpiOiintKZ1wgeg2K1f1",
        "LastSendDT": "2019-02-04T08:20:58.302+03:00",
        "MessageCount": 35008   }

GET /stat

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

Пример:

{
    "last10hour": [{
        "dt": "2019-02-04T08:20:00.000+03:00",
        "Count": 10
    },
    {
        "dt": "2019-02-04T08:21:00.000+03:00",
        "Count": 12
    },
    {
        "dt": "2019-02-04T08:22:00.000+03:00",
        "Count": 9
    }]
}

GET /showlog

Показывает лог работы программы

Обычная html страница, которая показывает файл лог, который лежит на сервере

Пример кода Delphi для вывода в ответе TIdHTTPResponseInfo файла лога в кодировке UTF8 содержащего Русскими символы:

if AnsiUpperCase(leftStr(ARequestInfo.URI, 15)) = '/API/V1/SHOWLOG' then
 begin
   SL := TStringList.Create;
   uOTSynopseLog.TOTSynLog.Family.SynLog.Flush(True);
   // Даём команду и ожидаем закрытия LOG файла во всех потоках.
   uOTSynopseLog.TOTSynLog.Family.SynLog.CloseLogFile;
   // Считываем LOG файл. Пока он не будет считан другие потоки его не откроют
   SL.LoadFromFile(uOTSynopseLog.TOTSynLog.Family.SynLog.FileName, TEncoding.UTF8);
   AResponseInfo.ContentType := 'text/plain';
   AResponseInfo.CharSet := 'utf-8';
   AResponseInfo.ContentText := SL.Text;
   SL.Free;
   exit;
 end;
end;

GET /admin

Возвращает html страницу управления

GET /checkupdate

Проверить наличие обновления (в БАЗЕ)

• если обновление не найдено, то возвращает пустую строку
• если обновление найдено, то возвращает версию обновления

GET /curversion

возвращает строку, текущая версия сервиса

POST /update

Обновиться

• проверить есть ли доставленное обнове в БД
• вызвать утилиту обновления для сервиса

Документация

Файл readme.md

В каталоге обязательно должен быть файл readme.md в формате markdown (для редактирования можно использовать Typora). Кодировка UTF-8. В нем должны быть следующие разделы:

• Назначение
• Описание работы
• Состав (список файлов с описанием)
• Установка
• Настройка (что можно настроить в ini файлах, что можно настроить в adj)
• Обновление
• Мониторинг (проверка работоспособности, где и какие логи ведутся, как посмотреть какие ошибки возникали)

По правильному, содержимое файла markodown нужно продублировать на wiki (в typora есть экспорт)

Файлы-примеры конфигурационных файлов (ini.example)

Для каждого из возможных ini файлов должен лежать файл пример с расширением ini.example со всеми значениями по умолчанию и комментариями. Например для kis_mqtt.ini должен быть файл kis_mqtt.ini.example

Документация разработчика

В исходных кодах в каталоге DOC должен быть файл readme_dev.md в формате markdown

Публикация и распространение

на WEBDAV в папку <LAST_SRV_FILES\имя-службы_большими буквами> необходимо выложить два файла:

• <имяслужбымаленькими>.7z
• ver.ini

Состав файла 7z

1. все необходимые для работы файлы
2. ini-файлы с настройками по умолчанию (как правило это два файла)
3. файл readme.md (см пункт "Документация")

Содержимое файла ver.ini

 [Ver]
 srv_ver=1.0.0.13

Автоматизация публикации

В папке CI (Continuous Integration) необходимо создать два файла:

• 01_pack.bat - создает архив 7z
• 02_webdav.bat публикует архив в папке на WEBDAV с помощью утилиты curl

Примеры скриптов можно брать из kisservices\trunk\kispg_rest\CI

Алгоритм публикации

1. Изменяем в проекте номер версии, успешно компилим
2. Правим файл ver.ini в папке bin
3. Последовательно запускаем скрипты 01_pack.bat, 02_webdav.bat (смотрим в логи что все успешно)

Список сервисов

• KIS MQTT_connector
• KIS_CERTIFICATE
• KIS_CLS_EMIAC_SRV
• KIS_COVID_VAC_SRV
• KIS_EHR_CONNECTOR_SRV
• KIS_EMIAC_GATE_SRV
• KIS_EMIAC_NSI_CSV
• KIS_LAB_LIS_SRV
• KIS_NSI_REP_SRV
• KIS_PG_REST
• KIS_RMUR_REP_SRV
• KIS_SIMI_SRV
• KIS_UPD_SRV
• KIS_SRV_INSTALLER