Глоссарий#

Введение#

Документ описывает процесс установки и настройки сервиса VisionLabs LUNA Access версии 2.19.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.

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

В руководстве приведены команды для CentOS.

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

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

sudo mkdir -p -v /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).

3． Проверьте установку Docker Compose:

docker-compose --version

В ответе должна быть указана версия docker-compose, например: docker-compose version 1.29.2, build 5becea4.

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

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

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

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

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

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

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

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

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

yum install unzip

Команда установки может отличаться в зависимости от менеджера пакетов в ОС, например в Ubuntu/Debian используется apt, а в AlmaLinux dnf.

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

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

Дистрибутив содержит (Таблица 7):

Таблица 7. Состав дистрибутива

4． Перейдите в директорию:

cd vl-access-2-v2.19.0

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

Настройка Access#

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

nano .env

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

Запуск Access#

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

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

docker load -i vl-access-2-images-v2.19.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.19.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 (Таблица 9).

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

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

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

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

Итоговый архив необходимо поместить в директорию 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 по умолчанию.

Найдите файл .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． Убедитесь, что в Access включён режим отладки (debug), и в логе worker присутствуют сообщения уровня DEBUG.

6． Найдите все логи, относящиеся к этому проходу, выполнив команду:

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

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

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

1． Убедитесь, что включён режим отладки (debug) для Access и в 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． Нажмите кнопку Отфильтровать.

Логирование при репликации#

Логирование репликации в Access позволяет отслеживать процесс синхронизации данных пользователей (лиц) и контроллеров из СКУД в систему распознавания лиц LUNA PLATFORM 5.

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

Для дополнительной информации о отслеживании конкретных событий прохода и использовании Trace ID обратитесь к разделу Отслеживание проходов с помощью trace_id.

Просмотр логов репликации#

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

1． Перейдите в директорию продукта:

cd /var/lib/vl-access-2/

2． Выведете логи контейнеров FastAPI и Worker в режиме реального времени:

docker compose logs fastapi worker --follow

Каждая строка содержит информацию о событии репликации с временной меткой, уровнем логирования (INFO, ERROR и т.д.) и описанием события.

Для остановки просмотра логов и возврата к командной строке нажмите одну из следующих сочетаний клавиш:

Ctrl + Z / Ctrl + C / Ctrl + D

Фильтрация логов#

Логи можно фильтровать по различным критериям, добавив команду grep в команду вывода.

1． Для поиска по ФИО пользователя:

docker compose logs fastapi worker --follow | grep "ФИО"

Где: ФИО - данные в поле "Информация" целевого лица в CLEMENTINE

2． Для поиска по ID пользователя:

docker compose logs fastapi worker --follow | grep "external_id"

Где: external_id - идентификатор лица из СКУД

3． Для поиска по ID компонента:

docker compose logs fastapi worker --follow | grep "component_id"

Где: component_id - идентификатор компонента в Access.

Структура процесса репликации#

Процесс репликации состоит из следующих основных этапов:

1． Инициирование репликации - репликация запускается автоматически при создании или перезагрузке компонента СКУД, либо вручную в интерфейсе ПО СКУД;

2． Репликация контроллеров - синхронизация данных контроллеров СКУД (если применимо);

3． Репликация лиц - синхронизация данных пользователей с их фотографиями;

4． Обработка ошибок и исключений - логирование любых проблем, возникших в процессе;

5． Завершение репликации - финальное логирование статуса.

Ключевые логи репликации

1． Начало репликации контроллеров.

Когда компонент СКУД начинает репликацию, вы увидите логи следующего вида:

Start controller replication

Лог указывает на то, что система начинает синхронизировать контроллеры из СКУД.

2． Начало репликации лиц (Рисунок 15).

Лог:

Start face replication

Этот лог служит маркером начала основного процесса синхронизации пользователей.

3． Создание нового лица и сохранение в хранилище (Рисунок 16).

Когда система находит нового пользователя в СКУД, который еще не добавлен в хранилище лиц LP5, создается новая запись:

Create new face: [face_id], ID [UUID], external ID [external_id] to list [list_id]
Saved person in storage: [storage_name]: [external_id] | [additional_info]

Параметры лога:

• face_id - внутренний ID лица в биометрической системе
• UUID - уникальный идентификатор записи в системе Access
• external_id - идентификатор лица из СКУД
• list_id - идентификатор списка, в который добавляется лицо
• storage_name - имя хранилища, в которое
• additional_info - дополнительная информация о лице, например значение доп. поля MDM_ID

Лог информирует о том, что новая запись о пользователе успешно создана в системе и подтверждает, что данные пользователя успешно синхронизированы и сохранены в локальном хранилище Access.

4． Изменение данных пользователя (Рисунок 17).

Когда данные пользователя изменяются в СКУД (например, изменение ФИО, фотографии или других атрибутов), система может выполнить операцию "удаление и пересоздание", вы увидите следующие логи:

Successfully updated face [face_id] name: [name] in list Luna
Saved person in storage: [storage_name]: [external_id] | [additional_info]

Параметры лога:

• face_id - внутренний ID лица в биометрической системе
• name - ФИО персоны в СКУД
• external_id - идентификатор лица из СКУД
• storage_name - имя хранилища, в которое
• additional_info - дополнительная информация о лице, например значение доп. поля MDM_ID

Эта операция может происходить не только во время полной репликации, но также и во время работы системы, когда администратор СКУД вносит изменения в данные пользователя.

5． Завершение репликации (Рисунок 18).

Когда все пользователи обработаны, система логирует завершение репликации:

End face replication

Лог обозначает успешное завершение процесса синхронизации лиц.

Рекомендации по анализу логов#

При возникновении проблем с репликацией:

1． Определите временной диапазон:

• Найдите логи "Start face replication" и "End face replication", это даст вам точные временные рамки проблемы

2． Отфильтруйте логи по компоненту:

• Используйте команды поиска с ID компонента для фокусировки на конкретном СКУД (см. Фильтрация логов)

3． Найдите ошибки/предупреждения:

• Ищите строки, содержащие "ERROR" или "WARNING"

4． Проверьте конкретного пользователя:

• Используйте команды поиска по ФИО или ID лица из СКУД (см. Фильтрация логов)
• Убедитесь, что пользователь реплицировался успешно

5． Проверьте последовательность операций:

• Убедитесь, что логи идут в правильном порядке
• Проверьте наличие как логов успешного сохранения, так и потенциальных ошибок

Решение типовых проблем#

При анализе логов репликации вы можете столкнуться с различными ошибками и предупреждениями. Таблица ниже служит быстрым справочником для диагностики проблем и поиска решений. Каждый сценарий соответствует конкретному типу ошибки, которую вы можете увидеть в логах, и указывает на возможные причины и действия для исправления (Таблица 10).

Таблица 10. Решение типовых проблем

Ошибка множественных лиц в изображении#

Когда биометрическая система LUNA обнаруживает несколько лиц на одной фотографии, логируется ошибка:

ERROR: LUNA API ERROR 11038 Multiple faces found in image

Возможные причины:

• Фотография содержит несколько человек;
• Качество фотографии низкое, и биометрическая система неправильно интерпретирует части изображения как отдельные лица.

Лицо не соответствует требованиям#

Если фотография не соответствует требованиям системы распознавания, логируется соответствующая ошибка:

ERROR: LUNA API ERROR [code] [error_description]

или

LUNA CLIENT ERROR The face hasn't been created due to wrong handler policies. <details>

Типичные ошибки валидации включают:

• Лицо слишком маленькое;
• Лицо повернуто под большим углом;
• Освещение недостаточное;
• Часть лица закрыта;
• Некорректное фото: перевернуто/размыто и проч.

Возможные причины:

• Фотография не соответствует требованиям качества LUNA PLATFORM;
• Фотография не соответствует требованиям политик обработчика;
• Некорректная обработка фотографии перед отправкой.

Блокировка пользователя#

Если пользователь заблокирован в СКУД система логирует:

Person is blocked

Возможные причины:

• Пользователь заблокирован в СКУД.