ClickHouse и пользовательские отчёты: настройка через pyrus-setup

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

Подробнее о назначении и преимуществах пользовательских отчетов

Движок отчётов работает на базе ClickHouse. Все операции по настройке выполняются с помощью специального мигратора pyrus-setup. Он запускается как разовый контейнер через команду docker-compose run --rm.

1. Переменные окружения для контейнера ClickHouse

  clickhouse:
    image: cr.yandex/crpl4n1nijtqddto2029/dev-pyrus-clickhouse:1.26.0
    container_name: pyrus-clickhouse
    environment:
      - CLICKHOUSE_USER=default
      - CLICKHOUSE_PASSWORD=default
      - CLICKHOUSE_DB=public
      - CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1
    volumes:
      - pyrus_clickhouse_data:/var/lib/clickhouse
      - pyrus_clickhouse_logs:/var/log/clickhouse-server
    networks:
      - pyrus-backend

Создание пользователей, выдача прав и смена паролей — это стандартные операции ClickHouse. Вот полезные ссылки на документацию:

• Пользователи и пароли в users.xml: https://clickhouse.com/docs/operations/settings/settings-users
• CREATE USER: https://clickhouse.com/docs/sql-reference/statements/create/user
• ALTER USER (в том числе и для смены пароля): https://clickhouse.com/docs/sql-reference/statements/alter/user
• SQL-управление доступами: https://clickhouse.com/docs/operations/access-rights

Если вы меняете пароль, не забудьте передать новые данные в Pyrus. Для этого используйте команду enable-report-engine из следующего раздела.

2. enable-report-engine — включение и настройка

Что делает команда:

1. сохраняет параметры подключения к ClickHouse в конфигурации Pyrus;
2. приводит схему ClickHouse к актуальной версии (накатывает миграции);
3. включает фича-флаг ReportEngine;
4. запускает online‑краулер, который переносит новые события в аналитическую базу.

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

Параметры:

Как определяются значения: явный аргумент → значение, уже сохранённое в конфигурации → стандартное значение по умолчанию.

Если параметр не передан — он не перезаписывается.

SingleNode:

docker-compose run --rm pyrus-setup enable-report-engine \
  --clickhouseMode SingleNode \
  --clickhouseHost pyrus-clickhouse \
  --clickhousePort 8123 \
  --clickhouseUser default \
  --clickhousePassword 'ПАРОЛЬ'

Replicated (кластер):

docker-compose run --rm pyrus-setup enable-report-engine \
  --clickhouseMode Replicated \
  --clickhouseCluster ИМЯ_КЛАСТЕРА \
  --clickhouseHost clickhouse-01 \
  --clickhousePort 8123 \
  --clickhouseUser pyrus_writer \
  --clickhousePassword 'ПАРОЛЬ'

Хотите только сменить пароль в конфигурации Pyrus — остальные параметры останутся прежними:

docker-compose run --rm pyrus-setup enable-report-engine \
  --clickhouseMode SingleNode \
  --clickhouseUser default \
  --clickhousePassword 'НОВЫЙ_ПАРОЛЬ'

После смены пароля перезапустите потребителей:

docker-compose restart pyrus-web-api pyrus-async-worker

3. disable-report-engine — отключение

Что делает команда: останавливает online‑краулер и снимает фича-флаг ReportEngine.

Параметров у команды нет.

docker-compose run --rm pyrus-setup disable-report-engine

А если хотите просто посмотреть текущее состояние флага (без изменений):

docker-compose run --rm pyrus-setup --setflag -f ReportEngine -v true -ls

4. --notes-to-analytic — индексация истории

Что делает команда: переносит уже накопленные исторические комментарии к задачам в аналитическую базу ClickHouse. Когда вы включаете движок отчётов, он обрабатывает только новые события. А чтобы по историческим данным тоже можно было строить отчёты, нужен этот отдельный запуск.

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

Параметры:

Пробный запуск только для одной формы:

docker-compose run --rm pyrus-setup --notes-to-analytic -pc 2 -forms 12345

Полный прогон:

docker-compose run --rm pyrus-setup --notes-to-analytic -pc 2

Запуск с повышенной нагрузкой:

docker-compose run --rm pyrus-setup --notes-to-analytic -prof Medium -pc 4

Возобновление после остановки:

docker-compose run --rm pyrus-setup --notes-to-analytic -pc 2 -start 372820809

5. Где хранятся настройки в Pyrus

Когда вы выполняете enable-report-engine, значения записываются в конфигурацию Pyrus. Вот каким ключам конфигурации соответствует каждый параметр:

Обратите внимание: пароль хранится зашифрованным, поэтому меняйте его только через команду enable-report-engine. Не пытайтесь править его напрямую в базе или через SQL-запросы.