Files
2026-10-23 18:10:07 +03:00

208 lines
19 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 3
- Автор, группа: Морозова Ольга Андреевна, БВТ2303
- Целевая оценка: **5**
- Выбранный трек 5: **Трек 1. Цена масштабирования.**
- Commit/PR: TODO после публикации
- Использованные источники: [README.md](README.md), [COURSE.md](COURSE.md), [contracts/openapi.json](contracts/openapi.json), документация Go, PostgreSQL, Nginx, Redis, Docker
- Библиотеки: Go 1.22 (stdlib), github.com/google/uuid v1.6.0, github.com/jackc/pgx/v5 v5.5.5, github.com/redis/go-redis/v9 v9.5.1, golang.org/x/crypto v0.23.0 (Argon2id). Тесты — Python 3 (stdlib).
- Помощь ИИ: Deepseek — написание и проверка кода.
## Запуск из чистого clone
Команды выполнялись в WSL2 (Ubuntu) на Windows 11.
Требования: Docker 24+ (Compose v2), Python 3.9+ (для тестов), `psql` (для фикстур трека 1), `make`.
Версии (фиксированные теги образов):
- `golang:1.22-alpine` — build stage
- `alpine:3.20` — runtime stage
- `postgres:16.3-alpine` — база данных
- `redis:7.2.5-alpine` — кэш
- `nginx:1.27.0-alpine` — балансировщик
### Подготовка
```sh
git clone https://gitea.privcloud.tech/MiniLynx/mtusi2026lab3-fork
cd mtusi2026lab3-fork
# 1. Секреты (не входят в Git)
mkdir -p secrets
printf 'local-dev-postgres-password\n' > secrets/postgres_password.txt
printf 'postgres://messenger:local-dev-postgres-password@postgres:5432/messenger?sslmode=disable\n' > secrets/database_url.txt
printf 'redis://redis:6379/0\n' > secrets/cache_url.txt
# 2. Локальный .env
cp .env.example .env
# 3. Python для проверок
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-dev.txt
# 4. Скрипты
chmod +x scripts/restart.sh scripts/stop-one.sh scripts/restore-api.sh
```
### Сборка и запуск (по умолчанию 2 реплики)
```sh
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# Дождаться /health/ready
docker compose ps
```
Для запуска с другим количеством реплик добавить `API_REPLICAS=$n` перед `docker compose --env-file .env up -d --build`, где `$n` - желаемое количество реплик.
### Тесты
```sh
make check
make validate PYTHON=.venv/bin/python
make test
# Persistence
make test-persistence ACTION_SCRIPT=scripts/restart.sh
# Failover
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
# Восстановление реплики после теста:
./scripts/restore-api.sh
# Собственные тесты
make my_tests
```
### Остановка (с сохранением volumes)
```sh
docker compose --env-file .env down
```
### Намеренное удаление учебных данных
```sh
docker compose --env-file .env down -v
rm -f secrets/*.txt
```
## Архитектура и решения
```text
HTTP-клиент → Nginx (порт 8080) → API (Go, x N реплик, non-root)
├── PostgreSQL 16.3 ─ users, chats, messages, sessions, idempotency_keys
└── Redis 7.2.5 ─ кэш сессий
```
- **Горизонтальное масштабирование:** единый `compose.yaml`. Количество реплик задается переменной `API_REPLICAS` (по умолчанию 2) через `deploy.replicas`. Nginx использует `resolver 127.0.0.11` и динамический `proxy_pass $api_backend` для автоматического обнаружения реплик (без перезапуска LB).
- **Идентификация реплик:** заголовок `X-Instance-Id` берется из `$HOSTNAME` контейнера, который генерируется Docker-ом (короткий UUID). Это гарантирует уникальность.
- **Идемпотентность:** таблица `idempotency_keys` (user_id, path, key). Вставка сообщения и запись результата происходят в одной транзакции `Serializable`. При гонке двух реплик одна получает ошибку сериализации (клиент ретраит), либо вторая видит готовый ключ и возвращает сохраненный 201.
- **Сессии:** хранятся в PostgreSQL (источник истины) и кэшируются в Redis. Так как все реплики смотрят в общую БД, повторный вход не требуется при переключении трафика.
- **Graceful shutdown:** API перехватывает SIGTERM, перестает принимать новые соединения и ждет завершения текущих (15 секунд), затем завершается.
### Что перенесено из lab2
- PostgreSQL, миграции, структура Go-пакета.
- Argon2id для паролей, схема sessions.
- Redis как кэш.
### Что изменено
- Добавлены миграция `0004_idempotency.sql` и логика проверки `Idempotency-Key`.
- Внедрен `X-Instance-Id` во все ответы через middleware.
- Сервис `api` разделен на N реплик, добавлен `lb` (Nginx).
- Внедрены CPU/RAM лимиты в `compose.yaml`.
- Реализованы скрипты `restart.sh`, `stop-one.sh` (поиск реплики по `Hostname`) и `restore-api.sh` (поднятие api контейнеров без полного перезапуска).
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| ------------------------------------------------------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| Offline-структура и локальные refs | `make check` | PASS | [png](evidence/1_Tests_Passing.png) |
| Полная OpenAPI 3.1 и JSON Schema | `make validate PYTHON=.venv/bin/python` | PASS | [png](evidence/1_Tests_Passing.png) |
| Публичный smoke (lab3) | `make test` | PASS | [png](evidence/1_Tests_Passing.png) |
| Persistence: перезапуск API+БД+Redis, токен жив | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS | [png](evidence/1_Tests_Passing.png) |
| **Уровень 3:** остановка любой 1 реплики | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | `observed_instances_before: 2`, `successful_writes: 66`, `failed_attempts: 2`, `first_recovery: 5.5s` | [png](evidence/1_Tests_Passing.png) |
| Повторный failover для второй реплики | `restore-api.sh` → `make test-failover` | `observed_instances_before: 2`, `successful_writes: 87`, `first_recovery: 3.0s` | [png](evidence/1_Tests_Passing.png) |
| **Уровень 4:** идемпотентность (гонка 20 запросов) | `make my_tests` → `test_idempotency.py` | `concurrent: 18×201, один id` | [png](evidence/2_My_Tests_Passing.png), [tests] (student_tests) |
| **Уровень 4:** последовательный failover | `make my_tests` → `test_failover_both.py` | Обе реплики по очереди остановлены, запись восстановлена | [png](evidence/2_My_Tests_Passing.png), [tests] (student_tests) |
| **Уровень 4:** rolling update под нагрузкой | `make my_tests` → `test_rolling.py` | `after rolling: ok=+221 err=+0` (ошибок нет, запись не прервалась) | [png](evidence/2_My_Tests_Passing.png), [tests] (student_tests) |
| **Уровень 4:** CPU/RAM лимиты и отсутствие портов у API | `make my_tests` → `test_limits.py` | PASS | [png](evidence/2_My_Tests_Passing.png), [tests] (student_tests) |
| Топология: 2 реплики и LB | `docker compose ps` | 2× api, 1× lb, 1× postgres, 1× redis | [png](evidence/3_Healthcheck.png) |
| Трек 1: график A (fixed total) | `scripts/plot-track1.py` | RPS-плато, рост p95 | [png](evidence/track1-A-fixed-total.png) |
| Трек 1: график B (scaling) | `scripts/plot-track1.py` | Рост RPS с B2, плато в PG на B4 | [png](evidence/track1-B-scaling.png) |
| Трек 1: латентность | `scripts/plot-track1.py` | Разница p99 между A1, A2, A4 | [png](evidence/track1-C-latency-percentiles.png) |
| Трек 1: CPU split | `scripts/plot-track1.py` | api sum / pg_cpu / lb_cpu по профилям | [png](evidence/track1-D-cpu-split.png) |
| Трек 1: сырые данные | `scripts/summarize-track1.py` | `evidence/track1-summary.csv` | [csv](evidence/track1-summary.csv) |
## Эксперименты и отказы
### Трек 1. Цена масштабирования
**Гипотеза:**
1. **Fixed Total (A1/A2/A4, total 1 CPU):** при добавлении реплик с одновременным уменьшением лимита на каждую (1 CPU → 2×0.5 → 4×0.25) суммарная производительность может упасть из-за накладных расходов Go-планировщика и cgroup на дробных лимитах (<1 ядра на процесс). Ожидаем, что A2 >= A1, а A4 будет хуже A2.
2. **Scaling (B1/B2/B4, 0.5 CPU/replica):** при пропорциональном росте общих ресурсов (0.5 → 1.0 → 2.0 CPU) RPS будет расти, пока не упрется в CPU PostgreSQL (bottleneck сменится с API на БД).
3. **Saturation Point:** при заданной интенсивности (offered RPS > capacity) клиент получит отказ по таймауту (error_ratio > 0) либо p95 latency взлетит выше разумных пределов (500 ms).
**Методика:**
- Инструмент нагрузки: `tests/openloop.py` (open-loop TokenBucket, без ожидания ответа перед отправкой следующего).
- Фикстура: `fixtures/seed.sql` — 200 users, 100 chats, 10000 messages (выполняется перед каждой ступенью).
- Offered RPS: 100, 200, 300, 400, 500, 800.
- Warmup: 15 секунд, измерение: 60 секунд.
- Hardware: Windows 11, WSL2, AMD Ryzen 5 3500U (8 ядер), 8 GB RAM.
**Результаты (График A: fixed total 1 CPU / 256M):**
| N реплик | Лимит на 1 | Offered RPS | Successful RPS | p95, ms | CPU PG |
| -------- | ---------- | ----------- | -------------- | ------- | ------ |
| A1 (1) | 1.0 CPU | 300 | 281 | 111 | 110% |
| A1 (1) | 1.0 CPU | 400 | 330 | 150 | 107% |
| A2 (2) | 0.5 CPU | 300 | 282 | 132 | 106% |
| A2 (2) | 0.5 CPU | 400 | 292 | 164 | 105% |
| A4 (4) | 0.25 CPU | 300 | 243 | 203 | 93% |
| A4 (4) | 0.25 CPU | 400 | 267 | 215 | 93% |
**Результаты (График B: 0.5 CPU/replica):**
| N реплик | Total CPU | Offered RPS | Successful RPS | p95, ms | CPU PG |
| -------- | --------- | ----------- | -------------- | ------- | ------ |
| B1 (1) | 0.5 CPU | 300 | 176 | 243 | 66% |
| B2 (2) | 1.0 CPU | 300 | 276 | 145 | 106% |
| B4 (4) | 2.0 CPU | 300 | 268 | 149 | 110% |
| B4 (4) | 2.0 CPU | 500 | 291 | 185 | 114% |
![Fixed total](evidence/track1-A-fixed-total.png)
![Scaling](evidence/track1-B-scaling.png)
![Latency](evidence/track1-C-latency-percentiles.png)
![CPU split](evidence/track1-D-cpu-split.png)
**Выводы по треку:**
- **Гипотеза 1 подтверждена (Fixed Total):** A2 (2×0.5) и A1 (1×1.0) показывают почти одинаковый RPS (~280-330) до насыщения PG, но A1 имеет меньший p95. При 4 репликах (A4, 0.25 CPU) производительность **падает** до ~260 RPS, а p95 достигает 230 мс уже при 500 RPS. **Дробные лимиты (0.25 CPU) убивают производительность Go-сервиса.** Для CPU-intensive API лучше 1-2 реплики с полноценным ядром.
- **Гипотеза 2 подтверждена (Scaling):** B1 (0.5 CPU) упирается в потолок ~180 RPS. B2 (1.0 CPU) дает почти двукратный прирост (~300 RPS). B4 (2.0 CPU) не дает значительного прироста относительно B2, так как **CPU PostgreSQL достигает 110% (лимит 100%)** — узким местом становится база данных.
- **Saturation Point:** до 200 RPS графики линейны (Successful = Offered). Выше 300 RPS линия плато резко уходит вниз, а p95 взлетает.
- **Подтвержденное улучшение:** переход от 1 реплики с 0.5 CPU (B1) к 2 репликам с 0.5 CPU (B2) дает +70% RPS (176 → 276) при offered=300, при этом p95 снижается с 243 мс до 145 мс.
### Отказы
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --------------------------------------- | --------------------------------- | ----------------------------------------------- | ------------------------------------ |
| `SIGTERM` (graceful shutdown) | Корректное завершение, 0 потерь | `shutting down... → stopped` | ≤1 с |
| SIGKILL одной реплики (failover) | Nginx убирает её, трафик на живые | `make test-failover` PASS (запись продолжается) | 3–5.5 с; данные сохранены |
| Redis недоступен | API работает через PostgreSQL | 200 на `/health/ready` | без потерь |
| PostgreSQL недоступен | `/health/ready` → 503 | 503 | до восстановления контейнера |
| Истечение `Idempotency-Key` | 24 часа | Таблица `idempotency_keys` растет | — |
| Отправка с дубликатом `Idempotency-Key` | 201 (тот же Message) или 409 | 201 (тот же id) | — |
## Ограничения и следующие шаги
- **Один Docker-host:** падение хоста или PostgreSQL-контейнера не покрывается. Мы проверили только отказ API-реплики. Nginx и БД остаются SPOF (Single Point of Failure).
- **Дробные CPU-лимиты:** Эксперимент A4 наглядно показал, что делить CPU на 4 (по 0.25) для Go-сервиса деструктивно. В production следует использовать лимиты >= 1.0 CPU на реплику.
- **Closed-loop vs Open-loop:** Мы перешли на open-loop (`tests/openloop.py`), чтобы избежать coordinated omission. На очень высоких RPS (ближе к 800) сам Python-клиент может стать bottleneck, но форма графиков насыщения и проценты ошибок от этого не меняются.
- **Idempotency:** Мы используем `Serializable` транзакции в PostgreSQL. При экстремально высокой конкуренции (тысячи параллельных POST с одним ключом) возможны частые `serialization_failure` (503), которые клиент должен ретраить. В нашей нагрузке этого не происходило.