ddadmin
ce15836093
Зачем: помочь учащемуся понять назначение стенда и порядок работы с ним. Что: убраны внутренние метафоры, пояснены термины, настройка перенесена перед запуском. Обновлена ссылка из путеводителя и удалена ссылка на предыдущий стенд. Проверка: команды, адреса и пароли сохранены; 24 ссылки README и входящие ссылки на разделы проверены. git diff --cached --check прошел.
158 lines
11 KiB
Markdown
158 lines
11 KiB
Markdown
# Учебная дата-платформа кликстрима
|
||
|
||
> Этим стендом можно пользоваться самостоятельно. Он также входит в
|
||
> [план обучения Data Engineering Roadmap](https://de.dementev.space) как
|
||
> курсовая работа. Если вам нужна помощь, обратитесь к автору материалов —
|
||
> ментору [@dementev_dev](https://t.me/dementev_dev).
|
||
|
||
Здесь вы будете работать с хранилищем данных небольшого интернет-магазина:
|
||
загружать и обрабатывать данные в ClickHouse, строить витрины, проверять
|
||
качество данных и создавать графики. Стенд рассчитан на тех, кто уже изучил
|
||
основы ClickHouse и хочет попрактиковаться.
|
||
|
||
Генератор создает заказы и кликстрим — записи о действиях посетителей
|
||
магазина. Данные поступают через Kafka в ClickHouse и проходят четыре слоя
|
||
обработки: STG, ODS, DDS и DM. В кластере ClickHouse два шарда и отдельный
|
||
ClickHouse Keeper. Airflow управляет загрузкой и обработкой, Superset
|
||
показывает отчеты, а Prometheus и Grafana помогают следить за работой стенда.
|
||
|
||
При первом запуске стенд загрузит данные за неделю работы магазина.
|
||
После запуска начните с [путеводителя](docs/handbook/README.md): он объясняет
|
||
устройство хранилища. Затем переходите к [учебным заданиям](docs/labs/README.md).
|
||
|
||
## Быстрый старт
|
||
|
||
Для запуска нужны Docker с Compose, `make`, `curl` и `jq`.
|
||
Выделите Docker около 8 ГБ оперативной памяти. В Docker Desktop и WSL2
|
||
проверьте лимит памяти виртуальной машины: он может быть меньше, чем общий
|
||
объем памяти компьютера. Команда `docker info --format '{{.MemTotal}}'`
|
||
покажет доступный Docker объем в байтах. В WSL2 лимит задается параметром
|
||
`memory` в файле `.wslconfig` в домашнем каталоге пользователя Windows.
|
||
После изменения выполните `wsl --shutdown`. Если ресурсов компьютера
|
||
недостаточно, стенд можно запустить на VPS.
|
||
|
||
По умолчанию должны быть свободны порты
|
||
`23000`, `28080`, `28088`, `28123`, `28124`, `29000`, `29001`, `29090`
|
||
и `29092`. Для работы с командами `make` в каталоге `generator/` также
|
||
понадобится `uv`.
|
||
|
||
В каталоге репозитория скопируйте образец настроек:
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
В `.env` задаются имя экземпляра стенда, внешние порты, учебные логины,
|
||
пароли и ключи. Проверьте `DOCKER_GID`: это числовой идентификатор группы
|
||
`docker` на вашей машине. Узнать его можно командой `getent group docker`.
|
||
Если число отличается от образца, замените значение в `.env`. От этой
|
||
настройки зависит запуск генератора из Airflow.
|
||
|
||
Запустите стенд:
|
||
|
||
```bash
|
||
make up
|
||
```
|
||
|
||
Команда запустит службы и дождется загрузки начальных данных. Порядок запуска
|
||
и проверки результата описаны в [справочнике проверок](docs/architecture/testing.md).
|
||
Если обязательной настройки в `.env` не хватает, Compose сообщит об ошибке.
|
||
Внутренние адреса служб, имена топиков и версии образов заданы в `compose.yaml`
|
||
и Dockerfile.
|
||
|
||
Логины и пароли Postgres и Grafana сохраняются при первом запуске в томах
|
||
Docker. Простая правка `.env` их не изменит. Чтобы задать новые значения
|
||
через `.env`, потребуется `make clean` и повторный `make up`. При этом
|
||
будут удалены все локальные данные стенда.
|
||
|
||
## Адреса и пароли
|
||
|
||
С настройками из `.env.example` порты доступны только с локальной машины:
|
||
|
||
- узел ClickHouse 1 — `http://127.0.0.1:28123`, нативный порт `29000`;
|
||
- узел ClickHouse 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`.
|
||
|
||
Подробнее о службах, правах пользователей и изменении настроек —
|
||
в [справочнике стенда](docs/architecture/stand.md).
|
||
|
||
## Добавить данные за следующие дни
|
||
|
||
Время в учебном магазине идет отдельно от календарного. В документации оно
|
||
называется модельным временем, а сам магазин с его посетителями и заказами —
|
||
миром.
|
||
|
||
В Airflow запустите `world_next_day`. Это даг — набор связанных задач,
|
||
которые Airflow выполняет в заданном порядке. Он создаст и загрузит данные
|
||
за следующий день работы магазина. В форме запуска можно задать число дней.
|
||
|
||
Чтобы новые данные поступали непрерывно, снимите с паузы даг `world_live`.
|
||
Он будет запускать генерацию день за днем; один модельный день занимает
|
||
около 24 минут. Подробности — в [справочнике генератора и модельного
|
||
времени](docs/architecture/world.md#даги-модельного-времени).
|
||
|
||
## Восстановить начальные данные
|
||
|
||
Если хотите начать заново, поставьте `world_live` на паузу и дождитесь
|
||
завершения уже запущенного дага генерации. Затем выполните
|
||
`make rebuild-storage`.
|
||
|
||
Команда удалит прикладные базы ClickHouse, топики и позиции потребителей
|
||
Kafka, затем заново создаст схему хранилища и загрузит начальные данные.
|
||
Службы и их тома останутся на месте.
|
||
|
||
## Остановить или удалить стенд
|
||
|
||
`make down` остановит стенд и сохранит данные. Для повторного запуска
|
||
выполните `make up`.
|
||
|
||
`make clean` удалит контейнеры и все данные в томах Docker. Для обычного
|
||
завершения работы достаточно `make down`.
|
||
|
||
## Подключиться из DBeaver
|
||
|
||
Драйвер ClickHouse в DBeaver подключается по JDBC через HTTP-порт. Укажите хост
|
||
`127.0.0.1`, порт `28123`, пользователя `analyst` и пароль из переменной
|
||
`CLICKHOUSE_ANALYST_PASSWORD` в `.env`; в образце это `analyst-26-reader`.
|
||
Для подключения ко второму узлу укажите порт `28124`.
|
||
|
||
Пользователь `analyst` может читать данные во всех слоях и справочниках.
|
||
Для создания учебных витрин используйте подключение, описанное
|
||
в [инструкции к заданиям](docs/labs/README.md#как-применить-свой-ddl).
|
||
Нативные порты `29000` и `29001` нужны `clickhouse-client`, но не DBeaver.
|
||
Остальные пользователи и роли описаны в
|
||
[справочнике стенда](docs/architecture/stand.md#пользователи-и-роли-clickhouse).
|
||
|
||
## Документация
|
||
|
||
- [docs/handbook/](docs/handbook/) — путеводитель по стенду и порядок чтения.
|
||
- [docs/labs/](docs/labs/) — учебные задания с порядком прохождения и
|
||
самопроверкой.
|
||
- [docs/specs/](docs/specs/) — требования к стенду и программа обучения.
|
||
- [docs/adr/](docs/adr/) — решения об устройстве стенда: что выбрали,
|
||
какие варианты отклонили и почему.
|
||
- [docs/architecture/](docs/architecture/) — технические справочники:
|
||
- [хранилище](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/) — форматы исходных данных, необходимые
|
||
для их загрузки и обработки. Эти документы собираются из кода командой
|
||
`make docs` в `generator/`; вручную их менять не нужно.
|
||
- [AGENTS.md](AGENTS.md) — правила работы в репозитории для ИИ-агентов.
|