29 KiB
Отчёт — лабораторная 3
- Автор, группа: Черненко, БПИ2301.
- Целевая оценка: 5, трек 1 «Цена масштабирования»; реализованы также уровни 3 и 4.
- Ветка:
solution/bpi2301-chernenko, основа skeleton0ab3a34. Идентификатор сдаваемого коммита:git rev-parse HEAD. PR автор создаёт сам; подготовлены описание PR и заполненный шаблон. - Дата экспериментов: 6 ноября 2026 года. В raw timestamps используется UTC, локальное время защиты — Москва (UTC+3).
- Реализация, тесты, запуск экспериментов и документация подготовлены с помощью OpenAI Codex. Чужой студенческий код не использовался. Библиотеки и официальные источники перечислены ниже; понимать и уметь менять решение обязан автор.
Запуск из чистого clone
Полная инструкция с пояснениями: RUNBOOK.md.
Нужны Docker с Linux containers и Compose v2+, Python на host для операторских
скриптов, доступ к Docker Hub/PyPI при первой сборке. Проверено: host Python
3.12.10, Docker Engine 29.3.1, WSL2 kernel 6.6.87.2, 16 логических CPU,
7 950 499 840 байт памяти Docker VM; CPU host — AMD Ryzen 7 H 260.
Контейнерный runtime — Python 3.12.10; образы python:3.12.10-slim-bookworm,
postgres:17.5-bookworm, haproxy:3.0.11-alpine, CLI тестового runner —
docker:28.1.1-cli. Runtime-библиотеки зафиксированы в requirements.lock.
ID использованных образов и ресурсы VM записаны в hardware.json.
git clone --branch solution/bpi2301-chernenko https://gitea.privcloud.tech/quzzqq/mtusi2026lab3.git
cd mtusi2026lab3
python3 scripts/bootstrap.py
docker compose config --quiet
docker compose up -d --build
docker compose build tester
docker compose run --rm -T tester python scripts/wait_ready.py
docker compose run --rm -T tester python scripts/demo.py
docker compose run --rm -T tester make check validate test
docker compose run --rm -T tester python student-tests/integration.py
python3 scripts/acceptance.py
python3 scripts/extra_checks.py
python3 scripts/run_experiments.py rolling
python3 scripts/run_experiments.py scaling --duration 20 --warmup 5 --repeats 3
docker compose run --rm -T tester python scripts/plot_results.py
На Windows команды python3 на host заменить на py -3.12 -X utf8.
Внутри Docker имена команд не меняются. Все проверки запускались через
контейнер tester, содержащий GNU Make и зависимости; Make на Windows не нужен.
Не выполнять сценарии параллельно: они намеренно меняют состояние стенда.
Bootstrap создаёт случайные локальные secrets и .env, сохраняя существующие.
Пароли, Bearer-токены и HMAC-secret в Git не входят. Единственная опубликованная
точка — http://127.0.0.1:8080; этот HTTP предназначен для изолированного
локального стенда с синтетическими данными. Для удалённой демонстрации нужен TLS.
docker compose down безопасно останавливает стенд без удаления данных;
docker compose up -d запускает с прежними volume/secrets.
Только для намеренного удаления учебных данных: docker compose down --volumes.
Ни один hook или тест эту команду не выполняет.
Архитектура и решения
Клиент → HAProxy → масштабируемый Compose-service api (обычно две реплики)
→ общая PostgreSQL. migrate — отдельный завершающийся job; tester — явный
одноразовый операторский runner, не публичный сервис.
| Роль → service | Версия / сборка | Проверка готовности | Volume / сеть / порты | Передача credentials |
|---|---|---|---|---|
PostgreSQL + sessions → db |
postgres:17.5-bookworm |
pg_isready 2s/1s, SQL/schema проверяет API | pgdata; только data; host-портов нет | db_password через Compose secret |
API → api |
Исходники + python:3.12.10-slim-bookworm; ID образа в hardware.json |
Docker ready-check 2s, HAProxy HTTP-check 1s | Без volume данных; edge+data; только внутренний :8080 | database_url и cursor_key через secrets |
Миграции → migrate |
Тот же собственный образ API | Успешный exit 0, checksum и advisory lock | Схема в общем pgdata через DB; data; без портов | Только database_url |
LB → lb |
haproxy:3.0.11-alpine |
Контроль backend /health/ready, внешний wait_ready через LB | Config read-only; edge; 127.0.0.1:8080 | Не получает service secrets |
Проверки → tester |
tester-stage Dockerfile, Python 3.12.10, Docker CLI 28.1.1 | Явный одноразовый запуск, exit status каждой команды | Рабочие файлы/evidence; edge; без host-портов | Нет service secret mounts; доверенный operator с Docker socket |
Предыдущий код lab2 не предоставлялся: обязательный минимум написан заново по контракту lab3. Сохранены регистрация, Argon2id, Basic-вход, Bearer-сессии с TTL и отзывом, чаты с неизменяемыми участниками, сообщения и keyset pagination. Добавлены балансировщик, общие ключи повторов, X-Instance-Id, hooks и исследования. Redis не требуется: нормативный контракт разрешает хранить сессии в PostgreSQL.
PostgreSQL — источник истины для всех данных и сессий. API хранит в памяти лишь настройки, пул соединений и alias процесса. Пароли хешируются Argon2id (time_cost=2, memory_cost=19456 KiB, parallelism=1); случайные Bearer имеют 256 бит энтропии, в БД хранится их SHA-256. Срок действия проверяется по времени БД и не продлевается при перезапуске. Cookies/sticky sessions не используются.
Создание чата и его участников — одна транзакция. Отправка сообщения и запись
результата идемпотентности — одна транзакция под pg_advisory_xact_lock от области
user/chat/key. Метод POST и тип пути фиксированы endpoint. Полная область имеет
PRIMARY KEY в БД; коллизия 64-битного lock hash только сериализует лишние запросы.
Повтор валидного body возвращает прежний Message и 201 в течение 24 h,
изменённый body — 409. Отсутствующий attachment_ids и [] нормализованы одинаково;
вложения до lab4 не поддерживаются. COMMIT предшествует 201. Транзиентные 5xx
не сохраняются как результат; после неопределённого POST клиент повторяет тот же
ключ. Сессия и участие проверяются и при повторе. Общего кеша истории нет.
Readiness проверяет БД и применённую схему; liveness — только процесс. HAProxy: HTTP-check /health/ready, inter=1s, fall=2, rise=2, timeout check=1s; консервативная оценка обнаружения зависшего backend — около 4 s. Docker DNS 127.0.0.11 и server-template на 8 адресов позволяют заменять IP без ручного редактирования LB. Connect timeout=0.5s, server=5s, client=10s; SQL statement_timeout=2.5s, lock_timeout=2s, pool wait=2s. HAProxy не повторяет POST автоматически. Uvicorn при SIGTERM прекращает принимать новые соединения, ждёт активные запросы до 5s; Compose даёт API 8s, failover-hook 6s. Результаты переходных ошибок измеряются, нулевая потеря соединений не обещается.
Мигратор применяет SQL под отдельной транзакционной advisory-блокировкой, хранит checksum и не запускается каждой API-репликой. Повтор job — проверка/пропуск применённого файла. Исследованная rolling replacement не меняет схему; будущий destructive DDL требует expand/contract и отдельно не проверялся.
Курсоры подписаны общим HMAC, привязаны к ресурсу; история сортируется по (created_at,id), выбирается limit+1. Неизменная история обходится без повторов. Между запросами нет общего snapshot: поздний COMMIT или коррекция часов БД может создать запись до уже пройденного курсора; актуальное чтение с первой страницы её увидит. Подтверждённое сообщение доступно следующему чтению любого API.
Рабочие переменные .env.example и их смысл подробно перечислены в RUNBOOK.
Ресурсы по умолчанию: каждая API 0.5 CPU/256 MiB, DB 1 CPU/512 MiB,
LB 0.5 CPU/128 MiB, мигратор 0.5 CPU/128 MiB, runner 2 CPU/512 MiB;
DB_POOL_SIZE=4 на API. API/DB не публикуют host-порты, container_name отсутствует.
Сети edge/data разделены; DB только в data, LB только в edge. Секрет БД получают
API и мигратор, cursor_key только API, db_password только DB. Runner с Docker
socket — локальный доверенный операторский инструмент, отдельно от API/LB.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Структура и полный OpenAPI | docker compose run --rm -T tester make check validate |
PASS обеих проверок | checks.txt |
| Публичный smoke, контракт lab2→3 | docker compose run --rm -T tester make test |
PASS API-сценария, включая auth, access, paging, idempotency | checks.txt |
| Compose, ≥2 API, общий DB/session store, единый LB | docker compose up -d --build; python scripts/stack_control.py snapshot |
Разные реальные API ID; PostgreSQL и LB; API/DB host-порты отсутствуют | compose.yaml, snapshots |
| Одна сессия на разных API | docker compose run --rm -T tester python student-tests/integration.py |
16 конкурентных запросов, наблюдались две реплики | student-tests.txt |
| Общая конкурентная идемпотентность | та же integration-проверка | Одинаковый Message, одна запись для 16 повторов, другой body→409, разная область независима | student-tests.txt |
| Persistence и прежняя сессия после полного рестарта | make test-persistence ACTION_SCRIPT=scripts/restart.sh в tester |
PASS с прежним токеном, подтверждённым сообщением | persistence.txt, hook output, процессы |
| Failover через явный hook, запись ≤10s, нет дублей | make test-failover ACTION_SCRIPT=scripts/stop-one.sh в tester, два запуска |
Восстановление 1.597s / 1.384s; 3 / 2 переходные ошибки; 129 / 127 успешных записей | failover-1, failover-2, остановленные процессы |
| Уровень 4: каждая API остановлена отдельно; чтение/запись во время отказа | python scripts/acceptance.py |
Для каждой реплики: read/write восстановились <1.5s, подтверждения сохранены, дублей 0; RPS/errors/latency записаны отдельно | mixed-1, mixed-2, процессы 1, процессы 2 |
| Уровень 4: health/readiness, тайм-ауты и SIGTERM | python scripts/extra_checks.py; failover-hooks |
live остаётся 200 при отказе DB, ready→503; LB исключает API при остановке | dependency-health, HAProxy, Dockerfile |
| Уровень 4: CPU/RAM, изоляция портов, секреты, масштабируемый service | docker compose config --quiet; snapshots |
Лимиты применены через inspect; наружу опубликован только LB | compose.yaml, resource samples |
| Уровень 4: поочерёдная замена под нагрузкой | python scripts/run_experiments.py rolling |
Оба исходных ID заменены; 5377 подтверждений, 58 ошибок, 71.607 RPS | rolling.json, raw load |
| Уровень 4: однократные согласованные миграции | docker compose up -d; повторный запуск migrate |
Схема применена отдельным job; checksum/lock; реплики не делают DDL | migrate.py, миграция |
| Дополнительно: истечение сессии | python scripts/extra_checks.py |
Действующая сессия→200; через TTL=2s→401 | session-expiry.txt |
| Трек 1: фиксированный бюджет API, 1/2/4 реплики | python scripts/run_experiments.py scaling --duration 20 --warmup 5 --repeats 3 |
Три повтора каждого варианта, одинаковый профиль | RESEARCH.md, summary.json, график |
| Трек 1: серия с ростом ресурсов | та же команда | 0.5 CPU/256 MiB на каждую из 1/2/4 реплик, DB/LB фиксированы | агрегаты, raw samples |
| Трек 1: saturation point и подтверждённое улучшение | та же команда, серии saturation и db-improved | Конкуренция 8/32/64; контролируемое увеличение только DB CPU .25→1; RPS/ошибки/задержки и CPU/RAM измерены | RESEARCH.md, график saturation |
Публичные файлы tests/, contracts/, README, COURSE, CONTRIBUTING, Makefile
и исходный workflow contracts не изменены. Новые проверки находятся отдельно
в student-tests/; приложение и runner проверяются новым application job без
pull_request_target и внешних секретов. Этот job подготовлен для GitHub; на Gitea
он не выдаётся за реально выполненный CI. Доказательства здесь — локальные прогоны.
Эксперименты и отказы
Гипотеза: при фиксированном общем ресурсе API число процессов само по себе не увеличивает пропускную способность линейно; после насыщения общей БД увеличение ресурсов API почти не помогает. Увеличение CPU этой БД должно сдвинуть её предел при неизменных API/LB и профиле запросов.
Методика: собственный closed-loop генератор HTTP POST сообщений на стандартном http.client, отдельное постоянное соединение на worker-поток через HAProxy, один новый синтетический чат на прогон, текст длиной 18 ASCII code points, уникальные Idempotency-Key, без retry. Регистрация/вход вне измерительного интервала. Прогрев 5 s, измерение 20 s, конкуренция 32, три повтора. Для saturation — конкуренция 1/4/8/32/64 при DB .25 CPU и 8/32/64 при DB 1 CPU с теми же прогревом, длительностью и числом повторов. Набор данных растёт; точные размеры users/chats/messages/sessions до/после каждого прогона есть в resources.json. В каждом новом чате до прогрева 0 сообщений; прогревные вставки сохраняются, но их latency не включена в измеряемую выборку.
Fixed: суммарно API 1 CPU/512 MiB, деление на 1/2/4. Growing: каждая API 0.5 CPU/256 MiB. В обеих сериях DB=.25 CPU/512 MiB, LB=.5 CPU/128 MiB. Следовательно, в fixed суммарный бюджет работающей серверной части неизменен: 1.75 CPU / 1152 MiB; отдельный генератор всегда имеет 2 CPU / 512 MiB. Завершившийся мигратор в нагрузке не участвует. Пулы в базовых сериях имеют одинаковый максимум 4 на процесс, поэтому их суммарная ёмкость растёт с N: это часть исследуемой цены размножения процессов, а не скрытый фиксированный лимит БД. Предварительные контроли pool=4→1 и очереди LB не дали устойчивого выигрыша с HTTPX и сохранены отдельно; в основную числовую серию они не входят. Это намеренно ограниченный стенд для выявления shared bottleneck, без искусственных sleep в приложении. В улучшенном варианте меняется только DB CPU .25→1; API остаются 4×.5 CPU/256 MiB. Это улучшение распределения ресурсов, не заявление об оптимизации SQL при неизменном бюджете.
По каждому запросу сохранены status, latency, время старта и alias API без
body/credentials/tokens в *.jsonl; по прогону — HTTP successful RPS,
error_ratio и p50/p95/p99 успешных запросов в *.json. CPU/RAM собираются
через docker stats, квоты — inspect; CPU 100% означает один логический CPU.
Сэмплы охватывают запуск, bootstrap и прогрев, не являются непрерывным trace.
Исчезновение одноразового контейнера при stats отмечено как sampling_error,
а не как нулевое потребление. Выводы и графики: RESEARCH.md.
Rolling replacement: 75 s измерения после 5 s прогрева, конкуренция 16, временно допускается третья API. Каждая из двух исходных по очереди останавливается, удаляется и заменяется после готовности дополнительной. Зафиксированы исходные/конечные ID и результаты запросов; схема и версия кода при замене не менялись. Утверждается проверенная поочерёдная замена процессов, а не совместимость любых будущих версий API. Этот функциональный тест выполнялся HTTPX-генератором: 5377 успешных ответов, 58 ошибок (27 HTTP 503 и 31 transport/timeout), error_ratio=1.0672%, 71.607 successful RPS, p50/p95/p99=101.455/722.203/1228.612 ms. Переходные ошибки не скрыты; zero-downtime не заявляется.
Основная ёмкостная серия полностью повторена после проверки генератора: на одном стенде с двумя API и DB 1 CPU новый клиент дал 270.793 RPS против 61.529 HTTPX при C=32. Исходные 57 опытов не выданы за предел сервера и сохранены в exploratory-httpx.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
| Отказ первой API | Сессия сохраняется, read/write≤10s | read 86/0 ошибок, write 83/3 ошибок; RPS 5.715/5.516 | read 1.476s, write 1.486s; 84 подтверждения сохранены |
| Отказ второй API | Тот же результат для другой реплики | read 86/0 ошибок, write 82/4 ошибок; RPS 5.692/5.428 | read 1.470s, write 1.479s; 83 подтверждения сохранены |
| Перезапуск API, PostgreSQL/session store и LB | Данные и старый токен переживают рестарт | Публичный persistence PASS; StartedAt всех компонентов изменён | Обнаружения потери подтверждённых сообщений нет; TTL не продлён |
| Поочерёдная замена API под нагрузкой | Новые процессы готовы до ухода старых | Исходные ID отсутствуют в конечном snapshot, load продолжался | Числа ошибок и задержки — rolling.json; это не тест потери host |
| Остановка PostgreSQL | Процесс live, синхронный путь not ready | live=200, ready=503 в диагностическом API-запросе | После возврата DB стенд восстанавливается, failover DB не заявлен |
| Истечение TTL | Токен перестаёт действовать | 200 до истечения, 401 после 2.2s при TTL=2s | Прежний срок не переносится на время перезапуска |
Основной числовой результат: при четырёх API и C=32 увеличение только CPU БД с 0.25 до 1 повысило медиану с 131.867 до 424.763 RPS (3.221×), снизило p95 с 694.982 до 225.987 ms; ошибок в обеих тройках повторов нет. При возврате квоты 0.25 CPU получено 133.953 RPS. Доля throttled periods БД снизилась с 90.42% до 4.75%. Полные данные и ограничения — в RESEARCH.md.
Ограничения и следующие шаги
Выдерживается отказ одного API-процесса при работающих другой реплике, PostgreSQL, LB и Docker-host. Единственные DB, LB и host остаются SPOF; нет репликации БД, multi-node failover или резервных копий. Persistent volume защищает от пересоздания контейнера, не от потери диска. HTTP ограничен loopback; удалённая эксплуатация без TLS не предполагается. DB account учебный, один для мигратора и приложения; отдельные least-privilege roles — следующий этап.
Генератор closed-loop ограничен клиентом и имеет coordinated omission. Перцентили относятся только к успешным ответам; ошибки считаются отдельно. RPS — HTTP-подтверждения, не точный счётчик COMMIT. Исследование не устанавливает универсальный production saturation point: оно локально для указанного профиля, VM и CPU-квот. Неизолированные фоновые процессы host, последовательный порядок серий, растущие индексы и прогретый page cache ограничивают точность сравнения; поэтому приводятся три повтора и диапазон, а не один лучший результат.
Нет автоматической очистки expired sessions/idempotency, TLS и rate limiting. Просроченные записи не действуют, но занимают место до явного обслуживания. Поддержка вложений, broker/worker и telemetry относятся к следующим лабораторным. Подтверждено только улучшение, измеренное в RESEARCH при изменении DB CPU; оптимизация индексов, SQL, пулов, async-драйвера и open-loop исследования — дальнейшие гипотезы, не выданные за выполненные результаты.
Источники и библиотеки
- Контракт и публичные проверки данного skeleton — нормативное основание.
- Docker Compose services: scale, ресурсы, healthcheck, depends_on и stop_grace_period.
- HAProxy 3.0 configuration: HTTP-check, fall/rise, resolvers и server-template.
- PostgreSQL 17 explicit locks: transaction-scoped advisory locks для общей идемпотентности и мигратора.
- Psycopg 3 connection pools: bounded AsyncConnectionPool и транзакционный connection context.
- argon2-cffi API: PasswordHasher, Argon2id и единицы memory_cost.
- FastAPI, Uvicorn, psycopg, argon2-cffi — runtime; httpx, Matplotlib и
openapi-spec-validator — инструменты проверки/исследования. Точные runtime
версии —
requirements.lock, основные прямые зависимости —requirements.txt. - Помощь ИИ: OpenAI Codex генерировал и проверял код, проводил локальные запуски, анализировал вывод и подготовил документацию. Данные измерений получены реальными прогонами, не сгенерированы как пример.
Ответы на вопросы README и объяснение для устной защиты: DEFENSE.md.