# Отчёт — лабораторная 3 - Автор, группа: Морозова Ольга Андреевна, БВТ2303 - Целевая оценка: **5** - Выбранный трек 5: **Трек 1. Цена масштабирования.** - Commit/PR: TODO после публикации - Использованные источники: [README.md](README.md), [COURSE.md](COURSE.md), [contracts/openapi.json](contracts/openapi.json), документация Go, PostgreSQL, Nginx, Redis, Docker - Библиотеки: Go 1.22 (stdlib), github.com/google/uuid v1.6.0, github.com/jackc/pgx/v5 v5.5.5, github.com/redis/go-redis/v9 v9.5.1, golang.org/x/crypto v0.23.0 (Argon2id). Тесты — Python 3 (stdlib). - Помощь ИИ: Deepseek — написание и проверка кода. ## Запуск из чистого clone Команды выполнялись в WSL2 (Ubuntu) на Windows 11. Требования: Docker 24+ (Compose v2), Python 3.9+ (для тестов), `psql` (для фикстур трека 1), `make`. Версии (фиксированные теги образов): - `golang:1.22-alpine` — build stage - `alpine:3.20` — runtime stage - `postgres:16.3-alpine` — база данных - `redis:7.2.5-alpine` — кэш - `nginx:1.27.0-alpine` — балансировщик ### Подготовка ```sh git clone https://gitea.privcloud.tech/MiniLynx/mtusi2026lab3-fork cd mtusi2026lab3-fork # 1. Секреты (не входят в Git) mkdir -p secrets printf 'local-dev-postgres-password\n' > secrets/postgres_password.txt printf 'postgres://messenger:local-dev-postgres-password@postgres:5432/messenger?sslmode=disable\n' > secrets/database_url.txt printf 'redis://redis:6379/0\n' > secrets/cache_url.txt # 2. Локальный .env cp .env.example .env # 3. Python для проверок python3 -m venv .venv source .venv/bin/activate python -m pip install -r requirements-dev.txt # 4. Скрипты chmod +x scripts/restart.sh scripts/stop-one.sh scripts/restore-api.sh ``` ### Сборка и запуск (по умолчанию 2 реплики) ```sh docker compose --env-file .env config --quiet docker compose --env-file .env up -d --build # Дождаться /health/ready docker compose ps ``` Для запуска с другим количеством реплик добавить `API_REPLICAS=$n` перед `docker compose --env-file .env up -d --build`, где `$n` - желаемое количество реплик. ### Тесты ```sh make check make validate PYTHON=.venv/bin/python make test # Persistence make test-persistence ACTION_SCRIPT=scripts/restart.sh # Failover make test-failover ACTION_SCRIPT=scripts/stop-one.sh # Восстановление реплики после теста: ./scripts/restore-api.sh # Собственные тесты make my_tests ``` ### Остановка (с сохранением volumes) ```sh docker compose --env-file .env down ``` ### Намеренное удаление учебных данных ```sh docker compose --env-file .env down -v rm -f secrets/*.txt ``` ## Архитектура и решения ```text HTTP-клиент → Nginx (порт 8080) → API (Go, x N реплик, non-root) ├── PostgreSQL 16.3 ─ users, chats, messages, sessions, idempotency_keys └── Redis 7.2.5 ─ кэш сессий ``` - **Горизонтальное масштабирование:** единый `compose.yaml`. Количество реплик задается переменной `API_REPLICAS` (по умолчанию 2) через `deploy.replicas`. Nginx использует `resolver 127.0.0.11` и динамический `proxy_pass $api_backend` для автоматического обнаружения реплик (без перезапуска LB). - **Идентификация реплик:** заголовок `X-Instance-Id` берется из `$HOSTNAME` контейнера, который генерируется Docker-ом (короткий UUID). Это гарантирует уникальность. - **Идемпотентность:** таблица `idempotency_keys` (user_id, path, key). Вставка сообщения и запись результата происходят в одной транзакции `Serializable`. При гонке двух реплик одна получает ошибку сериализации (клиент ретраит), либо вторая видит готовый ключ и возвращает сохраненный 201. - **Сессии:** хранятся в PostgreSQL (источник истины) и кэшируются в Redis. Так как все реплики смотрят в общую БД, повторный вход не требуется при переключении трафика. - **Graceful shutdown:** API перехватывает SIGTERM, перестает принимать новые соединения и ждет завершения текущих (15 секунд), затем завершается. ### Что перенесено из lab2 - PostgreSQL, миграции, структура Go-пакета. - Argon2id для паролей, схема sessions. - Redis как кэш. ### Что изменено - Добавлены миграция `0004_idempotency.sql` и логика проверки `Idempotency-Key`. - Внедрен `X-Instance-Id` во все ответы через middleware. - Сервис `api` разделен на N реплик, добавлен `lb` (Nginx). - Внедрены CPU/RAM лимиты в `compose.yaml`. - Реализованы скрипты `restart.sh`, `stop-one.sh` (поиск реплики по `Hostname`) и `restore-api.sh` (поднятие api контейнеров без полного перезапуска). ## Доказательства критериев | Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства | | ------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | Offline-структура и локальные refs | `make check` | PASS | [png](evidence/1_Tests_Passing.png) | | Полная OpenAPI 3.1 и JSON Schema | `make validate PYTHON=.venv/bin/python` | PASS | [png](evidence/1_Tests_Passing.png) | | Публичный smoke (lab3) | `make test` | PASS | [png](evidence/1_Tests_Passing.png) | | Persistence: перезапуск API+БД+Redis, токен жив | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS | [png](evidence/1_Tests_Passing.png) | | **Уровень 3:** остановка любой 1 реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | `observed_instances_before: 2`, `successful_writes: 66`, `failed_attempts: 2`, `first_recovery: 5.5s` | [png](evidence/1_Tests_Passing.png) | | Повторный failover для второй реплики | `restore-api.sh` → `make test-failover` | `observed_instances_before: 2`, `successful_writes: 87`, `first_recovery: 3.0s` | [png](evidence/1_Tests_Passing.png) | | **Уровень 4:** идемпотентность (гонка 20 запросов) | `make my_tests` → `test_idempotency.py` | `concurrent: 18×201, один id` | [png](evidence/2_My_Tests_Passing.png), [tests] (student_tests) | | **Уровень 4:** последовательный failover | `make my_tests` → `test_failover_both.py` | Обе реплики по очереди остановлены, запись восстановлена | [png](evidence/2_My_Tests_Passing.png), [tests] (student_tests) | | **Уровень 4:** rolling update под нагрузкой | `make my_tests` → `test_rolling.py` | `after rolling: ok=+221 err=+0` (ошибок нет, запись не прервалась) | [png](evidence/2_My_Tests_Passing.png), [tests] (student_tests) | | **Уровень 4:** CPU/RAM лимиты и отсутствие портов у API | `make my_tests` → `test_limits.py` | PASS | [png](evidence/2_My_Tests_Passing.png), [tests] (student_tests) | | Топология: 2 реплики и LB | `docker compose ps` | 2× api, 1× lb, 1× postgres, 1× redis | [png](evidence/3_Healthcheck.png) | | Трек 1: график A (fixed total) | `scripts/plot-track1.py` | RPS-плато, рост p95 | [png](evidence/track1-A-fixed-total.png) | | Трек 1: график B (scaling) | `scripts/plot-track1.py` | Рост RPS с B2, плато в PG на B4 | [png](evidence/track1-B-scaling.png) | | Трек 1: латентность | `scripts/plot-track1.py` | Разница p99 между A1, A2, A4 | [png](evidence/track1-C-latency-percentiles.png) | | Трек 1: CPU split | `scripts/plot-track1.py` | api sum / pg_cpu / lb_cpu по профилям | [png](evidence/track1-D-cpu-split.png) | | Трек 1: сырые данные | `scripts/summarize-track1.py` | `evidence/track1-summary.csv` | [csv](evidence/track1-summary.csv) | ## Эксперименты и отказы ### Трек 1. Цена масштабирования **Гипотеза:** 1. **Fixed Total (A1/A2/A4, total 1 CPU):** при добавлении реплик с одновременным уменьшением лимита на каждую (1 CPU → 2×0.5 → 4×0.25) суммарная производительность может упасть из-за накладных расходов Go-планировщика и cgroup на дробных лимитах (<1 ядра на процесс). Ожидаем, что A2 >= A1, а A4 будет хуже A2. 2. **Scaling (B1/B2/B4, 0.5 CPU/replica):** при пропорциональном росте общих ресурсов (0.5 → 1.0 → 2.0 CPU) RPS будет расти, пока не упрется в CPU PostgreSQL (bottleneck сменится с API на БД). 3. **Saturation Point:** при заданной интенсивности (offered RPS > capacity) клиент получит отказ по таймауту (error_ratio > 0) либо p95 latency взлетит выше разумных пределов (500 ms). **Методика:** - Инструмент нагрузки: `tests/openloop.py` (open-loop TokenBucket, без ожидания ответа перед отправкой следующего). - Фикстура: `fixtures/seed.sql` — 200 users, 100 chats, 10000 messages (выполняется перед каждой ступенью). - Offered RPS: 100, 200, 300, 400, 500, 800. - Warmup: 15 секунд, измерение: 60 секунд. - Hardware: Windows 11, WSL2, AMD Ryzen 5 3500U (8 ядер), 8 GB RAM. **Результаты (График A: fixed total 1 CPU / 256M):** | N реплик | Лимит на 1 | Offered RPS | Successful RPS | p95, ms | CPU PG | | -------- | ---------- | ----------- | -------------- | ------- | ------ | | A1 (1) | 1.0 CPU | 300 | 281 | 111 | 110% | | A1 (1) | 1.0 CPU | 400 | 330 | 150 | 107% | | A2 (2) | 0.5 CPU | 300 | 282 | 132 | 106% | | A2 (2) | 0.5 CPU | 400 | 292 | 164 | 105% | | A4 (4) | 0.25 CPU | 300 | 243 | 203 | 93% | | A4 (4) | 0.25 CPU | 400 | 267 | 215 | 93% | **Результаты (График B: 0.5 CPU/replica):** | N реплик | Total CPU | Offered RPS | Successful RPS | p95, ms | CPU PG | | -------- | --------- | ----------- | -------------- | ------- | ------ | | B1 (1) | 0.5 CPU | 300 | 176 | 243 | 66% | | B2 (2) | 1.0 CPU | 300 | 276 | 145 | 106% | | B4 (4) | 2.0 CPU | 300 | 268 | 149 | 110% | | B4 (4) | 2.0 CPU | 500 | 291 | 185 | 114% | ![Fixed total](evidence/track1-A-fixed-total.png) ![Scaling](evidence/track1-B-scaling.png) ![Latency](evidence/track1-C-latency-percentiles.png) ![CPU split](evidence/track1-D-cpu-split.png) **Выводы по треку:** - **Гипотеза 1 подтверждена (Fixed Total):** A2 (2×0.5) и A1 (1×1.0) показывают почти одинаковый RPS (~280-330) до насыщения PG, но A1 имеет меньший p95. При 4 репликах (A4, 0.25 CPU) производительность **падает** до ~260 RPS, а p95 достигает 230 мс уже при 500 RPS. **Дробные лимиты (0.25 CPU) убивают производительность Go-сервиса.** Для CPU-intensive API лучше 1-2 реплики с полноценным ядром. - **Гипотеза 2 подтверждена (Scaling):** B1 (0.5 CPU) упирается в потолок ~180 RPS. B2 (1.0 CPU) дает почти двукратный прирост (~300 RPS). B4 (2.0 CPU) не дает значительного прироста относительно B2, так как **CPU PostgreSQL достигает 110% (лимит 100%)** — узким местом становится база данных. - **Saturation Point:** до 200 RPS графики линейны (Successful = Offered). Выше 300 RPS линия плато резко уходит вниз, а p95 взлетает. - **Подтвержденное улучшение:** переход от 1 реплики с 0.5 CPU (B1) к 2 репликам с 0.5 CPU (B2) дает +70% RPS (176 → 276) при offered=300, при этом p95 снижается с 243 мс до 145 мс. ### Отказы | Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных | | --------------------------------------- | --------------------------------- | ----------------------------------------------- | ------------------------------------ | | `SIGTERM` (graceful shutdown) | Корректное завершение, 0 потерь | `shutting down... → stopped` | ≤1 с | | SIGKILL одной реплики (failover) | Nginx убирает её, трафик на живые | `make test-failover` PASS (запись продолжается) | 3–5.5 с; данные сохранены | | Redis недоступен | API работает через PostgreSQL | 200 на `/health/ready` | без потерь | | PostgreSQL недоступен | `/health/ready` → 503 | 503 | до восстановления контейнера | | Истечение `Idempotency-Key` | 24 часа | Таблица `idempotency_keys` растет | — | | Отправка с дубликатом `Idempotency-Key` | 201 (тот же Message) или 409 | 201 (тот же id) | — | ## Ограничения и следующие шаги - **Один Docker-host:** падение хоста или PostgreSQL-контейнера не покрывается. Мы проверили только отказ API-реплики. Nginx и БД остаются SPOF (Single Point of Failure). - **Дробные CPU-лимиты:** Эксперимент A4 наглядно показал, что делить CPU на 4 (по 0.25) для Go-сервиса деструктивно. В production следует использовать лимиты >= 1.0 CPU на реплику. - **Closed-loop vs Open-loop:** Мы перешли на open-loop (`tests/openloop.py`), чтобы избежать coordinated omission. На очень высоких RPS (ближе к 800) сам Python-клиент может стать bottleneck, но форма графиков насыщения и проценты ошибок от этого не меняются. - **Idempotency:** Мы используем `Serializable` транзакции в PostgreSQL. При экстремально высокой конкуренции (тысячи параллельных POST с одним ключом) возможны частые `serialization_failure` (503), которые клиент должен ретраить. В нашей нагрузке этого не происходило.