14 KiB
Отчёт по лабораторной работе № 2
Тема: PostgreSQL, сессии и Redis/Valkey
Студент: Кимпаев А.Р.
Группа: БПИ2303
Целевая оценка: 3
Трек уровня 5: не заявлен
Ветка решения: solution/bpi2303-kimpaev
1. Цель и выполненная работа
Цель — перенести серверную часть мессенджера из ЛР № 1 на постоянное хранилище PostgreSQL, реализовать аутентификацию и обеспечить сохранность подтверждённых данных и действующих сессий при перезапуске приложения и БД.
Перенесены функции ЛР № 1: регистрация пользователей, создание и просмотр чатов, управление составом участников при создании чата, отправка сообщений и чтение истории с пагинацией. С учётом перехода контракта ЛР № 2 регистрация требует пароль; POST /api/v1/auth/sessions использует HTTP Basic; остальные защищённые операции — Bearer-токен вместо X-User-Id. Добавлены завершение сеанса (logout) и время действия сессии.
Использованы Python 3.12, FastAPI, Pydantic, psycopg 3, PostgreSQL 16.8, Docker Compose. Redis/Valkey не использованы: на уровне оценки «3» источником истины для данных и сессий является PostgreSQL.
2. Архитектура и схема данных
HTTP-клиент
|
v
FastAPI (api, порт localhost:8080)
|
v
PostgreSQL (db, порт 5432 внутри сети Compose)
|
v
Именованный volume postgres_data
Структура описана миграцией migrations/001_initial.sql:
| Таблица | Назначение | Ключевые ограничения и индексы |
|---|---|---|
users |
Пользователи и хеши паролей | id — PK; username — UNIQUE; ограничение формата username |
chats |
Чаты | id — PK |
chat_members |
Участие пользователей в чатах | Составной PK (chat_id, user_id); FK на чаты/пользователей; индекс (user_id, chat_id) |
messages |
Сообщения | id — PK; FK на чат и отправителя; запрет пустого текста; индекс (chat_id, created_at, id) |
sessions |
Авторизованные сессии | PK token_hash, FK user_id, expires_at, индекс по времени истечения |
schema_migrations |
Применённые версии миграций | PK version |
При запуске FastAPI вызывает migrate(). Скрипты migrations/*.sql применяются по порядку; выполненные версии фиксируются в schema_migrations, повторное применение пропускается. Ограничения IF NOT EXISTS в начальной миграции дополнительно позволяют безопасно создавать отсутствующие объекты.
Транзакционные границы: создание чата (chats + все строки chat_members) производится в одной транзакции psycopg: ошибка отменяет операцию целиком. Вставка сообщения подтверждается завершением транзакции (COMMIT) перед возвращением успешного HTTP-ответа. История сообщений использует keyset-пагинацию по (created_at, id) и составной индекс с первым полем chat_id.
Сохранность: все постоянные данные и сессии находятся в PostgreSQL, которая использует именованный volume postgres_data. Перезапуск контейнеров без удаления volume не уничтожает уже подтверждённые записи. При сбое до COMMIT результат незавершённого запроса не гарантируется.
3. Аутентификация, авторизация и безопасность
- При регистрации пароль обрабатывается
scrypt(password KDF) с индивидуальной случайной солью. В БД хранится производный хеш, а не исходный пароль. - Вход выполняется через HTTP Basic только на
POST /api/v1/auth/sessions. При успешном входе создаётся случайный opaque Bearer-токен; клиент получает сам токен, PostgreSQL хранит только его SHA-256. - Срок действия сессии задаётся
SESSION_TTL_SECONDS(по умолчанию 3600 секунд). При обращениях проверяетсяexpires_at > now(); после истечения срока сессия перестаёт действовать. - Выход
DELETE /api/v1/auth/sessions/currentудаляет соответствующую запись изsessions. Повторное использование отозванного токена не допускается. - Для защищённых операций
X-User-Idне является доказательством входа. Доступ к конкретному чату проверяется поchat_members; постороннему пользователю данные чата не выдаются. - SQL-параметры передаются через плейсхолдеры psycopg. Файлы
.envиsecrets/исключены из Git через.gitignore.
4. Запуск из чистого clone
Требования: установленный и запущенный Docker Desktop (Docker Engine + Compose), Python 3.9+ для публичных тестов, make; команды выполнять в корне репозитория ЛР № 2.
Linux / WSL / Git Bash
bash scripts/setup.sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
curl http://localhost:8080/health/ready
make check
make test
setup.sh создаёт локальные файлы secrets/db_password, secrets/database_url и .env, если их ещё нет. При первом запуске PostgreSQL использует пароль из db_password; при сохранённом volume смена файла сама по себе не меняет пароль роли в БД. Не перегенерируйте секреты на уже инициализированном volume без синхронизации учётных данных.
Проверка сохранности с Linux/WSL-скриптом:
chmod +x scripts/restart.sh
make test-persistence ACTION_SCRIPT=scripts/restart.sh
В Windows Git Bash с Windows Python прямой запуск *.sh из subprocess может завершаться WinError 193. Для этого окружения применён эквивалентный scripts/restart.cmd:
@echo off
cd /d "%~dp0.."
docker compose --env-file .env restart db api
exit /b %errorlevel%
Проверка в Git Bash на Windows:
make test-persistence ACTION_SCRIPT=scripts/restart.cmd
Сценарии restart.sh / restart.cmd выполняют docker compose restart db api, не вызывают down -v, не удаляют volumes и не пересоздают тестовые данные. Для доказательства охвата перезапуска преподавателю можно показать текст скрипта и состояние контейнеров перед/после теста:
docker compose ps
docker compose logs --tail=30 api db
Swagger UI: http://localhost:8080/docs. Проверка liveness: http://localhost:8080/health/live; readiness (с подключением к БД): http://localhost:8080/health/ready.
Остановка без потери данных: docker compose down. Команду docker compose down -v не использовать, если данные требуется сохранить.
5. Результаты проверок
Проверки выполнены 03.11.2026, Windows 11 / Git Bash (UCRT64), локальный Docker Compose, http://localhost:8080.
| Проверка | Команда | Фактический результат |
|---|---|---|
| Структура проекта и синтаксис | make check |
PASS — offline skeleton structure, local refs and Python syntax; application NOT tested. |
| Публичный сценарий API | make test |
PASS — lab2 public API scenario; infrastructure and grading evidence remain separate. |
| Сохранность данных и сессии после перезапуска | make test-persistence ACTION_SCRIPT=scripts/restart.cmd |
PASS — persistence preserved confirmed data and existing session. Hook scope needs operator evidence. |
| Прямой health-check | curl http://localhost:8080/health/live |
{"status":"ok"} |
| Контейнеры после запуска | docker compose ps |
api — Up, db — Up (healthy) |
Вывод последней проверки persistence:
python3 tests/resilience.py --mode persistence --action-script "scripts/restart.cmd" --base-url "http://localhost:8080"
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
Проверка test-persistence подтвердила сохранение созданных тестом данных и действующего токена. При этом сам тест не доказывает, что hook действительно рестартовал оба контейнера; это подтверждается содержимым scripts/restart.cmd/scripts/restart.sh и демонстрацией Docker Compose. Отдельная проверка короткого TTL и повторного применения миграций на чистом volume в приведённых логах не зафиксирована; их можно продемонстрировать дополнительно на защите.
6. Ограничения и известные особенности
- Это локальный учебный стенд, слушающий
127.0.0.1:8080, без HTTPS на внешнем интерфейсе; Basic-аутентификацию нельзя использовать по незашифрованному соединению в публичной сети. - Нет Redis/Valkey, горизонтального масштабирования и отдельного connection pool — это не заявлено для уровня «3».
- При недоступности PostgreSQL операции с данными невозможны; приложение обрабатывает
psycopg.OperationalErrorкак ошибку зависимости. Не подтверждённые сервером записи после сбоя не считаются сохранёнными. - Для проверки persistence на Windows с Windows Python нужен
restart.cmd, а на Linux/WSL —restart.sh. - Публичные smoke/persistence тесты не заменяют полноценные нагрузочные, security и конкурентные испытания. Оценка преподавателем не определяется одним сообщением
PASS.
7. Источники и использование ИИ
Реализация выполнена на базе собственного проекта ЛР № 1 и skeleton ЛР № 2. Использованы требования README.md, COURSE.md, contracts/, tests/README.md, CONTRIBUTING.md, а также документация Python/FastAPI, PostgreSQL и Docker Compose. При подготовке и отладке кода, Docker-конфигурации и документации применялась помощь ChatGPT (OpenAI). Запуск контейнеров и публичных тестов произведён локально; фактические результаты приведены выше. Пароли, токены и содержимое secrets/ в отчёт не включены.
8. Контрольный список перед отправкой MR
- Реализованы основные функции ЛР № 1 с объявленным переходом на Basic/Bearer.
- PostgreSQL, миграции, ограничения и хранение действующих сессий.
- Локальный Compose-стенд с именованным volume.
make checkиmake test— PASS.- Persistence с
scripts/restart.cmdна Windows — PASS. - Имеется
scripts/restart.shдля Linux/WSL. - Перед публикацией проверить
git status,git diff --cachedи отсутствие.env,secrets/, данных volume. - После push вставить ссылку на MR и commit в раздел в начале отчёта.