20 KiB
Отчёт — лабораторная 2
- Автор, группа: Пластинин Денис, БВТ2303
- Целевая оценка: 5; трек 2 «План запроса и восстановление»
- Ветка:
solution/bvt2303-plastinin; ссылка на PR указывается при публикации - Основные библиотеки: pgx v5, valkey-go, Viper, x/crypto/argon2, Prometheus client_golang
- Источники: документация PostgreSQL по транзакциям и EXPLAIN, документация Valkey persistence, RFC 7617
Запуск из чистого clone
Требуются Docker с Compose, make, Python 3.9 или новее для преподавательских тестов. Go на хосте для обычного запуска не требуется. Версии основных образов закреплены: Go 1.26.5, Alpine 3.24.2, PostgreSQL 17.6, Valkey 8.1.4, Swagger UI 5.31.2.
cp lab2.env.example .env
docker compose config --quiet
docker compose up -d --build --wait --wait-timeout 120
make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
API доступен на http://localhost:8080, Swagger UI — на http://localhost:8081. Миграции встроены в бинарник и выполняются при запуске до начала приёма запросов. Повторное применение уже записанной версии сверяет checksum и не создаёт объекты повторно.
Собственные integration-тесты запускаются отдельным профилем:
docker compose --profile tests run --rm --build tests
Основной Compose одновременно запускает API, PostgreSQL, Valkey, Swagger UI, exporters, Prometheus и Grafana. Prometheus доступен на http://localhost:9090, Grafana — на http://localhost:3000. Пользователь Grafana — admin, пароль задаётся в локальном .env. Дашборд Highload / Messenger overview создаётся автоматически.
Безопасная остановка сохраняет именованные volumes:
docker compose down
Намеренное удаление всех локальных учебных данных выполняется отдельно:
docker compose down -v
Архитектура и решения
flowchart LR
C[HTTP client] --> A[Go API]
A --> P[(PostgreSQL)]
A --> V[(Valkey AOF)]
S[Swagger UI] --> A
M[Prometheus] --> A
M --> PE[PostgreSQL exporter]
M --> VE[Valkey exporter]
G[Grafana] --> M
Схема базы данных:
erDiagram
users ||--o{ chat_members : participates
chats ||--|{ chat_members : contains
chat_members ||--o{ messages : allows_sender
users {
uuid id PK
text username UK
text display_name
text password_hash
timestamptz created_at
}
chats {
uuid id PK
text title
timestamptz created_at
}
chat_members {
uuid chat_id PK,FK
uuid user_id PK,FK
smallint position
}
messages {
uuid id PK
uuid chat_id FK
uuid sender_id FK
text text
timestamptz created_at
}
PostgreSQL является источником истины для пользователей, чатов, участников и сообщений. Внешние ключи не позволяют сообщению ссылаться на отсутствующий чат, пользователя вне чата или удалённое членство. username защищён уникальным ограничением базы, поэтому конкурентные запросы не могут создать дубликаты.
Valkey хранит только сессии. Клиент получает 32 случайных байта в виде opaque Base64URL-токена, а в ключе Valkey используется SHA-256 токена. Значение содержит ID пользователя и срок действия. На ключ устанавливается TTL; logout удаляет ключ. Включены AOF и appendfsync everysec, поэтому штатный перезапуск сохраняет сессии. При аварийной остановке граница потери последних изменений AOF составляет примерно одну секунду.
Пароли хешируются Argon2id с отдельной случайной солью. Basic принимается только на POST /api/v1/auth/sessions. Бизнес-ручки принимают Bearer; X-User-Id не участвует в аутентификации и не меняет пользователя. Неверный, истёкший или отозванный токен приводит к 401. Ошибка PostgreSQL или Valkey приводит к 503, а не к анонимному обходу проверки.
Создание чата состоит из проверки участников, вставки чата и вставки всех членств в одной транзакции. Любая ошибка вызывает rollback. Все SQL-запросы параметризованы. Пул ограничен переменными DB_MIN_CONNS и DB_MAX_CONNS, установка соединения и проверки зависимостей имеют таймауты.
История сообщений использует keyset pagination по (created_at, id). Cursor содержит позицию последней строки, тип ресурса и область чата; сервер проверяет его целостность и принадлежность текущему запросу. Запрос использует индекс (chat_id, created_at, id) и не пересчитывает полный offset для каждой страницы.
Преподавательский .env.example сохранён без изменений. Рабочие параметры находятся в lab2.env.example; каждое поле снабжено пояснением. Viper читает настройки из окружения и завершает запуск с ошибкой, если обязательного значения нет. В репозитории находятся только учебные значения, а серверный .env хранится вне Git.
Доказательства критериев
| Критерий README | Команда или сценарий | Наблюдаемый результат | Файл доказательства |
|---|---|---|---|
| Публичный smoke | make test |
PASS: lab2 public API scenario |
evidence/lab2-verification.txt |
| Сохранение данных и сессии | make test-persistence ACTION_SCRIPT=scripts/restart.sh |
API, PostgreSQL и Valkey перезапущены; старый токен и подтверждённое сообщение сохранились | evidence/lab2-verification.txt |
| Миграции и повторный запуск | повторные сборки и перезапуски API на том же volume | checksum миграции совпал, схема не продублировалась, readiness вернулся в 200 |
evidence/lab2-verification.txt |
| Гонка username | docker compose --profile tests run --rm --build tests |
из 8 конкурентных вставок успешна одна, остальные получили conflict | internal/postgres/store_integration_test.go |
| Rollback чата | тот же integration suite | неизвестный участник дал ErrInvalidMembers, число чатов не изменилось |
internal/postgres/store_integration_test.go |
| TTL и logout | integration suite и make test |
сессия исчезла после TTL; после logout запрос и повторный logout дали 401 |
internal/session/session_integration_test.go |
| Неверный пароль и отказ зависимостей | go test -race ./internal/messenger |
неверный пароль — 401; ошибки PostgreSQL и Valkey — 503 |
internal/messenger/server_test.go |
| Реальный отказ зависимостей | go run ./cmd/dependencycheck |
поочерёдный stop PostgreSQL/Valkey дал 503; после up восстановились readiness и старый токен |
evidence/lab2-verification.txt |
| Индекс истории | Go-эксперимент, 100 000 сообщений, EXPLAIN (ANALYZE, BUFFERS) |
составной индекс: 0,069 мс и 0 отфильтрованных строк; глобальный индекс: 0,597 мс и 1900 отфильтрованных строк | evidence/lab2-track2.json |
| Стоимость записи | 5 повторов CopyFrom по 10 000 строк, медиана |
без вторичного индекса 309 172 строк/с; составной 286 011 строк/с; снижение около 7,5% | evidence/lab2-track2.json |
| Backup и restore | ./scripts/backup-restore.sh |
восстановление в messenger_restore за 1 с; counts, memberships и digest полей сообщений совпали |
evidence/lab2-backup-restore.txt |
Эксперимент с планом запроса
Гипотеза: индекс (chat_id, created_at, id) ускорит keyset pagination в небольшом чате относительно индекса (created_at, id), потому что PostgreSQL сможет сразу ограничить диапазон конкретным chat_id. Цена улучшения — дополнительное обслуживание более широкого индекса при записи и место на диске.
Эксперимент выполнен Go-программой cmd/lab2experiment. Среда обезличена: контейнер linux/arm64, Go 1.26.5, лимит 2 CPU. Создано 100 000 синтетических сообщений в 20 чатах с распределением 60 000, 20 000, 10 000 и от 588 до 592 сообщений в остальных чатах. Времена сообщений разных чатов чередуются, поэтому глобальный индекс не получает преимущества от последовательной загрузки одного чата.
Проверялся запрос страницы из 100 сообщений после cursor в середине одного из небольших чатов. Для каждого варианта индекс пересоздавался, выполнялся ANALYZE, затем сохранялся полный JSON-план EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON).
| Вариант | Execution time | Строк отброшено фильтром | Shared blocks hit/read |
|---|---|---|---|
(chat_id, created_at, id) |
0,069 мс | 0 | 6 / 4 |
(created_at, id) |
0,597 мс | 1900 | 1994 / 19 |
В данной точке составной индекс быстрее примерно в 8,7 раза. Причина видна в плане: он сразу выбирает диапазон одного чата, а глобальный индекс идёт по общей временной шкале и проверяет chat_id для чужих сообщений.
Стоимость записи измерялась отдельно. Для каждого варианта таблица создавалась заново, пять раз загружалось по 10 000 одинаково сформированных строк, в отчёт взята медиана.
| Вариант | Медиана | Производительность | Размер вторичного индекса |
|---|---|---|---|
| без вторичного индекса | 0,0323 с | 309 172 строк/с | 0 |
(chat_id, created_at, id) |
0,0350 с | 286 011 строк/с | 991 232 байта |
(created_at, id) |
0,0350 с | 285 326 строк/с | 425 984 байта |
Составной индекс выбран для приложения: потеря около 7,5% в синтетической пакетной записи компенсируется существенным ускорением основной операции чтения истории. Эти числа относятся к прогретой локальной среде, короткому запуску и 100 000 строк; они показывают направление и не являются производственным SLA.
Backup, восстановление и отказы
scripts/backup-restore.sh создаёт временный backup PostgreSQL в custom format, создаёт новую базу messenger_restore, выполняет pg_restore, затем сравнивает counts пользователей, чатов, членств и сообщений. Для десяти выбранных сообщений сравнивается digest полей id, chat_id, sender_id, text и created_at. Dump удаляется после проверки и не попадает в Git.
В проверенном запуске восстановлены 35 пользователей, 9 чатов, 17 членств и 8 сообщений; digest совпал, полное время сценария составило 1 секунду. RPO равен моменту snapshot, который видит pg_dump: транзакции, зафиксированные после начала snapshot, не входят в этот backup. RTO в 1 секунду относится к малому учебному набору; с ростом объёма он увеличится.
| Воздействие | Ожидаемое поведение | Наблюдение | Восстановление и потеря данных |
|---|---|---|---|
| штатный restart API, PostgreSQL и Valkey | readiness временно недоступен, затем старые данные и токен читаются | persistence-тест прошёл | автоматическое восстановление; подтверждённые данные не потеряны |
| недоступен PostgreSQL | readiness и операции с данными возвращают 503 |
реальный контейнер остановлен; после запуска прежний токен снова сработал | после возврата БД; анонимный доступ не разрешается |
| недоступен Valkey | readiness и Bearer-аутентификация возвращают 503 |
реальный контейнер остановлен; после запуска AOF восстановил прежний токен | после возврата Valkey; запрос не считается аутентифицированным |
| истёк TTL или logout | токен возвращает 401 |
integration и public smoke прошли | повторный login создаёт новую сессию |
| restore из backup | новая БД содержит снимок исходной | counts, memberships и message digest совпали | 1 с на учебном наборе; RPO равен snapshot |
CI/CD и мониторинг
.gitea/workflows/ci.yml запускается для PR в main, push в main и вручную. Он проверяет контракт, OpenAPI, форматирование, golangci-lint, race unit-тесты, сборку, public smoke, реальные PostgreSQL/Valkey integration-тесты и persistence.
.gitea/workflows/deploy.yml запускается после push в защищённую ветку main. Через appleboy/ssh-action он обновляет серверный clone до origin/main, пересобирает единый Compose-стек и выводит состояние контейнеров. Для запуска требуются repository secrets DEPLOY_HOST, DEPLOY_USER, DEPLOY_SSH_KEY; на сервере заранее создаются каталог ~/mtusi2026lab2 и локальный .env с рабочими паролями.
Мониторинг собирает метрики без пользовательских ID и raw URL в labels. Дашборд содержит RPS, классы HTTP-ответов, p95, in-flight, Go heap, соединения и транзакции PostgreSQL, размер БД, память, ключи и команды Valkey. Мониторинг не участвует в readiness приложения.
Ограничения и следующие шаги
- Стенд содержит одну API-реплику. Горизонтальное масштабирование и idempotency появляются в лабораторной 3.
- Локальный HTTP не шифруется. На сервере Basic и Bearer должны передаваться только через TLS reverse proxy; это будет частью эксплуатационной защиты последующих лабораторных.
- Valkey AOF
everysecсохраняет сессии при штатном рестарте, но допускает потерю примерно последней секунды при аварии процесса или узла. - PostgreSQL
COMMITподтверждает фиксацию согласноsynchronous_commit,fsyncи надёжности диска. Он не заменяет внешние backup и репликацию. - Exporters в локальном Compose используют учебные credentials сервисов. Для production следует создать отдельного пользователя PostgreSQL с ролью
pg_monitorи ограничить сетевой доступ к Prometheus/Grafana. - Эксперимент измеряет один запрос и короткие локальные серии. Для production нужны длительные прогоны, несколько объёмов данных, холодный cache, конкурентное чтение и запись.
Ответы на вопросы защиты
COMMIT делает изменения транзакции видимыми как единое целое и фиксирует их согласно настройкам durability PostgreSQL. Гарантия пережить отказ зависит от fsync, synchronous_commit, WAL и физического хранилища.
Сессии находятся в Valkey. TTL удаляет истёкшие ключи, logout удаляет ключ немедленно. AOF сохраняет их при рестарте; FLUSHDB удалит сессии, после чего клиенты должны войти заново.
Аутентификация отвечает на вопрос, кто выполняет запрос: Bearer-токен связывается с пользователем. Авторизация дополнительно проверяет членство пользователя в конкретном чате. Валидная сессия не даёт доступ к чужому чату.
Argon2id намеренно медленный и требует память, поэтому усложняет перебор паролей. Быстрый checksum предназначен для обнаружения случайного изменения данных и не подходит для хранения паролей.