Files
2026-10-30 20:54:04 +03:00

21 KiB
Raw Permalink Blame History

Отчёт — лабораторная 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. Команды ниже — для sh в Linux или WSL; из PowerShell блок целиком не выполняется. Порт 8080 на 127.0.0.1 должен быть свободен: его публикует только lb. Проверка ниже выполнена в WSL Ubuntu 26.04: Docker 29.4.2, Compose 5.1.3, Python 3.14.4. На Windows у python без PYTHONUTF8=1 публичный make check может не прочитать openapi.json в кодировке cp1251; в Linux/WSL это не требуется.

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. Миграции применяет одноразовый сервис migrate до старта реплик.

Дальше один сценарий. Сначала дождаться готовности и увидеть две реплики API без порта на хосте: наружу только 127.0.0.1:8080 у lb. Затем проверки уровня 3. После persistence — повтор миграций: в schema_migrations остаются две строки, по одной на 001_init.sql и 002_idempotency.sql. Failover оставляет одну реплику остановленной; docker compose ps это показывает. Перед grade4_probe.py её нужно поднять и дождаться, пока обе снова healthy: probe сам останавливает каждую реплику по очереди, собирает RPS и делает rolling update, и для старта ему нужны оба X-Instance-Id. Probe перезаписывает evidence/grade4.json.

python3 - <<'PY'
import time
import urllib.request
deadline = time.time() + 120
while True:
    try:
        body = urllib.request.urlopen("http://127.0.0.1:8080/health/ready", timeout=2).read().decode()
    except Exception:
        if time.time() > deadline:
            raise SystemExit("GET /health/ready не стал 200 за 120 с")
        time.sleep(2)
        continue
    print(body)
    break
PY
docker compose --env-file .env -f compose.yaml ps

# make check и make test
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
# make test-persistence ACTION_SCRIPT=scripts/restart.sh
python3 tests/resilience.py --mode persistence --action-script scripts/restart.sh --base-url http://127.0.0.1:8080

docker compose --env-file .env -f compose.yaml run --rm --no-deps migrate
docker compose --env-file .env -f compose.yaml exec -T postgres \
  sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" -c "SELECT version, count(*) FROM schema_migrations GROUP BY version ORDER BY version;"'

# make test-failover ACTION_SCRIPT=scripts/stop-one.sh
python3 tests/resilience.py --mode failover --action-script scripts/stop-one.sh --base-url http://127.0.0.1:8080
docker compose --env-file .env -f compose.yaml ps
sh scripts/restore-api.sh
i=0
n=0
while [ "$i" -lt 40 ]; do
  n=0
  for id in $(docker compose --env-file .env -f compose.yaml ps -q api); do
    status=$(docker inspect -f '{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' "$id")
    if [ "$status" = "healthy" ]; then
      n=$((n + 1))
    fi
  done
  if [ "$n" -ge 2 ]; then
    break
  fi
  i=$((i + 1))
  sleep 1
done
if [ "$n" -lt 2 ]; then
  echo "две реплики api не стали healthy" >&2
  exit 1
fi
python3 scripts/grade4_probe.py

Остановка без удаления данных:

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, 16 CPU на машине, лимиты контейнеров — из таблицы выше. Нагрузка — closed-loop POST, concurrency 4, timeout клиента 3 с, без повторов на клиенте. Это подтверждения HTTP, не замер предела БД. Дата прогона: 2026-10-30.

Критерий 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 evidence/smoke.txt
Две реплики, один вход, общая БД и сессии docker compose ps, 30 GET /users/me Два разных X-Instance-Id на одной сессии: 2d295e897529, 3770bdb4bd34. Порт только у lb. Postgres и Valkey без портов на хосте evidence/level4.txt, evidence/grade4.json
Отказ одной реплики ≤ 10 с tests/resilience.py --mode failover --action-script scripts/stop-one.sh 2 реплики до отказа; 136 успешных записей; 1 ошибка; первое успешное восстановление 3.76 с. api-4 остался Exited, api-3 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.73 с и 3.68 с. После возврата hook целевой id в успешных ответах отсутствует evidence/grade4.json
По очереди остановить каждую реплику, собрать RPS и ошибки python3 scripts/grade4_probe.py База: 117 rps, 0 ошибок, p50 11.6 мс, p95 97 мс. Отказ первой: 60 rps, 23 ошибки за 9.7 с, чужая реплика ответила через 0.028 с, свой id вернулся через 6.7 с после start. Отказ второй: 64 rps, 67 ошибок, чужая реплика через 0.038 с, восстановление id 5.9 с 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, 25.2 с, 2724 успеха, 154 ошибки (5.4%), 108 rps. Образ сменился с sha256:677eedd39f22 на sha256:1de321e159c5. В окне видны и старые, и новые id evidence/grade4.json
Миграции один раз и совместимы select version from schema_migrations Две строки, по одной на версию: 001_init.sql, 002_idempotency.sql. Повторный migrate строки не удвоил. API миграции не запускает. 002 только добавляет таблицу evidence/persistence.txt

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

Гипотеза: при остановке одной из двух реплик живая продолжит чтение и запись быстрее чем за 10 с, а один Idempotency-Key не создаст второе сообщение даже при параллельных POST.

Профиль: closed-loop POST сообщений, 4 потока, timeout 3 с, без клиентских retry. Прогрев — 8 с baseline. Окно отказа — время docker stop плюс 6 с. Rolling шёл под той же нагрузкой 25 с. Один прогон. Аппаратные лимиты — таблица сервисов, не вся машина (16 CPU, память WSL 7.5 GiB).

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
Baseline, обе реплики Оба id, ошибки около нуля 935 успехов, 0 ошибок, 117 rps, p50/p95/p99 = 11.6/97/173 мс —
stop-one.sh для 2d295e897529 Запись продолжается на второй реплике, ключ не двоит 579 успехов, 23 ошибки (3.8%), 60 rps. После возврата hook целевого id в успехах нет Успех на другой реплике через 0.028 с от старта stop. Тот же id снова виден через 6.7 с после restore. Потери подтверждённых сообщений нет
stop-one.sh для 3770bdb4bd34 То же для второй реплики 618 успехов, 67 ошибок (9.8%), 64 rps 0.038 с до чужой реплики, 5.9 с до возврата своего id
Публичный failover ≥2 id до отказа, восстановление ≤ 10 с, остановленная реплика не обслуживает 2 id, 136 успехов, 1 ошибка, first_recovery 3.76 с. api-4 Exited, api-3 healthy 3.76 с от старта hook. Подтверждённые сообщения и сессия на месте
Rolling update под нагрузкой Поочерёдная замена, сервис остаётся доступен exit 0, 154 ошибки на 2724 успеха, образ сменился Окно 25.2 с, rps 108. Дублей из-за замены не измерялось отдельно: каждая запись нагрузки имеет свой ключ
Рестарт api+postgres+valkey Старый токен и сообщение живы, volume на месте PASS публичного persistence Volumes не удалялись

Падение rps примерно вдвое при одной реплике совпадает с тем, что упор этого профиля — CPU API, а не отказ LB. 23 и 67 ошибок в окнах отказа — запросы, которые попали в реплику в первые секунды drain, пока Traefik ещё не снял её с балансировки. Клиент их не повторял; в публичном тесте неопределённый POST повторяется с тем же ключом, дубля нет.

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

Выдерживается остановка одного процесса API при живых LB, PostgreSQL и Valkey. Не выдерживается отказ узла, отказ самого LB и отказ PostgreSQL: это одна машина и одна БД. Падение Valkey делает /health/ready равным 503, потому что без общего хранилища сессий реплики разошлись бы.

Valkey без пароля и пароль БД в переменных compose — упрощение локального стенда. Сокет Docker у Traefik даёт балансировщику право читать состояние контейнеров; наружу этот сокет не публикуется.

Просроченные ключи идемпотентности удаляются при следующем использовании того же ключа, а не фоновой уборкой. scripts/rolling-update.sh вызывает docker build. В этом прогоне сборка шла через BuildKit, образ подменился, что видно по смене sha256. Схема во время rolling не мигрирует.

117 rps — closed-loop с четырьмя потоками на localhost, с coordinated omission. Это не предел стенда и не результат трека 5.