Общие PostgreSQL, Valkey и идемпотентность сообщений нужны, чтобы чтение и запись переживали остановку одной реплики.
19 KiB
Отчёт — лабораторная 3
- Автор, группа: Самсонов Александр, БВТ2303
- Целевая оценка: 4
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: PostgreSQL advisory lock, Traefik Docker provider, RFC 7617, hashlib.scrypt, psycopg 3, redis-py. Реализацию сервера, Compose и проверок помог собрать ИИ в Cursor.
Запуск из чистого clone
Нужны Docker Engine 24+ с Compose v2 и Python 3.9+ для публичных тестов. Приложение в контейнере — Python 3.12.6. Проверка ниже выполнена в WSL Ubuntu 22.04: Docker 29.1.3, Compose 2.40.3, Python 3.10. На Windows у python без PYTHONUTF8=1 публичный make check может не прочитать openapi.json в кодировке cp1251; в Linux/WSL это не требуется.
git clone <url-этого-форка>
cd mtusi2026lab3
cp .env.example .env
# в .env учебный POSTGRES_PASSWORD, файл не коммитить
chmod +x scripts/up.sh scripts/restart.sh scripts/stop-one.sh scripts/restore-api.sh scripts/rolling-update.sh
docker compose --env-file .env -f compose.yaml config --quiet
docker compose --env-file .env -f compose.yaml up -d --build --scale api=2 --remove-orphans
Тот же запуск одной командой: sh scripts/up.sh.
Готовность: GET http://127.0.0.1:8080/health/ready возвращает {"status":"ok"}. Порт 8080 опубликован только у lb и только на 127.0.0.1. Миграции применяет одноразовый сервис migrate до старта реплик. Повторный запуск не вставляет данные второй раз: версии лежат в schema_migrations (001_init.sql, 002_idempotency.sql).
Проверки:
python3 scripts/check_contract.py
python3 tests/smoke.py --base-url http://127.0.0.1:8080
python3 tests/student_level4.py --base-url http://127.0.0.1:8080
python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080
python3 tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080
python3 scripts/grade4_probe.py
После failover одна реплика остаётся остановленной. Вернуть её:
sh scripts/restore-api.sh
Остановка без удаления данных:
docker compose --env-file .env -f compose.yaml stop
Удаление учебных данных вместе с volumes:
docker compose --env-file .env -f compose.yaml down -v
Образы закреплены тегами: python:3.12.6-slim-bookworm, postgres:16.6-bookworm, valkey/valkey:8.0.2, traefik:v3.7.16. Зависимости Python закреплены в requirements.txt.
Архитектура и решения
Клиент --HTTP--> Traefik (lb) --HTTP--> API ×2 (src/server.py)
|--SQL--> PostgreSQL
+--сессия--> Valkey (AOF + volume)
Из lab2 перенесены пользователи, чаты, членство, сообщения, keyset-пагинация, формат ошибок, X-Request-Id, Basic/Bearer, scrypt и сессии в Valkey. Локальной памяти, от которой зависит корректность, у API нет: сессии в общем Valkey, сообщения и ключи идемпотентности в общем PostgreSQL. X-Instance-Id — hostname контейнера, стабильный на время жизни процесса. В Compose hostname совпадает с коротким id контейнера, поэтому scripts/stop-one.sh находит реплику по TARGET_INSTANCE_ID.
Sticky cookie нет. Traefik распределяет запросы по живым контейнерам сервиса api. Адреса он берёт из Docker API и обновляет по событиям start/die, а не из одного закэшированного DNS-ответа. Сокет Docker смонтирован только в lb и только на чтение.
Соответствие .env
| Переменная | Куда попадает |
|---|---|
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB |
postgres; из них же DATABASE_URL у migrate и api |
SESSION_TTL_SECONDS |
API, TTL сессии в Valkey |
IDEMPOTENCY_TTL_SECONDS |
API, окно повторного ключа, по умолчанию 86400 |
DRAIN_SECONDS |
API, пауза после SIGTERM до закрытия сокета, по умолчанию 3 |
API_REPLICAS |
scripts/up.sh и scripts/restore-api.sh, масштаб сервиса api |
REDIS_URL |
задаёт compose только сервису api: redis://valkey:6379/0 |
INSTANCE_ID в окружение реплик не передаётся: иначе обе получили бы один и тот же заголовок. DATABASE_URL_FILE и CACHE_URL_FILE приложение читает, если файл есть; этот стенд передаёт URL переменными и только тем сервисам, которым они нужны. Пароль Valkey нет: порт 6379 наружу не опубликован. Это учебное упрощение локального стенда.
Идемпотентность
Область ключа: пользователь + POST + путь /api/v1/chats/{id}/messages + Idempotency-Key. Канонический вид тела — JSON с отсортированными ключами, где отсутствующий attachment_ids равен []. В lab3 схема CreateMessage принимает только text; лишнее поле отклоняется с 400 до записи ключа, поэтому порядок ключей у валидного тела не создаёт второе сообщение.
Одинаковый ключ сериализуется pg_advisory_xact_lock. INSERT сообщения и INSERT в idempotency_keys — одна транзакция. Обрыв до COMMIT не оставляет ни сообщения, ни «окончательного» результата, поэтому тот же ключ можно безопасно повторить. Повтор того же канонического тела в течение TTL возвращает тот же 201 и ту же строку messages. Другое тело — 409. На повторе снова проверяются сессия и членство в чате. Чужой чат и пустой текст ключ не занимают.
Миграции
Их запускает только migrate (python3 /app/migrate.py), один процесс, под pg_advisory_lock. Реплики API миграции не выполняют. 002_idempotency.sql добавляет таблицу и совместим с уже работающим кодом lab2: старый процесс эту таблицу не читает. Rolling update схему не меняет. Ломающее изменение колонки при ещё живых старых репликах этот стенд не поддерживает.
Health, таймауты, SIGTERM
| Узел | Настройка |
|---|---|
API /health/live |
200, пока процесс жив, в том числе во время drain |
API /health/ready |
200, если не идёт остановка и доступны PostgreSQL и Valkey; иначе 503 |
| Traefik healthcheck | GET /health/ready каждые 1 с, timeout 1 с |
| Исключение backend | одна неуспешная проверка убирает реплику из балансировки |
| Верхняя оценка обнаружения | 1 с до следующей проверки + 1 с timeout = 2 с |
| Клиент и upstream Traefik | dial 1 с, ответ 8 с, idle 5 с / 1 с |
| SIGTERM API | сразу 503 на /health/ready и на новые бизнес-запросы; сокет закрывается через DRAIN_SECONDS (3 с) |
stop_grace_period API |
10 с; scripts/stop-one.sh вызывает docker stop -t 8 |
| Docker healthcheck API | /health/ready, интервал 2 с |
Пока реплика уже отдаёт 503, но ещё не вышла, Traefik перестаёт слать ей новые запросы. Краткие обрывы до этого момента возможны и измеряются ниже. restart: unless-stopped поднимает контейнер после падения процесса и не поднимает его после docker stop.
Лимиты и порты
Проверено docker inspect во время scripts/grade4_probe.py (evidence/grade4.json, поле container_limits):
| Сервис | CPU | RAM | Порт на хосте |
|---|---|---|---|
| api | 0.50 | 256 MiB | нет |
| lb | 0.25 | 128 MiB | 127.0.0.1:8080 |
| postgres | 0.75 | 512 MiB | нет |
| valkey | 0.25 | 128 MiB | нет |
| migrate | 0.50 | 256 MiB | нет, одноразовый контейнер |
container_name нет, сервис api масштабируется --scale.
Доказательства критериев
Стенд: WSL2, 20 CPU на машине, лимиты контейнеров — из таблицы выше. Нагрузка — closed-loop POST, concurrency 4, timeout клиента 3 с, без повторов на клиенте. Это подтверждения HTTP, не замер предела БД. Дата прогона: 2026-10-23.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | python3 tests/smoke.py --base-url http://127.0.0.1:8080 |
PASS | evidence/smoke.txt |
| Offline-структура | python3 scripts/check_contract.py |
PASS | вывод в той же сессии, контракт не менялся |
| Две реплики, один вход, общая БД и сессии | docker compose ps, 30 GET /users/me |
Два разных X-Instance-Id на одной сессии. Порт только у lb. Postgres и Valkey без портов на хосте |
evidence/level4.txt, evidence/grade4.json |
| Отказ одной реплики ≤ 10 с | tests/resilience.py --mode failover --action-script scripts/stop-one.sh |
2 реплики до отказа; 139 успешных записей; 4 ошибки; первое успешное восстановление 3.56 с. api-3 остался Exited, api-4 healthy |
evidence/failover.txt |
| Идемпотентность, в том числе гонка | tests/student_level4.py и блок parallel в probe |
8 параллельных POST, один id сообщения, оба instance id. Другое тело — 409. История без дубля | evidence/level4.txt, evidence/grade4.json |
| Сохранность токена и сообщений | tests/resilience.py --mode persistence --action-script scripts/restart.sh |
PASS. Перезапущены api, postgres, valkey. Volumes mtusi-lab3_pgdata и mtusi-lab3_valkeydata на месте |
evidence/persistence.txt |
| Health/readiness и SIGTERM согласованы, LB убирает backend | конфиг infra/traefik.yml, drain в src/server.py, probe |
Период проверки 1 с, максимум обнаружения 2 с. Hook docker stop вернулся за 3.70 с и 3.81 с. После возврата hook целевой id в успешных ответах отсутствует |
evidence/grade4.json |
| По очереди остановить каждую реплику, собрать RPS и ошибки | python3 scripts/grade4_probe.py |
База: 397 rps, 0 ошибок, p50 4.3 мс, p95 59 мс. Отказ первой: 171 rps, 154 ошибки за 9.7 с, чужая реплика ответила через 0.034 с, свой id вернулся через 5.3 с после start. Отказ второй: 172 rps, 40 ошибок, чужая реплика через 0.003 с, восстановление id 6.1 с | evidence/grade4.json |
| Параллельный один ключ через разные реплики | 8 потоков в probe и student_level4 | unique_message_ids=1, оба instance id |
evidence/grade4.json |
| CPU/RAM, нет обхода LB, нет container_name | docker inspect внутри probe |
Лимиты из таблицы выше. У API 8080/tcp без HostPort |
evidence/grade4.json |
| Rolling update под нагрузкой | scripts/rolling-update.sh во время той же нагрузки |
exit 0, 34.9 с, 12894 успеха, 80 ошибок (0.6%), 370 rps. Образ сменился с sha256:d1cb2d180884 на sha256:3ba24670218f. В окне видны и старые, и новые id |
evidence/grade4.json |
| Миграции один раз и совместимы | select version from schema_migrations |
Две строки: 001_init.sql, 002_idempotency.sql. API миграции не запускает. 002 только добавляет таблицу |
этот отчёт |
Эксперименты и отказы
Гипотеза: при остановке одной из двух реплик живая продолжит чтение и запись быстрее чем за 10 с, а один Idempotency-Key не создаст второе сообщение даже при параллельных POST.
Профиль: closed-loop POST сообщений, 4 потока, timeout 3 с, без клиентских retry. Прогрев — 8 с baseline. Окно отказа — время docker stop плюс 6 с. Rolling шёл под той же нагрузкой 35 с. Повтор одного прогона. Аппаратные лимиты — таблица сервисов, не вся машина (20 CPU, память WSL около 16 GiB).
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| Baseline, обе реплики | Оба id, ошибки около нуля | 3182 успеха, 0 ошибок, 397 rps, p50/p95/p99 = 4.3/59/68 мс | — |
stop-one.sh для 4cd3b03e049d |
Запись продолжается на второй реплике, ключ не двоит | 1664 успеха, 154 ошибки (8.5%), 171 rps. После возврата hook целевого id в успехах нет | Успех на другой реплике через 0.034 с от старта stop. Тот же id снова виден через 5.3 с после restore. Потери подтверждённых сообщений нет |
stop-one.sh для ee551154827e |
То же для второй реплики | 1693 успеха, 40 ошибок (2.3%), 172 rps | 0.003 с до чужой реплики, 6.1 с до возврата своего id |
| Публичный failover | ≥2 id до отказа, восстановление ≤ 10 с, остановленная реплика не обслуживает | 2 id, 139 успехов, 4 ошибки, first_recovery 3.56 с. api-3 Exited, api-4 healthy |
3.56 с от старта hook. Подтверждённые сообщения и сессия на месте |
| Rolling update под нагрузкой | Поочерёдная замена, сервис остаётся доступен | exit 0, 80 ошибок на 12894 успеха, образ сменился | Окно 34.9 с, rps 370. Дублей из-за замены не измерялось отдельно: каждая запись нагрузки имеет свой ключ |
| Рестарт api+postgres+valkey | Старый токен и сообщение живы, volume на месте | PASS публичного persistence | Volumes не удалялись |
Падение rps примерно вдвое при одной реплике совпадает с тем, что упор этого профиля — CPU API, а не отказ LB. 154 ошибки в первом отказе — запросы, которые попали в реплику в первые секунды drain, пока Traefik ещё не снял её с балансировки. Клиент их не повторял; в публичном тесте неопределённый POST повторяется с тем же ключом, дубля нет.
Ограничения и следующие шаги
Выдерживается остановка одного процесса API при живых LB, PostgreSQL и Valkey. Не выдерживается отказ узла, отказ самого LB и отказ PostgreSQL: это одна машина и одна БД. Падение Valkey делает /health/ready равным 503, потому что без общего хранилища сессий реплики разошлись бы.
Valkey без пароля и пароль БД в переменных compose — упрощение локального стенда. Сокет Docker у Traefik даёт балансировщику право читать состояние контейнеров; наружу этот сокет не публикуется.
Просроченные ключи идемпотентности удаляются при следующем использовании того же ключа, а не фоновой уборкой. scripts/rolling-update.sh вызывает docker build; на Docker 29 этот путь печатает предупреждение про legacy builder, образ при этом собирается и подменяется, что видно по смене sha256. Схема во время rolling не мигрирует.
397 rps — closed-loop с четырьмя потоками на localhost, с coordinated omission. Это не предел стенда и не результат трека 5.