20 KiB
Лабораторная 3 — отчёт
- Автор: Саламатин, БПИ-2304.
- Целевая оценка: 4, весь минимум уровня 3 и все пункты уровня 4. Треки на 5 не выполнялись.
- Проверка: 1 ноября 2026 года, Europe/Moscow. В JSON используется UTC.
- Ветка:
solution/bpi-2304-salamatin. Основа задания — commit0ab3a34репозиторияmtusi2026/mtusi2026lab3. - Сборка и обязательные проверки повторены из отдельного локального clone; проверенный commit
8846b05записан вevidence/clean-source.json. - Публикация: fork gwalut/mtusi2026lab3, PR №85 в
mainпреподавателя. - Перенесена собственная lab2 из gwalut/mtusi2026lab2, ветка
solution/bpi-2304-salamatin. README задания, COURSE, contracts и публичные tests lab3 сохранены.
Запуск
Нужны Docker Desktop с Linux containers и Docker Compose. Для полного автоматического прогона на хосте нужен Python 3.9+; Python приложения и зависимости устанавливаются в контейнере. На Windows текстовые проверки запускаются с -X utf8.
Из корня clone, PowerShell:
python -X utf8 scripts/init_local.py
python -X utf8 scripts/verify.py
verify.py собирает образы, поднимает стенд, выполняет публичные и собственные тесты, полный restart, failover, expiry, проверку SQL-плана и нагрузочные эксперименты. Итог — evidence/verification.json. Данные не удаляются; стенд остаётся работающим. Тесты создают только синтетических пользователей и сообщения.
На текущем компьютере переносимый Python находится на уровень выше репозитория:
..\.tools\python\python.exe -X utf8 scripts/verify.py
Для обычного запуска на Windows без установленного Python: ./start.ps1. Скрипт создаёт конфигурацию через Python-контейнер, собирает и запускает Compose. Эквивалентные команды вручную:
docker run --rm --mount "type=bind,source=$($PWD.Path),target=/work" --workdir /work python:3.13.15-slim-bookworm python scripts/init_local.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --wait-timeout 120
curl.exe --noproxy "*" http://127.0.0.1:8080/health/ready
init_local.py создаёт .env и локальные случайные пароли/DSN/ключ cursor в secrets/. Существующие значения сохраняются и не печатаются. Эти файлы исключены из Git. Не удалять секреты при сохранённых volumes: пароль существующей PostgreSQL не меняется от замены файла.
По умолчанию опубликован только 127.0.0.1:8080 балансировщика. Для другого свободного порта изменить API_PORT в .env до запуска. API_REPLICAS=2 задаёт число API, SESSION_TTL_SECONDS=3600 — срок новых сессий, APP_VERSION — метку конфигурации; остальные runtime-настройки и пути секретов заданы в Compose. Приложение всегда слушает 0.0.0.0:8080 внутри контейнера.
Отдельные проверки:
docker compose run --rm --no-deps checks make check test
docker compose run --rm --no-deps checks make test-student
docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/restart.sh; make test-persistence ACTION_SCRIPT=scripts/restart.sh'
docker compose run --rm --no-deps checks sh -ec 'chmod +x scripts/stop-one.sh; make test-failover ACTION_SCRIPT=scripts/stop-one.sh'
docker compose start api
docker compose run --rm --no-deps checks make explain
python -X utf8 scripts/experiments.py --base-url http://127.0.0.1:8080
После публичного failover реплика намеренно остаётся остановленной: восстановление выполняется отдельной командой docker compose start api. Полный verify.py делает это сам. После восстановления нужно дождаться готовности обеих реплик. На Linux для прямого запуска hooks: chmod +x scripts/restart.sh scripts/stop-one.sh.
Остановка с сохранением данных: docker compose stop, либо docker compose down для удаления контейнеров и сети с сохранением volumes. Только для намеренного удаления всех учебных данных: docker compose down --volumes. Эта команда не применяется в проверках отказа и restart.
Реализация
Клиент → HAProxy → API × 2 → общие PostgreSQL и Redis. Используется один масштабируемый сервис api без container_name. API, БД и Redis не публикуют порты. Балансировка round-robin, без sticky sessions. Лимиты установлены у всех runtime-контейнеров, сервиса миграций и клиента проверок.
Из lab2 сохранены FastAPI, PostgreSQL-миграции, параметризованные запросы, ограниченный pool, scrypt, Basic при входе, Bearer-сессии в Redis с TTL/AOF, проверка членства, подписанные cursor и индекс истории. Добавлены X-Instance-Id, обязательный ключ отправки, таблица message_requests, HAProxy и сценарии отказа/замены.
Результат отправки и само сообщение сохраняются одной SQL-транзакцией. Блокировка строки чата синхронизирует разные процессы. Повтор валидного тела и ключа в течение 24 часов возвращает тот же Message с 201; другое тело — 409. Область ключа включает пользователя и чат; повтор заново проходит аутентификацию и проверку доступа. Ошибка транзакции не сохраняется как окончательный результат. История не кэшируется.
Readiness API требует обе зависимости. HAProxy проверяет его с inter 1s, fall 2, rise 1, fastinter 500ms, timeout check/connect 1s; консервативный бюджет обнаружения зависшего backend — до 4 s при штатном планировании. Docker DNS обновляет адреса, HAProxy поддерживает до восьми реплик. API обрабатывает SIGTERM через Uvicorn: закрытие listener, до 5 s на текущие запросы; Compose даёт 8 s. Общий HTTP-бюджет API — 5 s, таймаут HAProxy до backend — 6 s. Прозрачных повторов POST в LB нет.
Миграции выполняет отдельный сервис migrate; advisory lock и checksum предотвращают гонку/изменение применённого SQL. Для последовательной замены миграции проверяются один раз перед обновлением. 002 добавляет новую таблицу, 001 сохранена. Подробности: docs/ARCHITECTURE.md, сценарий защиты — docs/DEFENSE.md.
Проверки критериев
| Критерий | Команда / сценарий | Результат | Доказательство в evidence/ |
|---|---|---|---|
| Обязательный API и переход lab2 → lab3 | make test через LB и smoke с хоста |
PASS | smoke.txt, published-smoke.txt |
| Две настоящие реплики и общая сессия | Повтор /users/me с одним токеном; Docker inspect |
Не менее двух instance ID и разных контейнеров | student-tests.txt, verification.json |
| Идемпотентность между репликами | 100 запросов, 10 клиентов, один ключ | Одно сообщение и одна запись результата | idempotency.json |
| Конфликт, область ключа, expiry и повтор после logout | Собственные интеграционные тесты | 409 / независимые ключи / новый результат после expiry / 401 | student-tests.txt |
| Атомарность сообщения и результата | SQL-trigger вызывает ошибку при INSERT результата | 503; обе записи откатились; повтор после устранения ошибки успешен | student-tests.txt |
| Полный перезапуск и сохранность | make test-persistence с реализованным hook |
Старый токен и данные сохранены; volumes те же, StartedAt изменился у всех пяти контейнеров | persistence.txt, restart.json |
| Публичный failover | make test-failover |
Две реплики до отказа; восстановление 2.064 s, 2 ошибки, 117 успешных записей | failover.txt, last-stop.json |
| Readiness, timeouts и SIGTERM | Healthchecks HAProxy, stop каждой API | Оба процесса завершились с exit code 0, записи продолжились менее чем за 10 s | failure-api-1.json, failure-api-2.json |
| Отказ каждой реплики с восстановлением предыдущей | scripts/experiments.py |
Измерены RPS, ошибки, latency и время первой записи после остановки | experiments.json |
| Ресурсные лимиты и одна точка входа | Inspect всех runtime-контейнеров | CPU/RAM ограничены; опубликован только LB; API non-root | verification.json |
| Поочерёдная замена под нагрузкой | Drain → stop/remove → recreate, отдельно для каждой API | Два новых контейнера; 0 HTTP-ошибок; все 4475 подтверждений сохранены | rolling-update.json |
| Прежние проверки уровня 4 lab2 | 12 интеграционных тестов, TTL=2, EXPLAIN | PASS; 401 через 2.3 s; индекс на 10 000 сообщениях | student-tests.txt, expiry.json, explain.txt |
| Воспроизводимость из чистого clone | Независимые secrets, Compose-проект и первоначально пустые volumes, повтор обязательных проверок | PASS; исходники не изменены; отдельный порт 18083 | clean-source.json, clean-verification.json, clean-build.txt, clean-student-tests.txt |
| Сохранность контракта задания | Сравнение с исходным commit, SHA-256 после нормализации EOL | 15 файлов задания/контракта/публичных проверок без изменений | source-integrity.json |
Измерения
Стенд: Windows, Docker Desktop 4.50.0/Engine 28.5.1, Linux x86_64. Docker VM: 16 логических CPU, около 7.47 GiB RAM. Лимиты: каждая API — 1 CPU/256 MiB, PostgreSQL — 1 CPU/512 MiB, Redis — 0.5 CPU/192 MiB, HAProxy — 0.5 CPU/128 MiB, checks — 1 CPU/256 MiB. Нагрузочный клиент работает на хосте; CPU/RAM компонентов во время нагрузки сохранены в JSON.
Версии образов: Python 3.13.15-slim-bookworm, PostgreSQL 17.6-bookworm, Redis 7.4.5-bookworm, HAProxy 3.0.12-alpine, Docker CLI проверок 28.5.1-cli. Зависимости закреплены в requirements.txt; image ID фактического стенда записаны в JSON.
Перед каждой нагрузкой создаётся отдельный чат и подтверждённое сообщение; наблюдаются две реплики с одной сессией. Нагрузка closed-loop, четыре клиента, преимущественно отправка сообщений и периодическое чтение текущего пользователя. Воздействие начинается через 4 секунды. При неопределённом результате POST сохраняются ключ и тело. После опыта читаются все страницы истории: сверяются ID и тела всех подтверждений, проверяются дубли. Общий snapshot истории не требуется.
| Опыт | Длительность | Успешные RPS | Ошибок попыток | Первая запись после воздействия | p50 / p95 / p99, ms | Подтверждений сверено |
|---|---|---|---|---|---|---|
| Остановка первой API | 24.041 s | 105.235 | 51 (1.976%) | 1.715 s | 32.652 / 75.027 / 96.705 | 2350 |
| Остановка второй API | 24.034 s | 108.762 | 57 (2.134%) | 1.697 s | 32.088 / 65.561 / 97.489 | 2429 |
| Поочерёдная замена обеих API | 45.015 s | 107.276 | 0 | Запросы продолжались; замена заняла около 23.5 s | 28.249 / 82.882 / 127.075 | 4475 |
Краткие ошибки при резкой остановке допустимы: HAProxy ещё обнаруживает отказ. Они включены в счётчики, потерянных подтверждений и дублей не обнаружено. При управляемой замене backend сначала переводится в drain; в выполненном опыте ошибок не было. Поле first_write_after_action_seconds отсчитывается от начала действия до первой записи после завершения действия; для rolling оно включает длительность всей замены и не означает 23.5 секунды простоя.
В отдельном clone повторены сборка, публичный API, 12 тестов, полный restart, публичный failover, expiry и SQL-план. Нагрузочные опыты там не повторялись. Вспомогательный запуск TTL-контейнера один раз завис в Compose Desktop: скрипт теперь после таймаута проверяет точное имя, метки проекта/сервиса, TTL и состояние запущенного контейнера, затем всё равно выполняет HTTP-проверку истечения сессии. Итоговый повтор завершился PASS. Проверочный стенд остановлен без удаления volumes.
Это одиночные функциональные опыты, не исследование максимальной производительности. Первые 4 s нагрузки служат коротким прогревом и входят в общий RPS. Percentile рассчитаны только для успешных HTTP-операций; closed-loop ограничен клиентом и не показывает реальную очередь при фиксированной входящей интенсивности. Профиль и лимиты одинаковы для двух отказов. Сырые агрегаты, двухсекундные интервалы нагрузки, ошибки, состояния контейнеров и выборки CPU/RAM находятся в соответствующих JSON.
Ограничения
Один host, одна БД, один Redis и один LB остаются точками отказа. Проверен отказ одной API-реплики, а не потеря host или любого хранилища. Сессии требуют сохранённого volume Redis. Backup/restore и треки на 5 не выполнялись. Просроченные ключи очищаются при повторном использовании; периодическая фоновая уборка не добавлена.
Проверена эквивалентная поочерёдная замена контейнеров того же приложения с APP_VERSION=lab3-v2, без изменения бизнес-кода между версиями. Совместимость произвольных будущих миграций не обещается; изменения схемы должны быть обратно совместимыми либо требовать отдельного окна обслуживания. Смешанный запуск старого lab2 и нового lab3 API не поддерживается из-за изменения обязательного контракта ключа.
Учебный стенд использует локальный HTTP и синтетические данные. У API нет UI; отдельные опыты масштабирования 1/2/4 и отказ нескольких узлов не заявляются.
Источники
- Задание lab3, нормативный OpenAPI и публичные проверки.
- HAProxy: DNS resolution, health checks, Runtime API.
- Docker Compose services, PostgreSQL locking.
- Использованы FastAPI, Pydantic, Uvicorn, Psycopg, redis-py и стандартная библиотека Python. Codex использовался при подготовке кода, проверок и документации.