Files
mtusi2026lab3/REPORT.md
T

273 lines
18 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 "Цена масштабирования"
- Commit/PR: e769e08
- Использованные источники, библиотеки и помощь ИИ:
- Скелет лабы 3 и материалы курса: COURSE.md, contracts/openapi.json, contracts/README.md
- Документация Docker Compose (services, deploy.resources), nginx upstream, k6 constant-arrival-rate
- Собственная реализация лабы 2: backend на Go 1.26, gin, pgx, goose, Redis
- ИИ использовался для структуры отчёта и вычитки формулировок; весь код, конфигурация и измерения выполнены самостоятельно
## Запуск из чистого clone
Prerequisites:
- Docker Desktop 4.30+ (WSL2 backend) или Docker Engine с Compose v2.20+
- Go 1.26+ (для локальной сборки без Docker; в Docker-варианте не нужен)
- Python 3.9+ (для публичных тестов из scaffold)
- k6 v0.55+ (для нагрузочных экспериментов и трека 1)
- git, make
Шаги запуска:
1. Клонировать fork и перейти на ветку solution:
```
git clone https://gitea.privcloud.tech/Maximillan_Mercer/mtusi2026lab3-fork.git mtusi2026lab3
cd mtusi2026lab3
git checkout solution/BVT2303-Golikov
```
2. Создать локальные secrets. Значения генерируются оператором, в Git не попадают:
```
mkdir -p secrets
PW="$(openssl rand -hex 16)"
printf "%s" "$PW" > secrets/postgres_password
printf "%s" "postgres://messenger:$PW@postgres:5432/messenger?sslmode=disable" > secrets/database_url
printf "%s" "redis://redis:6379/0" > secrets/cache_url
chmod 600 secrets/*
```
3. Создать .env из .env.example:
```
cp .env.example .env
```
Переменные и дефолты:
- API_REPLICAS=2 - число API-реплик
- API_CPUS=0.5, API_MEMORY=256M - лимиты на одну реплику
- POSTGRES_CPUS=1.0, POSTGRES_MEMORY=1G
- REDIS_CPUS=0.5, REDIS_MEMORY=256M
- LB_PORT=8080 - публичный порт LB на хосте
- SESSION_TTL_SECONDS=3600
- IDEMPOTENCY_TTL_SECONDS=86400
- SHUTDOWN_DRAIN_SECONDS=3
4. Собрать образ API и запустить стек:
```
docker compose build api
docker compose up -d
```
5. Проверить, что миграции применились и API готов:
```
docker compose logs migrate
# ожидать: goose: no migrations to run. current version: 2
# (при первом запуске: OK 0002_idempotency.sql)
curl -sS http://localhost:8080/health/ready
# ожидать: {"status":"ok"}
```
6. Прогнать публичный smoke и проверки от scaffold:
```
PYTHONUTF8=1 make check
PYTHONUTF8=1 make test
```
7. Проверки сохранности и отказа (требуют реализации scripts/restart.sh и scripts/stop-one.sh):
```
PYTHONUTF8=1 make test-persistence ACTION_SCRIPT=scripts/restart.sh
PYTHONUTF8=1 make test-failover ACTION_SCRIPT=scripts/stop-one.sh
```
Примечание для Windows. tests/resilience.py запускает хук через
subprocess.Popen, который на Windows не умеет исполнять .sh-файлы
(WinError 193). Локально созданы scripts/restart.cmd и scripts/stop-one.cmd,
вызывающие ту же логику через docker compose. В репозиторий .cmd не
коммитятся (в .gitignore), на Linux работают .sh-варианты.
Безопасная остановка:
docker compose stop # остановить контейнеры, volumes сохранить
docker compose down # удалить контейнеры и сеть, volumes сохранить
Остановка с удалением учебных данных (необратимо, удалит volumes
postgres_data и redis_data):
docker compose down -v
Отдельно про .env и secrets: оба пути в .gitignore, в репозиторий не
попадают. Значения паролей синтетические, для локального стенда.
## Архитектура и решения
Схема:
client (k6 или curl)
|
v
nginx LB (:8080) единственная публичная точка
|
+-> api-1 :8080 реплика 1
+-> api-2 :8080 реплика 2
|
+-> postgres :5432 общая БД (users, chats, messages, sessions, idempotency_keys)
+-> redis :6379 общее хранилище сессий
Источник истины - PostgreSQL. Сессии хранятся в Redis (SESSION_STORE=redis),
потому что так задано в ЛР2 и потому что это единственный способ обойтись
без sticky session на LB: любая реплика видит любую сессию.
Транзакционные границы. Идемпотентная отправка сообщения - одна транзакция
в Postgres. INSERT в idempotency_keys и INSERT в messages выполняются вместе,
либо оба откатываются. Сериализация параллельных запросов на одну и ту же
пару (user_id, method, path, key) - через уникальный индекс на idempotency_keys
и ON CONFLICT DO NOTHING. Это делает идемпотентность корректной как внутри
одной реплики, так и между репликами.
Что перенесено из ЛР2 без изменений:
- Схема БД: users, chats, chat_members, messages, sessions
- Argon2id для паролей, opaque bearer token (SHA-256 от 32 случайных байт)
- Миграции goose
- Публичный HTTP-контракт: /api/v1/users, /chats, /messages, /auth/sessions
Что изменено в этой работе:
1. Добавлен обязательный Idempotency-Key на POST /chats/{chat_id}/messages.
Хранится в новой таблице idempotency_keys. TTL из IDEMPOTENCY_TTL_SECONDS,
дефолт 24 часа.
2. Добавлен заголовок X-Instance-Id во все ответы API. Значение -
os.Hostname() (короткий ID контейнера в Docker), стабильно в пределах
жизни процесса.
3. Миграции вынесены в отдельный процесс /server migrate. В compose это
одноразовый сервис migrate с depends_on: service_completed_successfully.
Реплики больше не запускают goose при старте.
4. Graceful drain на SIGTERM. Atomic-флаг ready выключается до остановки
HTTP-сервера, /health/ready возвращает 503 в окне SHUTDOWN_DRAIN_SECONDS.
Затем srv.Shutdown ждёт завершения in-flight запросов.
5. CPU/RAM лимиты на api, postgres, redis через deploy.resources.
6. LB на nginx перед двумя репликами. Публичный порт только у LB, реплики
доступны только через expose.
7. Включён upstream keepalive в nginx (см. трек 1, это подтверждённое
улучшение пропускной способности).
Соответствие переменных .env.example реальной конфигурации:
- APP_HOST, APP_PORT - читаются в main.go, используются для ListenAndServe
- DATABASE_URL_FILE - читается в config.Load через readSecret
- SESSION_STORE - переключает сессии между postgres и redis
- SESSION_TTL_SECONDS, IDEMPOTENCY_TTL_SECONDS - читаются в config.Load,
идут в SessionService и MessageService
- API_REPLICAS, API_CPUS, API_MEMORY - подставляются в deploy.replicas
и deploy.resources в compose.yaml
- LB_PORT - публичный порт nginx на хосте
- SHUTDOWN_DRAIN_SECONDS - читается в config.Load, используется в main.go
перед srv.Shutdown
## Доказательства критериев
Уровень 3:
| Критерий | Команда | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Публичный smoke | PYTHONUTF8=1 make test | PASS: lab3 public API scenario | вывод на экран |
| >= 2 API-реплики за LB | docker compose ps | api-1 и api-2 Up (healthy), LB публикует :8080 | evidence/docker-stats-limits.txt |
| Разные X-Instance-Id при одной сессии | for i in 1..10; curl -D- health/live | два чередующихся ID | evidence/test-failover.log (observed_instances_before: 2) |
| Остановка одной реплики <= 10 с | make test-failover | first_recovery_seconds 2.466 | evidence/test-failover.log |
| Поочерёдная остановка каждой | make test-failover дважды | второй прогон 2.487 с, останавливалась другая реплика | evidence/test-failover-second.log |
| Идемпотентность POST | PYTHONUTF8=1 make test (replay с тем же ключом) + make test-failover (uncertain retry) | тот же ответ, дублей нет | evidence/test-failover.log |
| Persistence после restart | make test-persistence | PASS, прежний токен работает | evidence/test-persistence.log |
Уровень 4:
| Критерий | Команда | Наблюдаемый результат | Файл |
| --- | --- | --- | --- |
| Health/readiness, timeouts, SIGTERM согласованы | docker stop <api-N> с замером wall-clock | 3.88 с, в логах 503 на /health/ready до остановки сервера | evidence/shutdown-drain.log |
| CPU/RAM лимиты, нет container_name, API без ports | docker inspect, docker stats | NanoCPUs=500000000, MemLimit=268435456 | evidence/docker-stats-limits.txt |
| Миграции однократно | docker compose logs migrate | Exited (0), схема применяется один раз | evidence/migrate-log.txt |
| Rolling update под нагрузкой | scripts/run-rolling-experiment.sh | RATE=50, 3 мин, write_errors 0.26 процента | evidence/k6-rolling.json, evidence/rolling-update.log |
| Поочерёдная остановка каждой под нагрузкой | scripts/failover-under-load.sh 1, scripts/failover-under-load.sh 2 | прогон 1: 0 ошибок, 8.67 с; прогон 2: 1.38 процента в окне переключения nginx, 8.65 с | evidence/failover-load-api-1-k6.json, evidence/failover-load-api-2-k6.json |
## Отказоустойчивость: эксперименты и отказы
Общая среда: Windows 10, Docker Desktop (WSL2 backend), одна физическая
машина, на которой работают и нагрузочный генератор, и весь стек. Все
пользователи и сообщения синтетические. Версии: Postgres 16.4,
Redis 7.4, nginx 1.27.4, Go 1.26.
Профиль нагрузки на k6: constant-arrival-rate, executor open-loop.
Устраняет coordinated omission по сравнению с tests/load.py. Подробности
в разделе трека 1.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления, потеря данных |
| --- | --- | --- | --- |
| SIGTERM одной реплике | drain 3 с, 503 на /health/ready, exit 0 | ровно так, 3.88 с wall-clock | 3.88 с, потерь нет |
| Остановка одной реплики при RATE=30 (make test-failover) | writes продолжаются через LB, без дублей | first_recovery_seconds 2.466, повтор с тем же ключом даёт то же сообщение | 2.5 с, потерь нет |
| Перезапуск всего стека (scripts/restart.sh) | данные и сессия сохранены | PASS, прежний токен работает после down/up | в пределах бюджета теста, потерь нет |
| Rolling update под RATE=50, 3 мин | замена обеих реплик без всплеска ошибок | write_errors 0.26 процента, p95 6.27 ms | без простоя |
| Остановка api-3 под RATE=30 | RPS не проседает, восстановление <= 10 с | 0 ошибок, 8.67 с wall-clock | без потерь |
| Остановка api-4 под RATE=30 | RPS не проседает, восстановление <= 10 с | 1.38 процента ошибок в окне переключения, 8.65 с | без потерь |
Ошибки в окне переключения nginx (0.26 и 1.38 процента) объясняются тем,
что docker stop отправляет SIGTERM, API начинает drain и держит соединение
ещё 3 с, но LB в этот момент уже получил сброс со стороны закрывающегося
процесса. Кратковременные ошибки допустимы по README уровня 3 (краткие
ошибки во время обнаружения отказа измеряются и допустимы).
## Трек 1. Цена масштабирования
### Постановка и ошибки первой версии
Задача трека по README: при фиксированном суммарном CPU/RAM сравнить
1/2/4 API-реплики на одном профиле нагрузки, затем провести серию с
ростом ресурсов, найти saturation point, показать, почему рост реплик
перестаёт помогать, дать исходные данные, графики и одно подтверждённое
улучшение.
Первая версия отчёта содержала три ошибки методики, отмеченные на ревью:
1. Вывод о потолке 395 RPS был сделан из нагрузки RATE=400. Это точка,
где система справляется, а не упирается. Настоящее насыщение выше.
2. Отсутствовала серия с ростом ресурсов при фиксированном числе
реплик, хотя README требует её явно.
3. Метрики не разделяли успешные запросы, попытки и потерянные
итерации. Доля ошибок и потери k6 смешивались.
Отдельно: объяснение улучшения через «включение keepalive» расходилось
с Git. Директива `keepalive 32` присутствовала в `infra/nginx.conf` с
первого коммита (2211eaa), а коммит e769e08 добавил только
`keepalive_requests`, `keepalive_timeout` и увеличил
`worker_connections 512 -> 1024`. Значит, приписывать +80 % пропускной
способности включению keepalive было неверно.
Настоящий раздел написан заново. Серии A, B, C переделаны с нуля,
метрики разделены, выводы пересмотрены.
### Методика
Нагрузочный генератор: k6 v0.55, executor `constant-arrival-rate`
(open-loop). Скрипт `student-tests/load-k6.js`. Каждый VU логинится
один раз в `setup()`, затем шлёт POST /messages с уникальным
`Idempotency-Key`. Open-loop устраняет coordinated omission, в отличие
от `tests/load.py`.
Каждый замер - 2 или 3 прогона в зависимости от серии. Между прогонами
стек не пересоздаётся, но между конфигурациями - да, чтобы избежать
накопленного состояния. Медиана по прогонам в сводных таблицах.
Метрики разделены:
- **Успешные** (`write_total.rate`) - POST, завершившиеся 201.
- **Попытки** (`http_reqs.rate`) - все отправленные POST.
- **Потерянные** (`dropped_iterations.rate`) - k6 не смог даже
отправить запрос из-за нехватки VU. Это клиентский предел, не
серверная ошибка.
- **Ошибки** (`write_errors.rate`) - POST, вернувшие не-201.
- **p95 / max** (`write_latency_ms`) - хвосты latency успешных.
Среда: Windows 10, Docker Desktop (WSL2), одна физическая машина.
На ней и стек, и k6. Postgres 16.4, Redis 7.4, nginx 1.27.4, Go 1.26.
Аппаратные лимиты: api - 0.25-2.0 CPU / 128M-1G в зависимости от
конфигурации, postgres - 1.0 CPU / 1G, redis - 0.5 CPU / 256M,
lb - 0.5 CPU / 128M.
Данные: `evidence/new_ev/` (JSON summary k6 + CSV docker stats).
Скрипты запуска серий и сборки CSV в репозитории не публикуются,
это вспомогательные утилиты.