Перейти к основному содержимому

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

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

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

Скачайте и распакуйте дистрибутив 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 backend.planned_retention_policy_day_of_week — день недели в формате cron, когда будет запущена периодическая проверка задачи очистки. backend.planned_retention_policy_hour — час в формате cron, когда будет запущена периодическая проверка задачи очистки. backend.planned_retention_policy_minute — минута в формате cron, когда будет запущена периодическая проверка задачи очистки. backend.delete_sample_batch_size — размер пакета кадров попытки, который будет удален за один раз. backend.delete_sample_batch_sleep — время в секундах между удалениями батчей. backend.retention_process_count — количество процессов, выполняющих очистку кадров попытки. backend.sample_ttl — время в секундах, после которого кадры попытки будут удалены.
./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 — данные для подключения к базе. baf-email-secret — данные для подключения к SMTP серверу. ВНИМАНИЕ! Поле platform-token заполняется во время установки.
./cfg/baf.values.yaml | 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.error_data_retention_days: период хранения ошибочных данных в днях в хранилище объектов. minio.enable: выключите, если используете свой сервер minio. Примечание: необходимо поменять значения для video-recorder-minio в файле ./cfg/video_recorder.secrets.json и значения для minio.host, minio.port и minio.secure (1 для https, 0 для http) в текущем файле. video_recorder.webrtc_mock_video_recording:: включите для повышения производительности, если вам не нужно просматривать записанные видео. Видео размером 4 байта продолжат сохраняться для стабильности системы, но не будут воспроизводиться. Работает только в режиме записи через WebRTC 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> decoder.enabled: отключите, если не требуется декодирование видео. decoder.decoding_process_count: количество процессов декодирования, запускаемых в одной реплике сервиса. Чем больше процессов, тем больше одновременных сессий декодирования видео будет обрабатывать сервис. minio.delete_cleanup_interval: интервал, в котором minio удаляет объекты из корзины. video_recorder.retention_batch_size: размер пакета видео-контента попыток, который будет удален за один раз. video_recorder.retention_batch_pause: время в секундах между удалениями пакетов. video_recorder.retention_process_count: количество процессов, выполняющих очистку видео-контента попыток. video_recorder.retention_check_frequency: частота запуска проверки очистки в секундах.
./cfg/stunner.secrets.json | stunner-auth-secret.type — тип credentials. Всегда должен быть ephemeral. stunner-auth-secret.secret — секрет, который будет использоваться для генерации учетных данных для подключения к TURN.
./cfg/report.values.yaml | core.process_count — количество процессов построения отчетов. Чем больше процессов, тем больше отчетов может строиться одновременно.
./cfg/util-services.values.yaml | ingress.rules.gateway.host: должен быть равен домену ingress в файле ./cfg/baf.values.yaml

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

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

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

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

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

Для установки nvidia-container-runtime в качестве низкоуровневой среды выполнения по умолчанию выполните следующую команду:

    ./cli.sh smc nvidia install

##### Настройка использовая 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) (опционально)​

осторожно

Если вы обновляетесь с версии 1.12.0, убедитесь, что паттерны контроля движений перенесены в настройки новой версии, если это необходимо.

Если этого не сделать перед установкой новой версии video-recorder, данные паттернов будут безвозвратно утеряны.

Для подробной информации смотрите раздел Инструкция по обновлению.

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

В сценарии «Регистрация по селфи» 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

#### (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​

примечание

В версии 1.13.0 обновлен механизм паттернов. Для переноса паттернов между версиями обратитесь к разделу обновления.

Запустите команду для установки секретов 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

#### Установка подсистемы инструментальных сервисов Util Services (US) (опционально)​

Подсистема US необходима для работы необязательных, но полезных сервисов для отладки работы BAF.

Для установки Util Services запустите команду:

    $ ./cli.sh util-services install

### Настройка DNS​

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

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

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