diff --git a/README.md b/README.md index 5aa521e..c7bb0cc 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,21 @@ # Учебная дата-платформа кликстрима -Этот стенд — для менти, который видит такую систему впервые и хочет -проследить весь путь данных: от кликстрима и заказов до витрин, проверок и -графиков. Преемник учебного стенда +> Этим стендом можно пользоваться самостоятельно. Он также входит в +> [план обучения Data Engineering Roadmap](https://de.dementev.space) как +> курсовая работа. Если вам нужна помощь, обратитесь к автору материалов — +> ментору [@dementev_dev](https://t.me/dementev_dev). + +Этот стенд — для изучения и экспериментов с кликстримом и ClickHouse. Здесь +можно проследить весь путь данных: от кликстрима и заказов до витрин, проверок +и графиков. Это преемник учебного стенда [clickstream-ch-kafka-superset-demo](https://git.dementev.space/ddmitry/clickstream-ch-kafka-superset-demo). -Поднять стенд поможет [«Быстрый старт»](#быстрый-старт), выключить — -`make down`. Чтобы разобраться в устройстве, начните с -[путеводителя](docs/handbook/README.md), а учиться — с -[уроков](docs/labs/README.md). - -## Статус - -Репозиторий строится по спеке -[«Боевой реализм стенда (v2)»](docs/specs/2026-07-30-stand-v2-realism.md). -Сейчас работают кластер ClickHouse из двух шардов, отдельный -clickhouse-keeper, односерверная Kafka в режиме KRaft, Airflow 3.3, Superset, -Prometheus, Grafana, экспортёр метрик Kafka и общая база Postgres для -метаданных. Генератор кликстрима в [`generator/`](generator/) собран -целиком со стороны клиента: у него есть контракт схемы события, из которого -собрано [описание выгрузки](docs/formats/clickstream-event.md), модельный мир и -проигрыватель, отправляющий дни в Kafka или в файл. События доезжают до -типизированного `ods.event`, а `dds.event_v` отдаёт их на языке бизнес-модели -без копии данных. `make up` наполняет стенд стартовым миром — первой неделей -модельного времени. +В стенде подняты кластер ClickHouse из двух шардов, отдельный keeper, Kafka, +Airflow, Superset, Prometheus и Grafana; события кликстрима и заказы бэкенда +приезжают из генератора и идут по слоям STG → ODS → DDS → DM. `make up` +наполняет стенд стартовым миром — первой неделей модельного времени. Чтобы +разобраться в устройстве, начните с [путеводителя](docs/handbook/README.md), а +учиться — с [уроков](docs/labs/README.md). ## Быстрый старт @@ -35,27 +27,21 @@ Prometheus, Grafana, экспортёр метрик Kafka и общая баз пользователя 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`. +`make up` нужны `curl` и `jq`: первым он ходит в Airflow, вторым читает +паспорт мира, по которому ждет заливки. По умолчанию должны быть свободны +порты `23000`, `28080`, `28088`, `28123`, `28124`, `29000`, `29001`, `29090` +и `29092`. Всем целям генератора в `generator/` нужен `uv`. Сначала скопируйте настройки стенда: ```bash 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`. +`make up` сам ждет заливки стартового мира; что он делает по шагам и какие +проверки есть у стенда, описано в [карте +проверок](docs/architecture/testing.md). `.env.example` — образец обязательной локальной настройки. В нём живут имя экземпляра, внешние порты, учебные учётные данные и ключи. Одно значение образца @@ -72,38 +58,7 @@ make check-services все локальные данные стенда, а следующий `make up` создаст их с новыми значениями. -Что делает `make up`, кого спрашивает каждая проверка и как устроен смоук, -описано в [карте проверок](docs/architecture/testing.md). - -Обычный рабочий цикл — `make config-test` и `make smoke`; остальные цели гоняют -тогда, когда правка их касается. Что утверждает каждая проверка, нужен ли ей -поднятый стенд, сколько стоит прогон и куда класть новую — в -[карте проверок](docs/architecture/testing.md). - -Остановить контейнеры без удаления данных можно командой `make down`. Если нужно -вернуть прикладной мир к началу, `make rebuild-storage` запустит в Airflow его -явную пересборку: удалит прикладные базы ClickHouse, топики и позиции -потребителей Kafka, затем создаст схему и данные заново. Службы и их тома -останутся на месте. `make clean` удаляет весь стенд вместе с именованными томами -и для обычной разработки не нужен. Перед пересборкой поставьте `world_live` на -паузу и дайте уже начатому шаговому дагу закончить день. - -## Стартовый мир - -Стартовый мир и его паспорт описаны в [справочнике -мира](docs/architecture/world.md). - -## Как позвать генератор - -Режимы и команды запуска генератора описаны в -[справочнике мира](docs/architecture/world.md#как-запустить-генератор). - -### Даги модельного времени - -Даги времени, позиция мира и форма запуска описаны в [справочнике -мира](docs/architecture/world.md#даги-модельного-времени). - -## Состав и доступ +## Адреса и пароли С настройками из `.env.example` порты доступны только с локальной машины: @@ -118,21 +73,37 @@ make check-services Службы, пользователи и роли, применение настроек и результаты сверки конфигурации описаны в [справочнике стенда](docs/architecture/stand.md). -## Что здесь будет +## Сдвинуть мир вперед -- одно широкое событие кликстрима по образцу выгрузки Яндекс Метрики вместо - четырёх топиков; -- второй источник — заказы бэкенда, ежедневным слепком в ту же Kafka; -- сверка клиентской покупки с заказом бэкенда: деньги считаем по бэкенду, - поведение и атрибуцию — по трекеру; -- анонимный кликстрим и склейка кука↔пользователь через покупки; -- ClickHouse кластером как единственным режимом. +В Airflow запустите даг `world_next_day`: по умолчанию он сыграет один день, а +в форме запуска можно задать другое число дней. Снимите с паузы `world_live`, +и мир поедет сам в темпе модельного времени. Подробности — в [справочнике +мира](docs/architecture/world.md#даги-модельного-времени). -## Чем отличается от предшественника +## Вернуть мир к началу -Предшественник остаётся стабильным учебным стендом и заморожен для новых фич: -там событие разрезано на четыре топика, есть только просмотры страниц, -посетители опознаны по email, ClickHouse — одна нода. Развитие идёт здесь. +`make rebuild-storage` запустит в Airflow явную пересборку: удалит прикладные +базы ClickHouse, топики и позиции потребителей Kafka, затем создаст схему +и данные заново. Службы и их тома останутся на месте. Перед пересборкой +поставьте `world_live` на паузу и дайте уже начатому шаговому дагу закончить +день. + +## Выключить или сбросить целиком + +`make down` остановит контейнеры без удаления данных. `make clean` удалит весь +стенд вместе с именованными томами и для обычной работы не нужен. + +## Подключиться из DBeaver + +Драйвер ClickHouse в DBeaver подключается по JDBC через HTTP-порт. Укажите хост +`127.0.0.1`, порт `28123`, пользователя `analyst` и пароль из переменной +`CLICKHOUSE_ANALYST_PASSWORD` в `.env`; в образце это `analyst-26-reader`. +Ко второй ноде — порт `28124`. + +Пользователь `analyst` читает все слои и справочники. Нативные порты `29000` и +`29001` нужны `clickhouse-client`, но не DBeaver. Остальные пользователи и роли +описаны в [справочнике +стенда](docs/architecture/stand.md#пользователи-и-роли-clickhouse). ## Документация @@ -143,10 +114,20 @@ make check-services - [docs/adr/](docs/adr/) — принятые решения с доводами и отвергнутыми вариантами: почему сделано так, а не иначе. - [docs/architecture/](docs/architecture/) — рабочие справочники по зонам - ответственности: [хранилище](docs/architecture/storage.md) — конвенции имён, - раскладка по шардам, приём событий, карта таблиц; - [проверки](docs/architecture/testing.md) — что утверждает каждая цель `make` - и куда класть новую проверку. + ответственности: + - [хранилище](docs/architecture/storage.md) — конвенции имён, раскладка по + шардам, приём событий, карта таблиц. + - [конвейер](docs/architecture/etl.md) — движение данных между слоями и + работа дагов. + - [мир и модельное время](docs/architecture/world.md) — начальные данные, + ход дней и управление генератором. + - [стенд](docs/architecture/stand.md) — службы, доступ и настройка. + - [проверки](docs/architecture/testing.md) — что утверждает каждая цель + `make` и куда класть новую проверку. + - [мониторинг](docs/architecture/monitoring/README.md) — сбор метрик и + устройство дашборда. + - [Superset](docs/architecture/superset.md) — подключения, наборы данных и + граница автоматической настройки. - [docs/research/](docs/research/) — исследования; сейчас это формат кликстрима Яндекса, по которому строится модель события. - [docs/formats/](docs/formats/) — описания форматов источников: по ним diff --git a/docs/adr/0007-clickhouse-access.md b/docs/adr/0007-clickhouse-access.md index 1068a82..e322580 100644 --- a/docs/adr/0007-clickhouse-access.md +++ b/docs/adr/0007-clickhouse-access.md @@ -43,7 +43,7 @@ Сетевых ограничений на `default` нет: порты стенда и так открыты только на `127.0.0.1`, а внутри сети Compose дверь заперта паролем. -Раздел README «Состав и доступ» описывает, кто каким пользователем ходит и где +Раздел README «Адреса и пароли» описывает, кто каким пользователем ходит и где живут пароли; здесь остаются решение и доводы. Отдельного справочника по доступу в `docs/architecture/` нет: точные права видны в `access.xml`, конвенция чтения через `_v` описана в доке хранилища. @@ -107,7 +107,7 @@ источник истины — файл в git. Стенд считает `access.xml` и переданные через `.env` значения настройкой при создании контейнера; отдельного способа применять их на живом стенде нет, потому что уроки не меняют базовую модель -доступа. Порядок применения изменений — в разделе README «Состав и доступ». +доступа. Порядок применения изменений — в разделе README «Адреса и пароли». Оба варианта с SQL — локальное хранилище доступа с `ON CLUSTER` и реплицированное в keeper — делают пользователей состоянием тома: `.env` на них больше не влияет, и появляется расхождение того же сорта, которое README diff --git a/docs/architecture/stand.md b/docs/architecture/stand.md index 0948ba1..ada8bff 100644 --- a/docs/architecture/stand.md +++ b/docs/architecture/stand.md @@ -4,7 +4,7 @@ настройки доходят до контейнеров. Состав каркаса обоснован в [ADR 0001](../adr/0001-stand-services.md), доступ к ClickHouse — в [ADR 0007](../adr/0007-clickhouse-access.md). Адреса и пароли интерфейсов -остаются в [корневом README](../../README.md#состав-и-доступ). +остаются в [корневом README](../../README.md#адреса-и-пароли). ## Службы diff --git a/docs/architecture/world.md b/docs/architecture/world.md index 103e9a5..2421551 100644 --- a/docs/architecture/world.md +++ b/docs/architecture/world.md @@ -111,8 +111,8 @@ uv run --project generator python -m clickstream_generator batch \ ``` За один запуск можно проиграть несколько дней подряд: `--days 8`. Всё, что -принимается флагами, принимается и переменными окружения — так генератор позовёт -даг этапа 5; полный список у `--help`. +принимается флагами, принимается и переменными окружения — так генератор +запускают даги модельного времени; полный список у `--help`. **Значения по умолчанию есть не у всех параметров, и это сделано специально.** Зерно, число дней и темп живого дня описывают модель мира — их генератор знает diff --git a/docs/handbook/README.md b/docs/handbook/README.md index 03103be..891a8a3 100644 --- a/docs/handbook/README.md +++ b/docs/handbook/README.md @@ -43,7 +43,7 @@ ### Генератор: откуда берутся данные -Для менти генератор здесь — источник данных. Глава в общих чертах объяснит, -откуда берутся события и заказы и в каком виде их получает хранилище. Пока -главы нет, смотрите [`generator/`](../../generator/) и +Здесь генератор — источник данных, а не предмет изучения. Глава в общих +чертах объяснит, откуда берутся события и заказы и в каком виде их получает +хранилище. Пока главы нет, смотрите [`generator/`](../../generator/) и [описание события кликстрима](../formats/clickstream-event.md).