forked from mtusi2026/mtusi2026lab3
198 lines
24 KiB
Markdown
198 lines
24 KiB
Markdown
# Отчёт — лабораторная 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: подтверждённая ранее запись не дублируется, даже если повтор попал на другую реплику. Каждый успешный запрос также удаляет до 100 истёкших записей по индексу `expires_at`; `SKIP LOCKED` не даёт параллельным репликам ждать одну и ту же пачку.
|
||
|
||
### Миграции, обновление и развёртывание
|
||
|
||
API не выполняет DDL при старте. Отдельная команда `/app/messenger 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` |
|
||
| Конкурентная идемпотентность | Go black-box через Nginx и database integration suite | 16 одновременных HTTP-запросов обработаны минимум двумя instance ID и вернули один 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, репликация хранилищ, алерты и длительный soak test; при большом потоке следует отдельно измерить стоимость пакетной очистки idempotency records.
|
||
|
||
## Источники и инструменты
|
||
|
||
- 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 использовался для подготовки кода, конфигурации и текста; реализация и результаты проверены запуском тестов и экспериментов.
|