Инструкция по установке

Подготовка окружения

Скачивание дистрибутива

Скачайте и распакуйте дистрибутив BAF на машину, где планируется выполнить установку. Для этого можно воспользоваться командой:

$ curl --output baf.zip ссылка на дистрибутив

В curl-запросе укажите ссылку на дистрибутив BAF (zip-файл). Ссылка на папку, в которой размещен дистрибутив, и сопроводительная документация в формате pdf придут в электронном письме.

Далее переместите файл лицензии face_sdk.lic (файл прикреплен к электронному письму) в папку setup.

примечание

Убедитесь, что файл с лицензией называется именно face_sdk.lic. Использование другого имени приведёт к ошибкам генерации секретов.

Комплект установки BAF:

• ./cli.sh — точка входа для запуска команд.
• ./cfg — папка с файлами конфигурации.

Дальнейшие команды выполняются в системной консоли из директории setup.

Загрузка образов

Загрузите в локальный registry продуктовые образы из архива:

$ ./cli.sh generic load-images

Загрузите в локальный registry инфраструктурные образы из архива:

 $ ./cli.sh smc load-images

Конфигурация BAF

Базовая конфигурация

Ввод переменных окружения

Откройте следующие файлы конфигурации, используя текстовый редактор, установите значения переменных и сохраните изменения в файлах.

примечание

Значения, записанные через точку в YAML-файлах, обозначают структуру вложенности.

Файл конфигурации	Переменные
./cfg/smc.settings.cfg	apiserver_advertise_address — адрес для kube-apiserver, обычно используется внутренний IP-адрес машины. external_ip_address — адрес для ingess-controller, необходимо указать внешний IP-адрес машины.
./cfg/license-server.settings.cfg	license_key — лицензионный ключ. Как правило, ключ отправляется в сопроводительном письме с дистрибутивом. При отсутствии ключа обратитесь к вашему менеджеру по продажам. Для пробного периода ключ не требуется. license_server_address — адрес лицензионного сервера.
./cfg/platform.secrets.json	license-secret — установите лицензионный ключ и адрес лицензионного сервера вместо license_server_address. docker-registry — установите значения, если используется внешний docker-registry. rabbit-secret — имя пользователя и пароль для доступа к брокеру сообщений, используется для внутреннего взаимодействия сервисов OMNI Platform. Задайте произвольное имя, состоящее из латинских букв, без пробелов и пароль, состоящий из латинских букв и цифр, без пробелов. postgres-root-credentials — имя пользователя и пароль для root пользователя в базе данных. platform-service-key — секретный ключ для внутреннего взаимодействия сервисов OMNI Platform. platform-user-secret — учетные данные (адрес электронной почты и пароль), которые будут использоваться для доступа в OMNI Platform. При первом развертывании пользователи будут созданы автоматически. Указываемый адрес электронной почты должен состоять из цифр, латинских букв и символов. Пользователь admin обладает правами администратора системы. Пользователь default может быть использован для непривилегированного доступа к системе. platform-email-secret — параметры SMTP-сервера. Чтобы отключить отправку писем, оставьте поля пустыми. minio-credentials — имя пользователя и пароль для root пользователя в объектном хранилище. storage-engine-postgres — имя пользователя, пароль и имя базы данных для platform. event-service-postgres — имя пользователя, пароль и имя базы данных для event-service.
./cfg/platform.values.yaml	backend.query_limit — ограничение количества возвращаемых элементов в API-запросах для получения сущностей системы. Увеличение данного лимита не рекомендуется, т.к. время выполнения API-запроса может увеличиться в несколько раз. Также обратите внимание, что увеличение лимитов приведет к ухудшению работы системы. backend.index_update_period — значение в секундах, описывающее через какое время добавленный профиль появится в поисковом индексе. По умолчанию установлено значение 60 секунд. Если требуется увеличить скорость обновления поискового индекса, следует уменьшить значение. Значение влияет на скорость авторизации после регистрации. backend.enable_profile_autogeneration — автосоздание профилей для приходящих активностей с BAF Agent. Необходимо учитывать, что при включении этой опции будет увеличенный расход ресурсов лицензии (размер базы данных). Для включения функции установить значение 1. ingress.rules.gateway.host — доменное имя, используется в ingress для маршрутизации запросов на сервисы Kubernetes для OMNI Platform. postgres.enable — выключите, если используете свой сервер базы данных. Примечание. Необходимо поменять значения для postgres-root-credentials в файле ./cfg/platform.secrets.json и значения для postgres.host и postgres.port в текущем файле. minio.enable — обозначает, что для хранения изображений из событий будет использоваться объектное хранилище. Если выключить этот параметр, для хранения изображений будет использоваться postgres. Примечание. Если после первого развертывания уже накопилось какое-то количество изображений, то выключать данный параметр не рекомендуется, иначе будет невозможно получить накопленные данные. При развёртывании в AWS необходимо отключить этот параметр. matcher.shard_n — интерфейсный параметр, регулирует количество одновременных обращений к matcher-serivice. Должен быть равен параметру shard.quantity в файле matcher.values.yaml
./cfg/matcher.values.yaml	shard.quantity — количество создаваемых шардов, увеличение параметра позволяет ускорять поиск на больших данных shard.search_threads_n — количество используемых потоков для выполнения поиска
./cfg/baf.secrets.json	baf-user-secret — учетные данные (адрес электронной почты и пароль), которые будут использоваться для доступа в BAF. Обратите внимание, что минимальная длина пароля составляет 6 символов. Пароль должен состоять из латинских букв и цифр, содержать хотя бы одну заглавную букву и специальный символ "!". platform-token — токен для подключения к OMNI Platform. baf-postgres — данные для подключения к базе. ВНИМАНИЕ! Поле platform-token заполняется во время установки.
./cfg/baf.values.yaml	video_recorder.enabled — переключатель работы с Video Recorder. Поставьте 0, если не планируете работать с Video Recorder. ingress.rules.gateway.host — доменное имя, используется в ingress для маршрутизации запросов на сервисы Kubernetes для BAF. postgres.pool_size — размер пула соединений. Возможно потребуется увеличить значение, если ожидается высокая нагрузка на сервисы BAF.
./cfg/platform-ui.values.yaml	ingress.host — доменное имя, используется в ingress для маршрутизации запросов на сервисы Kubernetes. Значение должно совпадать со значением ingress.rules.gateway.host в файле ./cfg/platform.values.yaml.
./cfg/video-recorder.secrets.json	video-recorder-tokens — токен доступа и токен шифрования. video-recorder-postgres — данные для подключения к базе. video-recorder-minio — данные для подключения к объектному хранилищу. ВНИМАНИЕ! Поля video-recorder-tokens заполняются во время установки.
./cfg/video-recorder.values.yaml	minio.data_retention_days: период хранения данных в днях в хранилище объектов (видео, референсные кадры, шаблоны). minio.enable: выключите, если используете свой сервер minio. Примечание: необходимо поменять значения для lrs-minio в файле ./cfg/platform.secrets.json и значения для minio.host, minio.port и minio.secure (1 для https, 0 для http) в текущем файле. video_recorder.obtain_ref_frame: отключите для повышения производительности, если вам не нужно сравнивать кадры из видео. video_recorder.mock_video_recording: включите для повышения производительности, если вам не нужно просматривать записанные видео. Видео размером 4 байта продолжат сохраняться для стабильности системы, но не будут воспроизводиться. lrs.enable: отключите для повышения производительности, если вам не нужны расчёты liveness по видео. Liveness по видео продолжит сохраняться для стабильности системы, но всегда будет иметь значение 99. video_recorder.uvicorn_concurrency: количество одновременно обрабатываемых http-соединений для каждой поды. После превышения лимита будет возвращаться ошибка 503. video_recorder.sqlalchemy_pool_size: максимальное количество персистентных соединений, которые будет держать пул sql alchemy для каждой поды. video_recorder.sqlalchemy_pool_overflow: количество соединений сверху персистетного количества, которые будут закрыты после использования для каждой поды. video_recorder.max_webrtc_simultaneous_conn: количество одновременно обрабатываемых WebRTC сессий для каждой поды. После превышения лимита будут возвращаться ошибки 503 на попытки установить соединение. minio.buckets_prefix: префикс, который ставится перед всеми именами бакетов в подобном формате: <prefix>.<bucket name>
./cfg/stunner.secrets.json	stunner-auth-secret.type — тип credentials. Всегда должен быть ephemeral. stunner-auth-secret.secret — секрет, который будет использоваться для генерации учетных данных для подключения к TURN.
./cfg/decoder.values.yaml	core.decoding_process_count — количество процессов декодирования, запускаемых в одной реплике сервиса. Чем больше процессов, тем больше одновременных сессий декодирования видео будет обрабатывать сервис.
./cfg/report.values.yaml	core.process_count — количество процессов построения отчётов. Чем больше процессов, тем больше отчётов может строиться одновременно.

Обновление конфигурации работающего инстанса

Для применения обновлений в values модуля необходимо выполнить команду установки модуля. Если обновление не применилось, сначала удалите модуль, а затем установите его заново.

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

Расширенная конфигурация (опционально)

Настройка Docker для использования GPU

Для установки nvidia-container-runtime в качестве низкоуровневой среды выполнения по умолчанию добавьте следующие строки в файл конфигурации, который находится по адресу /etc/docker/daemon.json:

   {
   "default-runtime": "nvidia",
   "runtimes": {
       "nvidia": {
           "path": "/usr/bin/nvidia-container-runtime",
           "runtimeArgs": []
       }
     }
   }

Перезапустите docker-service, выполнив следующую команду:

$ sudo systemctl restart docker

Проверьте, что docker-service успешно работает:

$ sudo systemctl status docker

Настройка использовая GPU в BAF

Для включения GPU в BAF необходимо отредактировать файл ./cfg/image-api.values.yaml. Для этого пропишите в переменную processing.services.face-detector-template-extractor.configs.recognizer.params.use_cuda значение 1:

Пропишите значение 1 в переменную processing.services.face-detector-template-extractor.resources.limits.gpu:

Установка и настройка кластера

примечание

Если у вас уже есть развернутый кластер, перейдите к пункту «Настройка лицензирования».

Запустите команды для создания и настройки кластера:

./cli.sh smc system-patch
./cli.sh smc install
./cli.sh platform db-create-mountpoint
./cli.sh platform install-secrets

Эти команды выполняют следующие действия:

• Создание точки монтирования базы данных
• Инициализация кластера
• Установка секретов

Если вы используете GPU, дополнительно запустите скрипт по установке nvidia-plugin в кластер:

$ ./cli.sh smc nvidia install

Проверка работоспособности кластера

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

$ kubectl get nodes

В результате в терминале будет отображен следующий вывод:

NAME          STATUS      ROLES                   AGE     VERSION
master-node   Ready       control-plane,master    11d     v1.23.8

Для проверки всех элементов кластера запустите следующую команду:

$ kubectl get all --all-namespaces

Настройка лицензирования

Пользователю доступны 3 варианта активации лицензии: активация пробного периода, онлайн и офлайн активация лицензии.

Установка и запуск сервера лицензий

Перед установкой откройте файл license-server.settings.cfg и задайте IP адрес машины, на которой будет установлен сервер лицензий, в переменной license_server_address.

Запустите команду для установки и запуска сервера лицензий. Если license_server_address не аналогичен адресу хоста машины, где происходит развертывание, он будет установлен через sshpass:

$ ./cli.sh license-server install

Проверьте, что сервер лицензий находится в статусе Running, выполнив следующую команду:

$ ./cli.sh license-server status

Пример вывода в консоль:

floatingserver.service - Floating License Server
    Loaded: loaded (/etc/systemd/system/floatingserver.service; enabled; vendor preset: enabled)
    Active: active (running) since Tue 2022-12-20 12:25:54 +05; 1min 48s ago

Убедитесь, что сервер лицензий доступен. Для этого перейдите по адресу http://<license_server_address>:8090 в вашем браузере, на странице должна отобразиться форма входа.

Активация пробного периода

Важно:

• Требуется подключение к интернету.
• Не допускается запуск на виртуальной машине.

Активация пробного периода происходит при первом запуске BAF.

Онлайн активация лицензии

Перед активацией убедитесь, что в key (файл ./cfg/license-server.settings.cfg) записан лицензионный ключ.

Запустите команду активации лицензии:

$ ./cli.sh license-server activate

Пример вывода в консоль при успешной активации лицензии:

[2022-12-20 12:25:53+05:00] INF Activating license key...
[2022-12-20 12:25:54+05:00] INF License activated successfully!

Офлайн активация лицензии

Перед активацией убедитесь, что в поле license_key (в файле ./cfg/license-server.settings.cfg) записан лицензионный ключ.

примечание

Для офлайн активации установите “1” в поле enable_offline_activation в файле license-server.settings.cfg.

Запустите команду для генерации офлайн запроса на лицензию:

$ ./cli.sh license-server generate-offline

В результате выполнения команды в директории setup должен появиться файл request-offline.dat.

Отправьте сгенерированный файл запроса request-offline.license на почту baf-request@3divi.com. В ответном письме будет отправлен файл лицензии.

Поместите полученный лицензионный файл в папку setup.

Откройте файл конфигурации license-server.settings.cfg и заполните значение переменной license_offline_activation_file именем файла лицензии и его расширением, если присутствует, через точку.

Запустите команду для активации полученной лицензии:

$ ./cli.sh license-server activate

Пример вывода в консоль при успешной активации лицензии:

[2022-09-08 01:30:36+05:00] INF Offline activating license key...
[2022-09-08 01:30:36+05:00] INF License activated successfully!

Развертывание BAF

Запуск развертывания

Установка подсистемы распознавания лиц (OMNI Platform)

Запустите установку первого модуля OMNI Platform:

$ ./cli.sh image-api install

Запустите установку матчера (matcher-router + matcher-shard):

./cli.sh matcher install

Запустите установку второго модуля OMNI Platform:

$ ./cli.sh platform install

При необходимости запустите установку веб-интерфейса OMNI Platform:

./cli.sh platform-ui install

Чтобы продолжить установку, откройте файл /etc/hosts и добавьте в конец файла следующие строки:

<external_ip_address> : <platform_domain>
<external_ip_address> : <baf_domain>

Установка подсистемы для записи видео Video Recorder (VR) (опционально)

Если вам не требуется запись видео, пропустите этот шаг

В сценарии «Регистрация по селфи» Video Recorder предоставляет возможность сохранять видео попыток и проводить контроль движений.

Создайте директорию для хранения данных объектного хранилища с помощью команды:

$ ./cli.sh video-recorder minio-create-mountpoint

Запустите команду для генерации токенов Video Recorder:

$ ./cli.sh video-recorder generate-token

Пример вывода в консоль:

sha256:2473ba0ebf5ef66cd68b252bba7b46ae9f7cc3657b5acd3979beb7fbc5d8807f
Fernet key: ......
Access token: ......

В результате вы получите два токена, которые необходимо прописать в файл конфигурации ./cfg/video-recorder.secrets.json в раздел video-recorder-tokens.

Запустите команду для установки секретов Video Recorder:

$ ./cli.sh video-recorder install-secrets

Запустите команду для установки Video Recorder:

$ ./cli.sh video-recorder install

Установка подсистемы для расчёта Liveness Reflection (LRS) (опционально)

примечание

LRS не будет работать без подсистемы Video Recorder

Подсистема LRS используется для расчёта liveness по видео. Если расчёт liveness reflection не требуется, этот шаг можно пропустить.

В сценарии «Регистрация по селфи» LRS предоставляет возможность обнаружить атаку с внедрением видеопотока.

Запустите команду для установки LRS:

$ ./cli.sh lrs install

Установка подсистемы для декодирования видео Decoder Service (DS) (опционально)

примечание

Для работы Decoder Service требуется установить подсистему Video Recorder.

Подсистема Decoder Service используется для декодирования видео. Если вам не требуется функционал cross-matching, этот шаг можно пропустить.

Для установки Decoder Service запустите следующую команду:

$ ./cli.sh decoder install

(BETA) Установка подсистемы Stunner для проксирования запросов через TURN-сервер к Video Recorder (опционально)

Подсистема stunner необходима для успешного установления соединения между браузерами клиентов и сервером VR через WebRTC для записи видео с последующим расчётом liveness. Пропустите этот шаг, если модуль VR не установлен или используется тип соединения веб-компоненты и сервера, отличный от WebRTC.

Запустите команду для установки секретов stunner:

$ ./cli.sh stunner install-secrets

Запустите команду для установки stunner:

$ ./cli.sh stunner install

Используйте следующие команды, чтобы убедиться, что stunner запущен:

$ kubectl get pods | grep stunner
$ kubectl get svc | grep -P 'tcp|udp|stunner'

Если все поды имеют статус Running и 5 сервисов запущены, значит stunner работает успешно.

Запустите команду для получения портов по которым доступен TURN сервер извне:

$ ./cli.sh stunner get-ports

Пример вывода команды:

tcp-gateway: 31021
udp-gateway: 30796

Установка BAF

Получите токен от OMNI Platform:

$ ./cli.sh platform get-token - http://<platform_domain> <platform_user_email>

В результате вы получите токен, который необходимо прописать в файл конфигурации ./cfg/baf.secrets.json в раздел platform-token.

Далее инициализируйте секреты BAF для кластера:

$ ./cli.sh baf install-secrets

Запустите установку BAF:

$ ./cli.sh baf install

Для отслеживания процесса развертывания откройте ещё одну вкладку терминала и введите следующую команду:

$ watch 'kubectl get pods'

Наличие у всех pods статуса Running означает, что BAF запущен.

Установка подсистемы для построения отчётов Report Service (RS) (опционально)

Подсистема RS необходима для создания отчётов с метриками работы системы. Если вам не требуется функциональность отчётов, этот шаг можно пропустить.

Запустите команду для установки Report Service:

$ ./cli.sh report install

Настройка DNS

Для доступа к BAF DNS сервер вашей сети должен содержать запись о том, что домен доступен по адресу <external_ip_address>.

Для тестирования можно указать IP-адрес и домен в файле /etc/hosts на Linux или C:\Windows\System32\drivers\etc\hosts на Windows. Для этого добавьте в конец файла новую строку вида <external_ip_address> <host>, подставив значения соответствующих переменных, и сохраните файл.

Обратите внимание, для редактирования файла hosts необходимо обладать правами администратора.

Масштабирование

В случае, когда нагрузка возрастает, для стабилизации работы BAF предусмотрено масштабирование следующих сервисов в ручном режиме:

• image-api-liveness-estimator: сервис используется для детекции лиц и оценки принадлежности лица на изображении реальному человеку.
• image-api-age-estimator: сервис используется для оценки возраста человека по изображению лица.
• image-api-gender-estimator: сервис используется для оценки пола человека по изображению лица.
• image-api-mask-estimator: cервис позволяет определить наличие/отсутствие медицинской маски на лице человека.
• image-api-emotion-estimator: сервис используется для оценки эмоций человека по изображению лица.
• image-api-face-detector-template-extractor-dep: сервис используется для построения поискового биометрического шаблона по лицу.
• image-api-face-detector-face-fitter-dep: сервис используется для детекции лиц и определения антропометрических точек лица.
• decoder-core: сервис для декодирования видео.
• video-recorder-video-recorder: сервис для сохранения видео.
• lrs-lrs: сервис для вычисления liveness reflection.

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

$ kubectl scale deployment <SERVICE_NAME> --replicas <COUNT>

где <SERVICE_NAME> — наименование сервиса (например, gateway-dep), а <COUNT> — количество экземпляров сервиса.

Если входная нагрузка состоит в прохождении валидации с записью видео liveness reflection и контроля движений, где оба видео имеют следующие характеристики:

• формат: webm
• кодек: vp8
• разрешение: 720p
• длительность: 2.8 секунды
• число кадров в секунду: 13

Для поддержания нагрузки в A запросов/сек на сервере с физическим количеством ядер ЦП равным B следует установить значение реплик следующих сервисов по формулам:

по формуле min(A, B):

• decoder-core
• video-recorder-video-recorder
• lrs-lrs
• image-api-face-detector-face-fitter-dep

по формуле min(A*2, B):

• image-api-face-detector-template-extractor-dep .

Если используется сервер с установленым GPU, где C - это оперативная память GPU в мегабайтах, а D - это fix(C/1000), то сервис image-api-face-detector-template-extractor-dep следует масштабировать по формуле min(A, D).

Для сохранения параметров масштабирования откройте файлы ./cfg/platform.values.yaml, ./cfg/image-api.values.yaml, ./cfg/lrs.values.yaml, ./cfg/video-recorder.values.yaml и ./cfg/decoder.values.yaml, найдите поле replicas в блоке сервиса и укажите новые значения реплик.

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