docs(report): lab3 report filling
This commit is contained in:
@@ -1,37 +1,254 @@
|
||||
# Отчёт — лабораторная 3
|
||||
# Отчёт - лабораторная 3
|
||||
|
||||
- Автор, группа: TODO
|
||||
- Целевая оценка; выбранный трек 5, если нужен: TODO
|
||||
- Commit/PR: TODO после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: TODO
|
||||
- Автор, группа: Голиков, БВТ2303
|
||||
- Целевая оценка; выбранный трек 5: на 5, трек 1 "Цена масштабирования"
|
||||
- Commit/PR: de9930a02eee7446aeef3b5ba668f9547c969268
|
||||
- Использованные источники, библиотеки и помощь ИИ:
|
||||
- Скелет лабы 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
|
||||
|
||||
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
|
||||
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 дополнительно созданы scripts/restart.cmd и scripts/stop-one.cmd, потому что tests/resilience.py запускает хук через subprocess.Popen, а этот вызов на Windows не умеет исполнять .sh-файлы (WinError 193). .cmd-обёртки вызывают ту же логику через docker compose. На Linux используется .sh-вариант.
|
||||
|
||||
Безопасная остановка:
|
||||
|
||||
docker compose stop
|
||||
# или полностью с сохранением данных:
|
||||
docker compose down
|
||||
|
||||
Остановка с удалением учебных данных (необратимо, удалит volume postgres_data и redis_data):
|
||||
|
||||
docker compose down -v
|
||||
|
||||
Отдельно про .env и secrets: оба пути в .gitignore, в репозиторий не попадают. Значения паролей синтетические, для локального стенда.
|
||||
|
||||
## Архитектура и решения
|
||||
|
||||
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab2, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
|
||||
Схема:
|
||||
|
||||
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.
|
||||
|
||||
Соответствие переменных .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
|
||||
|
||||
## Доказательства критериев
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
| --- | --- | --- | --- |
|
||||
| Публичный smoke | make test | TODO | TODO |
|
||||
| Остальные пункты уровня 3 | TODO | TODO | TODO |
|
||||
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
|
||||
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
|
||||
Уровень 3:
|
||||
|
||||
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
|
||||
| Критерий | Команда | Наблюдаемый результат | Файл |
|
||||
| --- | --- | --- | --- |
|
||||
| Публичный 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 | k6 rolling update: повтор с тем же ключом | write_errors 0.26 процента, дублей нет | evidence/k6-rolling.json |
|
||||
| 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), схема применяется один раз | в логах при запуске, миграция 0002_idempotency.sql |
|
||||
| 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 процента, 8.65 с | evidence/failover-load-api-1-k6.json, evidence/failover-load-api-2-k6.json |
|
||||
|
||||
Трек 1: см. раздел ниже.
|
||||
|
||||
## Эксперименты и отказы
|
||||
|
||||
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
|
||||
Общая среда: Windows 10, Docker Desktop (WSL2 backend), одна физическая
|
||||
машина, на которой работают и нагрузочный генератор, и весь стек. Все
|
||||
пользователи и сообщения синтетические, генерируются тестами и k6.
|
||||
Версии: 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.
|
||||
|
||||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления, потеря данных |
|
||||
| --- | --- | --- | --- |
|
||||
| TODO | TODO | TODO | TODO |
|
||||
| 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 (краткие ошибки во время обнаружения отказа измеряются и
|
||||
допустимы).
|
||||
|
||||
## Ограничения и следующие шаги
|
||||
|
||||
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
|
||||
Что выдерживает:
|
||||
|
||||
- Отказ одной API-реплики (любой из двух) при RATE до 400 RPS.
|
||||
- Graceful drain с сохранением in-flight запросов.
|
||||
- Rolling update без простоя.
|
||||
- Перезапуск всего стека с сохранением данных и сессий.
|
||||
|
||||
Что не выдерживает:
|
||||
|
||||
- Отказ узла. Всё работает на одном хосте, потеря хоста = потеря системы.
|
||||
Postgres и Redis без репликации, LB без резерва.
|
||||
- RATE=800. При удвоении насыщения система деградирует: 28-40 процентов
|
||||
ошибок, p95 latency свыше 9 с. Это зафиксировано как результат
|
||||
эксперимента трека 1, а не как баг.
|
||||
|
||||
Не реализовано в этой работе:
|
||||
|
||||
- PgBouncer. Проверялась гипотеза о pool exhaustion в pgx, гипотеза не
|
||||
подтвердилась (см. трек 1), поэтому PgBouncer не добавлен.
|
||||
- Вторая реплика Postgres и failover БД. Не входит в обязательный
|
||||
минимум, отмечено как SPOF в ограничениях.
|
||||
- HTTPS. По контракту требуется только с ЛР7, здесь HTTP для локального
|
||||
стенда.
|
||||
- Полноценная распределённая нагрузка. k6 на одной машине со стеком
|
||||
измеряет не только стек, но и клиент. Это ограничение методики,
|
||||
зафиксировано в треке 1.
|
||||
|
||||
Учебные упрощения:
|
||||
|
||||
- БД и хранилище сессий живут в одном экземпляре, оба на том же хосте,
|
||||
что и API. Для уровня 3 достаточно, для продакшена недостаточно.
|
||||
- Migrations выполняются одноразовым сервисом migrate, но без
|
||||
отдельных rollback-сценариев. Если миграция падает, стек не
|
||||
поднимается.
|
||||
|
||||
Подтверждённые улучшения:
|
||||
|
||||
- Graceful drain снизил долю обрывов in-flight запросов при остановке
|
||||
реплики. Без drain (теоретически) остановка могла бы рвать активные
|
||||
POST-запросы, сейчас docker stop даёт серверу корректно завершиться
|
||||
с exit 0.
|
||||
- Изоляция миграций в отдельный процесс сняла гонку за goose lock при
|
||||
старте нескольких реплик одновременно.
|
||||
- X-Instance-Id позволяет на защите и в тестах однозначно сопоставить
|
||||
ответ конкретной реплике, без чтения логов.
|
||||
|
||||
Гипотезы, оставшиеся непроверенными:
|
||||
|
||||
- Узкое место в Docker Desktop networking при высокой интенсивности.
|
||||
Проверено частично (k6 в Docker-сети снизил долю ошибок с 40 до
|
||||
28 процентов, но не поднял RPS).
|
||||
- Накладные расходы nginx при проксировании. В пределах текущих
|
||||
метрик не выделяются: nginx держит около 10 процентов CPU на всём
|
||||
диапазоне.
|
||||
- Ограничения k6 на одном физическом хосте. При VU до 3141 k6 сам
|
||||
становится источником нагрузки на CPU хоста.
|
||||
|
||||
Следующий шаг для полной картины: вынести нагрузочный генератор на
|
||||
отдельный физический хост, повторить probe RATE=800. Если RPS начнёт
|
||||
расти - узкое место клиентское. Если нет - узкое место в стеке, и
|
||||
дальше копать в сторону Docker Desktop networking или оптимизации
|
||||
Postgres.
|
||||
|
||||
## Эксперименты трека 1
|
||||
|
||||
|
||||
Reference in New Issue
Block a user