From ce15836093a203e002082080ef88416e24ebd596 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sun, 13 Sep 2026 12:47:16 -0400 Subject: [PATCH] =?UTF-8?q?docs(readme):=20=D1=83=D0=BF=D1=80=D0=BE=D1=89?= =?UTF-8?q?=D0=B5=D0=BD=20=D1=8F=D0=B7=D1=8B=D0=BA=20=D0=B2=D0=B2=D0=BE?= =?UTF-8?q?=D0=B4=D0=BD=D0=BE=D0=B9=20=D0=B8=D0=BD=D1=81=D1=82=D1=80=D1=83?= =?UTF-8?q?=D0=BA=D1=86=D0=B8=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Зачем: помочь учащемуся понять назначение стенда и порядок работы с ним. Что: убраны внутренние метафоры, пояснены термины, настройка перенесена перед запуском. Обновлена ссылка из путеводителя и удалена ссылка на предыдущий стенд. Проверка: команды, адреса и пароли сохранены; 24 ссылки README и входящие ссылки на разделы проверены. git diff --cached --check прошел. --- README.md | 175 +++++++++++++++++++--------------- docs/handbook/airflow-dags.md | 2 +- 2 files changed, 99 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index c7bb0cc..1cf9769 100644 --- a/README.md +++ b/README.md @@ -5,132 +5,153 @@ > курсовая работа. Если вам нужна помощь, обратитесь к автору материалов — > ментору [@dementev_dev](https://t.me/dementev_dev). -Этот стенд — для изучения и экспериментов с кликстримом и ClickHouse. Здесь -можно проследить весь путь данных: от кликстрима и заказов до витрин, проверок -и графиков. Это преемник учебного стенда -[clickstream-ch-kafka-superset-demo](https://git.dementev.space/ddmitry/clickstream-ch-kafka-superset-demo). +Здесь вы будете работать с хранилищем данных небольшого интернет-магазина: +загружать и обрабатывать данные в ClickHouse, строить витрины, проверять +качество данных и создавать графики. Стенд рассчитан на тех, кто уже изучил +основы ClickHouse и хочет попрактиковаться. -В стенде подняты кластер ClickHouse из двух шардов, отдельный keeper, Kafka, -Airflow, Superset, Prometheus и Grafana; события кликстрима и заказы бэкенда -приезжают из генератора и идут по слоям STG → ODS → DDS → DM. `make up` -наполняет стенд стартовым миром — первой неделей модельного времени. Чтобы -разобраться в устройстве, начните с [путеводителя](docs/handbook/README.md), а -учиться — с [уроков](docs/labs/README.md). +Генератор создает заказы и кликстрим — записи о действиях посетителей +магазина. Данные поступают через Kafka в ClickHouse и проходят четыре слоя +обработки: STG, ODS, DDS и DM. В кластере ClickHouse два шарда и отдельный +ClickHouse Keeper. Airflow управляет загрузкой и обработкой, Superset +показывает отчеты, а Prometheus и Grafana помогают следить за работой стенда. + +При первом запуске стенд загрузит данные за неделю работы магазина. +После запуска начните с [путеводителя](docs/handbook/README.md): он объясняет +устройство хранилища. Затем переходите к [учебным заданиям](docs/labs/README.md). ## Быстрый старт -Нужны Docker с Compose и около 8 ГБ памяти, доступной Docker. Это не объём -ноутбука, а то, что отдано самому Docker: в Docker Desktop и WSL2 он живёт -внутри виртуальной машины и получает лишь часть памяти хозяина. Сколько выдано -сейчас, в байтах, покажет `docker info --format '{{.MemTotal}}'`. В WSL2 это -поднимается параметром `memory` в файле `.wslconfig` домашнего каталога -пользователя Windows; после правки нужен `wsl --shutdown`. Если своей машины не -хватает, стенд одинаково хорошо живёт на недорогом VPS. +Для запуска нужны Docker с Compose, `make`, `curl` и `jq`. +Выделите Docker около 8 ГБ оперативной памяти. В Docker Desktop и WSL2 +проверьте лимит памяти виртуальной машины: он может быть меньше, чем общий +объем памяти компьютера. Команда `docker info --format '{{.MemTotal}}'` +покажет доступный Docker объем в байтах. В WSL2 лимит задается параметром +`memory` в файле `.wslconfig` в домашнем каталоге пользователя Windows. +После изменения выполните `wsl --shutdown`. Если ресурсов компьютера +недостаточно, стенд можно запустить на VPS. -`make up` нужны `curl` и `jq`: первым он ходит в Airflow, вторым читает -паспорт мира, по которому ждет заливки. По умолчанию должны быть свободны -порты `23000`, `28080`, `28088`, `28123`, `28124`, `29000`, `29001`, `29090` -и `29092`. Всем целям генератора в `generator/` нужен `uv`. +По умолчанию должны быть свободны порты +`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 ``` -`make up` сам ждет заливки стартового мира; что он делает по шагам и какие -проверки есть у стенда, описано в [карте -проверок](docs/architecture/testing.md). +Команда запустит службы и дождется загрузки начальных данных. Порядок запуска +и проверки результата описаны в [справочнике проверок](docs/architecture/testing.md). +Если обязательной настройки в `.env` не хватает, Compose сообщит об ошибке. +Внутренние адреса служб, имена топиков и версии образов заданы в `compose.yaml` +и Dockerfile. -`.env.example` — образец обязательной локальной настройки. В нём живут имя -экземпляра, внешние порты, учебные учётные данные и ключи. Одно значение образца -верно не везде — `DOCKER_GID`: у группы `docker` на каждой машине свой номер, и -свой подскажет `getent group docker`. Пока он не сойдётся, стенд работает весь, -кроме [дагов модельного -времени](docs/architecture/world.md#даги-модельного-времени). `compose.yaml` не -дублирует их умолчаниями: если значения нет в `.env`, Compose сразу предложит -скопировать образец. Внутренние адреса, имена топиков и версии образов описывают -сам стенд, поэтому записаны литералами в `compose.yaml` и Dockerfile. - -Учётные данные Postgres и Grafana применяются при создании их томов. -После первого запуска меняйте их только вместе с `make clean`: команда удалит -все локальные данные стенда, а следующий `make up` создаст их с новыми -значениями. +Логины и пароли Postgres и Grafana сохраняются при первом запуске в томах +Docker. Простая правка `.env` их не изменит. Чтобы задать новые значения +через `.env`, потребуется `make clean` и повторный `make up`. При этом +будут удалены все локальные данные стенда. ## Адреса и пароли С настройками из `.env.example` порты доступны только с локальной машины: -- нода 1 — `http://127.0.0.1:28123`, нативный порт `29000`; -- нода 2 — `http://127.0.0.1:28124`, нативный порт `29001`; +- узел 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). +Подробнее о службах, правах пользователей и изменении настроек — +в [справочнике стенда](docs/architecture/stand.md). -## Сдвинуть мир вперед +## Добавить данные за следующие дни -В Airflow запустите даг `world_next_day`: по умолчанию он сыграет один день, а -в форме запуска можно задать другое число дней. Снимите с паузы `world_live`, -и мир поедет сам в темпе модельного времени. Подробности — в [справочнике -мира](docs/architecture/world.md#даги-модельного-времени). +Время в учебном магазине идет отдельно от календарного. В документации оно +называется модельным временем, а сам магазин с его посетителями и заказами — +миром. -## Вернуть мир к началу +В Airflow запустите `world_next_day`. Это даг — набор связанных задач, +которые Airflow выполняет в заданном порядке. Он создаст и загрузит данные +за следующий день работы магазина. В форме запуска можно задать число дней. -`make rebuild-storage` запустит в Airflow явную пересборку: удалит прикладные -базы ClickHouse, топики и позиции потребителей Kafka, затем создаст схему -и данные заново. Службы и их тома останутся на месте. Перед пересборкой -поставьте `world_live` на паузу и дайте уже начатому шаговому дагу закончить -день. +Чтобы новые данные поступали непрерывно, снимите с паузы даг `world_live`. +Он будет запускать генерацию день за днем; один модельный день занимает +около 24 минут. Подробности — в [справочнике генератора и модельного +времени](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 Драйвер ClickHouse в DBeaver подключается по JDBC через HTTP-порт. Укажите хост `127.0.0.1`, порт `28123`, пользователя `analyst` и пароль из переменной `CLICKHOUSE_ANALYST_PASSWORD` в `.env`; в образце это `analyst-26-reader`. -Ко второй ноде — порт `28124`. +Для подключения ко второму узлу укажите порт `28124`. -Пользователь `analyst` читает все слои и справочники. Нативные порты `29000` и -`29001` нужны `clickhouse-client`, но не DBeaver. Остальные пользователи и роли -описаны в [справочнике -стенда](docs/architecture/stand.md#пользователи-и-роли-clickhouse). +Пользователь `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/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/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) — контракт работы в репозитории. +- [docs/formats/](docs/formats/) — форматы исходных данных, необходимые + для их загрузки и обработки. Эти документы собираются из кода командой + `make docs` в `generator/`; вручную их менять не нужно. +- [AGENTS.md](AGENTS.md) — правила работы в репозитории для ИИ-агентов. diff --git a/docs/handbook/airflow-dags.md b/docs/handbook/airflow-dags.md index dc54499..2381c07 100644 --- a/docs/handbook/airflow-dags.md +++ b/docs/handbook/airflow-dags.md @@ -87,7 +87,7 @@ Airflow. Откройте Airflow по адресу из раздела [«Адреса и пароли»](../../README.md#адреса-и-пароли). В Admin → Variables найдите `world_position`. Затем запустите `world_next_day` на один день по [инструкции -из README](../../README.md#сдвинуть-мир-вперед). Убедитесь, что `orders_ingest` +из README](../../README.md#добавить-данные-за-следующие-дни). Убедитесь, что `orders_ingest` отработал, а витрины еще ничего не получили. Запустите `etl_pipeline` рукой. В DBeaver, подключенном по