Использованные источники, библиотеки и помощь ИИ: FastAPI, SQLAlchemy 2, Alembic, argon2-cffi, Nginx, PostgreSQL 16; документация Docker Compose и Nginx; помощь ИИ при генерации кода и текста отчёта.
Источник истины: PostgreSQL. Пользователи, сессии, чаты, участники, сообщения и ключи идемпотентности хранятся в одной БД. Локального состояния в API нет — реплики взаимозаменяемы.
Сессии: таблица sessions (SHA-256 от токена, expires_at). TTL задаётся SESSION_TTL_SECONDS (по умолчанию 3600). Переживают рестарт API и БД.
Идемпотентность: таблица idempotency_keys с PK (user_id, method, path, key) и body_hash. Создание сообщения и запись ключа — в одной транзакции. Конкурентный повтор через разные реплики разрешается уникальным PK: проигравший получает IntegrityError, откатывается и читает уже сохранённый результат. Другой body при том же ключе → 409.
X-Instance-Id: задаётся через env INSTANCE_ID (api-1/api-2), стабилен в пределах жизни процесса.
X-Request-Id: генерируется middleware, если клиент не передал; возвращается во всех ответах, включая ошибки.
LB: Nginx upstream с двумя явными backend-серверами, max_fails=2 fail_timeout=5s, proxy_next_upstream error timeout http_502 http_503 http_504, proxy_connect_timeout 2s. Обнаружение отказа ≤ 10 с.
Graceful shutdown: uvicorn по SIGTERM перестаёт принимать новые соединения и завершает текущие; stop_grace_period: 15s. Nginx перенаправляет запросы на живую реплику.
Миграции: one-shot сервис migrate (Alembic), запускается до API. Совместимы с работающей версией (только additive).
Лимиты: API — 0.5 CPU / 256 MiB, PostgreSQL — 1 CPU / 512 MiB, Nginx — 0.5 CPU / 128 MiB.
Порты: наружу публикуется только lb:8080. Порты API не публикуются.
Соответствие .env.example:
Переменная
Где используется
POSTGRES_PASSWORD
compose.yaml (postgres, migrate, api-*)
SESSION_TTL_SECONDS
app/config.py
IDEMPOTENCY_TTL_SECONDS
app/config.py (зарезервировано для очистки)
APP_HOST, APP_PORT
app/config.py
DATABASE_URL_FILE
не используется в текущей реализации (см. ограничения)
Доказательства критериев
Критерий README
Команда/сценарий
Наблюдаемый результат
Файл доказательства
Публичный smoke
make test
PASS: lab3 public API scenario
evidence/smoke.txt
≥2 API-реплики, одна точка входа
for i in 1 2 3 4; do curl -sI http://localhost:8080/health/live | grep X-Instance-Id; done
чередуются api-1 и api-2
evidence/instances.txt
Разные запросы одного пользователя на разных репликах
make test + X-Instance-Id в ответах
smoke проходит, X-Instance-Id меняется
evidence/smoke.txt
Остановка одной реплики, продолжение работы
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
PASS: failover preserved confirmed data
evidence/failover.txt
Идемпотентность (в т.ч. конкурентная)
make test (LAB≥3) + параллельный повтор
повтор возвращает тот же Message, дублей нет
evidence/smoke.txt
Persistence (рестарт с сохранением volumes)
make test-persistence ACTION_SCRIPT=scripts/restart.sh
PASS: persistence preserved confirmed data
evidence/persistence.txt
Health/readiness, SIGTERM, LB исключает backend
docker compose stop api-1 + curl /health/ready
200 через api-2, api-1 исключён из upstream
evidence/health.txt
Последовательная остановка каждой реплики под нагрузкой
make load + scripts/stop-one.sh для api-1, затем api-2
RPS/ошибки/время восстановления
evidence/load-*.json
CPU/RAM-лимиты, API не публикует порты
docker compose config
deploy.resources.limits заданы, у api-* нет ports:
evidence/compose-config.txt
Rolling update под нагрузкой
docker compose up -d --no-deps api-1 при работающем make load
ошибок нет, RPS не падает до нуля
evidence/rolling.txt
Миграции однократно
docker compose logs migrate
один прогон upgrade head, повторный up не падает
evidence/migrate.txt
Эксперименты и отказы
Гипотеза: при остановке одной API-реплики Nginx исключает её из upstream за ≤ 10 с, а вторая реплика продолжает обслуживать чтение и запись без потери подтверждённых сообщений и без дублей при повторе с тем же Idempotency-Key.
Стенд: локальный Docker Desktop, 4 CPU / 8 GiB. Лимиты: API 0.5 CPU / 256 MiB × 2, PostgreSQL 1 CPU / 512 MiB, Nginx 0.5 CPU / 128 MiB. Версии: postgres:16.4-alpine, nginx:1.27.3-alpine, python:3.12-slim.
Профиль нагрузки:make load — closed-loop, 4 потока, 30 с, POST сообщений. Ограничения: клиент на Python, coordinated omission, latency только по успешным запросам.
Воздействие
Что ожидаем
Что наблюдали
Время восстановления / потеря данных
scripts/stop-one.sh для api-1
Nginx исключает api-1, api-2 продолжает
ошибки в первые ~5 с, затем 200; X-Instance-Id = api-2
≤ 10 с; потерь нет
scripts/stop-one.sh для api-2 (после восстановления api-1)
симметрично
симметрично
≤ 10 с; потерь нет
scripts/restart.sh (postgres + api-*)
данные и сессии сохранены
smoke с прежним токеном проходит
~15 с; потерь нет
Rolling update api-1 под нагрузкой
без 5xx
кратковременный рост latency, 5xx нет
~5 с
Ограничения и следующие шаги
Выдерживается: отказ одной API-реплики (процесса/контейнера), рестарт API и PostgreSQL с сохранением volumes.
Не выдерживается: отказ узла (single-host Compose), отказ PostgreSQL (SPOF), отказ Nginx (SPOF). Для трека 2 потребовался бы Swarm/несколько узлов и репликация БД.
Упрощения:DATABASE_URL_FILE из .env.example не используется — пароль передаётся через POSTGRES_PASSWORD в env (для локального синтетического стенда допустимо; для production нужен Docker secret). Очистка idempotency_keys по TTL не реализована (запись остаётся, но контракт требует хранения ≥ 24 ч — выполнено). Вложения (lab4+) не реализованы — целевая оценка 4 в рамках lab3.
Подтверждено: failover одной реплики, persistence, идемпотентность (включая конкурентный повтор), rolling update без 5xx.
Гипотеза (не проверено): поведение при отказе PostgreSQL и при горизонтальном масштабировании на 4+ реплик.
# Отчёт — лабораторная 3
- Автор, группа: Бушков Евгений БВТ2301
- Целевая оценка: **4** (трек 5 не заявлен)
- PR: ЛР3 — БВТ2301— Бушков — на 4
- Использованные источники, библиотеки и помощь ИИ: FastAPI, SQLAlchemy 2, Alembic, argon2-cffi, Nginx, PostgreSQL 16; документация Docker Compose и Nginx; помощь ИИ при генерации кода и текста отчёта.
## Запуск из чистого clone
Prerequisites: Docker Engine 24+, Docker Compose v2.20+, `curl`, `make`, Python 3.9+ (для публичных тестов).
Версии образов закреплены: `postgres:16.4-alpine`, `nginx:1.27.3-alpine`, `python:3.12-slim` (базовый образ приложения).
```sh
cp .env.example .env
# отредактируйте .env: задайте POSTGRES_PASSWORD (не коммитить!)
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build
# дождитесь готовности через LB:
until curl -fsS http://localhost:8080/health/ready >/dev/null; do sleep 1; done
make test BASE_URL=http://localhost:8080
```
Миграции выполняются one-shot сервисом `migrate` (Alembic `upgrade head`) до старта API; API ждёт `service_completed_successfully`. Повторный `up` безопасен: Alembic идемпотентен.
Безопасная остановка (сохраняет данные):
```sh
docker compose --env-file .env stop
```
Намеренное удаление учебных данных (необратимо):
```sh
docker compose --env-file .env down -v
```
## Архитектура и решения
```
Клиент → Nginx (lb:8080) → api-1 / api-2 (FastAPI, uvicorn) → PostgreSQL 16
```
- **Источник истины:** PostgreSQL. Пользователи, сессии, чаты, участники, сообщения и ключи идемпотентности хранятся в одной БД. Локального состояния в API нет — реплики взаимозаменяемы.
- **Сессии:** таблица `sessions` (SHA-256 от токена, `expires_at`). TTL задаётся `SESSION_TTL_SECONDS` (по умолчанию 3600). Переживают рестарт API и БД.
- **Идемпотентность:** таблица `idempotency_keys` с PK `(user_id, method, path, key)` и `body_hash`. Создание сообщения и запись ключа — в одной транзакции. Конкурентный повтор через разные реплики разрешается уникальным PK: проигравший получает `IntegrityError`, откатывается и читает уже сохранённый результат. Другой body при том же ключе → 409.
- **X-Instance-Id:** задаётся через env `INSTANCE_ID` (`api-1`/`api-2`), стабилен в пределах жизни процесса.
- **X-Request-Id:** генерируется middleware, если клиент не передал; возвращается во всех ответах, включая ошибки.
- **LB:** Nginx `upstream` с двумя явными backend-серверами, `max_fails=2 fail_timeout=5s`, `proxy_next_upstream error timeout http_502 http_503 http_504`, `proxy_connect_timeout 2s`. Обнаружение отказа ≤ 10 с.
- **Graceful shutdown:** uvicorn по SIGTERM перестаёт принимать новые соединения и завершает текущие; `stop_grace_period: 15s`. Nginx перенаправляет запросы на живую реплику.
- **Миграции:** one-shot сервис `migrate` (Alembic), запускается до API. Совместимы с работающей версией (только additive).
- **Лимиты:** API — 0.5 CPU / 256 MiB, PostgreSQL — 1 CPU / 512 MiB, Nginx — 0.5 CPU / 128 MiB.
- **Порты:** наружу публикуется только `lb:8080`. Порты API не публикуются.
Соответствие `.env.example`:
| Переменная | Где используется |
| --- | --- |
| `POSTGRES_PASSWORD` | compose.yaml (postgres, migrate, api-*) |
| `SESSION_TTL_SECONDS` | app/config.py |
| `IDEMPOTENCY_TTL_SECONDS` | app/config.py (зарезервировано для очистки) |
| `APP_HOST`, `APP_PORT` | app/config.py |
| `DATABASE_URL_FILE` | не используется в текущей реализации (см. ограничения) |
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | `make test` | `PASS: lab3 public API scenario` | `evidence/smoke.txt` |
| ≥2 API-реплики, одна точка входа | `for i in 1 2 3 4; do curl -sI http://localhost:8080/health/live \| grep X-Instance-Id; done` | чередуются `api-1` и `api-2` | `evidence/instances.txt` |
| Разные запросы одного пользователя на разных репликах | `make test` + `X-Instance-Id` в ответах | smoke проходит, `X-Instance-Id` меняется | `evidence/smoke.txt` |
| Остановка одной реплики, продолжение работы | `make test-failover ACTION_SCRIPT=scripts/stop-one.sh` | `PASS: failover preserved confirmed data` | `evidence/failover.txt` |
| Идемпотентность (в т.ч. конкурентная) | `make test` (LAB≥3) + параллельный повтор | повтор возвращает тот же Message, дублей нет | `evidence/smoke.txt` |
| Persistence (рестарт с сохранением volumes) | `make test-persistence ACTION_SCRIPT=scripts/restart.sh` | `PASS: persistence preserved confirmed data` | `evidence/persistence.txt` |
| Health/readiness, SIGTERM, LB исключает backend | `docker compose stop api-1` + `curl /health/ready` | 200 через api-2, api-1 исключён из upstream | `evidence/health.txt` |
| Последовательная остановка каждой реплики под нагрузкой | `make load` + `scripts/stop-one.sh` для api-1, затем api-2 | RPS/ошибки/время восстановления | `evidence/load-*.json` |
| CPU/RAM-лимиты, API не публикует порты | `docker compose config` | `deploy.resources.limits` заданы, у api-* нет `ports:` | `evidence/compose-config.txt` |
| Rolling update под нагрузкой | `docker compose up -d --no-deps api-1` при работающем `make load` | ошибок нет, RPS не падает до нуля | `evidence/rolling.txt` |
| Миграции однократно | `docker compose logs migrate` | один прогон `upgrade head`, повторный `up` не падает | `evidence/migrate.txt` |
## Эксперименты и отказы
**Гипотеза:** при остановке одной API-реплики Nginx исключает её из upstream за ≤ 10 с, а вторая реплика продолжает обслуживать чтение и запись без потери подтверждённых сообщений и без дублей при повторе с тем же `Idempotency-Key`.
**Стенд:** локальный Docker Desktop, 4 CPU / 8 GiB. Лимиты: API 0.5 CPU / 256 MiB × 2, PostgreSQL 1 CPU / 512 MiB, Nginx 0.5 CPU / 128 MiB. Версии: `postgres:16.4-alpine`, `nginx:1.27.3-alpine`, `python:3.12-slim`.
**Профиль нагрузки:** `make load` — closed-loop, 4 потока, 30 с, POST сообщений. Ограничения: клиент на Python, coordinated omission, latency только по успешным запросам.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `scripts/stop-one.sh` для `api-1` | Nginx исключает api-1, api-2 продолжает | ошибки в первые ~5 с, затем 200; `X-Instance-Id` = `api-2` | ≤ 10 с; потерь нет |
| `scripts/stop-one.sh` для `api-2` (после восстановления api-1) | симметрично | симметрично | ≤ 10 с; потерь нет |
| `scripts/restart.sh` (postgres + api-*) | данные и сессии сохранены | smoke с прежним токеном проходит | ~15 с; потерь нет |
| Rolling update `api-1` под нагрузкой | без 5xx | кратковременный рост latency, 5xx нет | ~5 с |
## Ограничения и следующие шаги
- **Выдерживается:** отказ одной API-реплики (процесса/контейнера), рестарт API и PostgreSQL с сохранением volumes.
- **Не выдерживается:** отказ узла (single-host Compose), отказ PostgreSQL (SPOF), отказ Nginx (SPOF). Для трека 2 потребовался бы Swarm/несколько узлов и репликация БД.
- **Упрощения:** `DATABASE_URL_FILE` из `.env.example` не используется — пароль передаётся через `POSTGRES_PASSWORD` в env (для локального синтетического стенда допустимо; для production нужен Docker secret). Очистка `idempotency_keys` по TTL не реализована (запись остаётся, но контракт требует хранения ≥ 24 ч — выполнено). Вложения (lab4+) не реализованы — целевая оценка 4 в рамках lab3.
- **Подтверждено:** failover одной реплики, persistence, идемпотентность (включая конкурентный повтор), rolling update без 5xx.
- **Гипотеза (не проверено):** поведение при отказе PostgreSQL и при горизонтальном масштабировании на 4+ реплик.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Отчёт — лабораторная 3
Запуск из чистого clone
Prerequisites: Docker Engine 24+, Docker Compose v2.20+,
curl,make, Python 3.9+ (для публичных тестов).Версии образов закреплены:
postgres:16.4-alpine,nginx:1.27.3-alpine,python:3.12-slim(базовый образ приложения).Миграции выполняются one-shot сервисом
migrate(Alembicupgrade head) до старта API; API ждётservice_completed_successfully. Повторныйupбезопасен: Alembic идемпотентен.Безопасная остановка (сохраняет данные):
Намеренное удаление учебных данных (необратимо):
Архитектура и решения
sessions(SHA-256 от токена,expires_at). TTL задаётсяSESSION_TTL_SECONDS(по умолчанию 3600). Переживают рестарт API и БД.idempotency_keysс PK(user_id, method, path, key)иbody_hash. Создание сообщения и запись ключа — в одной транзакции. Конкурентный повтор через разные реплики разрешается уникальным PK: проигравший получаетIntegrityError, откатывается и читает уже сохранённый результат. Другой body при том же ключе → 409.INSTANCE_ID(api-1/api-2), стабилен в пределах жизни процесса.upstreamс двумя явными backend-серверами,max_fails=2 fail_timeout=5s,proxy_next_upstream error timeout http_502 http_503 http_504,proxy_connect_timeout 2s. Обнаружение отказа ≤ 10 с.stop_grace_period: 15s. Nginx перенаправляет запросы на живую реплику.migrate(Alembic), запускается до API. Совместимы с работающей версией (только additive).lb:8080. Порты API не публикуются.Соответствие
.env.example:POSTGRES_PASSWORDSESSION_TTL_SECONDSIDEMPOTENCY_TTL_SECONDSAPP_HOST,APP_PORTDATABASE_URL_FILEДоказательства критериев
make testPASS: lab3 public API scenarioevidence/smoke.txtfor i in 1 2 3 4; do curl -sI http://localhost:8080/health/live | grep X-Instance-Id; doneapi-1иapi-2evidence/instances.txtmake test+X-Instance-Idв ответахX-Instance-Idменяетсяevidence/smoke.txtmake test-failover ACTION_SCRIPT=scripts/stop-one.shPASS: failover preserved confirmed dataevidence/failover.txtmake test(LAB≥3) + параллельный повторevidence/smoke.txtmake test-persistence ACTION_SCRIPT=scripts/restart.shPASS: persistence preserved confirmed dataevidence/persistence.txtdocker compose stop api-1+curl /health/readyevidence/health.txtmake load+scripts/stop-one.shдля api-1, затем api-2evidence/load-*.jsondocker compose configdeploy.resources.limitsзаданы, у api-* нетports:evidence/compose-config.txtdocker compose up -d --no-deps api-1при работающемmake loadevidence/rolling.txtdocker compose logs migrateupgrade head, повторныйupне падаетevidence/migrate.txtЭксперименты и отказы
Гипотеза: при остановке одной API-реплики Nginx исключает её из upstream за ≤ 10 с, а вторая реплика продолжает обслуживать чтение и запись без потери подтверждённых сообщений и без дублей при повторе с тем же
Idempotency-Key.Стенд: локальный Docker Desktop, 4 CPU / 8 GiB. Лимиты: API 0.5 CPU / 256 MiB × 2, PostgreSQL 1 CPU / 512 MiB, Nginx 0.5 CPU / 128 MiB. Версии:
postgres:16.4-alpine,nginx:1.27.3-alpine,python:3.12-slim.Профиль нагрузки:
make load— closed-loop, 4 потока, 30 с, POST сообщений. Ограничения: клиент на Python, coordinated omission, latency только по успешным запросам.scripts/stop-one.shдляapi-1X-Instance-Id=api-2scripts/stop-one.shдляapi-2(после восстановления api-1)scripts/restart.sh(postgres + api-*)api-1под нагрузкойОграничения и следующие шаги
DATABASE_URL_FILEиз.env.exampleне используется — пароль передаётся черезPOSTGRES_PASSWORDв env (для локального синтетического стенда допустимо; для production нужен Docker secret). Очисткаidempotency_keysпо TTL не реализована (запись остаётся, но контракт требует хранения ≥ 24 ч — выполнено). Вложения (lab4+) не реализованы — целевая оценка 4 в рамках lab3.Принято. Закрываю МР.
Pull request closed