23 KiB
Отчёт - лабораторная 2
- Автор, группа: Миронов Алексей, бвт2302
- Целевая оценка: 4
- Commit/PR:
4905353lab2 condition inpostgres, sessions in redis / mtusi2026/mtusi2026lab2#65 - Использованные источники, библиотеки и помощь ИИ: исходный учебный репозиторий; FastAPI, Pydantic, psycopg/psycopg-pool, PostgreSQL, Redis, Argon2; документация соответствующих библиотек; использовалась помощь ИИ
Запуск из чистого clone
Требуются Docker Engine/Desktop с Docker Compose, Python 3.12+ и GNU Make. Команды ниже выполняются из корня репозитория.
- Создать локальную конфигурацию и заменить демонстрационный пароль:
Отредактировать
cp .env.example .env.env, задав длинный случайныйPOSTGRES_PASSWORD. Не добавлять.envв Git. - Выполнить офлайн-проверку структуры:
make check - Установить зависимости для валидации контракта и запустить её:
python -m pip install -r requirements-dev.txt make validate - Проверить конфигурацию Compose:
docker compose --env-file .env config --quiet - Собрать и запустить PostgreSQL, Redis и API:
Приложение применяет SQL-миграцию
docker compose --env-file .env up --buildmigrations/001_init.sqlпри инициализации. Дождаться готовности:curl -i http://localhost:8080/health/ready - Запустить основной сценарий API:
make test - После подготовки исполняемого hook перезапуска проверить сохранность данных и сессии:
make test-persistence ACTION_SCRIPT=scripts/restart.shscripts/restart.shперезапускает API, PostgreSQL и Redis, не удаляя именованные volumes. Запускать проверку только на локальном тестовом стенде. - Дополнительные проверки уровня 4 и их ожидаемые результаты описаны в разделах «Доказательства критериев» и «Эксперименты и отказы».
- Безопасно остановить сервисы, сохранив данные:
Намеренное удаление учебных данных вместе с именованными volumes:
docker compose --env-file .env downПоследняя команда удаляет сохранённые данные PostgreSQL и Redis; выполнять её только при осознанном сбросе локального учебного стенда.docker compose --env-file .env down -v
Архитектура и решения
Схема: клиент / smoke- и нагрузочные тесты -> FastAPI -> PostgreSQL и Redis.
- PostgreSQL - источник истины для пользователей, чатов, участников чатов и сообщений. Данные хранятся в именованном volume
postgres_data; схема создаётся SQL-миграциейmigrations/001_init.sql. - Redis хранит серверные сессии. Ключ сессии строится как
session:<sha256(token)>; значение содержит идентификатор пользователя и срок истечения. Исходный Bearer-токен не сохраняется. Redis настроен на AOF (appendonly yes,appendfsync everysec) и использует volumeredis_data. - Docker Compose запускает PostgreSQL, Redis и API. API зависит от успешных healthcheck хранилищ. Наружу опубликован только API-порт
127.0.0.1:8080; PostgreSQL и Redis не публикуют порты на хост. - Пул PostgreSQL ограничивается
DB_POOL_MIN_SIZE,DB_POOL_MAX_SIZEиDB_POOL_TIMEOUT_SECONDS; значение по умолчанию для максимального размера - 10 соединений. В подключении заданы ограничения времени соединения/выполнения запросов и транзакций. - Аутентификация: пароль хранится в виде Argon2id-хеша.
Authorization: Basicиспользуется для входа наPOST /api/v1/auth/sessions; после входа выдаётся случайный непрозрачный Bearer-токен. Защищённые запросы проверяют сессию в Redis. TTL настраивается черезSESSION_TTL_SECONDS; logout удаляет запись сессии. - Транзакции и целостность: создание чата и добавление его участников выполняются в одной транзакции, чтобы ошибка не оставляла частично созданный чат. Пагинация использует стабильный составной порядок
(created_at, id)и непрозрачный base64url cursor. API возвращаетX-Request-Idи единый JSON-формат ошибок. Недоступность обязательного хранилища должна отражаться в readiness и ответах затронутых запросов. - Конфигурация: переменные
.env.exampleсоответствуют Compose-конфигурации:APP_HOST,APP_PORT,SESSION_TTL_SECONDS, параметры пулаDB_POOL_*,REDIS_URLи параметры PostgreSQLPOSTGRES_DB,POSTGRES_USER,POSTGRES_PASSWORD. Пароль должен быть заменён локально; секреты не включаются в отчёт или Git. - Связь с lab1: сохранены основные сущности и сценарии API - пользователи, чаты, участники, сообщения, пагинация, общий формат ошибок,
X-Request-Idи health-endpoints. Ключевое изменение - перенос состояния из памяти процесса в PostgreSQL и введение серверных сессий вместо доверия к одному лишьX-User-Id.
Доказательства критериев
Все команды выполнены на локальном стенде (Windows, Git Bash и WSL, Docker Desktop) на синтетических данных. Проверки make check/make validate и тесты, запускаемые через python tests/..., выполнялись из корня репозитория. Вывод сохранён в evidence.txt, план запроса - в evidence/explain-level4.txt, нагрузка - в evidence/load-run.json.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Структура и синтаксис | make check |
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested. Проверка офлайн, приложение ею не тестируется |
evidence/evidence.txt |
| OpenAPI и JSON Schema | make validate |
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested. |
evidence/evidence.txt |
| Конфигурация Compose | docker compose --env-file .env config --quiet |
Команда завершилась без вывода, сообщений об ошибках нет | evidence/evidence.txt |
| Сборка и запуск | docker compose --env-file .env up --build |
Образы redis и postgres загружены; образ api собран (12/12 шагов, 42.1 с, базовый образ python:3.12.11-slim-bookworm) |
evidence/evidence.txt |
| Живость и готовность | curl -i http://localhost:8080/health/live, curl -i http://localhost:8080/health/ready |
Оба запроса: HTTP 200, тело {"status":"ok"}, заголовок x-request-id присутствует (16 Oct 2026, 16:32:06 и 16:33:35 GMT) |
evidence/evidence.txt |
| Состояние сервисов и порты | docker compose --env-file .env ps |
api, postgres (postgres:17.6-alpine) и redis (redis:7.4.2-alpine) в статусе healthy. На хост опубликован только 127.0.0.1:8080->8080/tcp; у PostgreSQL и Redis указаны лишь внутренние 5432/tcp и 6379/tcp |
evidence/evidence.txt |
| Публичный smoke | make test |
PASS: lab2 public API scenario; infrastructure and grading evidence remain separate. |
evidence/evidence.txt |
| Персистентность при рестарте | make test-persistence ACTION_SCRIPT=scripts/restart.sh (hook выполняет docker compose restart api postgres redis) |
PASS: persistence preserved confirmed data and existing session. Код возврата 0. До теста все три сервиса Up 22 minutes (healthy), после - Up 13 seconds (api) и Up 14 seconds (postgres, redis), все healthy; поле CREATED не изменилось (19-20 часов), то есть контейнеры перезапущены, а не пересозданы. Вывод hook тест скрывает намеренно, поэтому охват рестарта подтверждается этими ps |
evidence/evidence.txt |
| Redis AOF | docker compose --env-file .env exec redis redis-cli CONFIG GET appendonly, ... CONFIG GET appendfsync, ... INFO persistence |
appendonly = yes, appendfsync = everysec. В INFO persistence: aof_enabled:1, aof_last_write_status:ok, aof_last_bgrewrite_status:ok, aof_current_size:5969, aof_base_size:88, aof_rewrites:0, aof_rewrites_consecutive_failures:0, aof_delayed_fsync:0 |
evidence/evidence.txt |
| Истечение TTL сессии | SESSION_TTL_SECONDS=3 в .env, docker compose --env-file .env up -d --force-recreate api, затем python tests/session_ttl.py --base-url http://localhost:8080 |
PASS: expired Redis session is rejected with HTTP 401. После теста TTL возвращён к 3600, API пересоздан тем же up -d --force-recreate api |
evidence/evidence.txt |
| Отказ Redis | python tests/storage_failure.py --target redis --base-url http://localhost:8080 |
PASS: /health/ready returned HTTP 503 while redis was unavailable; затем PASS: readiness recovered to HTTP 200 after redis restart |
evidence/evidence.txt |
| Отказ PostgreSQL | python tests/storage_failure.py --target postgres --base-url http://localhost:8080 |
PASS: /health/ready returned HTTP 503 while postgres was unavailable; затем PASS: readiness recovered to HTTP 200 after postgres restart |
evidence/evidence.txt |
| Конкурентная регистрация | python tests/grade4_checks.py --base-url http://localhost:8080 |
PASS: concurrent same-username registration produced exactly one 201 and seven 409 (8 одновременных запросов с одним username) |
evidence/evidence.txt, evidence/explain-level4.txt |
| Откат транзакции | Та же команда tests/grade4_checks.py |
PASS: injected membership failure returned 503 and rolled back the chat row. Ошибка внедряется временным триггером на chat_members; скрипт удаляет триггер и функцию в блоке finally |
evidence/evidence.txt, evidence/explain-level4.txt |
| План запроса для 10 000 сообщений | Та же команда tests/grade4_checks.py |
PASS: EXPLAIN (ANALYZE, BUFFERS) used messages_chat_created_id_idx; saved evidence\explain-level4.txt. Подробный разбор плана ниже |
evidence/evidence.txt, evidence/explain-level4.txt |
| Нагрузочный прогон | python tests/load.py --base-url http://localhost:8080 --duration 30 --concurrency 4 --output evidence/load-run.json |
60 успешных запросов, 0 ошибок, 1.91 RPS, задержка успешных запросов p50 = 2079 мс, p95 = 2125 мс, p99 = 2140 мс. Один прогон; интерпретация ниже | evidence/evidence.txt, evidence/load-run.json |
План запроса. Набор данных: 10 000 синтетических сообщений в 100 чатах (по 100 сообщений в чате). Запрос: история одного чата в порядке (created_at, id), LIMIT 51. Индекс messages_chat_created_id_idx построен по messages(chat_id, created_at, id), то есть соответствует фильтру по чату и порядку выдачи. Фактический план:
Bitmap Index Scanпоmessages_chat_created_id_idxс условиемchat_id = ...вернул 100 строк (shared hit=3);Bitmap Heap Scanпрочитал 100 блоков, выбрав только строки этого чата;Sort(quicksort, 38 kB) упорядочил эти 100 строк по(created_at, id), затемLimitоставил 51;- суммарно
Buffers: shared hit=109,Planning Time: 0.974 ms,Execution Time: 0.696 ms.
Из плана следует, что запрос не сканирует всю таблицу из 10 000 строк: индекс сужает выборку до сообщений одного чата. Ограничения вывода: планировщик выбрал bitmap-план с отдельной сортировкой 100 строк, а не Index Scan, отдающий порядок индекса; измерялась первая страница без keyset-условия (created_at, id) > cursor; чаты одинакового размера. Поведение на очень больших или неравномерных чатах и со следующими страницами этим прогоном не проверялось.
Эксперименты и отказы
Нагрузочный эксперимент. Использован синтетический closed-loop сценарий tests/load.py: 4 параллельных исполнителя в течение 30 с отправляют POST сообщений в один чат от имени одного пользователя, без автоматических повторов. Фактическая длительность 31.406 с. Результат единственного прогона:
| Параметр | Значение |
|---|---|
| Успешных / неуспешных запросов | 60 / 0 (доля ошибок 0.0) |
| Успешных запросов в секунду | 1.91 |
| Задержка успешных запросов p50 / p95 / p99 | 2079 мс / 2125 мс / 2140 мс |
Задержка почти постоянна (2.08-2.14 с), поэтому при 4 исполнителях RPS примерно равен 4 / 2.08 ≈ 1.9. Причина столь высокой задержки одного POST не исследовалась: не разделено время сервера, клиента и сетевого стека Docker Desktop на Windows, прогон не повторялся. Поэтому результат фиксируется как измерение одного локального профиля, а не как оценка пропускной способности системы.
OS: Майкрософт Windows 11 Pro 10.0.22631 (build 22631) CPU: Intel(R) Core(TM) i5-8350U CPU @ 1.70GHz, cores=4, threads=8 RAM: 15.9 GB
Docker Compose version v2.32.4-desktop.1
docker version Client: Version: 27.5.1 API version: 1.47 Go version: go1.22.11 Git commit: 9f9e405 Built: Wed Jan 22 13:41:44 2025 OS/Arch: windows/amd64 Context: desktop-linux
Server: Docker Desktop 4.38.0 (181591) Engine: Version: 27.5.1 API version: 1.47 (minimum version 1.24) Go version: go1.22.11 Git commit: 4c9b3b0 Built: Wed Jan 22 13:41:17 2025 OS/Arch: linux/amd64 Experimental: false containerd: Version: 1.7.25 GitCommit: bcc810d6b9066471b0b6fa75f557a15a1cbf31bb runc: Version: 1.1.12 GitCommit: v1.1.12-0-g51d5e946 docker-init: Version: 0.19.0 GitCommit: de40ad0
Контролируемые воздействия. Время восстановления в тестах отказа не измеряется: tests/storage_failure.py ждёт HTTP 503 не дольше 10 с после остановки и восстановления HTTP 200 не дольше 45 с после запуска. Сообщения Docker Stopped/Started (0.3-0.4 с) относятся к самой команде, а не к готовности API.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
Истечение TTL (SESSION_TTL_SECONDS=3) |
Сразу после входа токен работает, после TTL запрос с тем же токеном получает HTTP 401 | tests/session_ttl.py: PASS, просроченная сессия отклонена с HTTP 401 |
Не относится к отказу сервиса; сессия истекает по TTL Redis без явного logout |
| Остановка Redis | Readiness становится HTTP 503; после восстановления Redis возвращается HTTP 200 | /health/ready вернул 503 при остановленном Redis, после его запуска вернулся к 200 |
Восстановление уложилось в таймаут теста 45 с, точное время не измерялось. Данные в этом тесте не создавались; сохранность сессий после рестарта проверена отдельным persistence-тестом |
| Остановка PostgreSQL | Readiness становится HTTP 503; после восстановления БД возвращается HTTP 200 | /health/ready вернул 503 при остановленной БД, после её запуска вернулся к 200 |
Восстановление уложилось в таймаут теста 45 с, точное время не измерялось. Данные в этом тесте не создавались; сохранность данных проверена persistence-тестом |
| 8 параллельных регистраций одного username | Одна регистрация успешна (201), остальные получают конфликт (409) | Ровно один ответ 201 и семь 409 | Не относится к отказу сервиса; дубликаты не созданы, так как уникальность username обеспечивает БД |
| Искусственная ошибка при добавлении участника в чат | Транзакция откатывается; частично созданный чат не остаётся | API вернул ограниченную ошибку 503, строка чата в БД отсутствует | Тестовые триггер и функция удаляются скриптом в finally |
| Запрос истории на 10 000 сообщений | Получить и сохранить фактический EXPLAIN (ANALYZE, BUFFERS) |
Использован индекс messages_chat_created_id_idx, время выполнения 0.696 мс; детали и ограничения - в разделе «Доказательства критериев» |
Не является тестом восстановления; синтетические строки скрипт удаляет после проверки |
| Перезапуск API, PostgreSQL и Redis через hook | Ранее созданные данные и действующая сессия остаются доступными, volumes сохраняются | make test-persistence: PASS, подтверждённые данные и существующая сессия сохранились; после перезапуска все сервисы healthy |
Время восстановления отдельно не измерялось: через 13-14 с после перезапуска сервисы уже были healthy. Потери подтверждённых данных и действующей сессии не обнаружено |
Ограничения и следующие шаги
- Нагрузочные измерения: тест использует closed-loop модель с фиксированным числом параллельных исполнителей. Это не полноценный open-loop capacity-тест; результаты зависят от времени ответа сервера, клиентских накладных расходов и характеристик машины. Без повторов и фиксации окружения нельзя делать универсальные выводы по одному запуску.
- Персистентность Redis: AOF с
appendfsync everysecснижает риск потери данных, но при аварии хоста последние примерно секунду изменений теоретически можно потерять. AOF не заменяет резервное копирование и не обеспечивает высокую доступность. - Отказы: предусмотрены контролируемые остановки одного хранилища и последующее восстановление. Автоматический failover, кластеризация PostgreSQL/Redis и восстановление из резервной копии не реализованы в текущей версии.
- Масштабирование и безопасность: rate limiting и горизонтальное масштабирование не реализованы. Порт API привязан к localhost в Compose; стенд предназначен для учебных синтетических данных.