Files
mtusi2026lab3/REPORT.md
T
2026-10-02 14:39:37 +03:00

198 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 3
- Автор, группа: Пластинин Денис, БВТ2303
- Целевая оценка: 5
- Выбранный трек: 1 — цена масштабирования
- Ветка/PR: `solution/bvt2303-plastinin`, PR #1
- Среда эксперимента: Docker, `linux/arm64`, Go 1.26.5
## Запуск из чистого clone
Требуются Git, Docker Engine с Docker Compose v2 и свободные локальные порты 8080, 8081, 9090 и 3000. Все внешние образы закреплены по версиям. Локальные пароли из примера предназначены только для изолированного стенда. Compose передаёт каждому контейнеру только нужные ему переменные: API получает строки подключения PostgreSQL/Valkey без отдельных исходных паролей и пароля Grafana, а `migrate` — только настройки PostgreSQL и миграций.
```sh
cp lab3.env.example .env
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --scale api=2 --wait --wait-timeout 120
```
Compose сначала ожидает PostgreSQL, затем однократно запускает контейнер `migrate`. API-реплики стартуют только после успешного завершения миграций. Единственная публичная точка API — Nginx на `http://localhost:8080`; порты отдельных API-контейнеров на хост не публикуются.
Доступные интерфейсы:
- Swagger UI: `http://localhost:8081`;
- Prometheus: `http://localhost:9090`;
- Grafana: `http://localhost:3000`, логин `admin`, локальный пароль берётся из `.env`;
- Nginx API: `http://localhost:8080`.
Проверки запущенного стенда:
```sh
make check
make test
docker compose --profile tests run --rm --build tests
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
```
Безопасная остановка сохраняет данные в named volumes:
```sh
docker compose stop
```
Повторный запуск выполняется командой `docker compose up -d --scale api=2 --wait`. Намеренное удаление всех учебных данных:
```sh
docker compose down -v
```
## Архитектура и решения
```mermaid
flowchart LR
C[Клиент] -->|HTTP :8080| N[Nginx]
N --> A1[API replica 1]
N --> A2[API replica 2]
N -. scale .-> AN[API replica N]
A1 --> P[(PostgreSQL)]
A2 --> P
AN --> P
A1 --> V[(Valkey)]
A2 --> V
AN --> V
M[Однократный migrate] --> P
PR[Prometheus] --> A1
PR --> A2
PR --> NE[Nginx exporter]
PR --> PE[PostgreSQL exporter]
PR --> VE[Valkey exporter]
G[Grafana] --> PR
```
PostgreSQL является источником истины для пользователей, чатов, сообщений и записей идемпотентности. Valkey хранит общие сессии, поэтому запросы с одним bearer token могут обслуживаться разными API-репликами. В Valkey ключ имеет вид `session:<sha256(token)>`, а значением служит JSON с `user_id` и сроком действия. Исходный случайный 256-битный токен возвращается клиенту один раз и не записывается в хранилище.
API остаётся stateless относительно пользовательских данных. Локально в процессе находятся только конфигурация, подключения, метрики конкретной реплики и флаг readiness. Каждый HTTP-ответ содержит `X-Instance-Id`, равный hostname контейнера.
### Балансировка и отказ реплики
Nginx OSS 1.30.5 использует round-robin, Docker DNS `127.0.0.11`, повторное разрешение имени `api` каждые 2 секунды и общий upstream zone. Keep-alive соединения ограничены 32. Таймаут подключения равен 1 секунде, таймауты отправки и чтения — 10 секунд. Ошибка соединения или ответ 502/503/504 временно исключают backend на 3 секунды; небезопасные POST автоматически не повторяются.
Docker проверяет `/health/ready` каждой API-реплики раз в 2 секунды с таймаутом 1 секунду. Readiness обращается к PostgreSQL и Valkey. При SIGTERM приложение сначала снимает readiness, затем вызывает `http.Server.Shutdown` с лимитом 5 секунд; Compose даёт контейнеру 8 секунд до принудительной остановки.
Nginx OSS в этом стенде использует пассивное исключение backend. Docker healthcheck не передаёт своё состояние напрямую в Nginx. Поэтому верхняя практическая граница обнаружения отказа складывается из connect timeout и fail timeout; в проверках восстановление произошло примерно за 1.4 секунды, что ниже требуемых 10 секунд.
### Общая идемпотентность
Для `POST /api/v1/chats/{chat_id}/messages` обязателен один заголовок `Idempotency-Key` длиной до 128 символов. Область ключа — `(user_id, chat_id, key)`, поэтому одинаковая строка независима для другого пользователя или чата. Минимальный TTL равен 24 часам.
Запись сообщения и запись идемпотентности создаются в одной транзакции PostgreSQL:
1. Проверяется участие пользователя в чате.
2. Из текста считается SHA-256 для выявления повторного использования ключа с другим запросом.
3. Строка идемпотентности блокируется через `SELECT ... FOR UPDATE`; конкурентные вставки разрешаются первичным ключом и `ON CONFLICT DO NOTHING`.
4. Победившая транзакция резервирует UUID сообщения и вставляет сообщение. Отложенный внешний ключ проверяется при commit.
5. Повтор с тем же телом читает исходное сообщение и возвращает тот же объект. Повтор с другим телом получает `409 Conflict`.
Это позволяет безопасно повторить POST после timeout: подтверждённая ранее запись не дублируется, даже если повтор попал на другую реплику. Истёкшая запись заменяется при следующем использовании ключа. Фоновая очистка не реализована; для длительной эксплуатации нужен периодический job по индексу `expires_at`.
### Миграции, обновление и развёртывание
API не выполняет DDL при старте. Отдельная команда `/app/migrate` берёт advisory lock и применяет versioned SQL один раз. Миграция идемпотентности только добавляет таблицу и индекс, поэтому совместима с уже работающей предыдущей версией.
`scripts/rolling-update.sh` собирает образы, запускает миграции, временно увеличивает число API с двух до трёх и поочерёдно заменяет старые контейнеры. Скрипт ждёт health каждого состава и затем возвращает две реплики. Workflow deploy запускается только вручную из `main` через `workflow_dispatch`; перед подключением к серверу он повторяет check, formatting, Go tests и build для SHA запуска. На сервере выполняется reset именно на этот SHA, даже если `main` успел измениться. Для SSH используются environment secrets `DEPLOY_HOST`, `DEPLOY_USER`, `DEPLOY_SSH_KEY` и заранее проверенный `DEPLOY_KNOWN_HOSTS`; изменяемых actions для SSH нет.
## Наблюдаемость
HTTP middleware каждой реплики публикует число запросов по route/status class, histogram latency, in-flight gauge, число replay идемпотентности, Go runtime и process metrics. Prometheus использует DNS service discovery имени `api` с периодом обновления 2 секунды и отдельно опрашивает Nginx, PostgreSQL и Valkey exporters каждые 5 секунд. Данные хранятся в Prometheus TSDB с retention 7 суток в named volume.
Provisioned dashboard Grafana показывает общий RPS, RPS и p95 по репликам, классы HTTP-ответов, число healthy replicas, in-flight, heap, replay rate, активные соединения и запросы Nginx, соединения PostgreSQL и состояние Valkey.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` через Nginx | PASS: регистрация, сессия, чат, пагинация, доступ и идемпотентность | `evidence/lab3-verification.txt` |
| Общие сессии и ≥2 реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | Одна сессия обслужена двумя instance ID | `evidence/lab3-verification.txt` |
| Конкурентная идемпотентность | `docker compose --profile tests run --rm --build tests` | 8 конкурентных запросов через два Store вернули один message ID; в БД одна строка | `evidence/lab3-verification.txt` |
| Сохранность | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | API, PostgreSQL и Valkey перезапущены; старые данные и token доступны | `evidence/lab3-verification.txt` |
| Отказ API | Два запуска failover с остановкой разных реплик | 125–131 успешная запись; 0–1 переходная ошибка; восстановление 1.35–1.44 с; дублей нет | `evidence/lab3-verification.txt` |
| Rolling update | 60 секунд Go-нагрузки и `scripts/rolling-update.sh` | 134894 подтверждения, 2248.16 RPS, 0 ошибок, p95 13.12 ms | `evidence/lab3-rolling-update.json` |
| CPU/RAM-лимиты | `docker compose config` и scale experiment | Лимиты заданы всем сервисам; при 128 MiB API не хватает памяти для Argon2id, поэтому рабочий минимум эксперимента — 256 MiB | `evidence/lab3-verification.txt` |
| Трек 1 | `scripts/run-scale-experiment.sh` | 1/2/4 реплики, два бюджета, concurrency 8/32/64, три повтора | `evidence/lab3-scale-results.json`, `evidence/lab3-scale-rps.svg` |
## Эксперименты и отказы
### Методика исследования масштабирования
Гипотеза: при фиксированном суммарном бюджете дробление ресурсов между большим числом процессов сначала улучшит распределение конкурентных запросов, но затем проиграет из-за меньших CPU-квот и пулов каждой реплики. При добавлении одинаковых ресурсов на реплику RPS должен расти до насыщения PostgreSQL или Nginx.
Используется Go-клиент `cmd/lab3experiment`. Он создаёт отдельного пользователя, сессию и чат, прогревает стенд 2 секунды, затем 6 секунд выполняет closed-loop POST сообщений через Nginx. Для каждого запроса генерируется уникальный idempotency key. Считаются только HTTP-подтверждения; автоматических retry измеряемого трафика нет. Для каждой точки используются concurrency 8, 32 и 64 и три изолированных повтора с новой базой.
CPU и Nginx RPS считаются по разности монотонных `process_cpu_seconds_total` и `nginx_http_requests_total`, прочитанных непосредственно до и после измеряемого интервала. Поэтому bootstrap, warmup и простой между точками в них не входят. Resident memory и число healthy replicas снимаются после нагрузки с `/metrics` каждой реплики, соединения PostgreSQL — instant query к Prometheus. Короткая контрольная точка дала 2355.97 client RPS и 2359.64 RPS по Nginx-счётчику, расхождение 0.16%.
Фиксированная серия имеет общий бюджет API 2 CPU и 1 GiB RAM: `1×(2 CPU, 1 GiB)`, `2×(1 CPU, 512 MiB)`, `4×(0.5 CPU, 256 MiB)`. Пулы PostgreSQL соответственно равны 16, 8 и 4 соединениям на реплику. В растущей серии каждая реплика получает 1 CPU, 256 MiB и пул 8, поэтому суммарный бюджет растёт вместе с числом процессов.
Предварительный прогон с общим лимитом 512 MiB показал, что вариант `4×128 MiB` не выполняет регистрацию: базовое потребление процесса около 71 MiB, а Argon2id временно требует ещё 64 MiB. Cgroup завершает реплику, Nginx наблюдает premature upstream close. Этот результат определил минимальный рабочий лимит 256 MiB и не включён в сравнение throughput.
Медианные результаты фиксированного суммарного бюджета:
| Concurrency | 1 реплика: RPS / p95 ms | 2 реплики: RPS / p95 ms | 4 реплики: RPS / p95 ms |
| ---: | ---: | ---: | ---: |
| 8 | 2412 / 5.86 | 2484 / 5.59 | 2242 / 6.35 |
| 32 | 2731 / 18.63 | 2365 / 24.93 | 2013 / 34.58 |
| 64 | 2733 / 32.99 | 2198 / 55.06 | 2103 / 67.89 |
При фиксированных 2 CPU и 1 GiB увеличение числа процессов не даёт линейного выигрыша. Две реплики дают небольшой выигрыш только при concurrency 8, одна быстрее при 32 и 64, а четыре проигрывают во всех профилях из-за квоты 0.5 CPU на процесс и расходов четырёх runtime. Для рабочего стенда две реплики остаются осознанным компромиссом ради отказоустойчивости, дальнейшее дробление бюджета не оправдано.
Медианные результаты серии с 1 CPU и 256 MiB на каждую реплику:
| Concurrency | 1 реплика: RPS / p95 ms | 2 реплики: RPS / p95 ms | 4 реплики: RPS / p95 ms |
| ---: | ---: | ---: | ---: |
| 8 | 2712 / 4.95 | 2554 / 5.28 | 2185 / 7.05 |
| 32 | 2818 / 15.34 | 2471 / 21.94 | 2130 / 24.14 |
| 64 | 2044 / 61.44 | 2239 / 57.76 | 1859 / 67.42 |
Даже при росте суммарного CPU практический предел не превышает двух реплик. При concurrency 64 переход `1→2` повышает медианный RPS на 9.6%, а `2→4` снижает его на 17.0%. Одновременно число соединений PostgreSQL растёт `9→17→33`, суммарная resident memory — примерно `36→65→397 MiB`, а p95 у четырёх реплик достигает 67.42 ms. Точная средняя загрузка API составляет примерно `0.43→0.52→0.54 core` при доступных `1→2→4 core`. API не упирается в CPU-квоту. Вместе с ростом DB connections и tail latency это указывает на насыщение общего пути PostgreSQL/Nginx/network и расходы дополнительных процессов, но данный эксперимент не разделяет вклад этих компонентов.
Во всех 54 основных точках было 0 HTTP-ошибок; каждая конфигурация наблюдала все заявленные реплики. Диапазоны трёх повторов заметно пересекаются и доступны в raw JSON, поэтому небольшие отличия нельзя считать точной оценкой абсолютной производительности.
Для настройки пула конфигурация `4×0.5 CPU, 256 MiB` при concurrency 64 дополнительно сравнивалась с 10 и 4 соединениями PostgreSQL на реплику:
| Пул на реплику | Median RPS | p50 / p95 / p99, ms | Соединения PostgreSQL | Ошибки |
| ---: | ---: | ---: | ---: | ---: |
| 10 | 1918 | 30.00 / 59.52 / 101.70 | 41 | 0 |
| 4 | 2179 | 23.61 / 66.76 / 80.91 | 17 | 0 |
Уменьшение пула `10→4` сократило число соединений на 58.5%, повысило медианный RPS на 13.6%, уменьшило p50 на 21.3% и p99 на 20.4%. p95 вырос на 12.2%, то есть распределение задержек изменилось неравномерно. Для данного стенда выбран пул 4: он соответствует CPU-квоте 0.5 core и заметно снижает давление на общую БД. При строгом SLO на tail latency значение следует подбирать повторно на более длинном open-loop тесте.
Итоговый график находится в `evidence/lab3-scale-rps.svg`, обезличенные исходные точки, медианы и диапазоны — в `evidence/lab3-scale-results.json`.
### Отказ и обновление
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| SIGTERM одной API-реплики | Nginx исключает backend, другая реплика продолжает работу | 0–1 переходная ошибка, старый instance ID исчез из последующих ответов | 1.35–1.44 с; подтверждённые сообщения сохранены, дублей нет |
| Полный restart API, PostgreSQL и Valkey без удаления volumes | Данные и сессия сохраняются | Старый bearer token и созданные сущности доступны после запуска | В пределах 90-секундного окна теста; потерь не обнаружено |
| Rolling update API 2→3→2 | Во время замены остаются healthy backend | 134894 успешных POST, 0 ошибок; наблюдались старые и новые instance ID | Перерыва по подтверждённым ответам не зафиксировано |
| Остановка PostgreSQL или Valkey | Readiness становится отрицательной | Все API теряют готовность, потому что хранилища общие | Автоматический failover хранилищ не реализован |
## Ограничения и следующие шаги
- Все компоненты работают на одном Docker-хосте. Отказ хоста, Nginx, PostgreSQL или Valkey останавливает сервис; выполнен отказ процесса API, а не отказ узла.
- Nginx является одной публичной точкой и SPOF. Для эксплуатации потребуются несколько LB с внешним virtual IP или управляемый балансировщик.
- PostgreSQL и Valkey не реплицированы. AOF Valkey с `appendfsync everysec` ограничивает возможную потерю примерно последней секундой при аварии хранилища, но этот сценарий в работе не заявляется как защищённый.
- Нагрузочный клиент closed-loop и подвержен coordinated omission. Результаты сравнивают конфигурации на одной машине и не являются абсолютной производительностью production-системы.
- Все реплики и клиент делят ресурсы одного хоста; дельта process CPU показывает потребление API, а не полную стоимость Docker/network/storage.
- Для эксплуатации нужны TLS, внешнее управление secrets, репликация хранилищ, алерты, план очистки истёкших idempotency records и длительный soak test.
## Источники и инструменты
- Nginx upstream и динамическое DNS: <https://nginx.org/en/docs/http/ngx_http_upstream_module.html>
- Docker Compose services и healthcheck: <https://docs.docker.com/reference/compose-file/services/>
- PostgreSQL explicit locking: <https://www.postgresql.org/docs/current/explicit-locking.html>
- Valkey persistence: <https://valkey.io/topics/persistence/>
- Argon2: RFC 9106, <https://www.rfc-editor.org/rfc/rfc9106>
- Go packages: `pgx/v5`, `valkey-go`, `prometheus/client_golang`, `google/uuid`, `viper`, `x/crypto/argon2`.
- OpenAI Codex использовался для подготовки кода, конфигурации и текста; реализация и результаты проверены запуском тестов и экспериментов.