forked from mtusi2026/mtusi2026lab3
94 lines
10 KiB
Markdown
94 lines
10 KiB
Markdown
# Отчёт — лабораторная 3
|
||
|
||
- Автор, группа: Березин Герман / БВТ2304
|
||
- Целевая оценка: 4
|
||
- Commit/PR: после публикации
|
||
- Использованные источники, библиотеки и помощь ИИ: Go 1.26, pgx, go-redis, HAProxy 3.0, PostgreSQL 17, Valkey 8.1; код lab2 перенесён за основу; ИИ-ассистент использован при разработке
|
||
|
||
## Запуск из чистого clone
|
||
|
||
Требуются Docker 29 с Compose v2 и Python 3.9+.
|
||
|
||
```sh
|
||
sh scripts/mksecrets.sh
|
||
cp .env.example .env
|
||
docker compose --env-file .env up -d --build --wait
|
||
make test
|
||
```
|
||
|
||
Порядок старта: postgres и valkey → одноразовый сервис `migrate` → `api` (2 реплики) → `lb`. Публичный адрес: `http://localhost:8080`.
|
||
|
||
Остановка без потери данных: `docker compose --env-file .env stop`. Намеренное удаление данных: `docker compose --env-file .env down -v`.
|
||
|
||
Проверки:
|
||
|
||
```sh
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
python3 tests/idempotency.py
|
||
python3 tests/scenario.py --mode failover-each --output evidence/failover-each.json
|
||
python3 tests/scenario.py --mode rolling --output evidence/rolling.json
|
||
```
|
||
|
||
После `make test-failover` остановленная реплика восстанавливается вручную: `docker compose --env-file .env up -d --wait`.
|
||
|
||
## Архитектура и решения
|
||
|
||
Клиент → HAProxy (`lb`, единственный опубликованный порт, 127.0.0.1:8080) → `api` × 2 → PostgreSQL и Valkey.
|
||
|
||
- Источник истины — PostgreSQL: пользователи, чаты, сообщения, сессии, ключи идемпотентности. Valkey используется только как общий кэш сессий. Состояния в памяти API нет, sticky session не используется.
|
||
- `X-Instance-Id` — hostname контейнера (12 символов id), по нему `stop-one.sh` находит контейнер.
|
||
- Миграции вынесены из API в сервис `migrate` (`messenger migrate`), который выполняется один раз до запуска `api` (`service_completed_successfully`), под `pg_advisory_lock`. Миграция 0002 только добавляет таблицу `idempotency_keys`, поэтому совместима с работающей предыдущей версией.
|
||
- Идемпотентность: таблица `idempotency_keys` с первичным ключом (user_id, method, path, key). Вставка ключа и сообщения выполняется в одной транзакции; `insert ... on conflict do nothing` заставляет конкурентный запрос ждать коммита первого. При повторе сверяется SHA-256 текста: совпал — возвращается сохранённый ответ 201, не совпал — 409. Ключи старше `IDEMPOTENCY_TTL_SECONDS` (24 ч) заменяются при следующем использовании. Сессия и членство в чате проверяются заново при каждом повторе.
|
||
- Переменные `.env.example` соответствуют конфигурации: `APP_ENV`, `SESSION_TTL_SECONDS`, `IDEMPOTENCY_TTL_SECONDS`, `API_REPLICAS`.
|
||
|
||
### Проверки готовности, таймауты, остановка
|
||
|
||
| Параметр | Значение |
|
||
| --- | --- |
|
||
| Периодичность health-check HAProxy (`GET /health/ready`) | inter 1 s, fastinter/downinter 0.5/1 s |
|
||
| Порог отказа / восстановления | fall 2 / rise 2 |
|
||
| Максимальное время обнаружения отказа | около 2–3 s (fall 2 × inter 1 s + timeout) |
|
||
| Повтор при ошибке соединения | `retries 3`, `option redispatch`, `retry-on conn-failure empty-response` |
|
||
| Таймауты HAProxy | connect 1 s, server 15 s, client 20 s |
|
||
| Таймауты API | ReadHeader 5 s, Read 10 s, Write 15 s, Idle 30 s; запросы к БД 3 s |
|
||
| SIGTERM | `/health/ready` сразу отвечает 503, затем пауза `DRAIN_SECONDS=3`, затем `Shutdown` до 10 s; `stop_grace_period: 15s` |
|
||
| Обновление адресов backend | `server-template api 1-8` + резолвер Docker DNS (127.0.0.11), `hold valid 1s` |
|
||
|
||
Лимиты: api, valkey, migrate, lb — 0.5 CPU / 128 MiB; postgres — 1 CPU / 512 MiB. Порты API наружу не публикуются, `container_name` не задан, число реплик меняется `API_REPLICAS` или `--scale`.
|
||
|
||
## Доказательства критериев
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||
| --- | --- | --- | --- |
|
||
| Публичный smoke | `make test` | PASS | evidence/smoke.txt |
|
||
| Сохранность после restart | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS, прежний токен действителен; перезапускаются postgres, valkey, api, lb | evidence/persistence.txt |
|
||
| Отказ одной реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | PASS, 2 реплики до отказа, 0 ошибок, восстановление записи 3.4 s; повтор для второй реплики — тоже PASS | evidence/failover-1.txt, evidence/failover-2.txt |
|
||
| Идемпотентность, параллельно | `python3 tests/idempotency.py` | 32 параллельных запроса с одним ключом через 2 реплики → 1 сообщение; другой body → 409; без ключа → 400 | evidence/idempotency.txt |
|
||
| Последовательная остановка каждой реплики | `tests/scenario.py --mode failover-each` | RPS, ошибки и восстановление по каждой реплике | evidence/failover-each.json |
|
||
| Лимиты ресурсов | `docker stats` | api ≤ 128 MiB, postgres ≤ 512 MiB | evidence/limits.txt |
|
||
| Rolling update под нагрузкой | `scripts/rolling-update.sh` через `tests/scenario.py --mode rolling` | обе старые реплики заменены новыми, ответы старых прекратились | evidence/rolling.json |
|
||
| Миграции однократно | сервис `migrate` | запускается один раз, выход 0, API стартует после него | `docker compose logs migrate` |
|
||
|
||
## Эксперименты и отказы
|
||
|
||
Стенд: один хост, 8 клиентских потоков, closed-loop POST сообщений с уникальным ключом; при ошибке запрос повторяется с тем же ключом. Лимиты ресурсов как выше. Базовая нагрузка около 1000 успешных RPS.
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||
| --- | --- | --- | --- |
|
||
| `docker stop` реплики 1 (под нагрузкой) | единицы ошибок, затем работа на второй реплике | 0–3 неуспешные попытки за 15 s, последняя ошибка в первые 0.7 s; остановленная реплика после остановки не отвечает; RPS ≈ 970 | запись не прерывалась дольше 1 s; подтверждённые сообщения целы |
|
||
| то же для реплики 2 | то же | 0–3 ошибки, RPS ≈ 960 | то же; возврат реплики в ротацию около 6 s после старта |
|
||
| Rolling update (4 контейнера, замена старых) | почти без ошибок | 1–4 неуспешные попытки за ≈ 13.5 s, RPS ≈ 975 | старые реплики перестают отвечать; дубликатов нет (повтор с тем же ключом) |
|
||
| Restart postgres/valkey/api/lb | данные и сессия сохраняются | PASS persistence | прежний токен действителен |
|
||
|
||
Точные значения лежат в `evidence/*.json`; от запуска к запуску число ошибок плавает (0–4), поэтому приведены диапазоны.
|
||
|
||
## Ограничения и следующие шаги
|
||
|
||
- Выдерживается отказ одной API-реплики. HAProxy, PostgreSQL и Valkey — единые точки отказа, репликации БД нет и выживание её отказа не заявляется.
|
||
- Ошибки во время отказа возможны на запросах, уже принятых остановленной репликой; клиент повторяет их с тем же ключом.
|
||
- Нагрузочный генератор на Python (closed-loop) ограничен клиентом и подвержен coordinated omission; RPS — ориентир, а не предел системы.
|
||
- HAProxy выполняет только проверки готовности по HTTP и не знает о версии приложения; rolling update построен скриптом (scale ×2 → остановка старых → возврат к исходному числу), а не оркестратором.
|
||
- Миграции совместимы только вперёд-аддитивно (новые таблицы); несовместимые изменения схемы потребуют схемы expand/contract.
|
||
- Секреты лежат в `./secrets` вне Git и доступны на чтение всем локально, чтобы их читал процесс с UID 10001; это допустимо только для локального стенда.
|