Files
mtusi2026lab3-fork/REPORT.md
T

18 KiB
Raw Blame History

Отчёт — лабораторная работа № 3 (целевая оценка: 4)

Автор: Стругов Максим
Группа: БПИ2303
Целевая оценка: 4

1. Воспроизводимый запуск

Требования: Docker Engine и Docker Compose plugin; Go на хосте не требуется; Python 3.9+ для проверочных скриптов.

cp .env.example .env
./scripts/init-secrets.sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2 --wait
make check
make validate
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
./scripts/restore.sh

После восстановления реплик проверить docker compose ps api: должны работать два экземпляра API со статусом healthy.

Публично опубликован только адрес 127.0.0.1:8080 балансировщика Nginx. API, PostgreSQL и Redis доступны внутри сети Docker Compose, но не публикуют свои порты на хост. Данные PostgreSQL сохраняются в Docker volume. Команда docker compose down останавливает стек без удаления данных; docker compose down -v удаляет тома и учебные данные, поэтому используется только осознанно.

Секреты создаются локально, не должны попадать в Git. Для secrets/database_url.txt и secrets/cache_url.txt установлены права 640, группа 10001 — GID процесса API. После изменения прав контейнер API был перезапущен и успешно достиг состояния healthy.

2. Архитектура и технические решения

Схема: клиент → Nginx 1.27.5 → две реплики Go API → общие PostgreSQL 16.4 и Redis 7.4.

  • Реплики API. Приложение не хранит критическое состояние в локальной памяти контейнера. Обе реплики работают с общими PostgreSQL и Redis. Заголовок X-Instance-Id содержит идентификатор экземпляра и позволяет проверить распределение запросов.
  • Сессии. PostgreSQL — источник истины для пользователей, чатов, сообщений и сессий. Решение о действительности Bearer-токена принимается по PostgreSQL; положительный ответ Redis-кэша не используется как самостоятельное подтверждение доступа. Это предотвращает доверие устаревшей записи после отзыва токена на другой реплике.
  • Идемпотентность. Для создания сообщений используется Idempotency-Key; в PostgreSQL действует уникальность (user_id, chat_id, key). Запись сообщения и ключа идемпотентности выполняется транзакционно. В рамках лабораторной тело запроса канонизируется как текст и пустой список вложений.
  • Балансировщик. Nginx использует Docker DNS 127.0.0.11 и динамическое разрешение api:8080 (resolve, valid=2s). Настроены proxy_connect_timeout 1s, proxy_read_timeout 12s, proxy_send_timeout 12s и максимум две upstream-попытки при предусмотренных сетевых ошибках. Автоматический повтор уже отправленного POST не гарантируется: повтор небезопасен без учёта идемпотентности.
  • Healthcheck и остановка. Проверка здоровья контейнера выполняется каждые 5 секунд. Go HTTP-сервер использует graceful shutdown с тайм-аутом 8 секунд; Compose задаёт stop_grace_period: 10s.
  • Миграции. Отдельный одноразовый сервис migrate запускает golang-migrate до старта API. SQL-миграции встроены в Go-бинарь через go:embed; применённые версии учитываются в schema_migrations.

Особенность настройки Nginx по результатам эксперимента: в upstream добавлено server api:8080 resolve max_fails=0;. Параметр отключает пассивное исключение адреса после неудачных попыток соединения. Это помогло в повторном испытании, но означает, что Nginx может продолжать выбирать недоступный IP до обновления Docker DNS. Активных health probes upstream в данной конфигурации нет.

3. Проверки и доказательства

Критерий Команда / сценарий Фактический результат Доказательство
Структура репозитория make check PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. Вывод терминала; при сдаче сохранить в evidence/
OpenAPI 3.1 и JSON Schema make validate PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested. Вывод терминала
Публичный API make test PASS: lab3 public API scenario; infrastructure and grading evidence remain separate. Вывод терминала
Персистентность make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence. Вывод терминала и scripts/restart.sh
Отказ одной реплики make test-failover ACTION_SCRIPT=scripts/stop-one.sh 115 успешных записей, 0 неудачных попыток, первая успешная запись после воздействия через 0,474 с; тест завершился PASS Вывод JSON и scripts/stop-one.sh
Балансировка 20 последовательных запросов /health/live В ответах наблюдались два разных X-Instance-Id, соответствующие двум репликам Вывод curl
Конкурентная идемпотентность python3 tests/idempotency_concurrent.py 20 параллельных запросов с одинаковым ключом, один уникальный ID сообщения, ответы от двух реплик; PASS Вывод теста; файл скрипта
Обычная нагрузка до обновления python3 tests/load.py --duration 30 --concurrency 4 --output evidence/load.json 11 816 успешных запросов, 0 ошибок; 393,589 успешных запросов/с; p50 7,992 мс, p95 27,642 мс, p99 46,719 мс evidence/load.json
Замена под нагрузкой scripts/rolling-update.sh одновременно с tests/load.py 35 685 успешных POST, 0 ошибок; обе реплики заменены и стали healthy evidence/rolling-load.json, evidence/rolling-update.log
Версия миграций SELECT version, dirty FROM schema_migrations; version=2, dirty=false Вывод psql
Доступ к секретам chmod 640, ls -l, перезапуск одной реплики Группа файлов 10001, режим 640; перезапущенная api-6 стала healthy, api-7 оставалась healthy Вывод ls, docker inspect, docker compose ps api

3.1. Проверка отказа одной реплики

Тест make test-failover ACTION_SCRIPT=scripts/stop-one.sh завершился успешно: 115 записей, 0 неудачных попыток, первая успешная запись после воздействия через 0,474 секунды. Дополнительно вручную остановлена одна реплика, а запрос к /health/live через Nginx продолжил возвращать HTTP 200 от второй. После запуска остановленной реплики и перехода в healthy Nginx снова распределял запросы между двумя X-Instance-Id.

Указанное время 0,474 секунды — метрика конкретного теста, а не гарантия максимального времени восстановления при любых условиях.

3.2. Поочерёдная замена реплик под нагрузкой

Использован сценарий эквивалентной поочерёдной замены контейнеров Docker Compose, а не обновление образа на новую версию приложения. Скрипт запоминает ID двух исходных контейнеров, удаляет их по одному, вызывает docker compose up -d --no-deps --no-recreate --scale api=2 api и ожидает healthy новой реплики перед переходом к следующей. Флаг --no-recreate сохраняет работающий второй экземпляр. Compose может выдавать новым контейнерам следующие порядковые номера (api-4, api-5 и т. д.), поэтому алгоритм не привязан к именам api-1 и api-2.

Условия нагрузочного испытания: 90 секунд, конкурентность 4, закрытая модель нагрузки (closed-loop), создание сообщений через POST, без автоматических повторов на стороне нагрузочного клиента.

Метрика Первый прогон Повторный прогон после изменения Nginx
Длительность 90,018 с 90,021 с
Успешные запросы 34 594 35 685
Неуспешные запросы 5 661 0
Доля ошибок 14,0628% 0%
Успешных запросов/с 384,301 396,409
p50 успешных запросов 8,035 мс 8,014 мс
p95 успешных запросов 25,285 мс 25,782 мс
p99 успешных запросов 39,950 мс 39,431 мс
Замена двух реплик PASS PASS

Разбор неудачного прогона. В логах Nginx многократно появлялось no live upstreams while connecting to upstream для POST-запросов. Это показывает, что балансировщик в некоторые моменты не имел доступного upstream. После изменения upstream на server api:8080 resolve max_fails=0; повторный прогон завершился без зарегистрированных ошибок. Эксперимент подтверждает улучшение в измеренных условиях

Ограничение методики. Перцентили вычисляются только по успешным запросам; ошибочные запросы учитываются отдельно. Closed-loop-нагрузка подвержена coordinated omission и накладным расходам клиента. Был проведён один повторный успешный прогон, а не три независимых повтора; поэтому статистическая воспроизводимость результата не установлена. Интервалы недоступности по секундам и CPU/RAM не замерялись.

3.3. Миграции и совместимость схемы

Сервис migrate выполняется как отдельная одноразовая задача, от успешного завершения которой зависит запуск API. Это отделяет изменение схемы от старта каждой реплики. golang-migrate отслеживает версии и состояние миграций; запрос к schema_migrations показал version=2, dirty=false.

0001_init создаёт основные таблицы и индексы. 0002_idempotency добавляет таблицу message_idempotency с уникальным составным ключом и индексом срока хранения, не удаляя существующие поля или таблицы. Это добавочное изменение схемы, потенциально совместимое с работающей предыдущей версией приложения. Однако совместная работа старой версии API с новой схемой не проверялась экспериментально, поэтому полной гарантии обратной совместимости нет. Для будущих несовместимых изменений требуется поэтапный подход expand–migrate–contract.

Наличие version=2, dirty=false подтверждает завершённое состояние схемы, но само по себе не доказывает количество фактических запусков контейнера миграций. Одноразовость обеспечивается архитектурой Compose (migrate как отдельный job), а не приведённым SQL-запросом.

4. Ограничения и риски

  1. SPOF. Один Nginx, один PostgreSQL и один Docker-хост остаются едиными точками отказа; отказ хоста или PostgreSQL не переживается автоматически.
  2. DNS и upstream. При смене контейнеров возможны краткие ошибки до обновления DNS. max_fails=0 отключает пассивное исключение неработающего адреса и имеет собственный компромисс: такой адрес может выбираться повторно.
  3. Границы rolling update. Подтверждена последовательная замена контейнеров на текущем образе. Развёртывание новой версии образа и проверка совместимости двух разных версий приложения не проводились.
  4. Идемпотентность. Ключи сохраняются на 24 часа и далее: автоматическая очистка истёкших записей пока отсутствует. Это не приводит к повторной записи при сохранённом ключе, но требует обслуживания таблицы и уточнения политики повторного использования ключей.
  5. Redis. Redis не является источником истины для авторизации. Проверка PostgreSQL на каждом запросе упрощает корректность отзыва сессий, но добавляет нагрузку на БД и ограничивает масштабирование.
  6. Методика нагрузки. Отсутствуют три независимых повтора успешного прогона, замеры CPU/RAM и точная временная диаграмма ошибок. Не следует утверждать, что система гарантирует zero downtime при любой нагрузке.
  7. Старые данные. При использовании базы с несовместимым форматом служебной таблицы миграций может потребоваться отдельная процедура переноса; docker compose down -v удаляет данные и не является безопасным способом обновления рабочей БД.

5. Источники, инструменты и использование ИИ

Исходные требования и контракт курса: contracts/openapi.json, contracts/README.md, contracts/infrastructure.json. В проекте используются Go, pgx/v5, golang-migrate/v4, go-redis/v9, PostgreSQL, Redis, Nginx и Docker Compose. Для анализа реализации, диагностики ошибок Nginx, подготовки сценариев испытаний и оформления отчёта использовался ChatGPT. Команды и фактические результаты экспериментов проверялись на Docker-хосте автором работы. Данные измерений не подменялись оценками ИИ.