clickstream-data-platform/README.md

Учебная дата-платформа кликстрима

Этот стенд — для менти, который видит такую систему впервые и хочет проследить весь путь данных: от кликстрима и заказов до витрин, проверок и графиков. Преемник учебного стенда clickstream-ch-kafka-superset-demo.

Поднять стенд поможет «Быстрый старт», выключить — make down. Чтобы разобраться в устройстве, начните с путеводителя, а учиться — с уроков.

Статус

Репозиторий строится по спеке «Боевой реализм стенда (v2)». Сейчас работают кластер ClickHouse из двух шардов, отдельный clickhouse-keeper, односерверная Kafka в режиме KRaft, Airflow 3.3, Superset, Prometheus, Grafana, экспортёр метрик Kafka и общая база Postgres для метаданных. Генератор кликстрима в generator/ собран целиком со стороны клиента: у него есть контракт схемы события, из которого собрано описание выгрузки, модельный мир и проигрыватель, отправляющий дни в Kafka или в файл. События доезжают до типизированного ods.event, а dds.event_v отдаёт их на языке бизнес-модели без копии данных. make up наполняет стенд стартовым миром — первой неделей модельного времени.

Быстрый старт

Нужны Docker с Compose и около 8 ГБ памяти, доступной Docker. Это не объём ноутбука, а то, что отдано самому Docker: в Docker Desktop и WSL2 он живёт внутри виртуальной машины и получает лишь часть памяти хозяина. Сколько выдано сейчас, в байтах, покажет docker info --format '{{.MemTotal}}'. В WSL2 это поднимается параметром memory в файле .wslconfig домашнего каталога пользователя Windows; после правки нужен wsl --shutdown. Если своей машины не хватает, стенд одинаково хорошо живёт на недорогом VPS.

Проверкам на поднятом стенде также нужны curl, jq, awk, grep, sed, tail, sleep и timeout. jq нужен и самому make up: им читается паспорт мира, по которому он ждёт заливки. По умолчанию должны быть свободны порты 23000, 28080, 28088, 28123, 28124, 29000, 29001, 29090 и 29092. Проверкам без стенда — make config-test и make lint в корне, всем целям генератора в generator/ — нужен uv.

Сначала скопируйте настройки стенда:

cp .env.example .env
make up
make smoke
make check-clickhouse
make check-services

Первому знакомству нужны все три проверки на стенде: make smoke говорит, что стенд собран, make check-clickhouse — что кластер работает кластером, а make check-services — что Airflow запускает DAG, а Superset ходит в базу. Дальше, в рабочей петле, обычно хватает make smoke.

.env.example — образец обязательной локальной настройки. В нём живут имя экземпляра, внешние порты, учебные учётные данные и ключи. Одно значение образца верно не везде — DOCKER_GID: у группы docker на каждой машине свой номер, и свой подскажет getent group docker. Пока он не сойдётся, стенд работает весь, кроме дагов модельного времени. compose.yaml не дублирует их умолчаниями: если значения нет в .env, Compose сразу предложит скопировать образец. Внутренние адреса, имена топиков и версии образов описывают сам стенд, поэтому записаны литералами в compose.yaml и Dockerfile.

Учётные данные Postgres и Grafana применяются при создании их томов. После первого запуска меняйте их только вместе с make clean: команда удалит все локальные данные стенда, а следующий make up создаст их с новыми значениями.

Что делает make up, кого спрашивает каждая проверка и как устроен смоук, описано в карте проверок.

Обычный рабочий цикл — make config-test и make smoke; остальные цели гоняют тогда, когда правка их касается. Что утверждает каждая проверка, нужен ли ей поднятый стенд, сколько стоит прогон и куда класть новую — в карте проверок.

Остановить контейнеры без удаления данных можно командой make down. Если нужно вернуть прикладной мир к началу, make rebuild-storage запустит в Airflow его явную пересборку: удалит прикладные базы ClickHouse, топики и позиции потребителей Kafka, затем создаст схему и данные заново. Службы и их тома останутся на месте. make clean удаляет весь стенд вместе с именованными томами и для обычной разработки не нужен. Перед пересборкой поставьте world_live на паузу и дайте уже начатому шаговому дагу закончить день.

Стартовый мир

Стартовый мир и его паспорт описаны в справочнике мира.

Как позвать генератор

Режимы и команды запуска генератора описаны в справочнике мира.

Даги модельного времени

Даги времени, позиция мира и форма запуска описаны в справочнике мира.

Состав и доступ

С настройками из .env.example порты доступны только с локальной машины:

• нода 1 — http://127.0.0.1:28123, нативный порт 29000;
• нода 2 — http://127.0.0.1:28124, нативный порт 29001;
• Kafka — 127.0.0.1:29092;
• Airflow — http://127.0.0.1:28080, пользователь admin, пароль airflow;
• Superset — http://127.0.0.1:28088, пользователь admin, пароль superset;
• Prometheus — http://127.0.0.1:29090;
• Grafana — http://127.0.0.1:23000, пользователь admin, пароль admin.

Службы, пользователи и роли, применение настроек и результаты сверки конфигурации описаны в справочнике стенда.

Что здесь будет

• одно широкое событие кликстрима по образцу выгрузки Яндекс Метрики вместо четырёх топиков;
• второй источник — заказы бэкенда, ежедневным слепком в ту же Kafka;
• сверка клиентской покупки с заказом бэкенда: деньги считаем по бэкенду, поведение и атрибуцию — по трекеру;
• анонимный кликстрим и склейка кука↔пользователь через покупки;
• ClickHouse кластером как единственным режимом.

Чем отличается от предшественника

Предшественник остаётся стабильным учебным стендом и заморожен для новых фич: там событие разрезано на четыре топика, есть только просмотры страниц, посетители опознаны по email, ClickHouse — одна нода. Развитие идёт здесь.

Документация

• docs/handbook/ — путеводитель по стенду и порядок чтения.
• docs/labs/ — учебные задания с порядком прохождения и самопроверкой.
• docs/specs/ — спеки: источник истины о задуманном.
• docs/adr/ — принятые решения с доводами и отвергнутыми вариантами: почему сделано так, а не иначе.
• docs/architecture/ — рабочие справочники по зонам ответственности: хранилище — конвенции имён, раскладка по шардам, приём событий, карта таблиц; проверки — что утверждает каждая цель make и куда класть новую проверку.
• docs/research/ — исследования; сейчас это формат кликстрима Яндекса, по которому строится модель события.
• docs/formats/ — описания форматов источников: по ним пишется сторона хранилища. Собираются из кода командой make docs в generator/, руками не правятся.
• AGENTS.md — контракт работы в репозитории.