Как настроить BI Конструктор для закрытой коробочной версии Битрикс24

BI Конструктор — инструмент для создания отчетов бизнес-аналитики на основе Apache Superset. В нем можно создавать аналитические отчеты на основе данных из вашего Битрикс24. В коробочной версии он работает как отдельное окружение: сначала его разворачивают через Docker, а потом подключают к Битрикс24 в настройках модуля BI-коннектор.

Docker — платформа для запуска приложений в контейнерах. Контейнер хранит все, что нужно приложению для работы: код, библиотеки и системные инструменты. Так BI Конструктор запускается как готовая сборка, а не настраивается вручную по частям.

В сборку входят:

• Apache Superset — основа BI Конструктора. В нем создают отчеты, графики и дашборды.
• Trino — движок для запросов к данным. Он получает данные из Битрикс24 и передает их в отчеты.
• База данных — хранит служебные данные BI Конструктора: настройки, пользователей, отчеты, графики и подключения.
• nginx — веб-сервер. Он принимает запросы к BI Конструктору и помогает открывать его в браузере.

Эти компоненты запускаются в отдельных Docker-контейнерах, а управляет ими Docker Compose — инструмент для управления контейнерами.

В статье расскажем, как подготовить сервер, запустить BI Конструктор, подключить его к коробочной версии Битрикс24 и что проверить при ошибках.

Что подготовить до начала настройки

Обновите Битрикс24. Локальный режим работы BI Конструктора доступен начиная с версий модулей:

• BI-коннектор (biconnector) — от 26.1050.0,
• BI Конструктор (superset) — от 26.400.0,
• Главный модуль (main) — от 26.750.0.

Посмотреть версии можно в разделе Настройки > Настройки продукта > Модули. Если хотя бы одна ниже, сначала обновите — иначе вкладка BI Конструктор в настройках не появится.

Расширение лицензии. Чтобы использовать свой сервер с BI Конструктором, нужно расширение лицензии Энтерпрайз. Оно включает локальный режим работы BI Конструктора — без него в коробочной версии доступен только облачный BI Конструктор. Купить расширение можно на сайте 1С-Битрикс.

Ссылка на покупку есть и в самом Битрикс24 — в разделе Настройки > Настройки продукта > Настройки модулей > BI-коннектор > BI Конструктор, рядом с переключателем режима работы. После оплаты вы получите купон — активируйте его в административном разделе, и локальный режим станет доступен.

Для установки BI Конструктора нужен сервер с Docker. Сборку можно развернуть на отдельном сервере или на том же сервере, где работает коробочная версия Битрикс24.

Сборке нужно не меньше 12 ГБ оперативной памяти, 8 ядер процессора и 40 ГБ свободного места там, где Docker хранит данные. Если планируете пользовательские отчеты и большие выгрузки, лучше заложить от 16 ГБ памяти и от 100 ГБ диска. Основной потребитель ресурсов — Trino: если увеличите его лимиты в файле .env, требования к серверу вырастут.

Перед настройкой проверьте, что сервер BI Конструктора видит Битрикс24 по сети. Например, если Битрикс24 открывается в браузере с компьютера, это еще не значит, что он доступен с сервера, где работает Docker. Если BI Конструктор и Битрикс24 работают на одном сервере, проверьте, что в /etc/hosts прописаны имена хостов Битрикс24 и BI Конструктора. Это нужно, чтобы контейнеры могли обращаться к нужным адресам внутри сервера.

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

• Docker Engine on Linux
• Docker Desktop on Windows
• Docker Desktop on Linux
• Docker Desktop on Mac

После установки проверьте, что Docker работает на сервере.

• Выполните команду docker --version.
• Затем проверьте Docker Compose командой docker compose version.

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

Скачайте файлы сборки BI Конструктора. Файлы находятся в репозитории: https://github.com/bitrix-tools/bi-builder. Скачайте сборку на сервер и разместите ее в отдельной папке, например bi-builder. Не храните ее вместе с другими проектами: команды Docker Compose нужно выполнять из папки, где находится файл docker-compose.yml.

Проверьте, что внутри папки есть основные файлы:

• docker-compose.yml — описание всех сервисов сборки,
• docker-init.sh — первичная настройка базы данных,
• .env.example — шаблон для файла .env,
• generate-env.sh — генерация файла .env с паролями и ключами,
• generate-ssl.sh — генерация самоподписанных SSL-сертификатов,
• nginx.conf — настройки веб-сервера nginx,
• superset_config.py — настройки Apache Superset.

Как запустить сборку BI Конструктора

Все команды выполняйте в терминале на сервере из папки со сборкой. В папке должен находиться файл docker-compose.yml. Ниже — общий порядок запуска: создать файл .env, проверить адрес Битрикс24, сгенерировать SSL-сертификаты и запустить контейнеры.

1. Перейдите в папку со сборкой. Откройте терминал на сервере и перейдите в папку, где находится файл docker-compose.yml.
2. Создайте файл .env. Файл хранит настройки BI Конструктора: адрес коробочной версии Битрикс24, пароли, ключи и параметры контейнеров. Чтобы создать файл, выполните команду ./generate-env.sh. Скрипт попросит выбрать протокол подключения к Битрикс24: http или https. Укажите нужный вариант: 1 или 2. Затем введите адрес коробочной версии Битрикс24, к которой подключаете BI Конструктор. После этого скрипт создаст файл .env, подставит в него выбранные параметры и сгенерирует служебные ключи.
3. Проверьте адрес Битрикс24 в .env. Откройте файл .env и проверьте параметр BX_PORTAL_URL. В нем должен быть адрес коробочной версии Битрикс24, который вы указали при запуске скрипта. Trino использует этот адрес, чтобы получать данные из Битрикс24.
4. Подготовьте SSL-сертификаты. Порядок действий зависит от того, где будет работать BI Конструктор.
   Рабочая среда. Понадобится сертификат, который выдал доверенный центр сертификации (CA) на домен, по которому будет открываться BI Конструктор. Например, если BI Конструктор доступен по адресу bi.company.ru, сертификат нужен именно на этот домен. Скопируйте свои файлы cert.pem и key.pem в папку ssl/ — если такой папки нет, создайте ее.
   Тестовый стенд. Здесь достаточно самоподписанных сертификатов. Выполните команду ./generate-ssl.sh — скрипт создаст папку ssl/ и файлы сертификатов: ssl/cert.pem и ssl/key.pem. Браузер будет показывать предупреждение о том, что сертификат ненадежный, — для тестового стенда это нормально.
5. Запустите контейнеры. Выполните команду docker compose up -d. Первый запуск может занять время: Docker подготовит сервисы BI Конструктора. В консоли будут отображаться статусы контейнеров. Когда контейнер bi_builder_superset_init перейдет в статус Exited, инициализация завершится. Статус Exited для bi_builder_superset_init — это нормально: контейнер выполнил первичную настройку и завершил работу.
6. Откройте BI Конструктор в браузере. Перейдите по адресу https://<адрес-сервера>. Если сборка запустилась, откроется страница с предложением подключить BI Конструктор к Битрикс24 — так и должно быть: пока он не подключен, интерфейс закрыт.

Как подключить BI Конструктор к Битрикс24

1. В административном разделе откройте Настройки > Настройки продукта > Модули и проверьте, что модуль superset установлен.

   

2. Перейдите в раздел Настройки > Настройки продукта > Настройки модулей > BI-коннектор > BI Конструктор.

   

3. В поле Режим работы BI Конструктора выберите Локальный. Битрикс24 покажет окно подтверждения. Подтвердите отключение от облачного BI Конструктора, чтобы продолжить настройку локального подключения.

   

4. В поле адреса укажите IP-адрес или доменное имя сервера, где развернут BI Конструктор. Если коробочная версия Битрикс24 работает в виртуальной машине, а BI Конструктор запущен на другом сервере или компьютере, не указывайте localhost. Для виртуальной машины localhost — это сама виртуальная машина, а не сервер с BI Конструктором. В этом случае укажите адрес сервера, где работает Docker. В поле пароля укажите значение BI_BUILDER_ADMIN_PASSWORD из файла .env и сохраните настройки подключения.

   

Если адрес и пароль указаны верно, подключение сохранится без ошибок.

Теперь BI Конструктор доступен. Перейдите на страницу входа https://<адрес-сервера>/login/?form=y и укажите данные из файла .env: логин — admin, пароль — значение BI_BUILDER_ADMIN_PASSWORD.

Если настройки не сохранились, проверьте:

• правильно ли указан адрес BI Конструктора,
• доступен ли BI Конструктор с сервера, где работает Битрикс24,
• совпадает ли пароль со значением BI_BUILDER_ADMIN_PASSWORD из файла .env,
• не блокируют ли подключение firewall или сетевые настройки виртуальной машины.

Например, если BI Конструктор открывается в браузере на вашем компьютере, но не открывается с сервера Битрикс24, проблема может быть в сетевом доступе, а не в пароле.

После подключения можно работать с отчетами из Битрикс24. При открытии отчета BI Конструктор автоматически авторизует пользователя и применяет его права доступа. Учетную запись admin используйте только для настройки служебного подключения.

Как обновить или перезапустить BI Конструктор

Все команды выполняйте из папки со сборкой, где находится файл docker-compose.yml. Не меняйте ключи и пароли без необходимости. Файл .env хранит служебные пароли и ключи BI Конструктора.

Изменить пароль администратора. Если пароль admin все же нужно сменить, помните: правки в файле .env для этого недостаточно — в самом BI Конструкторе пароль останется прежним. Чтобы сменить его, подключитесь к контейнеру Superset командой docker compose exec superset sh и выполните superset fab reset-password --username admin --password <новый-пароль>. Затем укажите новый пароль в разделе Настройки > Настройки продукта > Настройки модулей > BI-коннектор > BI Конструктор, иначе Битрикс24 не сможет подключиться к BI Конструктору.

Перезапустить BI Конструктор. Если нужно перезапустить контейнеры, выполните команду docker compose restart. Проверьте состояние контейнеров: docker compose ps.

Остановить и снова запустить BI Конструктор. Чтобы остановить контейнеры, выполните команду docker compose down. Чтобы запустить их снова, выполните docker compose up -d.

Обновить BI Конструктор. Перед обновлением рекомендуем сделать резервную копию. Для обновления выполните команды docker compose down, docker compose pull, docker compose up -d. После обновления откройте Настройки > Настройки продукта > Настройки модулей > BI-коннектор > BI Конструктор и проверьте текущую версию BI Конструктора.

Возможные ошибки при запуске и подключении

Если BI Конструктор не открывается, отчеты не получают данные или появляются ошибки авторизации, сначала проверьте контейнеры, настройки подключения и доступность коробочной версии Битрикс24 по сети.

BI Конструктор не запускается. Сначала проверьте логи контейнеров:

• контейнера инициализации: docker compose logs superset-init,
• базы данных: docker compose logs mysql,
• Superset: docker compose logs superset.

Например, если bi_builder_superset_init завершился с ошибкой, BI Конструктор может не открыться, потому что база данных еще не подготовлена.

Ошибка HTTP_ERROR при запросе данных из Битрикс24. Проверьте параметр BX_PORTAL_URL в файле .env. В нем должен быть указан актуальный адрес коробочной версии Битрикс24. Trino использует этот адрес, чтобы получать данные из Битрикс24. Если BI Конструктор и Битрикс24 работают на разных серверах, проверьте, что сервер BI Конструктора видит Битрикс24 по сети. Если оба сервиса работают на одном сервере, проверьте записи в /etc/hosts и доступность нужного порта. Например, если в .env указан старый IP-адрес Битрикс24, отчеты не смогут получить данные.

Ошибка WRONG_KEY при запросе данных из Битрикс24. Обновите ключ шифрования в разделе Настройки > Настройки продукта > Настройки модулей > BI-коннектор > BI Конструктор. Эта ошибка связана не с запуском Docker, а со связью между Битрикс24 и BI Конструктором.

В графиках загружаются не все данные. Откройте подробности ошибки в графике и проверьте два частых сценария:

1. Trino не хватает процессорных ресурсов. Увеличьте параметр TRINO_CPUS в файле .env, затем перезапустите контейнеры: docker compose restart.
2. Запрос выгружает слишком много данных. Добавьте фильтры в запрос или в дашборд. Запрашивайте только те колонки, которые нужны для отчета. Не используйте select *, если для отчета нужны только две или три колонки. Например, если график показывает количество сделок по месяцам, не нужно выгружать все поля сделок. Достаточно полей с идентификатором, датой и нужным показателем.

Ошибка 502 Gateway или OutOfMemoryError. Такая ошибка может появиться, если Trino не хватает памяти. Проверьте логи Trino: docker compose logs trino | grep -i "OutOfMemoryError". Если в логах есть OutOfMemoryError, увеличьте параметры в файле .env: TRINO_MEM_LIMIT и TRINO_JVM_XMX. После изменения пересоздайте контейнер Trino: docker compose up -d --force-recreate trino.
Перед увеличением памяти проверьте, что на сервере достаточно ресурсов.

Ошибка Max requests queued per destination xxx exceeded. Ошибка связана с очередью запросов. Она может появиться, если несколько пользователей одновременно открывают тяжелые отчеты. Увеличьте параметр в файле .env: TRINO_MAX_REQUESTS_QUEUED. После изменения перезапустите контейнеры: docker compose restart.

Ошибка «Доступ закрыт. Для восстановления доступа откройте раздел BI Конструктор в Битрикс24». Ошибка связана с авторизацией между Битрикс24 и BI Конструктором. Она может появиться после изменения ключей безопасности или проблем с бесшовной авторизацией. В административном разделе откройте Настройки > Настройки продукта > Настройки модулей > BI-коннектор. Перейдите на вкладку BI Конструктор и обновите публичный ключ JWT.

Ошибка SSL или nginx. Проверьте, есть ли сертификаты на месте: ls -la ssl/. В папке должны лежать файлы cert.pem и key.pem. Если папки или файлов нет, добавьте сертификаты: в рабочей среде положите в папку ssl/ свои сертификаты, на тестовом стенде выполните команду ./generate-ssl.sh. Проверьте логи nginx: docker compose logs nginx.
Например, если сертификаты не создались, nginx может не запуститься, а страница BI Конструктора не откроется по HTTPS.

Как сбросить настройки BI Конструктора

Если нужно начать настройку заново, можно полностью сбросить текущие данные BI Конструктора. Сброс удалит отчеты, графики, датасеты и служебные данные без возможности восстановления. Используйте сброс только для тестового стенда или если нужно начать с чистого состояния.

Если данные нужно сохранить, сначала сделайте резервную копию. Отчеты, датасеты и настройки BI Конструктора хранятся в томах Docker, а не в папке со сборкой, поэтому скопировать папку недостаточно. Вместе с копией базы обязательно сохраните файл .env — ключи из него шифруют пароли подключений, и без этого файла копия не поможет. Команды для копирования и восстановления есть в README сборки.

Для сброса выполните команды:

• docker compose down -v
• docker compose up -d

После сброса обязательно обновите настройки на стороне Битрикс24, иначе данные портала и BI Конструктора останутся рассинхронизированными и отчеты будут работать некорректно. Откройте Настройки > Настройки продукта > Настройки модулей > BI-коннектор > BI Конструктор и переключите режим работы на Облачный.

Если после сброса вы подключаете портал к другой инсталляции BI Конструктора, переключите режим на Облачный, сохраните настройки, а затем снова выберите Локальный и укажите новый адрес BI Конструктора. Например, если вы перенесли сборку на другой сервер, недостаточно просто поменять адрес в поле — сначала нужно переключиться на облачный режим и сохранить.

После этого проверьте работу отчетов.

Подробную информацию о работе с BI Конструктором читайте в статьях:

• BI Конструктор для создания аналитических отчетов
• Как создавать отчеты в BI Конструкторе
• Как редактировать отчеты в BI Конструкторе