forked from mtusi2026/mtusi2026lab2
158 lines
20 KiB
Markdown
158 lines
20 KiB
Markdown
# Отчёт — лабораторная 2
|
||
|
||
- Автор, группа: Пластинин Денис, БВТ2303
|
||
- Целевая оценка: 5; трек 2 «План запроса и восстановление»
|
||
- Ветка: `solution/bvt2303-plastinin`; ссылка на PR указывается при публикации
|
||
- Основные библиотеки: pgx v5, valkey-go, x/crypto/argon2, Prometheus client_golang
|
||
- Источники: документация PostgreSQL по [транзакциям](https://www.postgresql.org/docs/current/tutorial-transactions.html) и [EXPLAIN](https://www.postgresql.org/docs/current/using-explain.html), документация [Valkey persistence](https://valkey.io/topics/persistence/), [RFC 7617](https://www.rfc-editor.org/info/rfc7617/)
|
||
- Помощь ИИ: применялась для анализа задания и проверки реализации; команды и наблюдаемые результаты проверены локально
|
||
|
||
## Запуск из чистого 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.
|
||
|
||
```sh
|
||
cp lab2.env.example .env
|
||
./scripts/init-local-secrets.sh
|
||
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-тесты запускаются отдельным профилем:
|
||
|
||
```sh
|
||
docker compose --profile tests run --rm --build tests
|
||
```
|
||
|
||
Мониторинг не входит в обязательный путь запуска и включается явно:
|
||
|
||
```sh
|
||
docker compose --profile monitoring up -d
|
||
```
|
||
|
||
После запуска Prometheus доступен на `http://localhost:9090`, Grafana — на `http://localhost:3000`. Пользователь Grafana — `admin`, пароль хранится только в `secrets/grafana_admin_password`. Дашборд `Highload / Messenger overview` создаётся автоматически.
|
||
|
||
Безопасная остановка сохраняет именованные volumes:
|
||
|
||
```sh
|
||
docker compose --profile monitoring down
|
||
```
|
||
|
||
Намеренное удаление всех локальных учебных данных выполняется отдельно:
|
||
|
||
```sh
|
||
docker compose --profile monitoring down -v
|
||
```
|
||
|
||
## Архитектура и решения
|
||
|
||
```mermaid
|
||
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
|
||
```
|
||
|
||
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`: `SESSION_STORE=valkey`, пути Docker secrets задаются Compose, `SESSION_TTL_SECONDS` задаёт срок сессии, `DB_MIN_CONNS`/`DB_MAX_CONNS` ограничивают пул, `DEPENDENCY_TIMEOUT_SECONDS` ограничивает подключение и каждую операцию с зависимостями.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий 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 в solution/main и вручную. Он проверяет контракт, OpenAPI, форматирование, golangci-lint, race unit-тесты, сборку, public smoke, реальные PostgreSQL/Valkey integration-тесты и persistence.
|
||
|
||
Production deployment вынесен в `.gitea/workflows/deploy.yml`. Gitea 1.27 не поддерживает обязательное подтверждение environment, поэтому подтверждением служит ручной `workflow_dispatch` со строкой `DEPLOY`. Workflow разрешает только ветку `main` и для exact SHA повторяет OpenAPI, lint, race, smoke, integration, реальный dependency outage и persistence. После зелёных проверок он делает backup, создаёт release-каталог по SHA и номеру попытки и выполняет health check. Для включения требуются repository secrets `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_KEY`, `DEPLOY_KNOWN_HOSTS`; на сервере заранее создаются `/opt/mtusi-lab2/shared/.env` и `/opt/mtusi-lab2/shared/secrets`.
|
||
|
||
Профиль monitoring собирает метрики без пользовательских 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 в локальном профиле используют учебные credentials сервисов. Для production следует создать отдельного пользователя PostgreSQL с ролью `pg_monitor` и ограничить сетевой доступ к Prometheus/Grafana.
|
||
- Эксперимент измеряет один запрос и короткие локальные серии. Для production нужны длительные прогоны, несколько объёмов данных, холодный cache, конкурентное чтение и запись.
|
||
|
||
## Ответы на вопросы защиты
|
||
|
||
`COMMIT` делает изменения транзакции видимыми как единое целое и фиксирует их согласно настройкам durability PostgreSQL. Гарантия пережить отказ зависит от `fsync`, `synchronous_commit`, WAL и физического хранилища.
|
||
|
||
Сессии находятся в Valkey. TTL удаляет истёкшие ключи, logout удаляет ключ немедленно. AOF сохраняет их при рестарте; `FLUSHDB` удалит сессии, после чего клиенты должны войти заново.
|
||
|
||
Аутентификация отвечает на вопрос, кто выполняет запрос: Bearer-токен связывается с пользователем. Авторизация дополнительно проверяет членство пользователя в конкретном чате. Валидная сессия не даёт доступ к чужому чату.
|
||
|
||
Argon2id намеренно медленный и требует память, поэтому усложняет перебор паролей. Быстрый checksum предназначен для обнаружения случайного изменения данных и не подходит для хранения паролей.
|