Files
mtusi2026lab3/REPORT.md
T
2026-10-30 18:11:30 +03:00

16 KiB
Raw Blame History

Отчёт — лабораторная 3

  • Автор, группа: <TODO LATER>
  • Целевая оценка: 4
  • Commit/PR: TODO
  • Источники, библиотеки и помощь ИИ: официальная документация Docker Compose, HAProxy, Go/Fiber; код и инфраструктура подготовлены с помощью DeepSeek V4.1 Flash + OpenCode

1. Что сделано

Рабочая база lab2 (Go + Fiber v3, PostgreSQL, Redis-сессии, миграции) доведена до lab3:

  • HAProxy стал единственной публичной точкой входа;
  • запущены две API-реплики без публикации их портов;
  • сессии и идемпотентность сообщений вынесены в общие хранилища;
  • X-Instance-Id добавлен во все ответы API;
  • миграции вынесены в отдельный one-shot сервис;
  • настроены readiness, graceful shutdown и ограничения CPU/RAM;
  • добавлены action-скрипты для restart/failover и rolling replacement;
  • подготовлен профиль k6 для проверки rolling update под нагрузкой.

Обязательный контракт, lab.json и публичные тесты не изменялись. Существующие неочевидные решения отмечены в коде комментариями AGENT:; перечень файлов для их проверки и удаления находится в LEFT_TO_REVIEW.md. Новые комментарии AGENT: в этой итерации не добавлялись: изменения и их обоснование записаны в CHANGELOG.md.

2. Запуск из чистого clone

Требуется Docker Engine с Compose v2 и свободный порт 8080 (или другой LB_PORT). Версии образов зафиксированы в compose.yaml.

cp .env.example .env
# задать локальный POSTGRES_PASSWORD; остальное можно оставить по умолчанию
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
make wait

Порядок запуска:

  1. PostgreSQL и Redis проходят healthcheck.
  2. Сервис migrate один раз применяет миграции и завершается.
  3. Запускаются API-реплики с RUN_MIGRATIONS=false.
  4. HAProxy начинает отдавать /health/ready только после готовности API.

Проверки:

make test
make test-persistence ACTION_SCRIPT=scripts/restart.sh
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
make test-concurrency

Дополнительно:

make k6 VUS=20 DURATION=60s  # нагрузка через HAProxy
make validate PYTHON=.venv/bin/python

Остановка без удаления данных:

docker compose --env-file .env down

Намеренное удаление учебных данных (только отдельный стенд):

docker compose --env-file .env down -v

.env в репозиторий не попадает; в .env.example лежит только placeholder пароля.

3. Архитектура и решения

клиент
  │  HTTP :8080
  ▼
HAProxy  ── readiness /health/ready, retries, stats :8404, Prometheus /metrics
  │  Docker DNS, server-template api 1..4
  ├──────────────┐
  ▼              ▼
API-1          API-2      ... API-N   (Go/Fiber, без публикации портов)
  │              │
  └──────┬───────┘
         ▼
   PostgreSQL  ← users/chats/messages + message_idempotency
   Redis       ← общие сессии (AOF)

migrate  — one-shot, RUN_MIGRATIONS / MIGRATE_ONLY

3.1. Компоненты и лимиты

Компонент Роль Решение
haproxy LB и публичная точка входа server-template api 4 api:8080 resolvers docker; health check /health/ready каждые 1 с, fall 2
api бизнес-API deploy.replicas: ${API_REPLICAS:-2}, expose: 8080, без ports
migrate миграции тот же образ, MIGRATE_ONLY=true, restart: "no"
postgres источник истины named volume pgdata, healthcheck, версия 16.10
redis общие сессии AOF everysec, named volume redisdata
k6 нагрузка профиль load, подключается только при явном запуске

У API, PostgreSQL, Redis и HAProxy есть CPU/RAM-лимиты (deploy.resources.limits, значения из .env). У API нет container_name, поэтому Compose может масштабировать сервис.

3.2. Миграции

app/cmd/server/main.go поддерживает два режима:

  • обычный API: RUN_MIGRATIONS=false, схемой занимается отдельный сервис;
  • MIGRATE_ONLY=true: применить миграции, закрыть пул и выйти, не открывая Redis.

Это убирает гонку миграций при старте нескольких реплик и при rolling update. Миграция 0002_message_idempotency аддитивная: старая версия приложения может работать с уже созданной таблицей, новая версия требует её наличия. Поэтому порядок «сначала migrate, потом новые API» безопасен.

3.3. X-Instance-Id

Middleware в app/internal/app.go ставит заголовок на каждый ответ, включая health и ошибки. Значение берётся из INSTANCE_ID, а если он не задан — из hostname процесса. В Compose hostname уникален для контейнера, поэтому реплики различимы; значение не меняется в течение жизни процесса.

Если hostname получить нельзя и INSTANCE_ID не задан, конфигурация завершается ошибкой. Раньше в этом случае молча подставлялось литеральное значение api, из-за чего несколько процессов могли получить одинаковый идентификатор.

3.4. Идемпотентность сообщений

Таблица message_idempotency:

  • PK (sender_id, chat_id, idempotency_key) — ровно область «пользователь + путь чата + ключ»; метод в текущем API только один;
  • request_hash — SHA-256 текста сообщения;
  • message_id — ссылка на уже созданное сообщение;
  • created_at, expires_at — окно хранения (по умолчанию 24 часа).

Алгоритм в app/internal/store/messages.go:

  1. Быстрый lookup по ключу. Если запись не истекла и hash совпал — вернуть тот же Message с 201.
  2. Иначе открыть транзакцию, вставить сообщение с проверкой членства в чате, вставить ключ через ON CONFLICT.
  3. Если конкурентная реплика уже вставила этот ключ, транзакция текущего запроса откатывается, и читается результат победившей реплики. При другом hash — 409.
  4. Транзиентная ошибка не фиксирует ключ: транзакция откатывается, клиент может повторить с тем же ключом.

Так один ключ создаёт ровно одно сообщение даже при параллельных запросах через разные реплики. Повтор снова проходит аутентификацию и проверку доступа к чату.

3.5. HAProxy и graceful shutdown

  • backend discovery: Docker DNS 127.0.0.11:53, server-template api 4, поэтому docker compose up --scale api=N не требует правки конфига;
  • health check: GET /health/ready, inter 1s, fall 2 — обнаружение отказа около 2 секунд (при бюджете 10 секунд);
  • retries 2, option redispatch — короткие ошибки соединения не роняют запрос;
  • при SIGTERM приложение сначала перестаёт отдавать 200 на readiness, затем ждёт до 10 секунд; у контейнера stop_grace_period: 15s;
  • stats UI/CSV на :8404/stats, Prometheus на :8404/metrics.

3.6. Readiness и транзакции

/health/ready проверяет PostgreSQL и Redis и не захватывает прикладных блокировок. pgxpool.Ping берёт соединение из пула и возвращает его через defer; store.Ping ограничивает проверку двумя секундами.

Отдельно проверены транзакции в CreateChat и CreateMessage. Откат больше не выполняется на неограниченном context.Background(): используется контекст с таймаутом. Если PostgreSQL перестал отвечать, соединение закрывается, а PostgreSQL трактует закрытие соединения как откат и снимает блокировки строк. Это не даёт неудачной транзакции удерживать соединение пула и мешать readiness других запросов. Единственная явная advisory-блокировка — миграционная; она снимается в defer с собственным таймаутом.

4. Доказательства критериев

Критерий Команда/сценарий Наблюдаемый результат Файл
Публичный smoke make test PASS: lab3 public API scenario evidence/grade-3-4.md
Офлайн-проверки make check PASS: offline skeleton... evidence/grade-3-4.md
OpenAPI make validate PYTHON=.venv/bin/python PASS: full OpenAPI 3.1... evidence/grade-3-4.md
≥2 реплики, одна сессия 10 запросов /health/live через LB 2 разных X-Instance-Id evidence/grade-3-4.md
Остановка одной реплики make test-failover ACTION_SCRIPT=scripts/stop-one.sh 120–121 запись, 0–1 ошибка, восстановление 2.54–2.93 с evidence/grade-3-4.md
Сохранность после restart make test-persistence ACTION_SCRIPT=scripts/restart.sh данные и bearer-токен сохранились evidence/grade-3-4.md
Конкурентная идемпотентность make test-concurrency 12 запросов, 2 реплики, 1 сообщение, другой body → 409 evidence/grade-3-4.md
CPU/RAM-лимиты, API без host ports compose.yaml, docker compose ps API только expose, лимиты заданы compose.yaml
Rolling update под нагрузкой scripts/rolling-update.sh 2 + k6 20 VU/60 с 41 605 итераций, 0 failed checks, p95 55.27 мс evidence/k6-rolling-20vu-60s.json
Миграции однократно migrate service, API RUN_MIGRATIONS=false migrate завершился, API healthy compose.yaml, app/cmd/server/main.go

Проверки HTTP запускались из контейнера в сети стенда: в рабочей оболочке published ports были изолированы от хоста. Это ограничение среды, а не приложения; на обычной машине команды make test/make test-failover запускаются с хоста.

5. Эксперименты и отказы

5.1. Отказ одной API-реплики

Что сделано Ожидание Наблюдение Восстановление
Остановлена одна API-реплика при живой второй LB исключает её, подтверждённые данные и сессия целы 2 реплики до отказа; 120–121 успешная запись; 0–1 краткая ошибка 2.54–2.93 с до первой успешной записи
Вручную остановлена вторая реплика Трафик переходит на оставшуюся 1698 успешных записей, 1 ошибка; обе реплики наблюдались до отказа вторая реплика восстановлена через up

Ошибка на границе отказа ожидаема: клиент мог отправить запрос в момент, когда процесс уже остановлен, но HAProxy ещё не убрал backend. Повтор с тем же Idempotency-Key не создал дубль.

5.2. Rolling update под нагрузкой

scripts/rolling-update.sh 2 собирает образ и поочерёдно заменяет контейнеры: останавливает один, удаляет, создаёт replacement, ждёт health и только потом переходит к следующему. Во время этого k6 писал сообщения 20 VU в течение 60 с.

Метрика Значение
Всего запросов 41 608
Итераций 41 605
Ошибок проверок 0
p95 55.27 мс
p99 71.15 мс

Это подтверждает, что последовательная замена не рвёт поток целиком: HAProxy успевает исключить остановленный backend. Сырой summary: evidence/k6-rolling-20vu-60s.json.

6. Ограничения

  • Один Docker-host: потеря узла не переживается. HAProxy, PostgreSQL и Redis остаются единичными точками отказа; API-реплики не делают БД высокодоступной.
  • PostgreSQL не реплицирован. При потере pgdata данные теряются; Redis AOF спасает сессии от рестарта, но не от потери диска.
  • Compose — не Swarm: rolling-скрипт делает поочерёдную замену, но не даёт маршрутизации между узлами.
  • Профиль k6 — write-only. Он выбран намеренно: проверяется запись, идемпотентность и БД; чтение и смешанный профиль — отдельный эксперимент.
  • X-Instance-Id здесь — hostname контейнера, не скрыт.
  • Проверка пароля и ветка «пользователь не найден» имеют разное время выполнения: для неизвестного username Argon2 не запускается. Теоретически это позволяет перечислять имена по времени ответа. Контракт требует только одинаковый 401 и challenge; в lab3 временная атака не устраняется.