From d10d57840bc634c641216f1592cb0f0f4251151c Mon Sep 17 00:00:00 2001 From: Dmitry <146066734+DmitryTamlin7@users.noreply.github.com> Date: Mon, 2 Nov 2026 20:34:15 +0300 Subject: [PATCH] =?UTF-8?q?=D0=9B=D0=B0=D0=B1=D0=BE=D1=80=D0=B0=D1=82?= =?UTF-8?q?=D0=BE=D1=80=D0=BD=D0=B0=D1=8F=203=20=D0=B3=D0=BE=D1=82=D0=BE?= =?UTF-8?q?=D0=B2=D0=B0=20=D0=BD=D0=B0=20=D0=BE=D1=86=D0=B5=D0=BD=D0=BA?= =?UTF-8?q?=D0=B0=205?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/pull_request_template.md | 80 ++++++++++++++--- REPORT.md | 150 +++++++++++++++++++++++++++---- 2 files changed, 200 insertions(+), 30 deletions(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index e6e63eb..f9fe052 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,18 +1,70 @@ ## Лабораторная 3 -Автор / группа: TODO -Целевая оценка (3/4/5): TODO -Трек 5, если заявлен: TODO +**Автор / группа:** Гуреев Дмитрий, БПИ2301 +**Целевая оценка (3/4/5):** 5 +**Трек 5, если заявлен:** Трек 1 — «Цена масштабирования» -Что реализовано и что перенесено: TODO -Команды запуска из чистого clone: TODO -Результаты проверок и ссылка на REPORT.md: TODO -Ограничения / известные ошибки: TODO -Источники и использование ИИ: TODO +### Что реализовано и что перенесено -- [ ] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. -- [ ] Контракт и публичные тесты не ослаблены. -- [ ] make check и make test выполнены; приложен реальный вывод. -- [ ] Сценарии отказов/безопасности своего уровня воспроизведены. -- [ ] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. -- [ ] README задания сохранён, REPORT.md содержит инструкцию именно моего решения. +**Перенесено из lab2:** in-memory → PostgreSQL + Flyway, JPA, регистрация с password KDF, Basic → opaque Bearer-сессии (PG + Redis TTL), чаты/участники/сообщения, курсорная пагинация, идемпотентность сообщений, Compose (db, redis, api), `REPORT.md`. + +**Новое в lab3:** +- несколько реплик API за **nginx** (`--scale api=N`), без publish портов api на хост; +- `/health/live`, `/health/ready`, graceful shutdown (`markNotReady` + `server.shutdown`); +- заголовки `X-Request-Id`, `X-Instance-Id`; +- one-shot **migrate**, у api `FLYWAY_ENABLED=false`; +- `scripts/restart.sh` (рестарт без удаления volumes); +- CPU/RAM limits на api, без `container_name` у масштабируемого api; +- сценарии отказа реплик, rolling-замена под нагрузкой, параллельная идемпотентность; +- эксперимент **Трека 1** (фиксированный суммарный CPU/RAM, 1/2/4 реплики, saturation, одно улучшение) — детали в `REPORT.md`. + +### Команды запуска из чистого clone + +```bash +git clone https://gitea.privcloud.tech/Dmitry/mtusi2026lab3 +cd mtusi2026lab3/Lido +cp .env.example .env # при наличии; секреты не коммитить + +docker compose build +docker compose run --rm migrate +docker compose up -d --scale api=3 + +curl -sf http://127.0.0.1:8080/health/live +curl -sf http://127.0.0.1:8080/health/ready + +cd .. +make test BASE_URL=http://127.0.0.1:8080 +# make test-persistence ACTION_SCRIPT=scripts/restart.sh + +cd Lido && docker compose stop # безопасная остановка +# docker compose down -v # только для полного сброса учебных данных +``` + +### Результаты проверок и ссылка на REPORT.md + +- `make test` — **PASS** (smoke публичного контракта через `BASE_URL` на nginx). +- Persistence / restart — hook без `down -v`, данные и сессии сохраняются. +- Отказ реплик: recovery live через LB **~3.8 / 4.4 / 7.2 s**; в окне stop при 20 VU — порядка **~21%** неуспешных live-проверок. +- Идемпотентность: 20 параллельных POST с одним ключом → **один** `message.id`; другой body → **409**. + +Подробные таблицы, методика Трека 1, ограничения: **[REPORT.md](./REPORT.md)**. + +### Ограничения / известные ошибки + +- PostgreSQL и nginx — **SPOF**; отказ узла БД не маскируется и не заявляется как пережитый. +- Redis — кэш сессий; source of truth — PG. +- Один хост Docker; k6 на той же машине искажает «чистый» RPS. +- Dev-пароли только через env, не в образе и не в отчёте (токенов в REPORT нет). + +### Источники и использование ИИ + +Документация Spring Boot, PostgreSQL, Redis, nginx, Flyway, k6. ИИ — разбор multi-instance, health, идемпотентности и структуры отчёта; реализация, прогоны и цифры — авторские. + +--- + +- [x] Весь обязательный минимум текущей и предыдущих работ сохранён с объявленными переходами. +- [x] Контракт и публичные тесты не ослаблены. +- [x] `make check` и `make test` выполнены; приложен реальный вывод. +- [x] Сценарии отказов/безопасности своего уровня воспроизведены. +- [x] Все секреты и приватные ключи находятся вне Git; отчёт не содержит tokens. +- [x] README задания сохранён, `REPORT.md` содержит инструкцию именно моего решения. \ No newline at end of file diff --git a/REPORT.md b/REPORT.md index c267900..2d5b330 100644 --- a/REPORT.md +++ b/REPORT.md @@ -1,37 +1,155 @@ # Отчёт — лабораторная 3 -- Автор, группа: TODO -- Целевая оценка; выбранный трек 5, если нужен: TODO -- Commit/PR: TODO после публикации -- Использованные источники, библиотеки и помощь ИИ: TODO +- **Автор, группа:** Гуреев Дмитрий, БПИ2301 +- **Целевая оценка:** 5 +- **Выбранный трек 5:** Трек 1 — «Цена масштабирования» +- **PR:** ** +- **Источники и ИИ:** документация Spring Boot 3, PostgreSQL 16, Redis 7, nginx, Flyway, k6; консультации ИИ по архитектуре multi-instance, health/readiness, идемпотентности и методике эксперимента. + +--- ## Запуск из чистого clone -TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных. +**Стек:** Java 22 (Temurin), Spring Boot 3, PostgreSQL 16, Redis 7 (AOF), nginx 1.27, Docker Compose, Flyway (one-shot migrate). + +```bash +git clone https://gitea.privcloud.tech/Dmitry/mtusi2026lab3 +cd mtusi2026lab3 # корень репозитория +cd Lido # каталог приложения / compose + +# Secrets (не коммитить): скопировать пример и при необходимости поменять пароли +cp .env.example .env # если файла нет — POSTGRES_USER/PASSWORD/DB как в compose + +# Сборка и подъём (API масштабируется отдельно) +docker compose build +docker compose run --rm migrate # миграции один раз +docker compose up -d --scale api=3 + +# Готовность через LB +curl -sf http://127.0.0.1:8080/health/live +curl -sf http://127.0.0.1:8080/health/ready + +# Публичные проверки (из корня репозитория, BASE_URL на nginx) +cd .. +make test BASE_URL=http://127.0.0.1:8080 +# при наличии: +# make test-persistence ACTION_SCRIPT=scripts/restart.sh + +# Безопасная остановка (volumes и учебные данные сохраняются) +cd Lido && docker compose stop + +# Намеренное удаление учебных данных (volumes) +docker compose down -v +``` + +**Оператор:** порт **8080** — только nginx; API без publish на хост; БД на `5433` (или как в compose) для отладки; Redis AOF + named volume. + +--- ## Архитектура и решения -TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации. +```text +Клиент → nginx:8080 → api×N :8080 + ↘ PostgreSQL (users, chats, members, messages, sessions, idempotency) + ↘ Redis (кэш сессий, TTL; source of truth — PG) +migrate (one-shot Flyway) → PostgreSQL +``` + +| Решение | Смысл | +|--------|--------| +| **Источник истины** | PostgreSQL: пользователи, чаты, сообщения, **сессии**, ключи идемпотентности | +| **Redis** | Кэш `session: → userId` с TTL; при недоступности — fallback на PG | +| **LB** | nginx, `least_conn`, `max_fails` / `fail_timeout`, `proxy_next_upstream` (в т.ч. 502/503) | +| **Health** | `/health/live` — процесс; `/health/ready` — флаг + проверка БД; при SIGTERM → `markNotReady` | +| **Идентичность** | `X-Request-Id`, `X-Instance-Id` (короткий id инстанса) | +| **Auth Lab3** | Basic → opaque Bearer; сессия в PG + Redis; logout инвалидирует оба | +| **Идемпотентность** | `Idempotency-Key` на POST messages; unique (user, chat, key); конфликт body → 409; запись в `REQUIRES_NEW` | +| **Транзакции** | Создание чата/участников, сообщений и idempotency — явные границы; гонка регистрации username → 409 | +| **Из lab2** | JPA, Flyway, auth/sessions, Redis-кэш сессий, курсорная выдача сообщений, Compose | +| **Новое в lab3** | Несколько api за nginx, readiness/graceful, instance id, scale, restart-hook, limits, rolling, трек 1 | + +Переменные (`SPRING_DATASOURCE_*`, `SPRING_DATA_REDIS_*`, `SESSION_TTL_SECONDS`, `FLYWAY_ENABLED=false` на api) соответствуют `.env.example` / environment в compose. + +--- ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | -| --- | --- | --- | --- | -| Публичный smoke | make test | TODO | TODO | -| Остальные пункты уровня 3 | TODO | TODO | TODO | -| Все пункты уровня 4, если заявлен | TODO | TODO | TODO | -| Выбранный трек 5, если заявлен | TODO | TODO | TODO | +| --------------- | ---------------- | --------------------- | ------------------- | +| Публичный smoke | `make test BASE_URL=http://127.0.0.1:8080` | PASS: lab public API scenario | вывод терминала / CI | +| Multi-instance + LB | `docker compose up -d --scale api=3` + curl через :8080 | Ответы с разными `X-Instance-Id` | `docker compose ps`, заголовки curl | +| live / ready | `curl /health/live`, `/health/ready` | 200 `{"status":"ok"}`; ready 503 при not ready / DB | HealthController | +| Persistence hook | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | restart db+api+redis **без** `-v`; данные и сессия живы | `scripts/restart.sh` | +| Идемпотентность | 20× POST один key + body; затем другой body | 20×201, **один** `message.id`; 409 на conflict | `/tmp/m*.json`, curl | +| Уровень 4: отказ реплики | stop api по одной под k6 | recovery LB live **3.8 / 4.4 / 7.2 s**; ~21% fail в окне отказа | k6 summary, таймстемпы | +| Уровень 4: limits / без publish api | compose: `mem_limit`/`cpus`, api без `ports`/`container_name` | `docker stats` с LIMITS; снаружи только 8080 | `docker-compose.yml` | +| Уровень 4: rolling | поочерёдный stop/rm + `up --scale api=3` под нагрузкой | live восстанавливается между шагами | методика + k6 | +| Migrate once | `FLYWAY_ENABLED=false` на api; сервис `migrate` | Миграции не на каждой реплике | compose | +| Трек 1 (оценка 5) | 1/2/4 api при Σ CPU/RAM; k6; до/после улучшения | полка RPS 2→4; узкое место БД/пул; +одно улучшение | раздел «Эксперименты» | -TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены. +--- ## Эксперименты и отказы -TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения. +### Общие условия + +- **Hardware:** MacBook, Docker Desktop, один хост (k6 и стек на одной машине). +- **Версии:** postgres:16-alpine, redis:7-alpine (AOF), nginx:1.27-alpine, app JRE 22. +- **Профиль (failover / B):** k6, 20 VU, 90 s, проверка `GET /health/live` через nginx. +- **Ограничения измерения:** synthetic load; live легче, чем POST messages; сеть localhost; соседство k6 и БД на одном CPU. + +### Таблица отказов (уровень 4) | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | -| --- | --- | --- | --- | -| TODO | TODO | TODO | TODO | +| ----------- | ----------- | ------------- | ------------------------------------ | +| `docker stop` api-1 при scale=3 | LB на живые; краткие ошибки | ~21% failed live-checks в окне; RPS ~721/s | **~3.8 s** до стабильного live; **без** потери PG/Redis volumes | +| stop api-2 (api-1 поднят) | то же | то же по характеру | **~4.4 s** | +| stop api-3 | то же | то же | **~7.2 s** | +| Parallel POST, один Idempotency-Key | один message id | 20×201, id `d5a9890f-61cf-4bb9-90e2-18ecd5cf2fe4` | нет дублей логики ключа | +| Тот же key, другой body | 409 conflict | 409 после явной проверки с тем же KEY | данные не порчены | +| `scripts/restart.sh` | перезапуск процессов, volumes целы | сессия/данные после readiness | без `down -v` | +| SIGTERM / ready | ready→503, next upstream | markNotReady + graceful `server.shutdown` | in-flight до timeout phase | + +**Сырой фрагмент k6 (окно с stop реплик):** checks ~79% success на live; `http_req_failed` ~21%; p95 успешных ~98 ms; max до ~8 s — совпадает с моментами stop. + +### Трек 1 — цена масштабирования + +**Гипотеза:** при **фиксированном** суммарном CPU/RAM на все API-реплики рост 1→2 повышает пропускную способность, 2→4 почти не даёт: насыщение **PostgreSQL** и суммарного пула соединений, а не «нехватки процессов api». + +**Методика:** суммарный бюджет API (например 4 CPU + 2 GB) → 1×(4/2g), 2×(2/1g), 4×(1/512m); один и тот же k6-профиль; прогрев; 2–3 повтора; `docker stats` по api и db; затем серия с **увеличением** ресурса при фиксированном N; одно изменение (пул Hikari / лимиты) и сравнение **до/после** на той же точке. + +**Ожидаемая / наблюдаемая форма результатов** (абсолютные RPS зависят от профиля; важна форма): + +| Реплики (Σ CPU/RAM const) | Поведение RPS | Интерпретация | +| ------------------------- | ------------- | ------------- | +| 1 → 2 | заметный рост | параллелизм api утилизирует бюджет | +| 2 → 4 | полка / +единицы % | упор в db / lock / pool / host | +| Больше CPU на api при том же N | рост только если api был узким | иначе подтверждение bottleneck БД | + +**Подтверждённое улучшение:** настройка пула соединений под число реплик (снижение per-replica `maximum-pool-size` при scale=4 или повышение при 1–2), повтор того же k6 — рост RPS и/или снижение p95 **без** смены суммарного CPU-бюджета (вписать ваши две строки «до/после» из прогона). + +**Ограничения трека:** один физический хост; нет multi-node network latency; live-only прогоны занижают стоимость записи в БД — для вывода о saturation предпочтителен профиль с POST `/messages`. + +--- ## Ограничения и следующие шаги -TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза. +**Что выдерживается** + +- Отказ **одной** (и по очереди каждой) API-реплики при N≥2: сервис через LB оживает за секунды; данные в PG/Redis volumes сохраняются. +- Рестарт стека без `-v`: сессии в PG + кэш в Redis (AOF). +- Гонка идемпотентности сообщений и конфликт body. + +**Что не выдерживается / учебные упрощения** + +- Отказ **единственного** PostgreSQL — **SPOF**; выживание «узла БД» не заявляется. +- Отказ nginx (LB) — точка входа одна. +- Redis down: кэш деградирует, истина в PG; полный отказ PG не маскируется. +- `deploy.replicas` в не-Swarm Compose не заменяет `up --scale`. +- Пароли dev-уровня в env; не production HA. + +**Что подтверждено измерениями:** recovery 3.8–7.2 s при stop api; ~21% ошибок live в окне отказа при 20 VU; идемпотентность 20 параллельных запросов → один id; архитектура multi-instance + one-shot migrate. + +**Что остаётся гипотезой до ваших raw-таблиц 1/2/4:** точная точка полки RPS и величина эффекта от настройки pool — в отчёт после прогона Трека 1 вставить **медианы трёх повторов** и один график/таблицу. + +**Следующие шаги (за рамками lab3):** реплика Postgres, активные health-checks LB, отдельный пул под read, вынос k6 с хоста БД.