forked from mtusi2026/mtusi2026lab3
130 lines
13 KiB
Markdown
130 lines
13 KiB
Markdown
# Отчёт — лабораторная 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-образ собирает бинарный файл самостоятельно.
|
||
|
||
```sh
|
||
./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 не публикуются.
|
||
|
||
Остальные проверки:
|
||
|
||
```sh
|
||
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
|
||
```
|
||
|
||
Безопасная остановка с сохранением данных:
|
||
|
||
```sh
|
||
docker compose --env-file .env down
|
||
```
|
||
|
||
Намеренное удаление всех учебных данных и сессий:
|
||
|
||
```sh
|
||
docker compose --env-file .env down -v
|
||
```
|
||
|
||
## Архитектура и решения
|
||
|
||
```mermaid
|
||
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 нельзя переносить на другой компьютер без повторения опыта с теми же ресурсами и набором данных.
|