2ГИС Линза | On‑Premise | 2GIS Documentation
Карты
Поиск
Навигация
2ГИС Про
2ГИС Линза
Личный кабинет
On‑Premise
ру
en

Установка 2ГИС Линзы

Важное примечание:

Все пароли и ключи в этом разделе приведены в иллюстративных целях.

При реальной установке рекомендуется использовать более сложные и надёжные пароли.

1. Перед установкой

  1. Ознакомьтесь с основной информацией:

  2. Выполните предварительные шаги:

    1. Подготовка к установке
    2. Получение артефактов установки
    3. Установка сервиса лицензий
    4. Установка сервиса ключей
    5. Установка сервиса навигации
    6. Установка сервиса поиска
    7. Установка API для работы с картами
    8. Установка 2ГИС Про
    9. Установка Менеджера Платформы

  3. Соберите необходимые данные, заданные или полученные на предыдущих шагах:

    Объект Пример значения Как получить значение
    Endpoint зеркала реестра Docker artifacts.example.com См. Получение артефактов установки
    Секрет Kubernetes для доступа к зеркалу реестра Docker onpremise-registry-creds См. Получение артефактов установки
    Домен S3-хранилища с артефактами установки artifacts.example.com См. Получение артефактов установки
    Название бакета с артефактами установки onpremise-artifacts См. Получение артефактов установки
    Идентификатор ключа для доступа к артефактам установки AKIAIOSFODNN7EXAMPLE См. Получение артефактов установки
    Секрет ключа для доступа к артефактам установки wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY См. Получение артефактов установки
    Путь к файлу манифеста manifests/1640661259.json См. Получение артефактов установки
    Endpoint сервиса лицензий https://license.svc См. Установка сервиса лицензий
    Endpoint MapGL JS API mapgl.example.local См. Установка API для работы с картами
    Endpoint Catalog APIs catalog-api.example.local См. Установка API поиска
    Endpoint Pro API https://pro-api.host См. Установка 2ГИС Про

  4. Убедитесь, что удовлетворены требования к ресурсам, приведенные в Helm-чарте. Подробнее о том, как это сделать, смотрите в документе Системные требования.

    Примечание

    Содержание Helm-чарта, описанное в данном разделе, актуально для последней версии On-Premise (см. Релизы). Чтобы изучить параметры для более ранних версий, откройте values.yaml в GitHub и введите номер нужной версии комплекса (например, 1.18.0) в переключателе тегов слева.

  5. Определите доменные имена:

    Пример:

    • Доменное имя для сервиса 2ГИС Линза (UI для просмотра загруженных треков): http://citylens-web.host
    • Доменное имя для CityLens API, куда подключается мобильное приложение и загружает треки: http://citylens-api.host
    • Доменное имя для CityLens Routes API (backend-сервиса для планирования задач и построения маршрутов): http://citylens-routes-api.host

2. Подготовьте инфраструктуру

Настройте PostgreSQL

Разместите кластер PostgreSQL с доменным именем citylens-postgresql.storage.example.local в приватной сети. Предполагается, что кластер работает на стандартном порту 5432.

Настройте кластер PostgreSQL для использования в качестве хранилища:

  1. Подключитесь к кластеру от имени суперпользователя (обычно это postgres).

  2. Создайте пользователя базы данных и установите пароль для него:

    create user citylens password 'citylens';

  3. Создайте базы данных, принадлежащие этому пользователю:

    create database citylens owner citylens;
create database routes owner citylens;
create database hangfire owner citylens;

  4. Установите расширение PostGIS для PostgreSQL.

  5. Включите расширение PostGIS:

    create extension postgis;

Настройте S3-хранилище

Разместите S3-совместимое хранилище (например, Ceph) с доменным именем citylens-s3.storage.example.local в приватной сети. Предполагается, что хранилище работает на стандартном порту 80.

Настройте S3-совместимое хранилище:

  1. Создайте пользователя, который будет использоваться для сервиса:

    • accessKey: accessKey
    • secretAccessKey: secretAccessKey

    Запомните ключи доступа для этого пользователя.

  2. Определите префиксы названий бакетов (buckets): префикс для кадров и префикс для логов мобильного приложения (bucketPrefix и logsBucketPrefix соответственно в Helm-чарте). Бакеты (buckets) будут сгенерированы «на лету».

    Пример:

    • Бакет для основных данных: onprem-citylens.

Настройка Apache Kafka

Разместите кластер Apache Kafka с доменным именем citylens-kafka.storage.example.local в приватной сети. В этом руководстве предполагается, что кластер работает на стандартном порту 9092.

Создайте пользователя, который будет использоваться для сервиса:

  • username: kafka
  • password: kafka_password

Запомните реквизиты для этого пользователя.

3. Установите 2ГИС Линзу

Установите CityLens API и CityLens Routes API

  1. Создайте конфигурационный файл для Helm (для установки обоих компонентов CityLens API и CityLens Routes API нужен один файл). Подробное описание доступных параметров см. здесь.

    Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.

    values-citylens-api.yaml 
    dgctlDockerRegistry: docker.storage.example.local:5000

api:
  auth:
    enabled: true
    authServerUrl: https://keycloak.host
    realm: CityLens_app
    storeOIDCUserinfoFields: []
    predictorsTokens:
      camcom: token

  licensing:
    url: 'https://license.svc'

  ingress:
    className: nginx
    enabled: false
    hosts:
    - host: citylens-api.host
      paths:
      - path: /
        pathType: Prefix
    tls:
    - hosts:
      - citylens-api.host
web:
  auth:
    enabled: true
    realm: Inspection_Portal_backend
    authServerUrl: https://keycloak.host
    clientId: citylens-web-client
    clientSecret: secret
    pkce: false

  ingress:
    className: nginx
    enabled: true
    hosts:
    - host: citylens-web.host
      paths:
      - path: /
        pathType: Prefix
    tls: []
    - hosts:
      - citylens-web.host

worker:
  camcomSender:
    enabled: true
    apiKey: key
    endpointUrl: http://camcom-mock-service/user_upload
    sourceEnv: test
  reporterPro:
    enabled: true
    predictors: [camcom]
    replicas: 1

kafka:
  bootstrapServer: kafka1.host:9092,kafka2.host:9092,kafka3.host:9092
  username: kafka
  password: kafka_password
  topics:
    frames: frames
    tracks: tracks
    pro: pro
    proObjects: objects
    proDrivers: drivers
    logs: logs
    uploader: uploader
    framesLifecycle: flifecycle
    tracksLifecycle: tlifecycle
    objectsLifecycle: olifecycle
    predictions: predictions
  consumerGroups:
    prefix: citylens_

s3:
  endpoint: https://s3.host
  accessKey: accessKey
  secretAccessKey: secretAccessKey
  bucketPrefix: citylens # приложение само создаст бакет вида bucketPrefix + %Y%m
  logsBucketPrefix: citylens-logs
  verifySsl: true
  setPublicReadACL: false

dgctlStorage:
    host: artifacts.example.com
    secure: false
    bucket: onpremise-artifacts
    accessKey: AKIAIOSFODNN7EXAMPLE
    secretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEY
    manifest: manifests/1640661259.json

postgres:
  host: postgres.host
  port: 5432
  database: citylens
  username: citylens
  password: citylens

routes:
  worker:
    busConfig:
      consumers:
        appEvents:
          groupId: ''
  postgres:
    database: routes
  hangfire:
    postgres:
      database: hangfire
  pro:
    authorizationToken: ''
    mainTerritoryId: ''
  navi:
    url: http://navi-front
    key: key

dashboardDomain: https://citylens-web.host

locale: en

map:
  tileserverUrl: https://tiles-api-raster.host
  mapgl:
    host:  mapgl-js-api.host
    key: key

pro:
  baseUrl: https://pro-api.host
  key: key
  verifySsl: true
  framesAssetId: ''
  objectsAssetId: ''

customCAs:
  bundle: ''
  # bundle: |
  #   -----BEGIN CERTIFICATE-----
  #   ...
  #   -----END CERTIFICATE-----
  certsPath: ''

    Где:

    • dgctlDockerRegistry: эндпоинт вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС.

    • api: настройки CityLens API.

      • auth: настройки аутентификации.

        • enabled: включена аутентификация или нет.
        • authServerUrl: URL API службы аутентификации.
        • realm: realm для аутентификации.
        • storeOIDCUserinfoFields: список полей из ответа провайдера OIDC для хранения информации о водителях, загружающих треки.
        • predictorsTokens.camcom: случайно сгенерированная строка длиной 64 символа (ASCII + цифры). Передается в Camcom для доступа к CityLens API.

      • licensing: настройки сервиса лицензий.

        • url: URL-адрес сервиса лицензий. Пример: https://license.svc.

      • ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.

    • web: настройки веб-сервиса 2ГИС Линза.

      • auth: настройки аутентификации.

        • enabled: включена аутентификация или нет.
        • realm: realm для аутентификации.
        • authServerUrl: URL API службы аутентификации.
        • clientId: ID клиента поставщика OpenID Connect.
        • clientSecret: секрет клиента поставщика OpenID Connect.
        • pkce: включена ли проверка ключа PKCE.

      • ingress: конфигурация ресурса Ingress. Адаптируйте приведенную конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметре ingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.

    • worker: настройки рабочих процессов 2ГИС Линзы.

      • camcomSender: настройки рабочих процессов CamcomSender.

        • enabled: включен ли Camcom Sender.
        • apiKey: ключ доступа к API Camcom Sender.
        • endpointUrl: endpoint для Camcom Sender.
        • sourceEnv: имя окружения в Camcom, предоставляемое Camcom'ом.

      • reporterPro: настройки для выгрузки данных в 2ГИС Про.

        • enabled: включена ли интеграция с 2ГИС Про.
        • predictors: предиктор, используемый отгрузчиком данных.
        • replicas: количество реплик пода.

    • kafka: настройки доступа к брокеру Apache Kafka.

      • bootstrapServer: endpoint брокера Kafka. Пример: HOST:PORT.

      • username: имя пользователя.

      • password: пароль пользователя.

      • topics: настройки топиков.

        • frames: список топиков для Frames Saver.
        • tracks: список топиков для Track Metadata.
        • pro: топик для синхронизации фреймов с 2ГИС Про через Reporter Pro.
        • proObjects: топик для синхронизации локализованных детекций (распознанных объектов) с 2ГИС Про через Reporter Pro.
        • proDrivers: топик для синхронизации треков водителей с 2ГИС Про через Reporter Pro.
        • logs: топик для логов мобильного приложения (загружаются через CityLens API).
        • uploader: топик для Uploader.
        • framesLifecycle: топик для событий жизненного цикла фреймов.
        • tracksLifecycle: топик для событий жизненного цикла треков.
        • objectsLifecycle: топик для событий жизненного цикла объектов.
        • predictions: топик для событий прогнозов от детекторов.

      • consumerGroups: настройка группы потребителей.

        • prefix: префикс для топиков группы потребителей.

    • s3: настройки S3-совместимого хранилища.

      • endpoint: endpoint S3 хранилища. Пример: HOST:PORT или URL.
      • accessKey: идентификатор ключа для доступа к бакету S3.
      • secretAccessKey: секретный ключ для доступа к бакету S3.
      • bucketPrefix: префикс имени бакета в S3 для бакетов фреймов.
      • logsBucketPrefix: префикс имени бакета в S3 для бакетов логов мобильных приложений.
      • verifySsl: включена проверка SSL-сертификатов или нет.
      • setPublicReadACL: сделать ли S3-бакет публичным (просмотр кадров будет доступен без авторизации).

    • dgctlStorage: настройки хранилища артефактов развертывания.

      • host: адрес или IP S3-хранилища артефактов развертывания.
      • secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию: false.
      • bucket: имя бакета S3.
      • accessKey: идентификатор ключа для доступа к бакету S3.
      • secretKey: секретный ключ для доступа к бакету S3.
      • manifest: путь до файла с манифестом в формате manifests/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.

    • postgres: настройки доступа к PostgreSQL.

      • host: адрес или IP PostgreSQL read-write (rw) хоста.
      • port: номер порта.
      • database: имя БД.
      • username: имя пользователя БД c rw-доступом.
      • password: пароль пользователя БД.

    • routes: настройки CityLens Routes API.

      • worker.busConfig.consumers.appEvents.groupId: ID потребительской группы Kafka для передачи событий.

      • postgres.database: имя БД PostgreSQL.

      • hangfire.postgres.database: имя БД PostgreSQL для доступа hangfire (планировщика задач).

      • pro: настройки для интеграции с 2ГИС Про.

        • authorizationToken: Bearer-токен для отправки данных в Про. Подробнее см. в инструкции по загрузке данных по API.
        • mainTerritoryId: ID доступной территории.

      • navi: настройки для интеграции с API навигации.

        • url: URL для доступа к Navi-Front.

        • key: ключ для доступа к API навигации. Убедитесь, что выполнены следующие условия:

          • Этот ключ содержит права доступа к Routes Planner API.
          • Соответствующий сервисный токен из сервиса API-ключей добавлен в конфигурационный файл Navi-Router (параметр keys.apis.route-planner-api).

    • dashboardDomain: ссылка на веб-версию 2ГИС Линзы.

    • locale: используемый язык.

    • map: настройки карт.

      • tileserverUrl: URL сервера для получения растровых тайлов.

      • mapgl: настройки доступа к MapGL JS API.

        • host: имя хоста MapGL.
        • key: ключ сервера MapGL.

    • pro: группа настроек для интеграции 2ГИС Линзы с 2ГИС Про.

      • baseUrl: URL Pro API для актуализации фильтров.
      • key: токен аутентификации Pro API
      • verifySsl: включена проверка SSL-сертификатов или нет.
      • framesAssetId: ID набора данных для загрузки фреймов.
      • objectsAssetId: ID набора данных для загрузки объектов.

    • customCAs: настройки пользовательских сертификатов.

      • bundle: текстовое представление сертификата в формате X.509 PEM public-key.
      • certsPath: директория для монтирования сертификата внутри контейнера.

  2. Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-citylens-api.yaml:

    helm upgrade --install --version=1.37.0 --atomic --values ./values-citylens-api.yaml citylens 2gis-on-premise/citylens

Установите CityLens Routes UI

  1. Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь.

    Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.

    values-citylens-ui.yaml 
    dgctlDockerRegistry: docker.storage.example.local:5000

env:
    CATALOG_API_URL: 'https://catalog-api.ingress.host'
    MAPGL_API_URL: 'http://mapgl-js-api.ingress.host'
    MAPGL_KEY: ''
    PLATFORM_MANAGER_API_URL: ''
    PLATFORM_MANAGER_CLIENT_ID: ''
    PLATFORM_MANAGER_CLIENT_SECRET: ''
    PLATFORM_MANAGER_SCOPE: 'openid email name phone'
    ROUTES_API_URL: 'http://citylens-routes-api.ingress.host'

    Где:

    • dgctlDockerRegistry: эндпоинт вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС.

    • env: настройка окружения.

      • CATALOG_API_URL: базовый URL для Catalog APIs.
      • MAPGL_API_URL: базовый URL для MapGL JS API.
      • MAPGL_KEY: ключ для доступа к MapGL JS API.
      • PLATFORM_MANAGER_API_URL: базовый URL для API Менеджера Платформы в формате <origin>/realms/<realm> (например, https://<domain>.com/realms/Inspection_Portal_backend).
      • PLATFORM_MANAGER_CLIENT_ID: идентификатор клиента OpenID для Менеджера Платформы.
      • PLATFORM_MANAGER_CLIENT_SECRET: ключ клиента OpenID для Менеджера Платформы.
      • PLATFORM_MANAGER_SCOPE: набор пользовательских атрибутов, которые запрашивает клиент OpenID для Менеджера Платформы.
      • ROUTES_API_URL: базовый URL для CityLens Routes API.

  2. Установите сервис с помощью Helm, используя подготовленный конфигурационный файл values-citylens-ui.yaml:

    helm upgrade --install --version=1.37.0 --atomic --values ./values-citylens-ui.yaml citylens 2gis-on-premise/citylens

4. Проверьте работоспособность 2ГИС Линзы

Воспользуйтесь одним из способов:

  • Перейдите по адресу http://citylens-web.host.
  • Запустите мобильное приложение 2ГИС Линза.

5. Настройте аутентификацию пользователей

Настройте внешнего поставщика OpenID Connect для аутентификации конечных пользователей в 2ГИС Линзе.

Что дальше?