13 KiB
Отчёт — лабораторная 3
- Автор, группа: Меркулова М.А., БВТ2303
- Целевая оценка: 4
- Ветка:
solution/BVT2303-Merkulova; commit/PR указываются после публикации - Реализация: Go 1.26, PostgreSQL 17.6, Redis 8.2.1, Nginx 1.29.1, Docker Compose
- Библиотеки приложения:
pgx/v5,go-redis/v9,x/crypto/scrypt - Помощь ИИ: использовалась для проектирования, написания и проверки кода; требования сверялись с файлами текущего skeleton, все приведённые результаты получены локальным запуском
Запуск из чистого clone
Нужны Docker с Compose, Python 3.9+ и make. Локальный Go нужен только для go test; Docker-образ собирает бинарный файл самостоятельно.
./scripts/init-local.sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait
docker compose --env-file .env ps
make check
make test
init-local.sh создаёт случайные пароли, URL подключения и .env в игнорируемых Git файлах. Единственная публичная точка — http://127.0.0.1:8080 на Nginx. Порты API-реплик, PostgreSQL и Redis на host не публикуются.
Остальные проверки:
go test ./...
go vet ./...
ACTION_SCRIPT=./scripts/restart.sh make test-persistence
ACTION_SCRIPT=./scripts/stop-one.sh make test-failover
./scripts/start-api.sh
python3 student-tests/verify_idempotency.py
python3 student-tests/failover_experiment.py
python3 student-tests/verify_unready_backend.py
python3 student-tests/rolling_update_experiment.py
python3 student-tests/verify_grade4.py
python3 student-tests/verify_expiry.py
python3 student-tests/verify_dependencies.py
./scripts/explain_history.sh
Безопасная остановка с сохранением данных:
docker compose --env-file .env down
Намеренное удаление всех учебных данных и сессий:
docker compose --env-file .env down -v
Архитектура и решения
flowchart LR
C[Клиент] -->|HTTP :8080| L[Nginx]
L --> A1[API api-1]
L --> A2[API api-2]
A1 --> P[(PostgreSQL)]
A2 --> P
A1 --> R[(Redis + AOF)]
A2 --> R
M[Одноразовый migrate] --> P
Обе API-реплики собраны из одного образа, не имеют локального бизнес-состояния и используют общие PostgreSQL и Redis. PostgreSQL хранит пользователей, чаты, сообщения и идемпотентность. Redis хранит общие Bearer-сессии как SHA-256(token) → user UUID с TTL и AOF. Поэтому запросы одной сессии обслуживаются обеими репликами без sticky sessions.
Nginx выполняет round-robin между готовыми репликами. В его контейнере health-aware.sh опрашивает /health/ready каждой API-реплики по frontend-сети с паузой 1 секунду между циклами и при изменении набора готовых реплик обновляет upstream и перезагружает конфигурацию Nginx. Если обе реплики неготовы, он оставляет обе в upstream: API может вернуть обычные JSON-ответы 401 и 503 вместо ошибки Nginx «no live upstreams». Пока обновление upstream ещё не произошло, Nginx повторяет идемпотентный GET на второй реплике при 503, сетевой ошибке или таймауте. Автоматический повтор POST после отправки запроса не включён; после обнаружения отказа POST идёт только на готовую реплику. Docker healthcheck API запускается каждые 3 секунды и используется для начального запуска и наблюдения. Connect timeout равен 500 ms, Docker DNS перечитывается с периодом 2 секунды. X-Instance-Id равен стабильным alias api-1 или api-2.
API обрабатывает SIGTERM через http.Server.Shutdown с бюджетом 8 секунд; Compose даёт 10 секунд до принудительной остановки. Таймауты HTTP: header 5 s, read/write 10 s, idle 30 s. SQL получает DB_TIMEOUT_MS=3000; каждая реплика имеет пул максимум из 10 соединений.
Миграции выполняет отдельный одноразовый сервис migrate до API. При rolling update тот же сервис запускается ещё раз до замены первой реплики; уже применённые версии он пропускает. Таблица schema_migrations и транзакция предотвращают повторное применение. Миграция 002 аддитивно добавляет таблицу идемпотентности, поэтому старая схема lab2 остаётся читаемой во время последовательной замены процессов.
Для POST /messages обязателен Idempotency-Key. Область уникальности — (user_id, method, path, key). В одной PostgreSQL-транзакции создаётся запись ключа, сообщение и ссылка на результат. Конкурентный повтор блокируется общим уникальным ключом и после commit получает исходное сообщение с 201. Тот же ключ с другим логическим JSON даёт 409. Ключ действует минимум IDEMPOTENCY_TTL_SECONDS=86400; при повторном использовании просроченная запись удаляется. Записи ключей, которые больше не используют, пока остаются в таблице.
Из lab2 сохранены PostgreSQL, Redis-сессии, scrypt-пароли, транзакционное создание чатов, cursor pagination, request ID, JSON-ошибки, health endpoints и graceful shutdown. Новые обязательные изменения lab3: Nginx, две реплики, X-Instance-Id, общий Idempotency-Key, отдельные миграции и отказ одной API-реплики.
Ресурсные границы и секреты
Compose реально применил следующие limits:
| Сервис | CPU | RAM |
|---|---|---|
api1, api2 |
по 0.50 | по 192 MiB |
nginx |
0.25 | 64 MiB |
postgres |
1.00 | 512 MiB |
redis |
0.25 | 128 MiB |
migrate |
0.25 | 128 MiB |
PostgreSQL и Redis находятся только во внутренней backend-сети. Nginx видит API по frontend-сети. API получает только URL PostgreSQL и Redis; Nginx не получает секреты, PostgreSQL не получает Redis-пароль. Секретные значения создаются локально в secrets/ и не входят в Git.
Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Доказательство |
|---|---|---|---|
| Публичный API | make test |
PASS lab3, включая X-Instance-Id и повтор сообщения |
evidence/lab3-results.md |
| Две реплики через LB | шесть GET /health/live |
api-2, api-1 по очереди |
evidence/lab3-results.md |
| Persistence | ACTION_SCRIPT=... make test-persistence |
прежний токен и сообщение доступны после restart всех процессов и хранилищ | evidence/lab3-results.md |
| Отказ любой реплики | официальный failover и последовательный эксперимент | остановлены реальные api1 и api2; подтверждённые сообщения сохранились |
evidence/lab3-results.md |
| Метрики двух отказов | failover_experiment.py |
642.783 и 569.984 successful RPS; 0 ошибок; 0.600/0.610 s до подтверждения survivor | evidence/failover-grade4.json |
| Неготовая реплика с работающим HTTP | verify_unready_backend.py |
после отключения backend-сети api1 и состояния unhealthy: 40 GET и 10 POST через LB обслужила api2 |
evidence/lab3-results.md |
| Общая идемпотентность | verify_idempotency.py |
12 параллельных запросов через обе реплики, один message ID; другой body — 409 | evidence/idempotency.json |
| Rolling update | rolling_update_experiment.py |
поочерёдно пересозданы обе реплики; 25 388 успехов, 0 ошибок | evidence/rolling-update.json |
| Отказ Redis/PostgreSQL | verify_dependencies.py |
осмысленные 503, после возврата сервисов состояние восстановлено | evidence/lab3-results.md |
| Индекс истории | explain_history.sh |
Index Scan using messages_chat_history_idx на 10 000 сообщений |
evidence/explain-history.txt |
| Возможности lab2 | verify_grade4.py, verify_expiry.py, go test ./... |
гонка username, rollback, logout, TTL и password KDF прошли | evidence/lab3-results.md |
Эксперименты и отказы
Стенд повторно проверен 16 октября 2026 года на Docker Desktop/macOS arm64. До измерений выполнены smoke и несколько запросов прогрева. Все данные синтетические. Failover использует один закрытый цикл HTTP-клиента 8 секунд на реплику. Rolling update использует четыре закрытых параллельных клиента; метрики задержки относятся только к успешным ответам и включают клиентские и LB расходы.
| Воздействие | Успехи / ошибки | Наблюдаемое переключение | Потеря подтверждённых данных |
|---|---|---|---|
Stop api-1 |
5143 / 0 за 8.001 s | 0.600 s | нет |
Stop api-2 |
4560 / 0 за 8.000 s | 0.610 s | нет |
Rolling replace api-1, затем api-2 |
25388 / 0 за 16.832 s | обе реплики наблюдались | нет |
Rolling update: 1508.329 successful RPS, p50 2.221 ms, p95 3.998 ms, p99 6.040 ms. Это локальное наблюдение, а не универсальная оценка производительности. Closed-loop профиль имеет coordinated omission и не моделирует фиксированный внешний arrival rate.
Ограничения и следующие шаги
Стенд выдерживает остановку одного API-процесса. Все компоненты работают на одном Docker-host, поэтому потеря host останавливает систему. Nginx, PostgreSQL и Redis представлены по одному и остаются single points of failure. Остановка PostgreSQL или Redis корректно даёт 503, но бизнес-функции временно недоступны.
Nginx исключает неготовую реплику по HTTP-проверке /health/ready; между отказом и очередной проверкой возможна краткая ошибка POST. Docker healthcheck отвечает за запуск и наблюдаемость. Rolling update проверяет последовательную замену процессов одной совместимой версией на одном host. Автоматического rollback образа, репликации БД, отдельного backup/restore и multi-host orchestration в lab3 нет.
Просроченная запись ключа удаляется при повторном использовании того же ключа. Для длительной эксплуатации нужна периодическая очистка остальных записей. Приведённые RPS и latency нельзя переносить на другой компьютер без повторения опыта с теми же ресурсами и набором данных.