29 KiB
Отчёт — лабораторная 2
- Автор, группа: Казаков Амин, БВТ2303
- Целевая оценка: 5, трек 2 «План запроса и восстановление»
- Commit/PR: ветка
solution/bvt2303_kazakov, ссылка на PR — после публикации - Использованные источники, библиотеки и помощь ИИ: FastAPI, psycopg 3 + psycopg_pool, argon2-cffi, redis-py; документация PostgreSQL (transactions, EXPLAIN), Redis persistence, RFC 7617. Эндпоинты на SQL, кэш сессий, собственные тесты, скрипт EXPLAIN, схема БД, мигратор и скрипт исследования трека 2 писались вместе с ИИ-ассистентом Claude пошагово. Весь код разобран и объясняется на защите.
Запуск из чистого clone
Проверено на: Windows 11, Docker Desktop (Engine 29.8.2, Compose 5.5.1), 12 CPU / 8 GB RAM для Docker; Python 3.14 на хосте для тестов (тестам нужна только стандартная библиотека, скрипту EXPLAIN — psycopg).
Образы: postgres:17.6-alpine, redis:7.4.2-alpine, API собирается из python:3.11.9-slim; версии Python-зависимостей закреплены в requirements.txt.
# 1. локальные настройки (в Git не попадают); задать свой POSTGRES_PASSWORD
cp .env.example .env
# 2. сборка и запуск; миграции применяет само API при старте
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# 3. дождаться готовности
curl -f http://localhost:8080/health/ready # {"status":"ok"}
# 4. публичные проверки
make check
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
# на Windows без make:
# python tests/smoke.py
# python tests/resilience.py --mode persistence --action-script scripts/restart.cmd
# 5. собственные проверки уровня 4 (управляют контейнерами через docker compose)
python student-tests/test_auth.py
python student-tests/test_race.py
python student-tests/test_expiry.py
python student-tests/test_outage.py
python student-tests/explain_history.py # pip install "psycopg[binary]"
# 6. исследование уровня 5, трек 2 (отдельная база track2_lab, рабочая не трогается)
python student-tests/track2_research.py indexes # 160 000 сообщений, 4 варианта индекса, стоимость записи
python student-tests/track2_research.py backup # pg_dump -> новый контейнер + пустой volume -> pg_restore -> сверка
Остановка с сохранением данных: docker compose --env-file .env down (volume pgdata остаётся).
Намеренное удаление учебных данных: docker compose --env-file .env down -v — удаляет volume с БД безвозвратно.
Бутстрап БД: отдельных действий оператора нет. При старте API берёт pg_advisory_xact_lock, создаёт schema_migrations и применяет в одной транзакции все ещё не применённые migrations/*.sql по порядку имён. Повторный старт ничего не дублирует.
Архитектура и решения
клиент ──HTTP──> api (FastAPI, uvicorn, :8080)
├──> postgres:5432 — источник истины: users, chats, chat_members, messages, sessions
└──> redis:6379 — только кэш сессий (TTL), без persistence
Из lab1 перенесено: контракт эндпоинтов, формат ошибок с X-Request-Id, keyset-пагинация по (created_at, id), health. Изменено: словари в памяти заменены PostgreSQL; X-User-Id заменён на Bearer-сессии; регистрация требует пароль; добавлены Redis и миграции.
Схема (migrations/001_init.sql): PK у всех таблиц; FK chat_members → chats/users, messages → chats/users, sessions → users; UNIQUE(username) и CHECK по регулярке и длинам; составной PK chat_members(chat_id, user_id) запрещает дубли участников. Индексы: messages(chat_id, created_at, id) — история; chat_members(user_id) — «мои чаты»; sessions(user_id).
Транзакционные границы:
- Создание чата — одна транзакция:
INSERT chats+INSERT chat_membersдля всех участников. Неизвестный участник даёт FK violation, вся транзакция откатывается, ответ 400. - Регистрация — один
INSERT. Гонку одинаковых username решаетUNIQUEв PostgreSQL: проигравшие получаютunique_violationи ответ 409. - Остальные записи — одиночные
INSERT/UPDATEв autocommit-блоке пула. 201 возвращается только после COMMIT.
Аутентификация: пароль хешируется Argon2id (argon2-cffi, параметры по умолчанию). POST /auth/sessions принимает только Basic. Для несуществующего username тоже выполняется проверка против хеша-заглушки, поэтому время ответа и сам 401 одинаковые. Токен — secrets.token_urlsafe(32) (256 бит). В БД хранится только sha256(token): по дампу БД токенами воспользоваться нельзя. Сессия: expires_at = now() + SESSION_TTL_SECONDS; logout пишет revoked_at. Проверка: revoked_at IS NULL AND expires_at > now(). Сначала проверяется аутентификация (401), затем членство в чате (404 для чужого).
Redis — роль, источник истины, expiry, инвалидация:
- Источник истины —
sessionsв PostgreSQL. Redis — read-through кэшsession:<sha256>→{user, expires_at}. - TTL записи =
min(оставшаяся жизнь сессии, SESSION_CACHE_MAX_TTL=60 с), поэтому кэш никогда не продлевает сессию. - Logout: сначала
revoked_atв PostgreSQL, затем в Redis пишется надгробиеrevoked. Кэш заполняется черезSET NX, поэтому параллельный запрос не перезапишет надгробие. - Redis без persistence (
--save "" --appendonly no), потому что он не единственное хранилище. После restart илиFLUSHALLкэш пуст, сессии читаются из PostgreSQL. Отозванные сессии не «воскресают», это проверено тестом. - Redis недоступен: фоновый поток делает PING раз в 2 с. Пока Redis «лежит», запросы идут сразу в PostgreSQL.
/health/readyот Redis не зависит.
Пул и таймауты: psycopg_pool.ConnectionPool(min 1, max 10, timeout=5 с, check_connection), connect_timeout=5, statement_timeout=5000 мс. У Redis socket_timeout и connect_timeout по 0,3 с. Все SQL-запросы параметризованы (%s). В f-строки подставляются только константные фрагменты условий, без пользовательских данных.
Readiness: критичная зависимость одна — PostgreSQL (SELECT 1 за ≤2 с, иначе 503). Redis не критичен.
Переменные .env.example → реальная конфигурация:
| Логическое имя skeleton | Реализация |
|---|---|
APP_HOST, APP_PORT |
0.0.0.0:8080 в Dockerfile/compose |
SESSION_TTL_SECONDS |
одноимённая переменная, по умолчанию 3600 |
DATABASE_URL_FILE |
compose собирает DATABASE_URL из POSTGRES_* в .env; код поддерживает и DATABASE_URL_FILE |
SESSION_STORE |
postgres (источник истины) + redis (кэш) |
CACHE_URL_FILE |
REDIS_URL (поддерживается и REDIS_URL_FILE) |
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | make check, make test |
оба PASS | evidence/smoke.txt |
| Данные и сессии переживают рестарт API, PostgreSQL и Redis | tests/resilience.py --mode persistence с scripts/restart.cmd; отдельно sh scripts/restart.sh + smoke |
PASS: тот же токен читает те же данные; StartedAt всех трёх контейнеров изменился, volume pgdata не пересоздавался |
evidence/persistence.txt |
| PK/FK, UNIQUE username, миграции с нуля, повторный запуск без дублей | migrations/001_init.sql, db.run_migrations |
на пустом volume создаются 5 таблиц и schema_migrations; повторный старт API ничего не применяет |
migrations/, db.py |
| Атомарное создание чата / rollback | student-tests/test_race.py |
чат с неизвестным участником → 400; список чатов не изменился; 0 чатов без участников в БД | evidence/test_race.txt |
Basic только на POST /auth/sessions, Bearer на остальных, X-User-Id не даёт доступа |
smoke + student-tests/test_auth.py |
Basic/X-User-Id/чужой токен на бизнес-эндпоинте → 401 с WWW-Authenticate: Bearer |
evidence/test_auth.txt |
| Неверный пароль | test_auth.py |
401 с WWW-Authenticate: Basic ...; для неизвестного пользователя ответ такой же |
evidence/test_auth.txt |
| Logout | test_auth.py |
204 без тела; тот же токен → 401, хотя он был в кэше; повторный logout → 401 | evidence/test_auth.txt |
| Expiry при коротком TTL | student-tests/test_expiry.py (API перезапускается с SESSION_TTL_SECONDS=2) |
через 3,5 с тот же токен → 401 | evidence/test_expiry.txt |
| Пароли — password KDF | app.py: argon2.PasswordHasher (Argon2id) |
в users.password_hash строка $argon2id$... |
app.py |
| Secrets/volumes не в Git | .gitignore (.env, backups/, volumes/) |
git status не показывает .env |
— |
| Redis для сессий с TTL; источник истины и инвалидация | test_auth.py |
ключ session:* появляется после запроса; после logout — 401; после FLUSHALL действующая сессия работает, отозванная остаётся отозванной |
evidence/test_auth.txt, cache.py |
| Гонка регистрации одинакового username | test_race.py |
20 параллельных запросов → 201 ×1, 409 ×19 | evidence/test_race.txt |
| Параметризованные запросы, ограниченный пул, таймауты | код | %s-параметры; пул max 10, timeout 5 с; statement_timeout 5 с |
db.py, app.py |
| Индекс истории + EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщений | student-tests/explain_history.py |
25 000 сообщений, чат на 15 000. С индексом keyset-страница: Index Scan, 51 буфер, 0,09 мс. Без индекса: Seq Scan + Sort, 334 буфера, 1,95 мс | evidence/explain-history.txt |
| Пагинация без полного scan | там же | keyset читает ~51 буфер на любой глубине; OFFSET 10000 при том же индексе читает 10 095 буферов (для сравнения, в API не используется) | evidence/explain-history.txt |
| Недоступность Redis | student-tests/test_outage.py |
docker compose stop redis: вход, чтение, запись и logout работают через PostgreSQL; первый запрос до обнаружения отказа ≈4 с, следующие ≈0,03 с; ready = 200 |
evidence/test_outage.txt |
| Недоступность БД | test_outage.py |
docker compose stop postgres: запись → 503 unavailable за ≈5 с; аноним → 401; неизвестный токен → 503, не 200; ready → 503. После start тот же токен работает, история цела |
evidence/test_outage.txt |
Эксперименты и отказы
Стенд: один Docker-хост (Windows 11, Docker Desktop, 12 CPU / 8 GB), все контейнеры без CPU/RAM-лимитов. Исследование уровня 5 — в разделе «Трек 2» ниже.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|---|---|---|---|
scripts/restart.sh: stop api → restart postgres, redis → start api |
данные и действующий токен сохраняются | PASS persistence; smoke после рестарта PASS | ~10–15 с до ready; подтверждённых потерь нет |
docker compose stop redis |
обход кэша, без отказа клиентам | всё работает через PostgreSQL; ready 200 | первый запрос ≈4 с (DNS/таймаут), далее без задержки; после start кэш снова используется через ≤2 с |
redis-cli FLUSHALL |
действующие сессии из БД, отозванные остаются отозванными | так и есть | мгновенно; потерь нет |
docker compose stop postgres |
ограниченная ошибка 503, без доверия анониму | 503 за ≈5 с, аноним 401, ready 503 | после start ≈несколько секунд; неподтверждённая запись (503) не появилась, подтверждённые на месте |
SESSION_TTL_SECONDS=2 |
истечение сессии без продления кэшем | через 3,5 с → 401 | — |
Ответы на вопросы защиты:
- COMMIT гарантирует атомарность и видимость изменений. Durability при сбое ОС/питания зависит от
fsync=onиsynchronous_commit=on: это значения по умолчанию, они не менялись. Сsynchronous_commit=offпоследние подтверждённые транзакции могут потеряться. - Сессии: источник истины — PostgreSQL. После flush или restart Redis кэш пуст, сессии подтягиваются из БД, отозванные остаются отозванными.
- Аутентификация vs доступ: Bearer отвечает на вопрос «кто ты» (иначе 401). Членство в
chat_membersотвечает на вопрос «можно ли тебе в этот чат» (иначе 404, без раскрытия существования). - Хеш пароля vs checksum: Argon2 намеренно медленный и с солью, чтобы перебор паролей был дорогим. sha256 быстрый и подходит для токена: у токена 256 бит случайности, перебирать его бессмысленно, а проверка нужна на каждом запросе.
Трек 2 (оценка 5): план запроса и восстановление
Скрипт: student-tests/track2_research.py. Он работает в отдельной базе track2_lab того же PostgreSQL 17.6, к рабочей базе приложения не прикасается. Сырые результаты лежат в evidence/track2-indexes.txt и evidence/track2-backup-restore.txt.
Гипотеза
- Составной индекс
(chat_id, created_at, id)даёт постоянную стоимость страницы истории (десятки буферов, доли миллисекунды) независимо от размера чата и глубины страницы. Любая более простая альтернатива деградирует хотя бы на одном профиле чатов: огромном, среднем или маленьком. - Цену за индекс видно в объёме WAL и в размере индекса, а не во времени одиночного INSERT.
pg_dump+pg_restoreв новое хранилище возвращают данные бит в бит на момент снимка. Всё, что записано после снимка, теряется (RPO = интервал между бэкапами).
Методика
-
Данные (генерация повторяемая,
setseed(0.42)): 160 000 сообщений в 1 055 чатах с сильно неравномерным распределением:вид чата чатов сообщений в каждом всего huge 1 60 000 60 000 large 4 10 000 40 000 medium 50 1 000 50 000 small 1 000 10 10 000 Длина текста тоже неравномерна (
10 + 1990·random()³): большинство сообщений короткие, максимум ≈2000 символов, в среднем ≈512. Таблицаmessages— 90,6 MB heap. -
Варианты индекса (PK по
idесть всегда): A(chat_id, created_at, id)— текущий; B(chat_id); C(created_at, id); D без индекса. -
Чтение: запрос приложения
list_messages(LIMIT 51) на чатах huge / medium / small: первая страница, keyset-страница на 90 % глубины, а для huge ещё иOFFSET.EXPLAIN (ANALYZE, BUFFERS), медиана 7 прогонов, тёплый кэш. -
Запись: (а)
INSERT … SELECTна 20 000 строк, разбросанных по всем чатам; (б) 2 000 отдельныхINSERT, как делает API. Каждая вставка выполняется в транзакции сROLLBACK, чтобы данные не менялись между вариантами. Медиана 3 прогонов; WAL меряется черезpg_current_wal_insert_lsn(). -
Восстановление:
pg_dump -Fcиз compose-контейнера → новый контейнерpostgres:17.6-alpineс новым пустым volume →pg_restore→ сверка количества строк по всем таблицам, md5 по всем сообщениям, md5 распределения по чатам, списка индексов и 7 конкретных сообщений. После дампа в источник пишется 1 сообщение, чтобы показать границу потери.
Результаты: чтение (время, мс / прочитано буферов)
| страница | A (chat_id, created_at, id) |
B (chat_id) |
C (created_at, id) |
D нет |
|---|---|---|---|---|
| huge, первая | 0,084 / 8 | 40,1 / 12 509 (Seq Scan + Sort) | 0,069 / 51 | 29,5 / 14 269 |
| huge, keyset после 54 000-го | 0,073 / 18 | 20,7 / 4 410 (Bitmap + Sort 6 000 строк) | 0,574 / 1 060 | 26,0 / 14 211 |
huge, OFFSET 54000 |
105,8 / 11 691 (Seq Scan + Sort) | 116,6 / 12 509 | 100,5 / 13 389 | 97,3 / 14 269 |
| medium (1 000), первая | 0,080 / 15 | 0,875 / 110 | 3,0 / 5 750 | 25,5 / 14 269 |
| medium, keyset после 900-го | 0,069 / 9 | 0,769 / 110 | 7,5 / 2 274 | 26,1 / 14 211 |
| small (10), первая | 0,050 / 5 | 0,114 / 4 | 24,9 / 13 389 (Seq Scan) | 24,6 / 14 269 |
| small, keyset после 9-го | 0,069 / 4 | 0,114 / 4 | 6,4 / 2 276 | 28,6 / 14 181 |
Результаты: запись
| вариант | размер индекса | построение | 20 000 строк одним INSERT | WAL, Б/строка | 2 000 INSERT по одному | WAL, Б/строка |
|---|---|---|---|---|---|---|
| A | 9,0 MB | 148 мс | 1 055 мс (52,8 мкс/стр.) | 363 | 294 мс (146,8 мкс/стр.) | 364 |
| B | 1,1 MB | 99 мс | 1 209 мс (60,4) | 308 | 301 мс (150,6) | 340 |
| C | 6,2 MB | 115 мс | 1 089 мс (54,4) | 334 | 282 мс (141,0) | 367 |
| D | — | — | 1 098 мс (54,9) | 227 | 277 мс (138,3) | 257 |
Результаты: backup и восстановление
| этап | результат |
|---|---|
pg_dump -Fc |
2,89 с, файл 9,0 MB (сжатый формат; индексы хранятся как DDL, а не как данные) |
| старт нового PostgreSQL на пустом volume | 4,66 с до готовности по TCP |
pg_restore (данные + PK/FK + пересборка индексов) |
3,47 с |
| RTO (хранилище + restore, без доставки файла) | ≈8,1 с на 160 000 сообщений |
| сверка: users / chats / chat_members / messages | 200 / 1 055 / 2 110 / 160 000 — совпало |
| md5 всех сообщений и md5 распределения по чатам | совпали |
| 7 выбранных сообщений (5 случайных + 2 последних в huge) | совпали поле в поле |
| индекс истории после restore | есть и используется: тот же Index Scan, 18 буферов |
| сообщение, записанное после дампа | отсутствует в восстановленной базе |
Выводы
- Гипотеза 1 подтвердилась. Только вариант A на всех профилях держит 4–18 буферов и < 0,1 мс. Причина: индекс отсортирован так же, как запрос (
chat_id= …, затемORDER BY created_at, id), поэтому PostgreSQL сразу встаёт на позицию курсора и читает ровно 51 запись.- B
(chat_id)находит строки чата, но затем должен прочитать и отсортировать все сообщения чата. На огромном чате это 6 000–60 000 строк, в 280–480 раз медленнее, чем A. На маленьком чате B почти не хуже A, то есть проблема видна только при неравномерных данных. - C
(created_at, id)хорош только для огромного чата: его сообщения составляют 37 % таблицы и быстро встречаются при обходе по времени. Для среднего и маленького чата приходится просматривать тысячи чужих сообщений (5 750 буферов), а для маленького планировщик вообще уходит в Seq Scan (24,9 мс). - OFFSET дорог при любом индексе: 54 000 строк всё равно нужно пропустить, и планировщик выбирает Seq Scan + Sort (≈100 мс, ≈12 000 буферов). Поэтому в API используется keyset.
- B
- Гипотеза 2 подтвердилась частично. Индекс A стоит 9 MB (≈10 % от heap) и +42–60 % WAL на строку по сравнению с D (364 против 257 Б и 363 против 227 Б). Время вставки на этом объёме различается в пределах шума (±10 %, B оказался медленнее D). Больше времени уходит на FK-проверки, генерацию UUID и сам heap, а 3 повтора не позволяют различить разницу в несколько процентов. Объём WAL — более надёжная метрика: он влияет на репликацию, архивирование и размер бэкапов PITR.
- Гипотеза 3 подтвердилась. Восстановление в новое хранилище совпало по всем контрольным суммам, RTO ≈8 с. Сообщение, подтверждённое (COMMIT) после дампа, потеряно: при бэкапе
pg_dumpраз в N часов теряется до N часов подтверждённых сообщений. Чтобы сократить RPO до секунд, нужен непрерывный архив WAL (archive_mode/pg_basebackup+ PITR) или реплика.
Ограничения исследования
- Один хост, тёплый кэш: все данные помещались в
shared_buffers. На холодном диске разница между A и Seq Scan будет ещё больше, но это не измерялось. - Время записи меряется с шумом Docker Desktop (WSL2). Для достоверной разницы в единицы процентов нужно больше повторов и изолированный стенд.
created_atсинтетический (равномерный внутри чата + до 1 минуты разброса). Реальная переписка неравномернее по времени.- RTO измерен на 160 000 сообщений (дамп 9 MB). Время
pg_restoreрастёт примерно линейно с объёмом данных плюс пересборка индексов. Для гигабайтов нуженpg_restore -jили физический бэкап. - Дамп не шифруется и лежит рядом с проектом (
backups/в.gitignore). В реальной системе его нужно хранить отдельно от хоста БД.
Ограничения и следующие шаги
- Один экземпляр PostgreSQL на одном хосте: отказ хоста или диска не переживается. Логический бэкап
pg_dumpи восстановление проверены в треке 2, но автоматического расписания бэкапов и PITR нет. - Если Redis «зависнет», но сохранит данные (сетевой разрыв, а не остановка), logout в этот момент не запишет надгробие. Устаревшая положительная запись кэша тогда проживёт не дольше
SESSION_CACHE_MAX_TTL= 60 с. При остановке или рестарте Redis (без persistence) такой проблемы нет. - Первый запрос после внезапной остановки Redis ждёт ≈4 с, пока резолвится имя
redis(это не покрываетsocket_connect_timeout). Дальше фоновый PING отключает кэш. created_atназначаетnow()PostgreSQL (время начала транзакции). При конкурентных вставках сообщение с меньшимcreated_atможет закоммититься позже чтения страницы и не попасть в уже пройденный курсор. Повторов при обходе неизменной истории нет.- Rate limiting, 413/415 не реализованы: они не обязательны для lab2.
- Порт PostgreSQL проброшен только на
127.0.0.1(для EXPLAIN-скрипта). Пароль БД передаётся переменной окружения из.env; docker secrets — задача lab7.