Files
mtusi2026lab3/REPORT.md
2026-10-21 18:25:07 +03:00

31 KiB
Raw Permalink Blame History

Отчёт — лабораторная 3

  • Автор, группа: Черников Дмитрий, БВТ2304
  • Целевая оценка; выбранный трек 5, если нужен: 4; трек 5 не заявлен
  • Commit/PR: TODO после публикации
  • Использованные источники, библиотеки и помощь ИИ:
    • Балансировщик: HAProxy 3.4.5 (официальный образ).
    • Библиотеки приложения (точные версии и хеши — в requirements.txt): psycopg 3.3.6 и psycopg-pool 3.3.3, valkey 6.1.1, argon2-cffi 25.1.0. Тесты и скрипты проверок — только стандартная библиотека Python.
    • Источники: README, contracts/ и tests/ этого репозитория; документация HAProxy 3.4 (health checks, resolvers, http-error, retries); Compose services; документация PostgreSQL и psycopg.
    • ИИ: при написании тестов, конфигурации стенда и текста этого отчёта использовался ассистент Claude (Anthropic).

Запуск из чистого clone

Что нужно на машине: Docker с Compose v2 (проверено на Docker Desktop 29.8.1, Compose 5.5.1), Git и Python 3.9+ для тестов и скриптов проверок. make не обязателен: рядом с каждой командой make указана равнозначная. Выбран вариант Compose + HAProxy; Swarm не используется.

Роль Сервис Образ Готовность Volume Порт Учётные данные
Балансировщик lb haproxy:3.4.5-trixie@sha256:7692… проверяет /health/ready каждой реплики раз в секунду нет 127.0.0.1:8080 (API), 127.0.0.1:8404 (страница состояния) нет
API, 2 реплики api (deploy.replicas) mtusi-messenger:lab3, собирается из Dockerfile на python:3.14.7-slim-trixie@sha256:51da… HEALTHCHECK → /health/ready нет не публикуются, только сеть compose секреты database_url, cache_url
Миграции migrate тот же образ, выполняется один раз до старта реплик код выхода 0 нет нет секрет database_url
PostgreSQL postgres postgres:18.6-trixie@sha256:7493… pg_isready pgdata только сеть compose POSTGRES_PASSWORD_FILE
Valkey valkey valkey/valkey:9.0.6-trixie@sha256:6334… valkey-cli ping с паролем valkeydata только сеть compose requirepass из файла секрета

Команды для bash (в Linux вместо python -X utf8 — python3):

git clone <URL fork> mtusi2026lab3 && cd mtusi2026lab3
python scripts/init_secrets.py              # make secrets: случайные пароли в secrets/, в Git не попадают
cp .env.example .env                        # необязательно: в compose.yaml у всех значений есть умолчания
docker compose up -d --build --wait         # postgres, valkey, migrate, api x2, lb; ожидание healthy

python -X utf8 tests/smoke.py --base-url http://127.0.0.1:8080        # make test BASE_URL=http://127.0.0.1:8080
make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://127.0.0.1:8080
docker compose up -d --wait                 # вернуть остановленную тестом реплику
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://127.0.0.1:8080
BASE_URL=http://127.0.0.1:8080 python -X utf8 -m unittest discover -s student-tests -v   # make student-test
python -X utf8 scripts/lab3_checks.py --output evidence/lab3-checks.txt               # make checks

docker compose stop                         # безопасная остановка: SIGTERM, данные остаются в volumes
docker compose down -v                      # намеренное удаление всех учебных данных (volumes)

Особенности Windows:

  • Кодировка. Публичные тесты читают контракт в кодировке системы (cp1251), а в контракте lab3 есть символ, которого в ней нет. Поэтому их нужно запускать с python -X utf8.
  • Хуки. Скрипты .sh Windows выполнить не может, поэтому у хуков есть двойники scripts/stop-one.cmd и scripts/restart.cmd с теми же действиями.
  • Адрес. Используйте 127.0.0.1, а не localhost: иначе каждый запрос ждёт около двух секунд, пока система пробует IPv6.

Действия оператора:

  • Секреты. Один раз запустить scripts/init_secrets.py.
  • Миграции. Запускаются сами: сервис migrate выполняется один раз до старта реплик. Повтор вручную: docker compose run --rm migrate.
  • Число реплик. API_REPLICAS в .env или docker compose up -d --scale api=3. Балансировщик находит новые реплики сам.
  • После теста отказа. Остановленную реплику возвращает docker compose up -d --wait.
  • Поочерёдное обновление. Процедура описана ниже; автоматизирована в scripts/lab3_checks.py --only rolling.

Команды защиты по шагам — в DEMO.md.

Архитектура и решения

клиент ──HTTP──> lb: HAProxy, 127.0.0.1:8080, round-robin, без sticky session
                  │  адреса реплик — из DNS Docker (имя api), проверка /health/ready раз в 1 с
                  ├──> api-1 ──┐   пул ≤ 10 соединений на реплику ──> postgres: данные, ключи идемпотентности  [pgdata]
                  └──> api-2 ──┘   пул ≤ 20 соединений на реплику ──> valkey: сессии, AOF                      [valkeydata]
migrate (один раз, до старта реплик) ──> postgres: migrations/0001…0003

Что перенесено из lab2 и что изменено.

  • Перенесено без изменения смысла:
    • PostgreSQL со схемой и миграциями, сессии в Valkey с AOF, Argon2id;
    • формат API и ошибок, keyset-пагинация;
    • собственные тесты и проверки отказов хранилищ.
  • Добавлено в lab3:
    • балансировщик HAProxy и реплики API;
    • заголовок X-Instance-Id;
    • обязательный Idempotency-Key и таблица idempotency_keys;
    • двухшаговая остановка реплики;
    • лимиты CPU/RAM;
    • ограничение одновременных расчётов Argon2id;
    • хуки stop-one и restart.

Состояние вне реплик. Реплики ничего не хранят у себя. Сессии лежат в Valkey, данные и результаты идемпотентных запросов — в PostgreSQL. Поэтому любой запрос пользователя может попасть на любую реплику без повторного входа, и sticky session не нужна.

X-Instance-Id. Это hostname контейнера, то есть короткий ID Docker; значение стабильно для жизни процесса. Хук stop-one по нему находит контейнер через docker ps --filter id=... --filter label=com.docker.compose.service=api и останавливает только реплику API этого проекта. Ошибки, которые создаёт сам балансировщик, заголовка X-Instance-Id не имеют. Они приходят в формате ошибок контракта: JSON с X-Request-Id.

Балансировщик. Конфигурация — infra/haproxy/haproxy.cfg.

  • Распределение. Round-robin без sticky session. Реплики берутся из DNS Docker через server-template + resolvers (перечитывается каждую секунду), поэтому масштабирование и замена контейнеров не требуют правки конфигурации.
  • Повторы. Запрос повторяется на другой реплике (retry-on conn-failure, option redispatch), только если соединение с репликой не установилось. Значит, запрос до неё не дошёл, и повтор безопасен даже для POST.
  • Соединения к репликам. Закрываются после каждого ответа (http-server-close), поэтому запрос не уйдёт по старому соединению в реплику, которая уже закрывает приём.

Проверки, таймауты и SIGTERM согласованы.

Параметр Значение Зачем
Проверка готовности реплики GET /health/ready, раз в 1 с; после первой неудачи — раз в 0,5 с /health/ready требует PostgreSQL и Valkey и отвечает 503 после SIGTERM
Исключение / возврат после 2 неудачных / 2 успешных проверок подряд Исключение за 1–1,5 с, без ложных срабатываний от одной ошибки
Таймаут проверки и соединения 1 с Зависшая реплика не держит проверку
Ожидание ответа реплики (timeout server) 15 с Больше любого таймаута внутри API: ожидание пула 3 с, lock_timeout 3 с, statement_timeout 5 с
Остановка реплики по SIGTERM сначала /health/ready = 503 и ещё 3 с (APP_DRAIN_DELAY) обычной работы, затем закрытие приёма и до 4 с на начатые запросы 3 с больше времени исключения, поэтому балансировщик уходит с реплики раньше, чем она закрывает приём
Общий срок остановки 8 с (APP_SHUTDOWN_TIMEOUT) при stop_grace_period 10 с Укладывается в 10 с, Docker не доходит до SIGKILL

Максимальное время обнаружения отказа:

  • Штатная остановка. Балансировщик исключил реплику за 1,0–1,1 с (замерено по его странице состояния).
  • Падение процесса (docker kill). Адрес исчезает из DNS Docker, и HAProxy переводит реплику в MAINT за 0,4–0,5 с. Если бы адрес остался, сработали бы проверки: две неудачи за 1–1,5 с плюс 1 с таймаута, то есть не больше 2,5 с.

Идемпотентность. Таблица idempotency_keys (миграция 0003): область ключа — пользователь + метод + путь чата + ключ.

  • Атомарность. Ключ и сообщение записываются одной транзакцией. Строка чата блокируется на время вставки — это нужно для порядка истории ещё с lab2. Поэтому одновременные запросы с одним ключом через разные реплики выполняются по очереди: второй находит ключ первого и возвращает то же сообщение.
  • Сравнение тел. Тело сравнивается по sha256 от разобранного JSON, так что пробелы и экранирование не важны; другое тело с тем же ключом — 409.
  • Что запоминается. Ответы 4xx не запоминаются: в базе ничего не меняется. При 5xx транзакция откатывается, повтор с тем же ключом безопасен.
  • Повтор. Снова проверяет сессию и доступ.
  • Срок хранения. Ключ хранится IDEMPOTENCY_TTL_SECONDS (24 ч), старые удаляет фоновая очистка.

Миграции. Выполняются один раз сервисом migrate до старта реплик, а pg_advisory_lock исключает гонку, даже если запустить их параллельно. Миграция lab3 только добавляет таблицу, поэтому версия API из lab2 продолжает работать на новой схеме. Ограничение: удаление или переименование колонок так не провести. Для них нужна схема expand/contract в два выпуска: сначала добавить, потом удалить, когда старых реплик не осталось. В этой работе таких изменений нет.

Поочерёдное обновление. В Compose нет встроенного rolling update, поэтому замена выполняется по шагам (scripts/lab3_checks.py, секция rolling):

  1. Собрать новый образ и один раз применить миграции.
  2. Для каждой старой реплики:
    1. docker compose up -d --no-deps --no-recreate --scale api=3 api запускает одну новую реплику, старые остаются;
    2. дождаться, пока она станет healthy и начнёт отвечать через балансировщик;
    3. docker stop старой реплики (двухшаговая остановка) и docker rm.

Ресурсы.

  • Лимиты. У каждого контейнера есть лимиты CPU и памяти:

    Контейнер CPU Память
    API, каждая реплика 0,5 256 МБ
    lb 0,5 128 МБ
    postgres 1 512 МБ
    valkey 0,5 256 МБ
    migrate 0,5 128 МБ
  • Argon2id. Один расчёт занимает 19 МиБ памяти, поэтому реплика считает не больше 4 хешей одновременно. Остальные ждут до 5 с, затем получают 503. Пик памяти предсказуем и укладывается в лимит.

  • Соединения с БД. Не больше 10 на реплику, то есть 20 на две реплики при max_connections 100.

  • Порты и container_name. Наружу порты публикует только lb, на 127.0.0.1. container_name нигде нет, поэтому сервис api масштабируется.

Секреты. Каждый сервис получает только свои: api — database_url и cache_url, postgres — свой пароль, valkey — свой, lb — ни одного.

Недоступность хранилища через балансировщик.

  • Первые секунды. Запросы попадают в реплики и получают от них 503: при недоступном Valkey за 1 с, при недоступном PostgreSQL за 3 с.
  • Дальше. /health/ready отвечает 503 на всех репликах, балансировщик исключает их все и сам отвечает JSON 503 за 0,01 с на любой запрос.
  • Отличие от lab2. Во время такого отказа недоступна и регистрация (в lab2 она работала без Valkey). Это осознанное следствие того, что готовность реплики включает общие хранилища. Анонимный запрос ни в каком случае не обслуживается как доверенный.
  • Восстановление. Стенд возвращается в работу сам.

Переменные из .env.example.

Переменная Где используется По умолчанию
APP_HOST, APP_PORT Адрес и порт API внутри контейнера, заданы в compose.yaml 0.0.0.0, 8080
APP_PUBLISHED_PORT, LB_STATS_PORT Порты балансировщика на 127.0.0.1 хоста 8080, 8404
API_REPLICAS Число реплик API 2
APP_SHUTDOWN_TIMEOUT, APP_DRAIN_DELAY Общий срок остановки и время работы в режиме «не готов» после SIGTERM 8, 3
APP_ENV, APP_LOG_LEVEL Метка окружения в логе, уровень логов lab, INFO
SESSION_TTL_SECONDS Срок жизни сессии 3600
IDEMPOTENCY_TTL_SECONDS Срок хранения ключей идемпотентности, не меньше 24 ч 86400
DB_POOL_SIZE Максимум соединений с PostgreSQL на реплику 10
DATABASE_URL_FILE, CACHE_URL_FILE Файлы секретов с адресами PostgreSQL и Valkey /run/secrets/database_url, /run/secrets/cache_url
APP_VERSION Версия сборки (build arg), пишется в лог старта; меняется при поочерёдном обновлении lab3
SESSION_STORE Не используется: хранилище сессий всегда Valkey —

Доказательства критериев

Все проверки выполнены 2026-10-07 на compose-стенде: Windows 11, Docker Desktop 29.8.1, Intel Core Ultra 9 185H (16 ядер, 22 потока), 31 ГиБ RAM, лимиты контейнеров из таблицы выше. Весь трафик шёл через балансировщик.

Файлы доказательств:

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
3: стенд в compose.yaml, ≥2 реплики, одна точка входа, общие БД и сессии docker compose up -d --build --wait; секция Stack 2 реплики api, порты только у lb, общие postgres и valkey evidence/lab3-checks.txt, evidence/clean-clone.txt
3: разные запросы одного пользователя обслуживают разные реплики без повторного входа 40 запросов GET /users/me с одним токеном 20 и 20 ответов от двух разных X-Instance-Id, все 200 evidence/lab3-checks.txt, раздел Balancing
3: остановка любой одной реплики; чтения и записи продолжаются не позднее 10 с tests/resilience.py --mode failover с scripts/stop-one.cmd, повтор до остановки каждой реплики api-4: 112 записей, 0 ошибок, первая запись после хука через 3,83 с; api-3: 106 записей, 0 ошибок, 4,13 с; обе остановлены с кодом 0 evidence/lab3-checks.txt, раздел Public failover test
3: повтор POST с тем же Idempotency-Key не создаёт дубль, включая конкурентный повтор и смену реплики 20 одновременных POST с одним ключом; test_idempotency Один id сообщения, ответили обе реплики, в чате одно сообщение; другое тело — 409 evidence/lab3-checks.txt, раздел Idempotency; evidence/tests.txt
3: make test, persistence, failover smoke, оба публичных теста с хуками Все PASS; failover видит 2 реплики до отказа evidence/tests.txt, evidence/lab3-checks.txt
3: перезапуск всего стенда с тем же токеном tests/resilience.py --mode persistence с scripts/restart.cmd PASS; StartedAt сменился у обеих реплик, postgres, valkey и lb; volumes те же evidence/lab3-checks.txt, раздел Full restart
4: health/readiness, таймауты и SIGTERM согласованы, LB исключает недоступную реплику Остановка реплики под нагрузкой; лог HAProxy 0 ошибок клиента; HAProxy: «is DOWN, reason: Layer7 wrong status, code: 503» до закрытия приёма evidence/lab3-checks.txt, раздел Experiment
4: период проверок и максимальное время обнаружения Страница состояния HAProxy во время эксперимента Проверка раз в 1 с; исключение: остановка — 1,0–1,1 с, docker kill — 0,4–0,5 с evidence/lab3-checks.txt, раздел Experiment
4: поочерёдная остановка каждой реплики с восстановлением; RPS, ошибки, время восстановления Секция experiment: stop и kill каждой реплики под нагрузкой 6 клиентов Таблица ниже; 4858 подтверждённых записей, все в истории, дублей нет evidence/lab3-checks.txt, раздел Experiment
4: общая идемпотентность параллельными запросами с одним ключом Секция idempotency См. выше: одно сообщение на 20 запросов через 2 реплики evidence/lab3-checks.txt
4: CPU/RAM-лимиты, нет портов в обход LB, секреты только где нужно, нет container_name Секция stack Лимиты у всех 5 контейнеров; порты только у lb на 127.0.0.1; секреты по сервисам совпадают с таблицей выше; container_name нет evidence/lab3-checks.txt, раздел Stack
4: поочерёдная замена под нагрузкой Секция rolling 5582 запроса, 0 ошибок, 190 успешных RPS; обе реплики заменены новым образом по одной; 2791 запись без потерь и дублей evidence/lab3-checks.txt, раздел Rolling update
4: миграции однократно и совместимы с работающей версией Сервис migrate; повторный запуск; 0003 только добавляет таблицу Повторно applied_now=0, данные не задвоены evidence/lab3-checks.txt, разделы Migrations и Rolling update
lab2: гонка регистрации, откат создания чата, пул, таймауты, истечение сессии, отказ Valkey/PostgreSQL, EXPLAIN Секции race, rollback, pool, timeouts, expiry, valkey-down, postgres-down; scripts/explain_history.py Один 201 и 19 × 409; чат откатывается целиком; максимум 20 соединений на 2 реплики; 503 через 3,02 с при блокировке; сессия истекает при TTL 2 с; 503 и восстановление после отказов; Index Scan вместо Seq Scan evidence/lab3-checks.txt, evidence/explain.txt

Эксперименты и отказы

Методика.

  • Нагрузка: 6 потоков в замкнутом цикле через балансировщик. Каждый поток отправляет сообщение с новым Idempotency-Key, а при ошибке повторяет его с тем же ключом и телом. Потом читает /users/me.
  • По каждой реплике по очереди: 5 с исходной нагрузки, затем docker stop или docker kill, 8 с наблюдения, docker start и ожидание, пока реплика снова начнёт отвечать.
  • Время исключения берётся со страницы состояния HAProxy (опрос раз в 0,1 с).
  • После всех прогонов история сверяется со всеми подтверждёнными записями.
Реплика Действие Длительность команды, с Успешных RPS до RPS во время Ошибки Наибольший перерыв, с Исключена LB через, с Вернулась через, с RPS после
api-3 docker stop 3,93 148,2 81,3 0 0,18 1,00 5,19 218,1
api-4 docker stop 3,96 171,4 83,8 0 0,10 1,09 5,34 165,3
api-3 docker kill 0,40 202,0 69,4 2 0,93 0,47 5,47 123,8
api-4 docker kill 0,43 151,4 67,6 3 0,98 0,42 5,49 156,2

Наблюдения:

  • Штатная остановка. Ошибок 0. Балансировщик уходит с реплики через ~1 с по её ответу 503 на /health/ready, а приём она закрывает только через 3 с.
  • docker kill. 2–3 ошибки: это запросы, которые выполнялись в момент гибели процесса. Клиент повторил их с тем же ключом. Все 4858 подтверждённых записей оказались в истории ровно по одному разу.
  • RPS на одной реплике. Падает примерно вдвое: у каждой реплики лимит 0,5 CPU, и одна реплика обрабатывает примерно половину нагрузки двух. После возврата второй реплики RPS восстанавливается.
  • Возврат реплики. Около 5 с после docker start: старт процесса, затем две успешные проверки балансировщика.
Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Хук stop-one (публичный тест), каждая реплика Записи продолжаются ≤ 10 с, нет дублей 0 ошибок; первая запись после хука через 3,83 и 4,13 с Потерь и дублей нет
Поочерёдная замена реплик новым образом Нет ошибок клиента 5582 запроса, 0 ошибок Потерь и дублей нет
Перезапуск всего стенда хуком restart Те же данные и токен Публичный тест сохранности — PASS 19,9 с до готовности; потерь нет
docker compose stop valkey Ограниченный 503, нет анонимного доступа Сначала 503 от реплик за 1,02 с, затем 503 от балансировщика за 0,01 с Тот же токен работает через 1,5 с после старта Valkey
docker compose stop postgres Ограниченный 503 Сначала 503 за 3,02 с, затем 503 от балансировщика за 0,01 с Работает через 5,6 с после старта PostgreSQL

Ограничения и следующие шаги

  • Один хост. Отказ узла не выдерживается.
  • Единичные компоненты. Балансировщик, PostgreSQL и Valkey — по одному экземпляру: это единые точки отказа. Защищён только слой API.
  • Запись в один чат. Сообщения одного чата записываются строго по очереди (блокировка строки чата): это цена порядка истории и идемпотентности. На пропускную способность записи в один чат это ограничение, на разные чаты — нет.
  • Поочерёдное обновление выполняется скриптом, а не встроенным механизмом: в Compose такого механизма нет.
  • Падение процесса. При docker kill выполнявшиеся запросы получают ошибку 502; без потери данных их можно только повторить с тем же ключом, как делает нагрузочный клиент.
  • Отказ общего хранилища. Балансировщик отвечает 503 на все запросы, включая регистрацию.
  • X-Instance-Id раскрывает короткий ID контейнера. Для lab3 это удобно, в lab7 его нужно заменить случайным псевдонимом.
  • Без ограничений по нагрузке. Ограничения частоты запросов и защиты от перебора паролей нет. Поток создаётся на каждое соединение.
  • Нет CI. Job со сборкой стенда не добавлен: репозиторий размещён на GitFlic.