Глоссарий#

Введение#

Документ описывает процесс установки и настройки сервиса VisionLabs LUNA Access версии 2.18.0 (далее — Access), а также содержит аппаратные и программные требования к ПО.

Процесс настройки и установки необходимо выполнять под учетной записью суперпользователя (с root правами).

Системные требования#

Требования к программному обеспечению (Таблица 1).

Таблица 1. Требования к программному обеспечению

Требования к аппаратному обеспечению рабочей станции (Таблица 2).

Таблица 2. Требования к аппаратному обеспечению

Архитектура Access#

Общая схема работы#

Схема работы Access и описание представлены ниже (Рисунок 1) и (Таблица 3).

Таблица 3. Описание схемы Access.

Диаграммы последовательности работы Access#

Взаимодействие внутренних компонентов Access#

Взаимодействие и описание компонентов Access на примере типовой интеграции источник видеосигнала + LUNA PLATFORM 5 (LP5) + Sigur (Рисунок 2) и (Таблица 4).

Таблица 4. Описание диаграммы последовательности

Создание компонента#

Схема создания компонента в Access UI и описание (Рисунок 3) и (Таблица 5).

Таблица 5. Описание диаграммы последовательности

Автоматический мониторинг#

Схема автоматического мониторинга состояния компонентов и описание (Рисунок 4) и (Таблица 6).

Таблица 6. Описание диаграммы последовательности

Лицензирование#

Для работы Access не требуется лицензия.

Лицензированию могут быть подвержены внешние системы и сервисы, которые используются в интеграции. Лицензия в этом случае приобретается отдельно у правообладателя.

Установка Access#

Данный раздел описывает установку и использование Docker и Docker Compose для развертывания Access.

Docker и Docker Compose не входят в дистрибутив Access.

Подготовка к установке#

Создайте главную директорию, где в дальнейшем будут все версии продукта и перейдите в нее:

sudo mkdir /var/lib/vl-access-2/
sudo chown $(whoami) /var/lib/vl-access-2/
cd /var/lib/vl-access-2/

Установка Docker и Docker Compose#

Используйте официальную инструкцию для установки Docker Engine и Docker Compose для используемой ОС.

Перед запуском Access необходимо убедиться что Docker запущен и активен.

1․ Запустите Docker:

systemctl start docker
systemctl enable docker

2․ Проверьте Docker:

systemctl status docker

Ответ должен содержать статус Active (running).

Подготовка окружения и распаковка дистрибутива#

Дистрибутив представляет собой архив вида «vl-access-2-v2.18.0».

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

Архив содержит компоненты, необходимые для установки и эксплуатации Access.

Архив не включает зависимости, которые входят в стандартную поставку ОС и могут быть загружены из открытых источников.

Запуск Access осуществляется из Docker образа.

Для запуска необходимо выполнить действия:

1․ Переместите скачанный архив vl-access-2-v2.18.0.zip в директорию /var/lib/vl-access-2.

2․ Установите архиватор unzip, если он не установлен.

yum install unzip

3․ Распакуйте файлы дистрибутива:

unzip vl-access-2-v2.18.0.zip -d vl-access-2-v2.18.0

4․ Директория содержит:

• директорию docs с документацией в формате pdf/html;
• README_FOR_ENGINEERS.md файл c описанием быстрого запуска;
• .env файл конфигурации;
• конфигурацию docker-compose.yml;
• конфигурацию conf.yml;
• архив изменений CHANGELOG.md;
• архив с образом vl-access-2-images-v2.18.0.tar.gz (при наличии).

5․ Перейдите в директорию:

cd vl-access-2-v2.18.0

При работе с дистрибутивом без образа необходимо скачать образ при запуске, см. раздел Запуск

Настройка Access#

Произведите настройку с помощью файла .env (Таблица 7):

nano .env

Таблица 7. Описание параметров env

Запуск Access#

1․ Импортируйте образ:

1․1. При наличии образа в архиве

docker load -i vl-access-2-images-v2.18.0.tar.gz

1․2. Без образа:

docker login dockerhub.visionlabs.ru
docker-compose pull
docker logout dockerhub.visionlabs.ru

2․ Добавьте symlink в директорию /var/lib/vl-access-2/, которая ссылается на последнюю версию продукта:

ln -s /var/lib/vl-access-2-v2.18.0 /var/lib/vl-access-2/current

3․ Запустите Access:

docker-compose up -d

Контейнеры Access поставляются с предустановленными утилитами, необходимыми для работы с образом.

4․ Проверьте доступность Access по адресу: http://<IP_address>:9092/.

Для доступа к интерфейсу Access создайте администратора (см. раздел Управление учетными записями).

Управление учетными записями#

Добавление учетной записи#

В Access поддерживается создание учетной записи с ролью Администратора. Более подробно о ролях и доступах см. в Руководстве пользователя раздел Роли в сервисе.

1․ Запустите скрипт создания администратора:

docker-compose exec fastapi python backend/manage.py createadmin

2․ Следуйте указаниям консоли:

(venv) [root@localhost vl-access-2]# docker-compose exec fastapi python backend/manage.py createadmin
Admin creation:
Enter your login: admin
Enter your password:
Confirm your password
Admin user created successfully

Логин администратора должен быть уникальным

3․ Проверьте корректность создания администратора – войдите в созданную учетную запись http://<IP_address>:9092/.

Просмотр списка учетных записей#

1․ Выполните команду просмотра списка созданных администраторов:

docker-compose exec fastapi python backend/manage.py listadmin

В консоли отобразится список администраторов:

(venv) [root@localhost vl-access-2]# docker-compose exec fastapi python backend/manage.py listadmin
admin
admin2

Удаление учетной записи#

Получите информацию о логине необходимого аккаунта для удаления с помощью команды просмотра.

1․ Выполните команду для удаления администратора:

docker-compose exec fastapi python backend/manage.py deleteadmin

2․ Введите логин администратора.

В ответе на запрос консоль выдаст сообщение об успешном удалении:

(venv) [root@localhost vl-access-2]# docker-compose exec fastapi python backend/manage.py deleteadmin
Admin deletion:
Enter your login: admin2
Admin was deleted successfully.

Скрипты#

Скрипт загрузки образов#

Скрипт scripts/save_images.sh позволяет выгрузить docker образы по путям, указанным в docker-compose.yml в формат tar.gz (Таблица 8).

Выгрузка может понадобиться для сохранения образов на носитель и перенос на объект при отсутствии/плохом интернет-соединении.

Запуск скрипта:

./save_images.sh -f <path_to/docker-compose.yml> -d <local_path_to/docker_images> -u <dockerhub_username> -p <dockerhub_password> 

Таблица 8. Доступные команды:

Итоговый архив необходимо поместить в директорию Access и произвести запуск по инструкции.

Обновление Access#

1․ Экспортируйте файл настроек старой версии продукта, для этого нажмите на стрелку справа от аватара пользователя и кнопку Экспортировать настройки (Рисунок 5).

Загрузится файл со всеми настройками компонентов в формате json.

2․ Сохраните конфигурационный файл .env старой версии, расположенный по пути /var/lib/vl-access-2/vl-access-2-v2.*.*/.env, где v2.*.* - номер версии продукта.

3․ Для обновления Access необходимо выполнить Удаление → Распаковку новой версии дистрибутива → Настройку параметров env (перенесите необходимые значения переменных из сохраненного конфигурационного файла .env старой версии в новый файл) и повторную Установку и запуск Access.

4․ После установки новой версии перейдите в UI Access, нажмите на стрелку справа от аватара пользователя и кнопку Импортировать настройки (Рисунок 6).

В открывшемся окне выберете ранее сохраненный json файл, введите название настройки и нажмите кнопку Загрузить (Рисунок 7).

При попытке импортировать файл настроек прежней версии Access в новую могут возникнуть ошибки обратной совместимости компонентов. В случае возникновения проблем обратитесь в техническую поддержку VisionLabs.

Удаление Access#

Удаление Access выполняется путем остановки и удаления контейнеров Docker.

Выполните следующие действия:

1․ Перейдите в директорию с файлом docker-compose.yml. Остановите запущенные контейнеры:

docker-compose down

2․ Удалите директорию установленного Сервиса:

rm -rf vl-access-2-v2.*.*

Система логирования#

Инструкция по сбору логов#

Сбор логов необходим для:

• Предоставления информации технической поддержки VisionLabs для составления тикета на поиск проблемы;
• Самостоятельного поиска ошибок.

Для получения полной информации о нештатной ситуации при работе Access необходимо подготовить и передать информацию представителю VisionLabs о:

• Файле настроек;
• Логах контейнеров;
• Файле .env;
• Информацию о рабочем окружении;
• Скриншоты UI (только в случаях ошибок UI).

Файл настроек#

Файл настроек – JSON файл, который содержит информацию об используемых компонентах в Access.

Файл настроек становится доступен для экспорта после создания в Access компонента.

1․ После создания любого из 4-х типов компонентов необходимо нажать на справа от аватара пользователя и нажать кнопку "Экспортировать настройки" (Рисунок 8).

При этом произойдет загрузка JSON файла с именем vl-access_setting.json.

2․ Найдите JSON на локальной машине.

Для Linux-систем по умолчанию /home/<username>/Downloads.

3․ Переименуйте файл настроек в зависимости от основных используемых сервисов и устройств, например: bolid+gate+fast.json.

Логи контейнеров#

Файлы логов контейнеров содержат всю информацию о работе Access от момента запуска (docker compose up) до создания логов, при условии активности контейнеров.

1․ Откройте в консоли директорию Access.

Для самопроверки удостоверьтесь, что в этой директории есть /db и docker-compose.yml (Рисунок 9).

2․ Выполните команды для записи логов контейнеров worker и fastapi:

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

docker-compose logs worker &> worker_<components_names>.log
docker-compose logs fastapi &> fastapi_<components_names>.log

3․ Проверьте наличие созданных файлов .log в той же директории.

Файл .env#

Файл .env находится в корневой папке дистрибутива (там же где docker-compose.yml), но может не отображаться в UI по умолчанию.

1․ Найдите файл .env для передачи представителю VisionLabs.

Информация о рабочем окружении#

Сверьте аппаратные и программные свойства рабочей машины с минимальными (см. Требования).

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

1․ Версия ОС локальной машины:

hostnamectl

2․ Версия docker/docker-compose:

docker --version
docker-compose --version

3․ Информация о аппаратных характеристиках:

cat /proc/cpuinfo | grep "model name"

4․ Объем свободной оперативной памяти:

free -h

5․ Объем свободного дискового пространства:

df -h

Скриншоты UI#

Скриншоты необходимы только для поиска проблемы с UI:

• неадекватно отображается статус is_alive компонента,
• отображается компонент, которого не должно быть (удалили, но он "вернулся"),
• появилась нечитаемая ошибка,
• в списке в LUNA Clementine дубли - на скриншот должны попасть даты создания лиц в списке,
• есть расхождения с событиями в LUNA Clementine, неверный тег события,
• прочее проблемы с UI.

Отслеживание проходов с помощью trace_id#

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

Использование trace_id позволяет быстро и точно отслеживать весь процесс прохода, анализировать задержки на разных этапах и выявлять возможные проблемы.

С помощью trace_id можно отследить:

• Время получения и обработки событий в системе;
• Информацию о результате распознавания: ФИО, номер карты, идентификаторы в СКУД и биометрической системе;
• Время выполнения ключевых операций: детекция, распознавание, отправка данных на терминал и контроллер;
• Другие технические детали, связанные с обработкой прохода.

Отслеживание проходов через события Luna Platform#

1․ Откройте интерфейс Luna CLEMENTINE / Luna Platform и перейдите в раздел Последние события. 2․ Найдите самое раннее успешное событие распознавания. 3․ Перейдите в карточку этого события, нажав на стрелку в правом верхнем углу возле фотографии (Рисунок 10).

4․ Скопируйте восьмизначный trace_id из поля Теги (Рисунок 11).

5․ Убедитесь, что в LUNA Access 2 включён режим отладки (debug), и в логе worker присутствуют сообщения уровня DEBUG. 6․ Найдите все логи, относящиеся к этому проходу, выполнив команду:

docker-compose logs fastapi worker | grep "<trace_id>"

Пример (Рисунок 12).

Как найти trace_id по ФИО персоны#

1․ Убедитесь, что включён режим отладки (debug) для LUNA Access 2 и в worker есть DEBUG-логи. 2․ Найдите нужный лог по ФИО:

docker-compose logs worker | grep -i "<name>"

3․ В найденном логе будет указан trace_id в формате trace <trace_id> (Рисунок 13).

4․ Используйте данный trace_id для поиска всех связанных логов:

   docker-compose logs fastapi worker | grep "<trace_id>"

Поиск события в Luna Platform по trace_id#

Порядок действий для отображения события по trace_id в UI (Рисунок 14).

1․ В Luna CLEMENTINE / Luna Platform перейдите в раздел Последние события. 2․ Нажмите на значок фильтра справа. 3․ Введите значение trace_id в поле Теги: 4․ Нажмите кнопку Отфильтровать.