ddmitry/clickstream-data-platform
1
0 Fork 0
Code Issues 5 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

docs(readme): упрощен язык вводной инструкции

Browse Source 
Зачем: помочь учащемуся понять назначение стенда и порядок работы с ним.

Что: убраны внутренние метафоры, пояснены термины, настройка перенесена перед запуском. Обновлена ссылка из путеводителя и удалена ссылка на предыдущий стенд.

Проверка: команды, адреса и пароли сохранены; 24 ссылки README и входящие ссылки на разделы проверены. git diff --cached --check прошел.
This commit is contained in:
ddadmin committed 2026-09-13 12:47:16 -04:00
1 parent 8c9c10a875
commit ce15836093
2 files changed
+99 -78
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+98 -77
View File
@@ -5,132 +5,153 @@
> курсовая работа. Если вам нужна помощь, обратитесь к автору материалов — > курсовая работа. Если вам нужна помощь, обратитесь к автору материалов —
> ментору [@dementev_dev](https://t.me/dementev_dev). > ментору [@dementev_dev](https://t.me/dementev_dev).
Этот стенд — для изучения и экспериментов с кликстримом и ClickHouse. Здесь Здесь вы будете работать с хранилищем данных небольшого интернет-магазина:
можно проследить весь путь данных: от кликстрима и заказов до витрин, проверок загружать и обрабатывать данные в ClickHouse, строить витрины, проверять
и графиков. Это преемник учебного стенда качество данных и создавать графики. Стенд рассчитан на тех, кто уже изучил
[clickstream-ch-kafka-superset-demo](https://git.dementev.space/ddmitry/clickstream-ch-kafka-superset-demo). основы ClickHouse и хочет попрактиковаться.
В стенде подняты кластер ClickHouse из двух шардов, отдельный keeper, Kafka, Генератор создает заказы и кликстрим — записи о действиях посетителей
Airflow, Superset, Prometheus и Grafana; события кликстрима и заказы бэкенда магазина. Данные поступают через Kafka в ClickHouse и проходят четыре слоя
приезжают из генератора и идут по слоям STG → ODS → DDS → DM. `make up` обработки: STG, ODS, DDS и DM. В кластере ClickHouse два шарда и отдельный
наполняет стенд стартовым миром — первой неделей модельного времени. Чтобы ClickHouse Keeper. Airflow управляет загрузкой и обработкой, Superset
разобраться в устройстве, начните с [путеводителя](docs/handbook/README.md), а показывает отчеты, а Prometheus и Grafana помогают следить за работой стенда.
учиться — с [уроков](docs/labs/README.md).
При первом запуске стенд загрузит данные за неделю работы магазина.
После запуска начните с [путеводителя](docs/handbook/README.md): он объясняет
устройство хранилища. Затем переходите к [учебным заданиям](docs/labs/README.md).
## Быстрый старт ## Быстрый старт
Нужны Docker с Compose и около 8 ГБ памяти, доступной Docker. Это не объём Для запуска нужны Docker с Compose, `make`, `curl` и `jq`.
ноутбука, а то, что отдано самому Docker: в Docker Desktop и WSL2 он живёт Выделите Docker около 8 ГБ оперативной памяти. В Docker Desktop и WSL2
внутри виртуальной машины и получает лишь часть памяти хозяина. Сколько выдано проверьте лимит памяти виртуальной машины: он может быть меньше, чем общий
сейчас, в байтах, покажет `docker info --format '{{.MemTotal}}'`. В WSL2 это объем памяти компьютера. Команда `docker info --format '{{.MemTotal}}'`
поднимается параметром `memory` в файле `.wslconfig` домашнего каталога покажет доступный Docker объем в байтах. В WSL2 лимит задается параметром
пользователя Windows; после правки нужен `wsl --shutdown`. Если своей машины не `memory` в файле `.wslconfig` в домашнем каталоге пользователя Windows.
хватает, стенд одинаково хорошо живёт на недорогом VPS. После изменения выполните `wsl --shutdown`. Если ресурсов компьютера
недостаточно, стенд можно запустить на VPS.
`make up` нужны `curl` и `jq`: первым он ходит в Airflow, вторым читает По умолчанию должны быть свободны порты
паспорт мира, по которому ждет заливки. По умолчанию должны быть свободны `23000`, `28080`, `28088`, `28123`, `28124`, `29000`, `29001`, `29090`
порты `23000`, `28080`, `28088`, `28123`, `28124`, `29000`, `29001`, `29090` и `29092`. Для работы с командами `make` в каталоге `generator/` также
и `29092`. Всем целям генератора в `generator/` нужен `uv`. понадобится `uv`.
Сначала скопируйте настройки стенда: В каталоге репозитория скопируйте образец настроек:
```bash ```bash
cp .env.example .env cp .env.example .env
```
В `.env` задаются имя экземпляра стенда, внешние порты, учебные логины,
пароли и ключи. Проверьте `DOCKER_GID`: это числовой идентификатор группы
`docker` на вашей машине. Узнать его можно командой `getent group docker`.
Если число отличается от образца, замените значение в `.env`. От этой
настройки зависит запуск генератора из Airflow.
Запустите стенд:
```bash
make up make up
``` ```
`make up` сам ждет заливки стартового мира; что он делает по шагам и какие Команда запустит службы и дождется загрузки начальных данных. Порядок запуска
проверки есть у стенда, описано в [карте и проверки результата описаны в [справочнике проверок](docs/architecture/testing.md).
проверок](docs/architecture/testing.md). Если обязательной настройки в `.env` не хватает, Compose сообщит об ошибке.
Внутренние адреса служб, имена топиков и версии образов заданы в `compose.yaml`
и Dockerfile.
`.env.example` — образец обязательной локальной настройки. В нём живут имя Логины и пароли Postgres и Grafana сохраняются при первом запуске в томах
экземпляра, внешние порты, учебные учётные данные и ключи. Одно значение образца Docker. Простая правка `.env` их не изменит. Чтобы задать новые значения
верно не везде — `DOCKER_GID`: у группы `docker` на каждой машине свой номер, и через `.env`, потребуется `make clean` и повторный `make up`. При этом
свой подскажет `getent group docker`. Пока он не сойдётся, стенд работает весь, будут удалены все локальные данные стенда.
кроме [дагов модельного
времени](docs/architecture/world.md#даги-модельного-времени). `compose.yaml` не
дублирует их умолчаниями: если значения нет в `.env`, Compose сразу предложит
скопировать образец. Внутренние адреса, имена топиков и версии образов описывают
сам стенд, поэтому записаны литералами в `compose.yaml` и Dockerfile.
Учётные данные Postgres и Grafana применяются при создании их томов.
После первого запуска меняйте их только вместе с `make clean`: команда удалит
все локальные данные стенда, а следующий `make up` создаст их с новыми
значениями.
## Адреса и пароли ## Адреса и пароли
С настройками из `.env.example` порты доступны только с локальной машины: С настройками из `.env.example` порты доступны только с локальной машины:
- нода 1 — `http://127.0.0.1:28123`, нативный порт `29000`; - узел ClickHouse 1 — `http://127.0.0.1:28123`, нативный порт `29000`;
- нода 2 — `http://127.0.0.1:28124`, нативный порт `29001`; - узел ClickHouse 2 — `http://127.0.0.1:28124`, нативный порт `29001`;
- Kafka — `127.0.0.1:29092`; - Kafka — `127.0.0.1:29092`;
- Airflow — `http://127.0.0.1:28080`, пользователь `admin`, пароль `airflow`; - Airflow — `http://127.0.0.1:28080`, пользователь `admin`, пароль `airflow`;
- Superset — `http://127.0.0.1:28088`, пользователь `admin`, пароль `superset`; - Superset — `http://127.0.0.1:28088`, пользователь `admin`, пароль `superset`;
- Prometheus — `http://127.0.0.1:29090`; - Prometheus — `http://127.0.0.1:29090`;
- Grafana — `http://127.0.0.1:23000`, пользователь `admin`, пароль `admin`. - Grafana — `http://127.0.0.1:23000`, пользователь `admin`, пароль `admin`.
Службы, пользователи и роли, применение настроек и результаты сверки Подробнее о службах, правах пользователей и изменении настроек —
конфигурации описаны в [справочнике стенда](docs/architecture/stand.md). в [справочнике стенда](docs/architecture/stand.md).
## Сдвинуть мир вперед ## Добавить данные за следующие дни
В Airflow запустите даг `world_next_day`: по умолчанию он сыграет один день, а Время в учебном магазине идет отдельно от календарного. В документации оно
в форме запуска можно задать другое число дней. Снимите с паузы `world_live`, называется модельным временем, а сам магазин с его посетителями и заказами —
и мир поедет сам в темпе модельного времени. Подробности — в [справочнике миром.
мира](docs/architecture/world.md#даги-модельного-времени).
## Вернуть мир к началу В Airflow запустите `world_next_day`. Это даг — набор связанных задач,
которые Airflow выполняет в заданном порядке. Он создаст и загрузит данные
за следующий день работы магазина. В форме запуска можно задать число дней.
`make rebuild-storage` запустит в Airflow явную пересборку: удалит прикладные Чтобы новые данные поступали непрерывно, снимите с паузы даг `world_live`.
базы ClickHouse, топики и позиции потребителей Kafka, затем создаст схему Он будет запускать генерацию день за днем; один модельный день занимает
и данные заново. Службы и их тома останутся на месте. Перед пересборкой около 24 минут. Подробности — в [справочнике генератора и модельного
поставьте `world_live` на паузу и дайте уже начатому шаговому дагу закончить времени](docs/architecture/world.md#даги-модельного-времени).
день.
## Выключить или сбросить целиком ## Восстановить начальные данные
`make down` остановит контейнеры без удаления данных. `make clean` удалит весь Если хотите начать заново, поставьте `world_live` на паузу и дождитесь
стенд вместе с именованными томами и для обычной работы не нужен. завершения уже запущенного дага генерации. Затем выполните
`make rebuild-storage`.
Команда удалит прикладные базы ClickHouse, топики и позиции потребителей
Kafka, затем заново создаст схему хранилища и загрузит начальные данные.
Службы и их тома останутся на месте.
## Остановить или удалить стенд
`make down` остановит стенд и сохранит данные. Для повторного запуска
выполните `make up`.
`make clean` удалит контейнеры и все данные в томах Docker. Для обычного
завершения работы достаточно `make down`.
## Подключиться из DBeaver ## Подключиться из DBeaver
Драйвер ClickHouse в DBeaver подключается по JDBC через HTTP-порт. Укажите хост Драйвер ClickHouse в DBeaver подключается по JDBC через HTTP-порт. Укажите хост
`127.0.0.1`, порт `28123`, пользователя `analyst` и пароль из переменной `127.0.0.1`, порт `28123`, пользователя `analyst` и пароль из переменной
`CLICKHOUSE_ANALYST_PASSWORD` в `.env`; в образце это `analyst-26-reader`. `CLICKHOUSE_ANALYST_PASSWORD` в `.env`; в образце это `analyst-26-reader`.
Ко второй ноде — порт `28124`. Для подключения ко второму узлу укажите порт `28124`.
Пользователь `analyst` читает все слои и справочники. Нативные порты `29000` и Пользователь `analyst` может читать данные во всех слоях и справочниках.
`29001` нужны `clickhouse-client`, но не DBeaver. Остальные пользователи и роли Для создания учебных витрин используйте подключение, описанное
описаны в [справочнике в [инструкции к заданиям](docs/labs/README.md#как-применить-свой-ddl).
стенда](docs/architecture/stand.md#пользователи-и-роли-clickhouse). Нативные порты `29000` и `29001` нужны `clickhouse-client`, но не DBeaver.
Остальные пользователи и роли описаны в
[справочнике стенда](docs/architecture/stand.md#пользователи-и-роли-clickhouse).
## Документация ## Документация
- [docs/handbook/](docs/handbook/) — путеводитель по стенду и порядок чтения. - [docs/handbook/](docs/handbook/) — путеводитель по стенду и порядок чтения.
- [docs/labs/](docs/labs/) — учебные задания с порядком прохождения и - [docs/labs/](docs/labs/) — учебные задания с порядком прохождения и
самопроверкой. самопроверкой.
- [docs/specs/](docs/specs/) — спеки: источник истины о задуманном. - [docs/specs/](docs/specs/) — требования к стенду и программа обучения.
- [docs/adr/](docs/adr/) — принятые решения с доводами и отвергнутыми - [docs/adr/](docs/adr/) — решения об устройстве стенда: что выбрали,
вариантами: почему сделано так, а не иначе. какие варианты отклонили и почему.
- [docs/architecture/](docs/architecture/) — рабочие справочники по зонам - [docs/architecture/](docs/architecture/) — технические справочники:
ответственности: - [хранилище](docs/architecture/storage.md) — правила именования,
- [хранилище](docs/architecture/storage.md) — конвенции имён, раскладка по распределение данных по шардам, прием событий и список таблиц.
шардам, приём событий, карта таблиц.
- [конвейер](docs/architecture/etl.md) — движение данных между слоями и - [конвейер](docs/architecture/etl.md) — движение данных между слоями и
работа дагов. работа дагов.
- [мир и модельное время](docs/architecture/world.md) — начальные данные, - [мир и модельное время](docs/architecture/world.md) — начальные данные,
ход дней и управление генератором. создание данных за следующие дни и управление генератором.
- [стенд](docs/architecture/stand.md) — службы, доступ и настройка. - [стенд](docs/architecture/stand.md) — службы, доступ и настройка.
- [проверки](docs/architecture/testing.md) — что утверждает каждая цель - [проверки](docs/architecture/testing.md) — команды `make` для проверки
`make` и куда класть новую проверку. стенда и правила добавления новых проверок.
- [мониторинг](docs/architecture/monitoring/README.md) — сбор метрик и - [мониторинг](docs/architecture/monitoring/README.md) — сбор метрик и
устройство дашборда. устройство дашборда.
- [Superset](docs/architecture/superset.md) — подключения, наборы данных и - [Superset](docs/architecture/superset.md) — подключения, наборы данных и
граница автоматической настройки. автоматическая настройка при запуске.
- [docs/research/](docs/research/) — исследования; сейчас это формат - [docs/research/](docs/research/) — исследования; сейчас это формат
кликстрима Яндекса, по которому строится модель события. кликстрима Яндекса, по которому строится модель события.
- [docs/formats/](docs/formats/) — описания форматов источников: по ним - [docs/formats/](docs/formats/) — форматы исходных данных, необходимые
пишется сторона хранилища. Собираются из кода командой `make docs` в для их загрузки и обработки. Эти документы собираются из кода командой
`generator/`, руками не правятся. `make docs` в `generator/`; вручную их менять не нужно.
- [AGENTS.md](AGENTS.md) — контракт работы в репозитории. - [AGENTS.md](AGENTS.md) — правила работы в репозитории для ИИ-агентов.
docs/handbook/airflow-dags.md
+1 -1
View File
@@ -87,7 +87,7 @@ Airflow.
Откройте Airflow по адресу из раздела [«Адреса и Откройте Airflow по адресу из раздела [«Адреса и
пароли»](../../README.md#адреса-и-пароли). В Admin → Variables найдите пароли»](../../README.md#адреса-и-пароли). В Admin → Variables найдите
`world_position`. Затем запустите `world_next_day` на один день по [инструкции `world_position`. Затем запустите `world_next_day` на один день по [инструкции
из README](../../README.md#сдвинуть-мир-вперед). Убедитесь, что `orders_ingest` из README](../../README.md#добавить-данные-за-следующие-дни). Убедитесь, что `orders_ingest`
отработал, а витрины еще ничего не получили. Запустите `etl_pipeline` рукой. отработал, а витрины еще ничего не получили. Запустите `etl_pipeline` рукой.
В DBeaver, подключенном по В DBeaver, подключенном по