33 KiB
Отчёт — лабораторная 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 и управление секретами.