273 lines
18 KiB
Markdown
273 lines
18 KiB
Markdown
# Отчёт - лабораторная 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 в репозитории не публикуются,
|
||
это вспомогательные утилиты.
|