Files
mtusi2026lab2-fork/REPORT.md

33 KiB
Raw Permalink Blame History

Отчёт — лабораторная 2

  • Автор, группа: Гришко Дмитрий Михайлович, БВТ2303
  • Целевая оценка: 5, трек 2
  • Ветка: solution/BVT2303-grishko
  • PR: ссылка на Pull Request
  • Источники: задание, контракт, проверки, golang-migrate, документация PostgreSQL и Go
  • Зависимости: Go 1.22.2, PostgreSQL 16.10, Redis 7.4.11, pgx/v5, go-redis/v9, golang-migrate/v4, x/crypto/argon2, google/uuid; frontend — Vite, React, TypeScript;
  • Помощь ИИ: OpenAI Codex — реализация и проверка кода

Запуск из чистой копии

Нужны Docker Engine с Compose v2, Python 3.9+, Make и OpenSSL. Backend и frontend собираются в Docker; отдельная установка Go и Node.js не требуется. Команды приведены для Linux/WSL в корне репозитория.

1. Клонирование и настройка

git clone --branch solution/BVT2303-grishko https://gitea.privcloud.tech/TAskMAster339/mtusi2026lab2-fork.git
cd mtusi2026lab2-fork
cp .env.example .env
sed -i "s/replace-with-local-random-password/$(openssl rand -hex 24)/" .env

openssl rand -hex 24 генерирует случайный пароль PostgreSQL. Вместо этой команды можно вручную заменить POSTGRES_PASSWORD в .env длинным случайным значением.

2. Запуск проекта

docker compose --env-file .env config --quiet
make app-up

3. Тесты и эксперимент

make check
make test
make test-backend
make test-persistence ACTION_SCRIPT=scripts/restart.sh
docker compose --env-file .env run --rm --no-deps backend-tests go vet ./src/backend/...
docker compose --env-file .env exec frontend npm run build
make track2-run RUN_ID=lab2-grade5-01
  • База доступна только внутри Compose-сети;

  • HTTP API опубликован на 127.0.0.1:8080, frontend — на 127.0.0.1:5173. Миграции up применяются автоматически перед запуском HTTP-сервера и встроены из src/backend/repositories/migrations. Применение вручную: docker compose --env-file .env run --rm --no-deps api migrate up при уже запущенной БД. Откат одной версии: остановить API командой docker compose --env-file .env stop api, затем выполнить docker compose --env-file .env run --rm --no-deps api migrate down. Откат версии 2 восстанавливает пустую таблицу sessions; откат начальной версии 1 удаляет таблицы и их данные.

  • Безопасная остановка: docker compose --env-file .env down — volume сохранится. Намеренное удаление учебных данных: docker compose --env-file .env down -v. После смены пароля в .env для уже инициализированного volume надо отдельно менять пароль роли PostgreSQL;

Архитектура и решения

Браузер → React frontend → Go net/http API → PostgreSQL (пользователи, чаты, сообщения)
                                         → Redis (сессии с TTL и AOF)
  • Перенесены модели, маршруты, валидация JSON и курсоры из лабораторной 1. Работа с БД находится в repositories, бизнес-логика — в services, обработка HTTP — в handlers, тесты — в tests внутри src/backend;
  • прежние in-memory коллекции удалены. Публичная регистрация теперь требует пароль. На POST /api/v1/auth/sessions допускается только Basic;
  • остальные защищённые маршруты проходят через проверку Bearer. Идентификатор пользователя передаётся обработчикам через контекст запроса, X-User-Id игнорируется.
Таблица Ключи и ограничения Назначение
users PK id, UNIQUE username, CHECK длины и формата Пользователи и хеши паролей
chats PK id, CHECK длины названия Чаты
chat_members PK (chat_id,user_id), FK на обе таблицы, индекс (user_id,chat_id) Членство и выборка доступных чатов
messages PK id, FK на чат и отправителя, индекс (chat_id,created_at,id) История и keyset-пагинация

Сессии хранятся в Redis: ключ messenger:session:<SHA-256 токена>, значение — ID пользователя; срок действия задаётся TTL. Именованный том Redis хранит AOF с appendfsync everysec.

Создание чата и всех записей членства — одна транзакция: при ошибке ни чат, ни часть участников не сохраняются. Регистрация и отправка сообщения выполняются отдельными атомарными SQL-операциями; создание и отзыв сессии — командами Redis SET с TTL и DEL. Все SQL-параметры передаются через pgx. Чтение истории выполняет ORDER BY created_at,id LIMIT limit+1 с условием курсора. Время сообщения назначается в API; при конкурентных вставках между страницами единый snapshot всей истории не обещается.

Пароль обрабатывается Argon2id: память 64 MiB, 3 итерации, параллелизм 2, случайная соль 16 байт и производный ключ 32 байта. В колонке password_hash хранится PHC-строка с алгоритмом, параметрами, солью и хешем. Значение не входит в API-ответ. Токен сессии содержит 256 случайных бит; в Redis используется его SHA-256. Каждый защищённый запрос проверяет сессию в Redis и наличие пользователя в PostgreSQL. Истечение обеспечивается TTL, logout удаляет ключ. GET /health/ready проверяет обе зависимости; их недоступность возвращает 503, неверный или истёкший токен — 401.

golang-migrate хранит номер версии и признак незавершённой миграции в schema_migrations. Версия 1 создаёт исходную схему; версия 2 удаляет таблицу PostgreSQL-сессий после перехода на Redis. Обе миграции имеют up/down, повторный up не создаёт данные заново. Откат проверен на отдельной БД: 2 → 1 → 2, dirty=false.

Пул PostgreSQL ограничен 10 соединениями; подключение и SQL-операции имеют таймаут 5 секунд. Пул Redis — 10 соединений, сетевые таймауты — 1 секунда. HTTP: чтение заголовков 5 секунд, чтение/запись 10 секунд, idle 60 секунд. scripts/restart.sh сначала перезапускает PostgreSQL и Redis и ждёт их готовности, затем перезапускает API; тома сохраняются.

Переменные из .env.example: POSTGRES_DB задаёт имя базы, POSTGRES_USER — роль, POSTGRES_PASSWORD — локальный пароль для PostgreSQL и строки подключения API, SESSION_TTL_SECONDS — срок жизни сессии (по умолчанию 3600 секунд). APP_HOST=0.0.0.0 и APP_PORT=8080 задаются в Compose; внешний порт привязан к 127.0.0.1.

Доказательства критериев

Критерий README Команда/сценарий Наблюдаемый результат Файл доказательства
Публичный smoke, API lab1 с новой аутентификацией make test PASS: lab2 public API scenario; проверены Basic, Bearer, членство, пагинация, logout Публичный smoke и API
PostgreSQL: пользователи, чаты, членство, сообщения, ключи и индексы запуск на чистом volume, SQL-проверка схемы версия миграции 2, dirty=false; отдельной колонки password_salt нет Чистая схема PostgreSQL, ключи и индексы
Атомарное создание чата make test-backend, ошибка вставки второго участника транзакция откатывается: чат и участники отсутствуют Атомарное создание чата
Argon2id, Basic для входа, Bearer, expiry и logout make test, make test-backend; TTL 2 секунды неверный пароль и старый заголовок отклонены; истёкший токен получил 401 Argon2id, Basic, Bearer, TTL и logout
Redis-сессии и сохранность при перезапуске make test-persistence ACTION_SCRIPT=scripts/restart.sh PASS с прежним токеном после рестарта API, PostgreSQL и Redis Сохранность данных и Redis-сессии
Повторный запуск миграции и откат up → down → up на отдельной БД версии 2 → 1 → 2, dirty=false; таблица sessions восстанавливается пустой и удаляется вновь Повторное применение и откат миграций
Стенд, volumes и секреты docker compose --env-file .env config --quiet, git check-ignore .env API, БД, Redis и frontend healthy; именованные тома; .env исключён из Git Стенд, тома и исключение секретов из Git
Локальные проверки кода make check, make test-backend, go vet ./... PASS, backend-тесты с -race Проверки кода и race detector
Ограничение ресурсов и таймауты проверка конфигурации пулов и HTTP, make test-backend PostgreSQL/Redis: пулы по 10; таймауты подключения, запросов и HTTP заданы Пулы, таймауты и параметризованные SQL
Отказ зависимостей остановка Redis и PostgreSQL по очереди readiness и защищённый запрос — 503, анонимный запрос — 401; после запуска сервисов прежний токен работает Отказ Redis и PostgreSQL
История на 10 000 сообщений EXPLAIN первой и поздней страниц Index Scan по messages_history_idx, по 51 строке без полного сканирования истории План истории на 10 000 сообщений

Эксперименты и отказы

Проверки приложения выполнены на отдельном Compose-стенде с новыми томами PostgreSQL и Redis. Миграции применились с нуля до версии 2, dirty=false; PostgreSQL, Redis, API и frontend стали healthy. Smoke, backend-тесты с race detector, штатный persistence, go vet и сборка frontend завершились успешно. Результаты: API, persistence, backend-тесты и сборка.

Воздействие Что ожидаем Что наблюдали Время восстановления / потеря данных
scripts/restart.sh API, PostgreSQL и Redis перезапускаются с сохранением томов persistence PASS: прежний токен прочитал подтверждённые данные; все сервисы healthy подтверждённые данные и действующая сессия сохранились
TTL 2 секунды и logout истёкшая или отозванная сессия отклоняется сразу после создания HTTP 200; после истечения TTL и после logout HTTP 401 сессия удаляется по TTL или явно
Неверный пароль и анонимный запрос доступ отклоняется HTTP 401; X-User-Id не заменяет Bearer данные не изменяются
Недоступность Redis / PostgreSQL readiness и защищённый запрос возвращают 503 автоматические тесты PASS; анонимный запрос возвращает 401 после восстановления зависимостей запрос с действующей сессией работает
Конкурентная регистрация одного username создаётся один пользователь ответы 201 и 409, в БД одна строка ограничение UNIQUE предотвращает дубликат
Ошибка вставки второго участника чата вся составная операция откатывается chats=0, chat_members=0 частичные данные не сохраняются
Откат миграции на отдельной БД восстанавливается предыдущая версия схемы 2 → 1 → 2, dirty=false; sessions восстанавливается пустой и вновь удаляется проверка на отдельной БД; прежние Redis-сессии обратно в PostgreSQL не переносятся

Оценка «5»: трек 2 — план запроса и восстановление

Гипотеза и методика

Гипотеза сформулирована до измерений: курсор (created_at,id) с индексом (chat_id,created_at,id) позволяет читать около размера страницы независимо от её глубины; OFFSET на поздней странице обрабатывает пропущенные строки. Покрывающий индекс с INCLUDE(sender_id,text) может ускорить чтение, но увеличит размер индекса и WAL вставок. Backup должен восстановить данные на момент снимка, а запись после backup должна отсутствовать в восстановленной копии. Гипотеза и методика: протокол эксперимента.

Эксперимент запускается отдельно командой make track2-run RUN_ID=<уникальное-имя>. Файл compose.track2.yaml создаёт отдельный проект, сеть и два тома PostgreSQL; рабочая БД приложения не участвует. Сценарий применяет существующие миграции, а seed.sql создаёт одного синтетического пользователя и три чата: 100 000, 15 000 и 5 000 сообщений. UUID, тексты и времена детерминированы. В каждом новом прогоне схема и данные создаются с нуля; повторное использование RUN_ID отклоняется. Порты БД на хост не публикуются.

Измеряется PostgreSQL 16.10, один последовательный клиент, без параллельной нагрузки. Для каждого из двух индексов выполняется VACUUM (ANALYZE), один прогрев и семь измерений первой и поздней страницы каждого чата через EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON). Страница содержит 50 сообщений; поздняя начинается после 90% истории. Для каждого чата сравниваются курсор и OFFSET, а равенство возвращаемых строк проверяется автоматически. Отдельно сохраняются время выполнения (медиана и диапазон), тип сканирования, число строк, буферы и размер индекса. Время клиента и Docker exec не включается во время SQL.

Стоимость записи сравнивается на трёх вспомогательных таблицах с одинаковым PK: без индекса истории, с обычным индексом и с покрывающим. Источник вставки одинаковый: первые 10 000 сообщений, предварительно подготовленные в отдельной таблице. Перед каждой вставкой — TRUNCATE; один прогрев и семь измерений EXPLAIN (ANALYZE, BUFFERS, WAL, FORMAT JSON). Вспомогательные таблицы без FK, удаляются до backup. Это стоимость пакетной вставки в пустую таблицу с индексами, а не производительность HTTP API.

После возвращения обычного индекса создаётся pg_dump -Fc; в источник добавляется сообщение-маркер. Архив восстанавливается pg_restore --exit-on-error в новую БД на втором томе. Проверяется полное равенство счётчиков пяти таблиц, числа сообщений по чатам и девяти выбранных сообщений (первое, среднее, последнее в каждом чате). Маркер должен присутствовать в источнике и отсутствовать в копии. Измеряются время dump, размер архива, время pg_restore и полное время запуска нового хранилища, восстановления и проверки. Сверяются все поля выбранных сообщений, а не только ID.

Характеристики, результаты и доказательства

Измерения выполнены 01.10.2026: Windows / WSL2 Ubuntu, AMD Ryzen 9 PRO 7940HS (8 ядер, 16 потоков), Docker Engine 28.5.1, Compose 2.40.2. Docker видит 16 CPU и около 7,4 GiB RAM; отдельные CPU/RAM лимиты контейнеров не заданы. PostgreSQL 16.10: shared_buffers=128 MiB, work_mem=4 MiB, effective_cache_size=4 GiB, fsync=on, synchronous_commit=on, full_page_writes=on. Хост общий; профиль теста — один последовательный SQL-клиент, 120 000 коротких сообщений, страницы по 50 строк.

Основной прогон — 20261001-c, контрольный — 20261001-b. Данные и SQL одинаковые. В каждом сохранено 126 планов чтения и 21 план вставки — семь измерений на вариант после одного прогрева. Параметры среды и SHA-256 текущего сценария, Compose, seed и миграций сохранены в manifest.json.

Медианы времени PostgreSQL основного прогона, миллисекунды:

Чат Индекс Первая страница, курсор Поздняя страница, курсор Поздняя страница, OFFSET
100 000 Обычный 0,111 0,145 18,060
100 000 Покрывающий 0,132 0,160 19,628
15 000 Обычный 0,162 0,158 8,073
15 000 Покрывающий 0,249 0,138 2,403
5 000 Обычный 0,116 0,122 2,940
5 000 Покрывающий 0,136 0,143 1,002

Все курсорные сканы возвращали 50 строк. Для большого чата OFFSET обработал 90 050 строк. В первом измеренном плане обычный индекс использовал 6 shared hit blocks для позднего курсора и 1933 для OFFSET; покрывающий — 5 и 1237. Shared read blocks этих планов равны нулю: чтение шло из кэша PostgreSQL. Курсорные запросы с обычным индексом использовали Index Scan, с покрывающим — Index Only Scan с Heap Fetches=0. Для OFFSET среднего и малого чатов с обычным индексом PostgreSQL выбрал Bitmap Index Scan → Bitmap Heap Scan → Sort, прочитав все 15 000 и 5 000 строк соответствующего чата. Диапазон времени позднего курсора большого чата с обычным индексом — 0,111–0,175 мс, OFFSET — 16,037–23,447 мс. Полные планы всех повторов сохранены.

Индексы вспомогательной таблицы INSERT 10 000, медиана мс Диапазон мс WAL, медиана байт Размер всех индексов после вставки, байт
Только PK 34,362 31,466–35,912 2 319 396 417 792
PK + обычный индекс истории 48,760 43,652–62,255 3 343 720 1 024 000
PK + покрывающий индекс истории 46,544 45,157–51,712 3 897 536 1 572 864

На 120 000 сообщениях размер обычного индекса истории — 7 086 080 байт, покрывающего — 13 574 144 байта. Размер таблицы в обоих случаях — 14 049 280 байт.

Анализ результатов

Гипотеза о курсоре подтверждена для проверенных страниц: первая и поздняя страницы читают по 50 строк. OFFSET большого чата обрабатывает в 1 801 раз больше строк; его медиана примерно в 125 раз выше медианы позднего курсора. В контрольном прогоне поздний курсор занимал 0,171 мс, OFFSET — 18,651 мс. Курсор заранее известен клиенту; его получение для подготовки эксперимента не входит в измерение страницы.

Покрывающий индекс устранил обращения к таблице после VACUUM, но устойчивого ускорения коротких курсорных страниц не показал. Его размер примерно в 1,92 раза больше, WAL вставки — на 16,6% больше обычного индекса. В основном прогоне медиана INSERT с покрывающим индексом (46,544 мс) ниже обычного (48,760 мс), тогда как в контрольном — выше. Диапазоны времени перекрываются. Поэтому гипотеза о росте затрат подтверждается размером и WAL, но устойчивое замедление INSERT по времени не доказано. Для текущей пагинации сохранён обычный индекс.

Гипотеза о восстановлении подтверждена: в новой БД получены 1 пользователь, 3 чата, 3 записи членства, 120 000 сообщений и одна строка schema_migrations. Распределение 100 000 / 15 000 / 5 000 и все поля девяти выбранных сообщений совпали с источником до backup. После добавления маркера источник содержит 120 001 сообщение, копия — 120 000; маркер в копии отсутствует. Контрольные данные совпали между независимыми прогонами; SHA-256 архивов проверены: сверка повторяемости.

Прогон Время dump, с Размер архива, байт Время pg_restore, с Запуск нового хранилища + restore + вся сверка, с
20261001-b 1,903 3 613 568 2,172 29,519
20261001-c 1,649 3 613 568 2,026 27,816

Время dump/restore включает передачу архива и накладные расходы Docker. Полное время включает инициализацию нового тома, ожидание готовности и контрольные запросы. Размер архива — около 3,45 MiB. До завершения первого проверенного запроса SELECT count(*) FROM users прошло 8,615 с: расчёт по журналу. Полная сверка завершилась за 27,816 с.

Файлы и повторение

Планы запросов, сводки, характеристики среды и результаты сверки сохранены в evidence/track2/<RUN_ID>/. Бинарный архив создаётся при запуске эксперимента и не включается в Git. Повтор: make track2-run RUN_ID=my-repeat-01 с новым идентификатором. Предыдущие данные сохраняются. make track2-status RUN_ID=... показывает состояние, make track2-stop RUN_ID=... останавливает сервисы, make track2-clean RUN_ID=... удаляет только тома указанного эксперимента и сохраняет доказательства.

Критерий трека 2 Команда / сценарий Наблюдаемый результат Файл доказательства
≥100 000 сообщений, неравномерные чаты make track2-run RUN_ID=20261001-c 120 000 сообщений: 100 000 / 15 000 / 5 000 Трек 2: объём и распределение истории
≥2 индекса/запроса и стоимость записи 2 индекса × 3 чата × 3 варианта чтения; 3 варианта INSERT 126 EXPLAIN чтения и 21 вставки; время, WAL и размеры Трек 2: чтение и стоимость записи
Backup → новое хранилище → сверка pg_dump -Fc → pg_restore --exit-on-error Новый том; счётчики и 9 сообщений совпали, пост-backup маркер отсутствует Трек 2: backup и восстановление

Ограничения методики и границы потери данных

Измерения относятся к одному общему хосту, коротким синтетическим сообщениям, уникальным временам и тёплому кэшу. Проверялся один последовательный SQL-клиент; HTTP latency, RPS и конкурентная нагрузка не измерялись. Варианты выполнялись последовательно; на результаты могли влиять кэш, checkpoint и внешняя нагрузка. EXPLAIN ANALYZE добавляет затраты измерения. Время INSERT и его WAL не включают TRUNCATE и COMMIT/fsync, но включают сортировку общего входа. Вспомогательные таблицы не имеют FK. Обычный индекс заполнялся вставками, покрывающий строился после заполнения таблицы; плотность страниц влияет на сравнение размеров. Нулевые heap fetches получены после VACUUM; при частых изменениях Index Only Scan может обращаться к таблице.

Резервная копия PostgreSQL содержит согласованный снимок; последующие записи в него не входят. Без архивации WAL и восстановления на момент времени (PITR) граница потери данных — изменения после последнего dump. Redis-сессии в архив PostgreSQL не входят; они сохраняются отдельно через AOF с everysec. При аварийной потере хоста возможна потеря примерно последней секунды записей Redis. Архивы находятся на том же хосте, поэтому для защиты от его потери нужна внешняя копия. Время восстановления относится к измеренному объёму и оборудованию. Сверка подтверждает количество строк и содержимое девяти выбранных сообщений.

Источники методики: EXPLAIN PostgreSQL 16, Index Only Scan и INCLUDE, pg_dump.

Ограничения и следующие шаги

Стенд использует по одной копии API, PostgreSQL и Redis. Проверены перезапуск с сохранением данных и сессии, резервное копирование PostgreSQL и восстановление в отдельное хранилище. Следующие шаги — автоматизация периодических backup с хранением вне хоста, архивация WAL для PITR и проверка восстановления на большем объёме данных. Для удалённого размещения нужны TLS и управление секретами.