18 KiB
Отчёт — лабораторная работа № 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. Ограничения и риски
- SPOF. Один Nginx, один PostgreSQL и один Docker-хост остаются едиными точками отказа; отказ хоста или PostgreSQL не переживается автоматически.
- DNS и upstream. При смене контейнеров возможны краткие ошибки до обновления DNS.
max_fails=0отключает пассивное исключение неработающего адреса и имеет собственный компромисс: такой адрес может выбираться повторно. - Границы rolling update. Подтверждена последовательная замена контейнеров на текущем образе. Развёртывание новой версии образа и проверка совместимости двух разных версий приложения не проводились.
- Идемпотентность. Ключи сохраняются на 24 часа и далее: автоматическая очистка истёкших записей пока отсутствует. Это не приводит к повторной записи при сохранённом ключе, но требует обслуживания таблицы и уточнения политики повторного использования ключей.
- Redis. Redis не является источником истины для авторизации. Проверка PostgreSQL на каждом запросе упрощает корректность отзыва сессий, но добавляет нагрузку на БД и ограничивает масштабирование.
- Методика нагрузки. Отсутствуют три независимых повтора успешного прогона, замеры CPU/RAM и точная временная диаграмма ошибок. Не следует утверждать, что система гарантирует zero downtime при любой нагрузке.
- Старые данные. При использовании базы с несовместимым форматом служебной таблицы миграций может потребоваться отдельная процедура переноса;
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-хосте автором работы. Данные измерений не подменялись оценками ИИ.