31 KiB
Отчёт — лабораторная 3
- Автор, группа: Черников Дмитрий, БВТ2304
- Целевая оценка; выбранный трек 5, если нужен: 4; трек 5 не заявлен
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ:
- Балансировщик: HAProxy 3.4.5 (официальный образ).
- Библиотеки приложения (точные версии и хеши — в
requirements.txt):psycopg3.3.6 иpsycopg-pool3.3.3,valkey6.1.1,argon2-cffi25.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. - Хуки. Скрипты
.shWindows выполнить не может, поэтому у хуков есть двойники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):
- Собрать новый образ и один раз применить миграции.
- Для каждой старой реплики:
docker compose up -d --no-deps --no-recreate --scale api=3 apiзапускает одну новую реплику, старые остаются;- дождаться, пока она станет healthy и начнёт отвечать через балансировщик;
docker stopстарой реплики (двухшаговая остановка) иdocker rm.
Ресурсы.
-
Лимиты. У каждого контейнера есть лимиты CPU и памяти:
Контейнер CPU Память API, каждая реплика 0,5 256 МБ lb0,5 128 МБ postgres1 512 МБ valkey0,5 256 МБ migrate0,5 128 МБ -
Argon2id. Один расчёт занимает 19 МиБ памяти, поэтому реплика считает не больше 4 хешей одновременно. Остальные ждут до 5 с, затем получают 503. Пик памяти предсказуем и укладывается в лимит.
-
Соединения с БД. Не больше 10 на реплику, то есть 20 на две реплики при
max_connections100. -
Порты и
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, лимиты контейнеров из таблицы выше. Весь трафик шёл через балансировщик.
Файлы доказательств:
- evidence/tests.txt — тесты;
- evidence/clean-clone.txt — сборка и тесты из чистого clone;
- evidence/lab3-checks.txt — проверки инфраструктуры,
RESULT: PASS, 34 из 34; - evidence/race.json — конкурентный тест;
- evidence/explain.txt — планы запроса.
| Критерий 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.