437 lines
65 KiB
Markdown
437 lines
65 KiB
Markdown
# Отчёт — лабораторная 3
|
||
|
||
Балансировка и отказ API-реплики
|
||
|
||
- Автор, группа: Максимова Мария, БВТ2303
|
||
- Целевая оценка: 4
|
||
- Commit/PR: ветка `solution/maksimova_bvt2303`
|
||
- Использованные средства: Python 3.12.7 (в Docker), FastAPI, uvicorn, SQLAlchemy 2 (async) + asyncpg, argon2-cffi, redis-py (клиент Valkey) — всё из lab2; PostgreSQL 16.4, Valkey 8.0.1, HAProxy 3.0.11, Docker Desktop 29.3.0 + Compose v5.1.0.
|
||
- Источники: документация HAProxy 3.0 (resolvers, server-template, http-check, retry-on, http-error), Docker Compose (deploy.replicas, resources, depends_on conditions, secrets), uvicorn (Server, graceful shutdown), PostgreSQL (INSERT … ON CONFLICT, advisory locks).
|
||
- Помощь ИИ: Claude Code использовался для переноса lab2 под lab3 (идемпотентность, drain при SIGTERM, X-Instance-Id), конфигурации HAProxy, операторских скриптов, собственных тестов и черновика отчёта. Измерения выполнены на моём стенде 2026-10-13 (сырые результаты — в `evidence/`), все команды раздела 3 повторно проверены 2026-10-20.
|
||
|
||
## 1. Коротко и простыми словами
|
||
|
||
Раньше (lab2) был один процесс API. Если он падал — мессенджер не работал. В lab3 процессов API два, а перед ними стоит балансировщик HAProxy. Клиент всегда ходит на один адрес `localhost:8080`, а HAProxy по очереди отправляет запросы то в одну реплику, то в другую. Если одна реплика умирает, HAProxy это замечает и отправляет всё в живую.
|
||
|
||
Чтобы такое работало, API не должен ничего важного хранить «у себя в памяти». Всё хранится в общих местах:
|
||
|
||
- PostgreSQL — все данные, сессии (токены входа) и ключи идемпотентности;
|
||
- Valkey — только быстрый кэш сессий (если его потерять, ничего не сломается — данные возьмутся из PostgreSQL).
|
||
|
||
Поэтому неважно, какая реплика обработала запрос: обе видят одни и те же данные и один и тот же токен.
|
||
|
||
Вторая проблема — повторы. Клиент отправил сообщение, реплика упала, ответа нет. Сообщение сохранилось или нет? Клиент не знает и повторяет запрос. Чтобы повтор не создал дубль, клиент передаёт заголовок `Idempotency-Key` — уникальную строку на одно сообщение. Сервер запоминает ключ в PostgreSQL вместе с сообщением. Если пришёл тот же ключ ещё раз, сервер не создаёт новое сообщение, а возвращает уже сохранённое.
|
||
|
||
|
||
| Что | Результат |
|
||
|------------------------------------------------------------|-------------------------------------------------------------------|
|
||
| Публичные тесты `make check`, `make validate`, `make test` | PASS |
|
||
| Запросы одного пользователя обслуживают разные реплики | да, `X-Instance-Id` чередуется, повторный вход не нужен |
|
||
| Остановка каждой реплики (`make test-failover`) | PASS для обеих, 0 ошибок, запись снова работает через 4.3–4.5 s |
|
||
| Перезапуск всего стенда (`make test-persistence`) | PASS, данные и прежний токен сохранились |
|
||
| 16 одновременных POST с одним ключом, 10 раз | каждый раз ровно 1 сообщение, запросы шли через обе реплики |
|
||
| Остановка/убийство реплик под нагрузкой (4 прогона) | 1 ошибка на ~11 600 запросов (при SIGKILL), потерь и дублей 0 |
|
||
| Rolling update (замена обеих реплик новой версией) | 70 s под нагрузкой, 0 ошибок, 4 826 записей, потерь и дублей 0 |
|
||
|
||
### 1.1 О чём лаба?
|
||
|
||
В прошлой лабе у меня был один сервер API. Если он падал — падал весь мессенджер.
|
||
В этой лабе я запустила два одинаковых сервера API (реплики), а перед ними поставила балансировщик HAProxy.
|
||
Пользователь всегда отправляет запросы на один адрес. HAProxy по очереди отдаёт их то первой реплике, то второй.
|
||
Если одна реплика ломается, HAProxy это замечает и отправляет всё на вторую — пользователь ничего не замечает.
|
||
Чтобы это работало, реплики ничего не хранят у себя: все данные, сессии и ключи лежат в общей базе PostgreSQL. Поэтому неважно, какая реплика ответила.
|
||
|
||
Какая реплика ответила — видно по заголовку `X-Instance-Id` (это имя контейнера).
|
||
|
||
Схема: Клиент → HAProxy (:8080) → api × 2 → PostgreSQL + Valkey.
|
||
|
||
### 1.2 Как сделана отказоустойчивость?
|
||
|
||
1. Балансировка round-robin. В конфиге HAProxy `balance roundrobin` — запросы раздаются по кругу: 1-й на первую реплику, 2-й на вторую, 3-й снова на первую. Это встроенный алгоритм HAProxy. Sticky session (привязки клиента к одной реплике) нет — она не нужна, потому что всё состояние общее.
|
||
2. Проверка здоровья (health check). HAProxy каждую секунду сам спрашивает у каждой реплики `/health/ready` — «ты готова?». 2 неудачи подряд — реплика считается мёртвой, запросы ей больше не идут. 2 успеха подряд — возвращается обратно. В конфиге это `inter 1s fall 2 rise 2`.
|
||
3. Повтор на другую реплику. Если запрос не дошёл до реплики (она упала), HAProxy сам повторяет его на другой реплике (`retries 2`, `option redispatch`, `retry-on`). Пользователь ошибки не видит. Повтор уже отправленного запроса разрешён только для GET и для отправки сообщения с `Idempotency-Key` — чтобы не создать дубль.
|
||
4. Реплики находятся сами через DNS Docker. IP-адреса не прописаны вручную. HAProxy спрашивает у DNS Docker «какие адреса у сервиса `api`?» и получает адреса всех живых реплик (`server-template api 8 api:8080` + `resolvers docker`). Новая реплика попадает в пул сама.
|
||
5. Мягкое выключение (graceful shutdown). При остановке реплика не выключается сразу: 3 секунды продолжает работать, но на проверку здоровья отвечает «я не готова» (503). За это время HAProxy убирает её из пула, и только потом она закрывается. Поэтому при остановке реплики у пользователей 0 ошибок.
|
||
|
||
Итог с цифрами: остановка каждой реплики под нагрузкой — 0 ошибок; жёсткое убийство (`kill -9`) — 1 ошибка на ~11 600 запросов; сообщения не потерялись и не задвоились.
|
||
|
||
Время обнаружения отказа: упавшая реплика — на первом же запросе (или ≤ 2 s по проверкам); «жива, но не готова» — ≤ 3 s; зависла — ≈ 4 s.
|
||
|
||
### 1.3 Почему HAProxy, а не nginx? Какие альтернативы?
|
||
|
||
Я выбрала HAProxy, потому что это специализированный балансировщик, и бесплатно в нём есть:
|
||
1. Активная проверка здоровья — он сам опрашивает реплики. В бесплатном nginx такой проверки нет (только в платном NGINX Plus), есть только пассивная — по ошибкам реальных запросов.
|
||
2. Сам находит новые реплики через DNS Docker. Бесплатный nginx узнаёт адреса один раз при запуске и после пересоздания контейнера продолжает слать запросы на старый адрес.
|
||
3. Гибкая настройка повторов (какие запросы можно повторять, какие нельзя).
|
||
4. Страница статистики `/stats` — видно, какая реплика живая (UP), а какая нет (DOWN).
|
||
|
||
Альтернативы:
|
||
|
||
| Что | Что это |
|
||
|---------------------------|---------------------------------------------------------------------------------|
|
||
| Nginx | веб-сервер, который тоже умеет балансировать (round-robin, least_conn, ip_hash) |
|
||
| Traefik | сам находит контейнеры в Docker/Kubernetes по меткам |
|
||
| Envoy | мощный современный прокси, на нём работает Istio |
|
||
| Caddy | простой конфиг, сам делает HTTPS |
|
||
| Docker Swarm / Kubernetes | встроенная балансировка оркестратора |
|
||
| Облачные | AWS ALB/NLB, Yandex Application Load Balancer |
|
||
|
||
Другие алгоритмы балансировки: `leastconn` (на сервер с наименьшим числом соединений), `source` (по IP клиента — фактически sticky), `random`, веса `weight`.
|
||
|
||
### 1.4 Что такое Idempotency-Key?
|
||
|
||
Пользователь отправил сообщение, реплика упала, ответа нет. Он не знает, сохранилось ли сообщение, и отправляет ещё раз. Без защиты будет два одинаковых сообщения.
|
||
Поэтому клиент шлёт заголовок `Idempotency-Key` — уникальную строку на каждое сообщение.
|
||
Сервер сохраняет ключ в базе вместе с сообщением, в одной транзакции.
|
||
Пришёл тот же ключ ещё раз — сервер не создаёт новое, а возвращает старое сообщение (заголовок `Idempotent-Replayed: true`).
|
||
Тот же ключ, но другой текст — ошибка 409.
|
||
Ключ хранится в общей базе, поэтому защита работает, даже если повтор пришёл на другую реплику. Если два одинаковых запроса пришли одновременно на разные реплики, второй ждёт в PostgreSQL (на уникальном ключе), пока первый закончит.
|
||
Проверено: 16 одновременных запросов с одним ключом — каждый раз ровно 1 сообщение.
|
||
|
||
### 1.5 Вопросы-ответы
|
||
|
||
Чем отказ процесса отличается от отказа узла?
|
||
Процесс — одна программа (у меня один контейнер API). Упал — вторая реплика работает.
|
||
Узел — целый компьютер: выключился — выключилось всё. У меня всё на одном компьютере, поэтому отказ узла стенд не переживёт (для этого нужны несколько машин и копия базы).
|
||
|
||
Почему `depends_on` и healthcheck — не балансировщик?
|
||
`depends_on` задаёт только порядок запуска (сначала база, потом API). Healthcheck только ставит метку healthy/unhealthy. Ни то, ни другое не принимает запросы, не распределяет их и не переключает на живую реплику. Это делает только балансировщик.
|
||
|
||
Какие POST можно повторять после timeout?
|
||
Только те, повтор которых не создаст дубль: у меня это отправка сообщения с `Idempotency-Key`. Создание пользователя, чата, входа — повторять нельзя, создастся второй объект. (Если запрос даже не дошёл до сервера — ошибка соединения, — повторять можно любой.)
|
||
|
||
Что сломается, если сессии хранить в памяти реплики?
|
||
Вошёл через первую реплику — сессия есть только у неё. Следующий запрос уйдёт на вторую — она пользователя не знает → 401, «выкинет». Выход на одной реплике не сработает на другой. При перезапуске реплики все её сессии пропадут. Поэтому сессии у меня в общей базе.
|
||
|
||
- Миграции — выполняет отдельный контейнер `migrate` один раз перед запуском API, чтобы реплики не делали это одновременно.
|
||
- Почему у `api` нет `ports` — чтобы к репликам нельзя было обратиться в обход балансировщика.
|
||
- Почему нет `container_name` — имя контейнера должно быть уникальным, с ним нельзя запустить 2 копии.
|
||
- Rolling update — по очереди заменяю старые реплики новыми: запускаю новую, жду, пока она здорова, потом останавливаю старую. Получилось 0 ошибок.
|
||
- `docker stop` и `docker kill` — `stop` шлёт SIGTERM, и приложение успевает аккуратно закрыться; `kill -9` (SIGKILL) убивает мгновенно, начатые запросы обрываются.
|
||
- Почему был важен Dockerfile — в lab2 был `CMD ["sh","-c","uvicorn …"]`: главным процессом был `sh`, он не передавал SIGTERM, и мягкое выключение не работало. Стало `CMD ["python","-m","app.server"]`.
|
||
- Слабые места (SPOF) — балансировщик один, база одна, компьютер один. Как исправить: два HAProxy + keepalived (общий IP), репликация PostgreSQL (Patroni), несколько узлов.
|
||
- Почему `X-Instance-Id` — не доказательство — заголовок пишет само приложение; поэтому после остановки показываю `docker ps -a`: у нужного контейнера статус `Exited`.
|
||
|
||
### 1.6 Защита
|
||
|
||
1. Поднять стенд, `docker compose ps` — 2 контейнера `api`.
|
||
2. Показать, что `X-Instance-Id` чередуется (раздел 3.4).
|
||
3. `make test-failover` → `docker ps -a` (остановлен реальный контейнер) → `start-api.sh` → то же для второй реплики.
|
||
4. `make test-persistence`.
|
||
5. Для «4»: тест идемпотентности, серия отказов, страница `http://127.0.0.1:8404/stats`, результаты rolling update.
|
||
|
||
## 2. Что сделано
|
||
|
||
Из lab2 перенесены `app/`, миграции 001–002, `scripts/migrate.py`, `scripts/init-secrets.sh`, `requirements.txt`. Новое в lab3:
|
||
|
||
1. HAProxy (`infra/haproxy/haproxy.cfg`) — единственная публичная точка входа `:8080`. Сервис Compose `api` запускается в 2 экземплярах (`deploy.replicas: 2`), у него нет `ports` и нет `container_name`.
|
||
2. HAProxy сам находит реплики через встроенный DNS Docker: имя `api` возвращает IP всех работающих контейнеров сервиса (`server-template api 8 api:8080 … resolvers docker`). Каждую секунду HAProxy проверяет у каждой реплики `/health/ready`. Балансировка — обычный round-robin, без sticky session.
|
||
3. В процессе API нет локального состояния: всё в PostgreSQL и общем Valkey.
|
||
4. Каждый ответ API содержит заголовок `X-Instance-Id` = hostname контейнера (короткий Docker ID). По нему видно, какая реплика ответила.
|
||
5. `POST /chats/{id}/messages` требует `Idempotency-Key` (миграция `003_idempotency_keys.sql`, код — `app/repositories.py: create_message_idempotent`).
|
||
6. Graceful shutdown (`app/server.py`): получив SIGTERM, реплика 3 s продолжает работать, но отвечает `503` на `/health/ready`. За это время HAProxy выводит её из пула, и только потом она закрывает порт и дорабатывает начатые запросы.
|
||
7. Миграции выполняет отдельный одноразовый сервис `migrate` до старта API, а не каждая реплика сама. `pg_advisory_lock` защищает от двух одновременных запусков.
|
||
8. Операторские скрипты: `stop-one.sh` (остановить одну реплику), `kill-one.sh` (убить SIGKILL), `start-api.sh` (вернуть), `restart.sh` (перезапуск всего стенда), `rolling-update.sh` (поочерёдная замена реплик).
|
||
9. Argon2 (хеширование пароля, ~0.5–1 s CPU) выполняется в отдельном потоке (`asyncio.to_thread`), чтобы регистрация/вход не блокировали event loop и `/health/ready` реплики продолжал отвечать.
|
||
|
||
Исправления в коде lab2, найденные при переносе:
|
||
|
||
- `Dockerfile`: было `CMD ["sh","-c","uvicorn …"]`, стало `CMD ["python","-m","app.server"]`. При `sh -c` процессом №1 в контейнере был `sh`: он не передавал SIGTERM в uvicorn, и `docker stop` убивал процесс без graceful shutdown (проверено через `docker top`).
|
||
- `CreateChat.title`: максимум 255 → 100 символов, как в контракте.
|
||
- `init-secrets.sh`: файлы секретов 0644 внутри каталога 0700. На Linux пользователь контейнера `appuser` не мог прочитать файл 0600, смонтированный как secret.
|
||
- `migrate.py`: повтор подключения к БД и `pg_advisory_lock`.
|
||
|
||
Исправления по замечаниям ревью:
|
||
|
||
- `POST /auth/sessions` принимает только `Authorization: Basic` без тела (`contracts/README.md`). Раньше тело игнорировалось: `{bad` или `{}` с действительным Basic давали `201`. Теперь любое непустое тело → `400 invalid_request` до проверки пароля (`app/main.py`, `login`). Без тела (в т.ч. с `Content-Type: application/json`) — по-прежнему `201`.
|
||
- `CreateChat.member_ids`: добавлен максимум 100 элементов, как `maxItems: 100` в `contracts/openapi.json` (`app/models.py`). 101 участник → `400 invalid_request`, ровно 100 → `201`.
|
||
- Проверка обоих сценариев: `docker compose --profile tools run --rm tester python3 student-tests/contract_edge_cases.py` (6 проверок, `PASS: тело при входе и лимит участников соответствуют контракту`).
|
||
- Проверено 2026-10-20 на пересобранном стенде: оба сценария ревью, `make check`/`validate`/`test` — PASS, `make test-failover` — PASS (`failed_attempts: 0`), идемпотентность — PASS.
|
||
|
||
## 3. Все команды
|
||
|
||
Все образы закреплены версиями:
|
||
|
||
| Роль | Service | Образ | Health/readiness | Volume | Сеть / порт | Секреты |
|
||
|------------|----------------------------|--------------------------------------------------------------------------------------------|-----------------------------------------------|-----------------|------------------------------------------------------------|------------------------------------|
|
||
| LB | `lb` | `haproxy:3.0.11-alpine` | `wget /lb-health` (:8404) | — | `edge`; `LB_PORT` (8080) публично, 8404 только `127.0.0.1` | нет |
|
||
| API ×2 | `api` | `messenger-lab3-api:<APP_VERSION>` (сборка из `Dockerfile`, база `python:3.12.7-slim`) | `GET /health/ready` (БД доступна и нет drain) | — | `edge` + `backend`, порт не публикуется | `database_url`, `cache_url` |
|
||
| Миграции | `migrate` | тот же образ | завершается с кодом 0 | — | `backend` | `database_url` |
|
||
| БД | `db` | `postgres:16.4-alpine` | `pg_isready` | `postgres_data` | `backend` (internal) | `postgres_password` |
|
||
| Кэш сессий | `valkey` | `valkey/valkey:8.0.1-alpine` | `valkey-cli ping` | нет (это кэш) | `backend` (internal) | `valkey_password` |
|
||
| Проверки | `tester` (profile `tools`) | сборка `student-tests/Dockerfile.tester` (`python:3.12.11-alpine3.22` + docker CLI 28.5.1) | — | — | `edge` | docker.sock (только учебный стенд) |
|
||
|
||
Сеть `backend` — `internal: true`: у PostgreSQL и Valkey нет выхода наружу, и HAProxy к ней не подключён. Наружу опубликован только порт балансировщика.
|
||
|
||
Команды ниже — для Windows PowerShell (мой стенд). Отличия для Linux/macOS — в разделе 3.8.
|
||
|
||
### 3.1 Что нужно установить
|
||
|
||
- Docker Desktop (Compose v2);
|
||
- Git for Windows — даёт команду `sh` для скриптов `*.sh`;
|
||
- make: `winget install ezwinports.make`;
|
||
- Python 3.11 или 3.12 (на 3.14 не ставятся закреплённые `pydantic-core`/`asyncpg` — для них нет готовых wheel).
|
||
|
||
### 3.2 Первый запуск из чистого clone
|
||
|
||
```powershell
|
||
git clone https://gitea.privcloud.tech/Mariia_Maksimova/mtusi2026lab3.git
|
||
cd mtusi2026lab3
|
||
git checkout solution/maksimova_bvt2303
|
||
|
||
# Секреты: создаются один раз в infra/secrets/, в Git не попадают, значения не печатаются
|
||
sh scripts/init-secrets.sh
|
||
|
||
# Параметры стенда (секретов не содержит)
|
||
Copy-Item .env.example .env
|
||
# Если порт 8080 занят (у меня его держит служба Windows AgentService.exe) —
|
||
# в .env поставить LB_PORT=8081
|
||
|
||
# Проверка конфигурации, сборка, миграции (сервис migrate) и запуск;
|
||
# --wait ждёт, пока все сервисы станут healthy
|
||
docker compose --env-file .env config --quiet
|
||
docker compose --env-file .env up -d --build --wait
|
||
docker compose ps
|
||
```
|
||
|
||
В `docker compose ps` должно быть: `api` ×2, `db`, `valkey`, `lb` — `healthy`; `migrate` — `Exited (0)`.
|
||
|
||
### 3.3 Настройка окна PowerShell для проверок
|
||
|
||
```powershell
|
||
# Один раз: виртуальное окружение (нужно для make validate; make check/test используют только stdlib)
|
||
py -3.11 -m venv .venv
|
||
.venv/Scripts/python.exe -m pip install -r requirements-dev.txt
|
||
|
||
# В КАЖДОМ новом окне PowerShell — до любых make (без этого будет "Error 9009")
|
||
$env:PYTHONUTF8 = "1" # иначе Python читает openapi.json в cp1251 -> UnicodeDecodeError
|
||
$env:PYTHON = ".venv/Scripts/python.exe" # в Windows нет python3, который Makefile вызывает по умолчанию
|
||
$env:BASE_URL = "http://localhost:8080" # или http://localhost:8081, если в .env LB_PORT=8081
|
||
```
|
||
|
||
Makefile берёт `PYTHON` и `BASE_URL` из окружения (`PYTHON ?= python3`, `BASE_URL ?= http://localhost:8080`), поэтому после этих трёх строк `make check`/`validate`/`test` запускаются без дополнительных параметров. На контейнер `tester` эти переменные не влияют: у него свои `BASE_URL=http://lb:8080` и `python3`.
|
||
|
||
### 3.4 Проверки уровня 3
|
||
|
||
```powershell
|
||
# Публичные проверки с хоста
|
||
make check
|
||
make validate
|
||
make test
|
||
|
||
# Разные реплики через один LB: X-Instance-Id чередуется
|
||
1..4 | ForEach-Object { curl.exe -s -D - -o NUL "$env:BASE_URL/health/live" | findstr /i "x-instance-id" }
|
||
|
||
# Отказ реплики №1: тест сам выбирает реплику и вызывает scripts/stop-one.sh
|
||
docker compose --profile tools run --rm tester make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
|
||
# Доказательство: какой контейнер реально остановлен (Exited (0))
|
||
docker ps -a --filter "label=com.docker.compose.project=messenger-lab3" --filter "label=com.docker.compose.service=api" --format "table {{.Names}}\t{{.ID}}\t{{.Status}}"
|
||
|
||
# Вернуть остановленную реплику
|
||
docker compose --profile tools run --rm tester sh scripts/start-api.sh
|
||
|
||
# Отказ реплики №2: один лишний запрос сдвигает round-robin, тест выберет другую реплику
|
||
curl.exe -s -o NUL "$env:BASE_URL/health/live"
|
||
docker compose --profile tools run --rm tester make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||
docker ps -a --filter "label=com.docker.compose.project=messenger-lab3" --filter "label=com.docker.compose.service=api" --format "table {{.Names}}\t{{.ID}}\t{{.Status}}"
|
||
docker compose --profile tools run --rm tester sh scripts/start-api.sh
|
||
|
||
# Перезапуск всего стенда с сохранением volume и прежнего токена
|
||
docker compose --profile tools run --rm tester make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||
```
|
||
|
||
Почему failover/persistence запускаются в контейнере `tester`: публичный тест вызывает `.sh`-скрипт через `subprocess.Popen`, а Windows не умеет исполнять `.sh` напрямую. В `tester` есть Python, make и docker CLI, а `BASE_URL = http://lb:8080` — тот же балансировщик, только изнутри Docker-сети (поэтому `LB_PORT` хоста здесь не важен). Сами тесты не менялись.
|
||
|
||
### 3.5 Проверки уровня 4
|
||
|
||
```powershell
|
||
# Идемпотентность: 10 раундов × 16 одновременных POST с одним ключом -> ровно 1 сообщение
|
||
docker compose --profile tools run --rm tester python3 student-tests/idempotency_concurrency.py --output evidence/idempotency-concurrency.json
|
||
|
||
# Серия отказов под нагрузкой: stop и kill каждой реплики по очереди, с восстановлением
|
||
# (результаты: evidence/failover-stop-*.json, evidence/failover-kill-*.json)
|
||
docker compose --profile tools run --rm tester sh student-tests/run-failover-series.sh
|
||
|
||
# Жёсткий отказ одной реплики вручную (ID взять из docker ps), потом вернуть
|
||
docker compose --profile tools run --rm -e TARGET_INSTANCE_ID=<12 символов ID> tester sh scripts/kill-one.sh
|
||
docker compose --profile tools run --rm tester sh scripts/start-api.sh
|
||
|
||
|
||
# Нагрузка (справочно) и потребление ресурсов
|
||
docker compose --profile tools run --rm tester make load
|
||
docker stats --no-stream
|
||
```
|
||
|
||
Rolling update под нагрузкой — два окна PowerShell:
|
||
|
||
```powershell
|
||
# Окно 1: нагрузка 70 s
|
||
docker compose --profile tools run --rm tester python3 student-tests/failover_load.py --duration 70 --label rolling-update --output evidence/rolling-update-load.json
|
||
|
||
# Окно 2 (сразу после старта нагрузки): сборка новой версии, миграции один раз, поочерёдная замена реплик
|
||
$env:APP_VERSION = "v3"
|
||
sh scripts/rolling-update.sh
|
||
```
|
||
|
||
После rolling update реплики работают на образе `messenger-lab3-api:v3`. Все дальнейшие `docker compose up` нужно выполнять с тем же `APP_VERSION` (`$env:APP_VERSION = "v3"` или строка `APP_VERSION=v3` в `.env`), иначе Compose пересоздаст реплики на образе `dev`.
|
||
|
||
### 3.6 Наблюдение и логи
|
||
|
||
```powershell
|
||
# Состояние реплик в LB (UP/DOWN, счётчики ошибок и повторов) — открыть в браузере:
|
||
# http://127.0.0.1:8404/stats
|
||
docker compose logs lb --tail 30 # строки "Server api/apiN is DOWN/UP"
|
||
docker compose logs api --tail 30 # "draining for 3.0 s", "drain finished: closing listener"
|
||
docker compose ps
|
||
```
|
||
|
||
### 3.7 Остановка стенда
|
||
|
||
```powershell
|
||
docker compose down # безопасно: данные остаются в volume postgres_data
|
||
docker compose down -v # ОСТОРОЖНО: удаляет volume с базой
|
||
```
|
||
|
||
### 3.8 Linux/macOS
|
||
|
||
Всё то же, но: `cp .env.example .env`; `python3 -m venv .venv && .venv/bin/python -m pip install -r requirements-dev.txt`; `export PYTHON=.venv/bin/python` (или по умолчанию `python3`); `PYTHONUTF8` не нужен; `curl -s -D - -o /dev/null "$BASE_URL/health/live" | grep -i x-instance-id`. Failover/persistence можно запускать прямо с хоста: `make test-failover ACTION_SCRIPT=scripts/stop-one.sh`, `make test-persistence ACTION_SCRIPT=scripts/restart.sh`. Rolling update: `APP_VERSION=v3 sh scripts/rolling-update.sh`.
|
||
|
||
### 3.9 Частые ошибки
|
||
|
||
| Ошибка | Причина | Что сделать |
|
||
|-----------------------------------------------------------------------------------|----------------------------------------------------------------|------------------------------------------------------------------------------------|
|
||
| `Python make: *** [Makefile:13: check] Error 9009` (то же для `validate`, `test`) | в Windows нет команды `python3`; не задан `$env:PYTHON` | `$env:PYTHON = ".venv/Scripts/python.exe"` (раздел 3.3) |
|
||
| `UnicodeDecodeError: 'charmap' codec …` | Python на Windows читает файлы в cp1251 | `$env:PYTHONUTF8 = "1"` |
|
||
| `FAIL: GET /health/live: connection/TLS failure (TimeoutError)` | тест идёт на 8080, а LB на другом порту (или стенд не запущен) | `$env:BASE_URL = "http://localhost:8081"` (порт из `LB_PORT`); `docker compose ps` |
|
||
| `Failed building wheel for pydantic-core` / `asyncpg` | venv на Python 3.14 | пересоздать: `@py -3.11 -m venv .venv` |
|
||
| `secret ... file not found` при `up` | не созданы секреты | `sh scripts/init-secrets.sh` |
|
||
| failover-тест на Windows с хоста не запускает `.sh` | Windows не исполняет `.sh` | запускать через `tester` (раздел 3.4) |
|
||
|
||
Переменные `.env.example` → реальная конфигурация:
|
||
|
||
| `.env.example` | Где используется |
|
||
|---------------------------|------------------------------------------------------------------|
|
||
| `LB_PORT` | публичный порт HAProxy на хосте (по умолчанию 8080) |
|
||
| `APP_VERSION` | тег образа `api`/`migrate` (по умолчанию `dev`) |
|
||
| `API_REPLICAS` | `deploy.replicas` сервиса `api` (по умолчанию 2) |
|
||
| `SESSION_TTL_SECONDS` | `api` (по умолчанию 3600) |
|
||
| `IDEMPOTENCY_TTL_SECONDS` | `api` (86400 = 24 ч) |
|
||
| `APP_HOST`, `APP_PORT` | заданы в `compose.yaml` (0.0.0.0:8080 внутри контейнера) |
|
||
| `DATABASE_URL_FILE` | `/run/secrets/database_url` у `api` и `migrate` |
|
||
| `SESSION_STORE` | `valkey`: сессии в PostgreSQL, cache-aside в Valkey (как в lab2) |
|
||
| `CACHE_URL_FILE` | `/run/secrets/cache_url` у `api` |
|
||
| `APP_ENV` | не используется приложением |
|
||
|
||
## 4. Архитектура и решения
|
||
|
||
```
|
||
client ──HTTP:8080──► HAProxy (lb) ──round-robin, проверка /health/ready раз в 1 s──► api-1 ─┐
|
||
│ DNS Docker 127.0.0.11: имя "api" → IP всех реплик api-2 ─┤
|
||
└─ X-Request-Id, повтор на другую реплику при отказе ... │
|
||
▼
|
||
сеть backend (internal): PostgreSQL (источник истины)
|
||
Valkey (кэш сессий)
|
||
```
|
||
|
||
Источник истины — PostgreSQL: пользователи, чаты, участники, сообщения, сессии (хеш токена), ключи идемпотентности. Valkey хранит только копию «хеш токена → пользователь» с TTL ≤ 60 s. Logout на одной реплике пишет в общий Valkey отметку `revoked` (tombstone), её сразу видят все реплики. Поэтому повторный вход при смене реплики не нужен: в failover-тесте 40 запросов `/users/me` одним токеном обслужили 2 разные реплики.
|
||
|
||
Как работает идемпотентность. Таблица `idempotency_keys`: первичный ключ `(user_id, chat_id, method, key)`, `request_hash` = SHA-256 тела запроса, `message_id`. Всё делается в одной транзакции:
|
||
|
||
1. `INSERT … ON CONFLICT DO UPDATE … WHERE created_at < now() - TTL RETURNING 1` — «занять» ключ. Если тот же ключ в этот момент занимает незавершённая транзакция на другой реплике, PostgreSQL заставляет вторую транзакцию ждать на уникальном индексе. Так одновременные повторы выстраиваются в очередь в самой БД, без блокировок в памяти API.
|
||
2. Ключ занят нами → `INSERT` сообщения, `UPDATE` ключа ссылкой на сообщение, `COMMIT`. Если что-то упало до COMMIT, откатываются обе записи: ни сообщения, ни ключа нет, и повтор выполнится заново.
|
||
3. Ключ уже был сохранён раньше → если хеш тела совпадает, возвращается `201` с тем же сообщением и заголовком `Idempotent-Replayed: true`; если тело другое — `409`. Ключ старше 24 ч можно использовать заново.
|
||
|
||
До всего этого повтор проходит проверку токена и членства в чате (посторонний получит `404`). Область действия ключа: пользователь + метод + чат + ключ — тот же ключ у другого пользователя или в другом чате создаёт новое сообщение (проверено тестом).
|
||
|
||
Миграции. Сервис `migrate` стартует после того, как БД стала healthy, а API — только после того, как `migrate` успешно завершился (`depends_on: service_completed_successfully`). Повторный запуск печатает `SKIP`. Миграция 003 только добавляет таблицу, поэтому её можно применить, пока работает старая версия API. Правило на будущее: удалять/переименовывать колонки — отдельным релизом, когда ни одна реплика их уже не использует (expand → deploy → contract). Автоматической проверки совместимости нет — это ограничение.
|
||
|
||
Транзакционные границы: создание чата с участниками — одна транзакция (из lab2); сообщение + ключ идемпотентности — одна транзакция; отзыв сессии — UPDATE в PostgreSQL, затем tombstone в Valkey.
|
||
|
||
## 5. Health, timeouts и обнаружение отказа (уровень 4)
|
||
|
||
| Параметр | Значение | Где |
|
||
|------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------|
|
||
| `/health/live` | 200, только «процесс жив» | `app/main.py` |
|
||
| `/health/ready` | 200, если `SELECT 1` в PostgreSQL успешен и нет drain; иначе 503. Valkey не критичен: без него запросы идут в PostgreSQL | `app/main.py` |
|
||
| Активная проверка LB | `inter 1s`, `fall 2`, `rise 2`, `timeout check 1s` (раз в секунду; 2 неудачи подряд → DOWN; 2 успеха → UP) | `infra/haproxy/haproxy.cfg` |
|
||
| Пассивная проверка LB | `observe layer4 error-limit 1 on-error mark-down`: первая же ошибка соединения на реальном запросе сразу переводит сервер в DOWN | там же |
|
||
| DNS-обновление списка реплик | `hold valid 2s` (резолвер Docker 127.0.0.11) | там же |
|
||
| Таймауты LB | connect 1 s, server 10 s, http-request 10 s, keep-alive 10 s, client 30 s | там же |
|
||
| Повторы в LB | `retries 2`, `option redispatch 1`, `retry-on conn-failure empty-response 503`. Повтор уже отправленного запроса запрещён для POST (кроме POST сообщения с `Idempotency-Key`) и для DELETE | там же |
|
||
| Приложение | statement_timeout 5 s, ожидание соединения из пула 3 s, connect 3 s; uvicorn keep-alive 30 s (больше, чем 10 s у LB — соединение первым закрывает LB) | `compose.yaml`, `app/server.py` |
|
||
| SIGTERM | drain 3 s (readiness 503, `Connection: close`), затем закрытие порта и ожидание текущих запросов ≤ 8 s; `stop_grace_period: 15s` > 3 + 8 | `app/server.py`, `compose.yaml` |
|
||
| Docker healthcheck API | каждые 2 s, 2 неудачи | `compose.yaml` |
|
||
|
||
Как таймауты согласованы между собой: `timeout server` LB (10 s) больше, чем БД может держать запрос (5 s statement + 3 s ожидание пула), поэтому LB не обрывает запрос, который приложение ещё может успешно завершить. Drain (3 s) больше, чем время, за которое LB замечает 503 (≈ 2–3 s), поэтому к моменту закрытия порта новые запросы на реплику уже не идут.
|
||
|
||
Максимальное время обнаружения отказа (по конфигурации):
|
||
|
||
- процесс упал (connection refused/reset) — на первом же реальном запросе (`observe layer4`), сам запрос тут же повторяется на другой реплике; если трафика нет — активная проверка, ≤ `inter × fall` = 2 s;
|
||
- процесс жив, но не готов (нет БД, идёт drain) — ≤ `inter × fall + timeout check` ≈ 3 s;
|
||
- процесс завис (не отвечает вовсе) — ≤ 2 × (1 s интервал + 1 s таймаут проверки) ≈ 4 s; запросы, уже отправленные на зависшую реплику, ждут до `timeout server` = 10 s.
|
||
|
||
Что видно при `docker stop` реплики: в логе HAProxy `Server api/apiN is DOWN, reason: Layer7 wrong status, code: 503`, затем в логе API `drain finished: closing listener`, контейнер завершается с `Exited (0)`. Сам `docker stop` занимает ≈ 4 s (окно действия 4.13 и 4.04 s в `evidence/failover-stop-*.json`). При SIGKILL (`kill-one.sh`) код выхода `137`.
|
||
|
||
## 6. Доказательства критериев
|
||
|
||
Прогоны с измерениями — 2026-10-13, 14:49–14:58 UTC, на стенде из раздела 7. Повторная проверка команд 2026-10-20: `make check`/`validate`/`test` — PASS; `make test-failover` — PASS (`observed_instances_before: 2`, `failed_attempts: 0`, `first_recovery_seconds: 4.262`, у остановленного контейнера `Exited (0)`); `make test-persistence` — PASS; идемпотентность — PASS.
|
||
|
||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл |
|
||
|------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
|
||
| Публичный smoke | `make test` (хост → LB) | `PASS: lab3 public API scenario` | `evidence/public-tests.txt` |
|
||
| Структура контракта | `make check`, `make validate` | PASS | `evidence/public-tests.txt` |
|
||
| ≥2 реплики, одна точка входа, общая БД и сессии | `docker compose ps`; 4 запроса подряд через LB; 40× `/users/me` одним токеном в failover-тесте | 2 контейнера `api`; `X-Instance-Id` чередуется `fcae2c6047af` / `1ff54c0efa0c`; `observed_instances_before: 2`, без повторного входа | `evidence/public-tests.txt` |
|
||
| Остановка любой одной реплики, восстановление ≤10 s | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` дважды — по разу для каждой реплики (в tester) | оба PASS; `failed_attempts: 0`; `first_recovery_seconds` 4.4 и 4.52; в `docker ps -a` `Exited (0)` сначала у `1ff54c0efa0c`, потом у `fcae2c6047af` — остановлен реальный контейнер | `evidence/public-tests.txt` |
|
||
| Повтор с тем же ключом без дублей, в т.ч. во время отказа | `resilience.py` повторяет неопределённый POST тем же ключом; smoke: повтор = то же сообщение, другое тело = 409 | PASS, дублей нет | `evidence/public-tests.txt` |
|
||
| Persistence | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | PASS, прежний токен действует; `StartedAt` у db, valkey, обеих api и lb — после запуска hook (14:50:49–14:51:02), volume `messenger-lab3_postgres_data` на месте | `evidence/persistence.txt` |
|
||
| 4: health/readiness/timeouts/SIGTERM согласованы, LB исключает backend | конфигурация + `docker stop` реплики | раздел 5; реплика перестаёт получать запросы через 0.87–0.99 s после начала `docker stop`; выход с кодом 0 | раздел 5, `evidence/failover-stop-*.json` |
|
||
| 4: поочерёдная остановка каждой реплики под нагрузкой: RPS, ошибки, время восстановления | `student-tests/run-failover-series.sh` (stop и kill для каждой реплики, с восстановлением предыдущей) | таблица в разделе 7; 1 ошибка на 4 прогона, потерь и дублей 0 | `evidence/failover-*.json`, `evidence/failover-series.txt` |
|
||
| 4: параллельные запросы с одним ключом | `student-tests/idempotency_concurrency.py` (10 раундов × 16 одновременных POST с одним ключом) | в каждом раунде 1 сообщение и 15 ответов-повторов; все 10 раундов прошли через 2 реплики; другое тело → 409; ключ не мешает другому пользователю/чату | `evidence/idempotency-concurrency.json` |
|
||
| 4: CPU/RAM-лимиты, нет портов API наружу, нет `container_name`, секреты только где нужны | `compose.yaml` | лимиты у всех сервисов; у `api` нет `ports`; db/valkey в `internal`-сети; у LB нет секретов (таблица в разделе 3) | `compose.yaml` |
|
||
| 4: rolling update под нагрузкой, однократные совместимые миграции | `APP_VERSION=v3 sh scripts/rolling-update.sh` + параллельно `failover_load.py` (70 s, 4 потока) | обе реплики v2 заменены на v3 (новые `a9d3dc77f288`, `ea0e32824716`); 4 826 подтверждённых записей, 0 ошибок, максимальная пауза между записями 0.054 s; миграции один раз, все `SKIP` | `evidence/rolling-update.txt`, `evidence/rolling-update-load.json` |
|
||
| Нагрузка (справочно) | `tests/load.py --duration 30 --concurrency 4`, 4 прогона | 142–154 успешных RPS (среднее ≈ 148), 0 ошибок, p50 ≈ 15 ms, p95 76–86 ms, p99 98–138 ms | `evidence/load*.json`, `evidence/load-docker-stats.txt` |
|
||
|
||
Почему `X-Instance-Id` — не единственное доказательство: заголовок пишет само приложение. Поэтому после каждого отказа сохранён вывод `docker ps -a`: видно, что `Exited` именно тот контейнер, чей ID был в `TARGET_INSTANCE_ID`, а остальные сервисы продолжают работать.
|
||
|
||
## 7. Эксперименты и отказы
|
||
|
||
Стенд. Docker Desktop 29.3.0 (WSL2), хост 14 CPU / 7.4 GiB RAM. Лимиты: каждая api — 0.5 CPU / 256 MiB, db — 1 CPU / 512 MiB, valkey — 0.25 CPU / 128 MiB, lb — 0.5 CPU / 128 MiB. Генератор нагрузки — в контейнере `tester` в той же Docker-сети. Данные: синтетические, каждый прогон создаёт своих пользователей и чат.
|
||
|
||
Профиль нагрузки (`student-tests/failover_load.py`): закрытый цикл, 4 потока, 30 s, без прогрева; 50 % — POST сообщения, 50 % — GET истории (limit 20); таймаут клиента 3 s. Клиент ведёт себя как настоящий: если результат неизвестен, повторяет POST с тем же ключом и текстом. Через 8 s запускается action-скрипт против выбранной реплики; после прогона она возвращается (`start-api.sh`), и следующий прогон бьёт по другой. В конце вся история чата читается заново и проверяется: каждое подтверждённое сообщение на месте, одинаковых текстов нет.
|
||
|
||
Гипотеза. При `docker stop` (SIGTERM) клиенты не увидят ошибок: реплика сначала уходит из пула, потом закрывается. При SIGKILL возможны единичные ошибки: запросы, которые были внутри убитого процесса, оборвутся; большую часть из них HAProxy повторит на другой реплике. После отказа пропускная способность упадёт, потому что API упирается в CPU-лимит реплики.
|
||
|
||
RPS ниже — все успешные запросы (чтение + запись) в секунду. «Во время» — окно, пока выполняется action-скрипт (≈ 4 s для stop, < 1 s для kill).
|
||
|
||
| Воздействие | Что ожидаем | Что наблюдали: успешные RPS до → во время → после; p95 до → после | Восстановление / потеря данных |
|
||
|--------------------------------|----------------------------|---------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------|
|
||
| `stop-one` реплика 1 (SIGTERM) | 0 ошибок | 130.6 → 79.1 → 93.5; p95 86 → 99 ms; ошибок 0 | реплика перестала получать запросы через 0.99 s; макс. пауза между записями 0.40 s; 1 525 записей, потерь и дублей 0; `Exited (0)` |
|
||
| `stop-one` реплика 2 (SIGTERM) | 0 ошибок | 149.2 → 108.0 → 87.9; p95 81 → 100 ms; ошибок 0 | 0.87 s; пауза 0.39 s; 1 606 записей, потерь 0; `Exited (0)` |
|
||
| `kill-one` реплика 1 (SIGKILL) | единичные ошибки | 106.1 → 44.3 → 89.4; p95 99 → 100 ms; ошибок 0 | 0.06 s; пауза 0.19 s; 1 398 записей, потерь 0; `Exited (137)` |
|
||
| `kill-one` реплика 2 (SIGKILL) | единичные ошибки | 118.8 → 23.8 → 74.2; p95 94 → 104 ms; **1 ошибка** (через 0.13 s после kill) | 0.11 s; пауза 0.29 s; 1 273 записи, потерь и дублей 0; `Exited (137)` |
|
||
| Rolling update api ×2 → v3 | 0 ошибок | 137.8 RPS в среднем за 70 s, ошибок 0; по секундам не ниже 52 успешных запросов | макс. пауза между записями 0.054 s; 4 826 записей, потерь и дублей 0 |
|
||
| Restart всего стенда | данные и токен сохраняются | `make test-persistence` PASS | на время перезапуска сервис недоступен (ожидаемо: останавливаются и LB, и БД); БД поднялась в 14:50:49, LB — в 14:51:02 (≈ 13 s) |
|
||
|
||
Реплики: 1 = `fcae2c6047af`, 2 = `1ff54c0efa0c`.
|
||
|
||
Выводы.
|
||
|
||
1. Graceful stop работает: 0 ошибок в обоих прогонах. Реплика ещё ≈ 1 s обслуживает запросы во время drain, потом HAProxy убирает её из пула.
|
||
2. Гипотеза про SIGKILL подтвердилась: в одном прогоне 0 ошибок, в другом 1 ошибка из ~2 500 запросов. Почти все оборванные запросы HAProxy сам повторил на другой реплике (`retry-on conn-failure empty-response`). Единственную ошибку клиент повторил с тем же ключом — сообщение не потерялось и не задвоилось. Повторять в LB можно только потому, что GET безопасен, а POST сообщения защищён `Idempotency-Key`. Для остальных POST повтор в LB отключён.
|
||
3. С одной репликой пропускная способность падает на ~30–40 % (с ~106–149 до ~74–94 RPS). `docker stats` под нагрузкой: обе api ≈ 49 % CPU при лимите 0.5 CPU, то есть упираются в свой лимит; db ≈ 34 % от 1 CPU, lb ≈ 22 %. Узкое место — CPU API, а не БД. Падение меньше двукратного, потому что часть времени запроса уходит на сеть, БД и сам генератор нагрузки на том же хосте.
|
||
4. Rolling update прошёл без ошибок: новая реплика добавляется и проходит проверки до того, как останавливается старая, поэтому в пуле всегда минимум 2 рабочие реплики.
|
||
|
||
Ограничения измерений. Закрытый цикл (coordinated omission: пока клиент ждёт медленный ответ, он не шлёт новые, поэтому задержки занижены). Каждый сценарий отказа — один прогон по 30 s без повторов. Генератор нагрузки на том же хосте и делит с ним CPU. RPS «во время» посчитан по окну < 5 s и шумный. `first_recovery_seconds` публичного теста считается от начала hook до первой записи после его окончания, а сам `docker stop` с drain длится ≈ 4 s — реальный перерыв в записи намного меньше (макс. пауза 0.39–0.40 s).
|
||
|
||
## 8. Ограничения и следующие шаги
|
||
|
||
- Выдерживается отказ одной API-реплики (процесса/контейнера). Не выдерживаются: отказ PostgreSQL (один экземпляр без реплики), отказ HAProxy (единственная точка входа) и потеря Docker-хоста — всё работает на одном хосте. Отказ Valkey выдерживается: API переходит на PostgreSQL (проверялось в lab2).
|
||
- Кэш сессий очищается (`FLUSHDB`) при старте каждого процесса API — решение из lab2 против потерянной инвалидации. С несколькими репликами каждый рестарт/rolling update сбрасывает общий кэш: на корректность не влияет, но ненадолго увеличивает нагрузку на PostgreSQL.
|
||
- Время сообщения — `now()` начала транзакции PostgreSQL (одни часы для всех реплик). Транзакции могут фиксироваться не в порядке `created_at`, поэтому читатель, листающий историю во время конкурентной записи, может не увидеть сообщение, вставленное «позади» курсора. При чтении уже неизменной истории пропусков и повторов нет.
|
||
- Старые ключи идемпотентности автоматически не удаляются: через 24 ч ключ переиспользуется, индекс по `created_at` подготовлен для будущей периодической очистки.
|
||
- `X-Instance-Id` раскрывает hostname контейнера (короткий Docker ID) — по нему `stop-one.sh` находит контейнер. В lab7 его стоит заменить случайным псевдонимом.
|
||
- `rolling-update.sh` использует `docker compose --scale`, поэтому номера контейнеров растут (api-5, api-6…). Автоматического отката нет: при ошибке скрипт останавливается, старые реплики продолжают работать.
|
||
- Контейнер `tester` монтирует `docker.sock` — это полный доступ к Docker-хосту; допустимо только на учебном стенде.
|
||
- Тесты lab2 (`level4.py`, `db_checks.py`) не перенесены: они рассчитаны на топологию lab2 (API напрямую на :8080, отдельный `api_short_ttl` на :8081).
|