Установка 2ГИС Ситискан
При реальной установке используйте более сложные и надёжные пароли.
1. Перед установкой
-
Ознакомьтесь с основной информацией:
-
Выполните предварительные шаги:
-
Соберите необходимые данные, заданные или полученные на предыдущих шагах:
Объект Пример значения Как получить значение Endpoint реестра Docker для хранения образов сервисов docker.registry.example.comСм. Получение артефактов установки Секрет Kubernetes для доступа к реестру Docker onpremise-registry-credsСм. Получение артефактов установки Endpoint S3-совместимого хранилища артефактов установки artifacts.example.comСм. Получение артефактов установки Название бакета с артефактами установки onpremise-artifactsСм. Получение артефактов установки Идентификатор ключа для доступа к артефактам установки AKIAIOSFODNN7EXAMPLEСм. Получение артефактов установки Секрет ключа для доступа к артефактам установки wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEYСм. Получение артефактов установки Путь к файлу манифеста manifests/citylens/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ГИС Про -
Убедитесь, что удовлетворены требования к ресурсам, приведённые в Helm-чартах:
Подробнее о том, как это сделать, см. в документе Системные требования.
Используйте чарты, соответствующие версии 2ГИС СитисканСодержание Helm-чартов, описанных в данном разделе, актуально для последней версии 2ГИС Ситискан (см. Релизы 2ГИС Ситискан). Чтобы изучить параметры для предыдущих версий, откройте нужный values.yaml в GitHub и в списке тегов слева выберите тег
Citylens-<версия>. -
Определите доменные имена:
Пример:
- Доменное имя для сервиса 2ГИС Ситискан (UI для просмотра загруженных треков):
http://citylens-web.host. - Доменное имя для CityLens API, куда подключается мобильное приложение и загружает треки:
http://citylens-api.host. - Доменное имя для CityLens Routes API (backend-сервиса для планирования задач и построения маршрутов):
http://citylens-routes-api.host.
- Доменное имя для сервиса 2ГИС Ситискан (UI для просмотра загруженных треков):
2. Подготовьте инфраструктуру
Если вместо PostgreSQL и Apache Kafka вы используете аналоги из реестра Минцифры, для инструкций по их настройке обратитесь к официальной документации этих сервисов.
Настройте PostgreSQL
-
Разместите кластер PostgreSQL с доменным именем
citylens-postgresql.storage.example.localв приватной сети. Предполагается, что кластер работает на стандартном порту5432. -
Подключитесь к кластеру от имени суперпользователя (обычно это
postgres). -
Создайте пользователя базы данных и установите пароль для него:
create user citylens password 'wNgJamrIym8UAcdX'; -
Создайте базы данных, принадлежащие этому пользователю:
create database citylens owner citylens;create database routes owner citylens;create database hangfire owner citylens;create database realtime_data owner citylens; -
Установите расширение PostGIS для PostgreSQL.
-
Включите расширение PostGIS:
create extension postgis;
Настройте S3-хранилище
-
Разместите S3-совместимое хранилище с доменным именем
citylens-s3.storage.example.localв приватной сети. Предполагается, что хранилище работает на стандартном порту80. -
Создайте ключи для подключения к сервису. Запомните реквизиты.
Пример:
- Ключ доступа:
PHEI4AHTHEETHAHXEEGE. - Секретный ключ:
aiw6ahlaeshahngaiJaebie6aeth0aiV2pucuey1.
- Ключ доступа:
-
Определите префиксы названий бакетов: префикс для кадров и префикс для логов мобильного приложения (
bucketPrefixиlogsBucketPrefixсоответственно в Helm-чарте). Бакеты будут сгенерированы «на лету».Пример:
- Бакет для основных данных:
onprem-citylens.
- Бакет для основных данных:
Настройте Apache Kafka
-
Разместите кластер Apache Kafka с доменным именем
citylens-kafka.storage.example.localв приватной сети. Предполагается, что кластер работает на стандартном порту9092. -
Создайте пользователя для подключения к сервису. Запомните его реквизиты.
Пример:
- Имя пользователя:
kafka. - Пароль:
kafka_password.
- Имя пользователя:
-
(Рекомендуется) Настройте топики Apache Kafka следующим образом:
Имя топика Передаваемые данные Рекомендуемые настройки kafka.topics.framesКадры съёмки из мобильного приложения - Максимальный размер сообщения — 10 Мб (
max.message.bytes: 10485760). - Период хранения файла лога — 2 дня (
retention.ms: 172800000). См. подробные рекомендации по выбору значения ниже.
kafka.topics.tracksМета-информация о треке и GPS-трек - Максимальный размер сообщения — 1 Мб (
max.message.bytes: 1048576). - Период хранения файла лога — 2 дня (
retention.ms: 172800000). См. подробные рекомендации по выбору значения ниже.
kafka.topics.logsЛоги трека из мобильного приложения - Максимальный размер сообщения — 5 Мб (
max.message.bytes: 5242880). - Период хранения файла лога — 2 дня (
retention.ms: 172800000). См. подробные рекомендации по выбору значения ниже. - Формат сжатия — Gzip (
compression.type: gzip).
kafka.topics.predictionsДетекции Максимальный размер сообщения — 1 Мб ( max.message.bytes: 1048576)kafka.topics.framesLifecycleДанные кадров Максимальный размер сообщения — 1 Мб ( max.message.bytes: 1048576)kafka.topics.tracksLifecycleДанные треков Максимальный размер сообщения — 1 Мб ( max.message.bytes: 1048576)kafka.topics.objectsLifecycleДанные распознанных объектов Максимальный размер сообщения — 1 Мб ( max.message.bytes: 1048576)kafka.topics.proНабор данных Кадры Максимальный размер сообщения — 1 Мб ( max.message.bytes: 1048576)kafka.topics.proDriversНабор данных Водители Максимальный размер сообщения — 5 Мб ( max.message.bytes: 5242880)kafka.topics.proObjectsНабор данных Объекты Максимальный размер сообщения — 1 Мб ( max.message.bytes: 1048576)Параметр
retention.msопределяет гарантированное время хранения сообщений в Apache Kafka и используется как буфер на случай деградации или недоступности потребителей (consumers) и соответствующих сервисов. Значение параметра следует выбирать исходя из скорости обработки очереди и допустимого времени восстановления системы. Более высокое значение снижает риск потери данных при инцидентах, но избыточное увеличение не даёт дополнительной надёжности, при этом увеличивает расход дискового пространства и время восстановления кластера. Для топиков с данными от мобильного приложения, особенно с кадрами и треками, рекомендуется закладывать увеличенный, но обоснованныйretention.ms, который соответствует ожидаемым сценариям деградации системы.Указанные значения параметра
retention.ms— рекомендуемые, так как помогают сохранить баланс между надёжностью хранения данных и эксплуатационными затратами. Вы можете изменять значения, если это обосновано нагрузкой, архитектурными особенностями или требованиями к времени восстановления.Полное описание настроек см. в документации Apache Kafka.
- Максимальный размер сообщения — 10 Мб (
3. Установите 2ГИС Ситискан
Установите CityLens API и CityLens Routes API
-
Создайте конфигурационный файл для Helm (для установки обоих компонентов CityLens API и CityLens Routes API нужен один файл). Подробное описание доступных параметров см. здесь.
Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-citylens-api.yamldgctlDockerRegistry: docker.registry.example.comapi:auth:enabled: trueauthServerUrl: https://keycloak.hostrealm: CityLens_appstoreOIDCUserinfoFields: []predictorsTokens:camcom: tokenlicensing:url: 'https://license.svc'ingress:className: nginxenabled: falsehosts:- host: citylens-api.hostpaths:- path: /pathType: Prefixtls:- hosts:- citylens-api.hostweb:auth:enabled: truerealm: Inspection_Portal_backendauthServerUrl: https://keycloak.hostclientId: citylens-web-clientclientSecret: secretpkce: falseingress:className: nginxenabled: truehosts:- host: citylens-web.hostpaths:- path: /pathType: Prefixtls:- hosts:- citylens-web.hostworker:camcomSender:enabled: trueapiKey: keyendpointUrl: http://camcom-mock-service/user_uploadsourceEnv: testreporterPro:enabled: truepredictors: [camcom]replicas: 1kafka:bootstrapServer: kafka1.host:9092,kafka2.host:9092,kafka3.host:9092username: kafkapassword: kafka_passwordtopics:frames: framestracks: trackspro: proproObjects: objectsproDrivers: driverslogs: logsuploader: uploaderframesLifecycle: flifecycletracksLifecycle: tlifecycleobjectsLifecycle: olifecyclepredictions: predictionsconsumerGroups:prefix: citylens_s3:endpoint: https://s3.hostaccessKey: PHEI4AHTHEETHAHXEEGEsecretAccessKey: aiw6ahlaeshahngaiJaebie6aeth0aiV2pucuey1bucketPrefix: onprem-citylens # приложение само создаст бакет вида bucketPrefix + %Y%mlogsBucketPrefix: citylens-logsverifySsl: truesetPublicReadACL: falsedgctlStorage:host: artifacts.example.comsecure: truebucket: onpremise-artifactsaccessKey: AKIAIOSFODNN7EXAMPLEsecretKey: wJalrXUtnFEMIK7MDENGbPxRfiCYEXAMPLEKEYmanifest: manifests/citylens/1640661259.jsonpostgres:host: postgres.hostport: 5432database: citylensusername: citylenspassword: citylensroutes:api:ingress:enabled: trueclassName: nginxhosts:- host: citylens-routes-api.ingress.hostpaths:- path: /pathType: Prefix- hosts:- citylens-routes-api.ingress.hostsecretName: secret.tlsimagePullSecrets: [onpremise-registry-creds]adminCredentials:username: adminpassword: secret_passwordcookieSigningKey: randomKeyendpointInternalApiKey:dataScience: 451d6159-191a-4391-bf1e-c36224a859d2randomKeycompanies: fc3b5fa0-aa2a-488a-9fa6-bf6fe3f42b6frandomKeyusers: 4230b288-301e-4ec6-82c6-db6a8a72c2afrandomKeyworker:busConfig:consumers:appEvents:groupId: ''postgres:api:database: routeshangfire:database: hangfirerealtimeDataApi:database: realtime_datanavi:url: http://navi-frontkey: keypro:authorizationToken: ''keys:url: http://keys-apirealtimeData:url: https://realtimedata-api.hostdashboardDomain: https://citylens-web.hostlocale: enmap:tileserverUrl: https://tiles-api-raster.hostmapgl:host: mapgl-js-api.hostkey: keypro:baseUrl: https://pro-api.hostkey: keyverifySsl: trueframesAssetId: ''objectsAssetId: ''customCAs:bundle: ''# bundle: |# -----BEGIN CERTIFICATE-----# ...# -----END CERTIFICATE-----certsPath: ''Где:
-
dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в форматеHOST:PORT. -
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.accessKey: идентификатор ключа для доступа к бакету S3.secretAccessKey: секретный ключ для доступа к бакету S3.bucketPrefix: префикс имени бакета S3 для бакетов кадров.logsBucketPrefix: префикс имени бакета S3 для бакетов логов мобильных приложений.verifySsl: включить ли проверку SSL-сертификатов при подключении кs3.endpoint.setPublicReadACL: сделать ли S3-бакет публичным (просмотр кадров будет доступен без авторизации).
-
dgctlStorage: настройки доступа к хранилищу артефактов установки.host: endpoint S3-совместимого хранилища артефактов установки в форматеHOST:PORT.secure: использовать ли HTTPS для работы с S3-совместимым хранилищем. Значение по умолчанию:false.bucket: имя бакета S3.accessKey: идентификатор ключа для доступа к бакету S3.secretKey: секретный ключ для доступа к бакету S3.manifest: путь до файла с манифестом в форматеmanifests/citylens/1640661259.json. Этот файл содержит в себе описания фрагментов данных, которые требуются сервисам для работы. См. Жизненный цикл артефактов установки.
-
postgres: настройки доступа к PostgreSQL.host: адрес или IP PostgreSQL read-write (rw) хоста.port: номер порта PostgreSQL.database: имя БД.username: имя пользователя БД c rw-доступом.password: пароль пользователя БД.
-
routes: настройки CityLens Routes API.api.ingress:конфигурация ресурса Ingress. Адаптируйте приведённую конфигурацию для соответствия используемому вами Ingress. URL, указанный в параметреingress.hosts.host, должен быть доступен извне вашего кластера Kubernetes, чтобы пользователи из приватного сегмента сети могли получить доступ к ресурсам по этому URL.imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС.adminCredentials: настройки доступа к Hangfire (Планировщику задач).username: имя пользователя. Обязательный параметр.password: пароль. Обязательный параметр.cookieSigningKey: ключ для подписи файлов cookie. Ключ должен быть уникальным и состоять минимум из 32 символов. Обязательный параметр.
endpointInternalApiKey: ключи для доступа к внутренним сервисам без авторизации.dataScience: ключ доступа к контроллеру Data Science. Ключ должен быть уникальным и состоять из букв и цифр. Обязательный параметр.companies: ключ доступа к контроллеру компаний. Ключ должен быть уникальным и состоять из букв и цифр. Обязательный параметр.users: ключ доступа к контроллеру пользователей. Ключ должен быть уникальным и состоять из букв и цифр. Обязательный параметр.
worker.busConfig.consumers.appEvents.groupId: ID потребительской группы Kafka для передачи событий.postgres: настройки доступа к PostgreSQL.api.database: имя базы данных для доступа API.hangfire.database: имя базы данных для доступа Hangfire (Планировщика задач).realtimeDataApi.database: имя базы данных для доступа RealtimeData API (для получения текущей геопозиции водителя).
navi: настройки для интеграции с API навигации.url: URL для доступа к Navi-Front.key: ключ для доступа к API навигации. Убедитесь, что выполнены следующие условия:- Этот ключ содержит права доступа к Routes Planner API.
- Соответствующий сервисный токен из сервиса API-ключей добавлен в конфигурационный файл Navi-Router (параметр
keys.apis.route-planner-api).
pro: настройки для интеграции с 2ГИС Про.authorizationToken: Bearer-токен для отправки данных в Про. Подробнее см. в инструкции по загрузке данных по API.
keys.url: endpoint сервиса API-ключей.realtimeData: настройки для интеграции с RealtimeData API.url: URL для доступа к RealtimeData 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: директория для монтирования сертификата внутри контейнера.
-
-
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл
values-citylens-api.yaml:helm upgrade --install --version=VERSION --atomic --values ./values-citylens-api.yaml citylens 2gis-on-premise/citylensВ параметре
--versionукажите нужную версию 2ГИС Ситискан. Список версий см. в разделе Релизы 2ГИС Ситискан.предупреждениеВерсии сервисов внутри компонента должны быть одинаковыми и совпадать с версией компонента.
Установите CityLens Routes UI
-
Создайте конфигурационный файл для Helm. Подробное описание доступных параметров см. здесь.
Пример файла уже заполнен всеми необходимыми данными, собранными на предыдущих этапах.
values-citylens-ui.yamldgctlDockerRegistry: docker.registry.example.comimagePullSecrets: [onpremise-registry-creds]env:CATALOG_API_KEY: ''CATALOG_API_URL: 'https://catalog-api.ingress.host'MAPGL_API_URL: 'https://mapgl-js-api.ingress.host'MAPGL_DEFAULT_CENTER: ''MAPGL_KEY: ''SSO_API_URL: https://keycloak.example.com/realms/platformSSO_CLIENT_ID: platformSSO_CLIENT_SECRET: secretSSO_SCOPE: 'openid email name phone'ROUTES_API_URL: 'https://citylens-routes-api.ingress.host'Где:
-
dgctlDockerRegistry: endpoint вашего реестра Docker, в котором находятся образы сервисов программного комплекса 2ГИС в форматеHOST:PORT. -
imagePullSecrets: Kubernetes Secrets для доступа к реестру Docker, в котором находятся образы сервисов программного комплекса 2ГИС. -
env: настройка окружения.CATALOG_API_KEY: ключ для доступа к Catalog APIs.CATALOG_API_URL: базовый URL для Catalog APIs.MAPGL_API_URL: базовый URL для MapGL JS API.MAPGL_DEFAULT_CENTER: координаты центра карты по умолчанию в форматедолгота,широта(например,37.61565,55.76805).MAPGL_KEY: ключ для доступа к MapGL JS API.SSO_API_URL: базовый URL для API авторизации по технологии единого входа (SSO) в формате<origin>/realms/<realm>(например,https://<domain>.com/realms/Inspection_Portal_backend).SSO_CLIENT_ID: идентификатор клиента OpenID для SSO-авторизации.SSO_CLIENT_SECRET: ключ клиента OpenID для SSO-авторизации.SSO_SCOPE: набор пользовательских атрибутов, которые запрашивает клиент OpenID для SSO-авторизации.ROUTES_API_URL: базовый URL для CityLens Routes API.
-
-
Установите сервис с помощью Helm, используя подготовленный конфигурационный файл
values-citylens-ui.yaml:helm upgrade --install --version=VERSION --atomic --values ./values-citylens-ui.yaml citylens 2gis-on-premise/citylensВ параметре
--versionукажите нужную версию 2ГИС Ситискан. Список версий см. в разделе Релизы 2ГИС Ситискан.предупреждениеВерсии сервисов внутри компонента должны быть одинаковыми и совпадать с версией компонента.
4. Проверьте работоспособность 2ГИС Ситискан
Воспользуйтесь одним из способов:
- Перейдите по адресу http://citylens-web.host.
- Запустите мобильное приложение 2ГИС Ситискан.
5. Настройте аутентификацию пользователей
Настройте внешнего поставщика OpenID Connect для аутентификации конечных пользователей в 2ГИС Ситискан.
6. После установки
Если вы устанавливаете версию 2ГИС Ситискан 2.3.0 или выше:
- Откройте панель администратора по адресу
https://citylens-routes-api.ingress.host/internal/admin, используя доступы из блока параметровroutes.adminCredentials. - Назначьте роль Владелец хотя бы одному пользователю.
- Перейдите на вкладку Hangfire Dashboard → Recurring Jobs и запустите вручную MigrateUserRolesJob для миграции пользователей.
После установки 2ГИС Ситискан в вашем контуре и настройки доступов конечные пользователи могут начать работу с продуктом. Подробные инструкции см. в Руководстве пользователя.
Что дальше?
-
Узнайте, как обновить 2ГИС Ситискан.
-
Установите другие продукты программного комплекса 2ГИС:
-
Изучите рекомендации по обслуживанию системы.