docs: complete lab 3 report and add final clean clone check
Fill the remaining report sections: clean clone run with versions and prerequisites, lab 2 carry-over, transaction boundaries, teacher agreements, skeleton variable mapping, rubric cross-check, experiment overview, limitations summary, sources and AI usage. Record the clean clone run of every documented command on default ports. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -2,56 +2,147 @@
|
||||
|
||||
- Автор, группа: Сафронов Роман Николаевич, БВТ2301
|
||||
- Целевая оценка 5; выбранный трек 5: трек 1 «Цена масштабирования» (серии сняты, change `scaling-bench`; одно подтверждённое улучшение — пул без переполнения, change `scaling-improvement`, засчитано с оговоркой: раздел «Улучшение по найденному узкому месту: пул без переполнения»)
|
||||
- Commit/PR: TODO после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: TODO
|
||||
- Commit/PR: ветка `solution/bvt2301-safronov`, PR «ЛР 3 — БВТ2301 —
|
||||
Сафронов — на 5» — ссылка на PR после публикации (push и PR делает
|
||||
автор). Из чистого clone проверен код commit `67b4303`
|
||||
(`evidence/tests/clean-clone-final.md`); последующие commit меняют
|
||||
только документы.
|
||||
- Использованные источники, библиотеки и помощь ИИ: раздел «Источники,
|
||||
библиотеки и использование ИИ» в конце отчёта.
|
||||
|
||||
Сделано по changes OpenSpec (`openspec/changes/archive/`), поверх кода
|
||||
лабы 2:
|
||||
- `X-Instance-Id` и обязательный `Idempotency-Key` с ключами в
|
||||
PostgreSQL — `instance-id-idempotency` (уровень «3»);
|
||||
- HAProxy перед двумя репликами API, лимиты, failover hook
|
||||
`scripts/stop-one.sh` — `replicas-lb` (уровни «3» и «4»);
|
||||
- согласованная цепочка таймаутов и профиль отказа под нагрузкой —
|
||||
`graceful-failover` (уровень «4»);
|
||||
- поочерёдная замена реплик с дренажём через runtime API HAProxy,
|
||||
expand-миграция и профиль замены под нагрузкой — `rolling-update`
|
||||
(уровень «4»);
|
||||
- трек 1 «Цена масштабирования»: серии `a`, `b`, `pool`, `db`, A/A,
|
||||
графики, точка насыщения и ответ 503 на «too many clients» —
|
||||
`scaling-bench` (уровень «5»);
|
||||
- одно улучшение по найденному узкому месту — пул без переполнения —
|
||||
`scaling-improvement` (уровень «5»).
|
||||
|
||||
## Запуск из чистого clone
|
||||
|
||||
TODO (этап 7, `PLAN.md`): версии runtime/образов и prerequisites одним
|
||||
списком, повторная проверка из настоящего `git clone` на стенде с LB.
|
||||
**Версии.** Образ API: `python:3.12.14-slim-trixie` и `uv 0.12.17`;
|
||||
LB: `haproxy:3.4.6-trixie`; Postgres: `postgres:18.6-trixie`; Valkey:
|
||||
`valkey/valkey:9.1.2-trixie`. Все закреплены тегом и digest индекса
|
||||
(amd64 + arm64) в `Dockerfile` и `docker-compose.yml`. Приложение:
|
||||
Python 3.12, FastAPI 0.141.1, uvicorn 0.54.0, pydantic 2.13.5,
|
||||
SQLAlchemy 2.1.1 (async), asyncpg 0.31.0, alembic 1.20.0, argon2-cffi
|
||||
25.1.0, redis-py 8.1.0, structlog 24.4.0 и остальное строго по
|
||||
`uv.lock`. Тесты: pytest 9.1.1, httpx 0.28.1; нагрузка: k6 2.3.0 в
|
||||
контейнере (`grafana/k6:2.3.0@sha256:…`, `bench/run.py`). Проверено на
|
||||
Docker Desktop 29.8.2 (ВМ linux/arm64, 12 CPU, 7,7 GiB), Compose
|
||||
v5.5.1, macOS на Apple M3 Pro.
|
||||
|
||||
Стенд с балансировщиком (change `replicas-lb`):
|
||||
**Нужно на машине:**
|
||||
- Docker с BuildKit и Compose v2, `make`, `openssl` (пароли в
|
||||
`make env_setup`);
|
||||
- `python3` 3.9+ для публичных `make check`, `make test`,
|
||||
`make test-persistence`, `make test-failover`, `make instances`,
|
||||
`make test_isolated`, `make failure_checks`;
|
||||
- uv — для `make validate` (валидатор в dev-группе), `make
|
||||
student_test`, `make failure_checks`, `make test_isolated` (внутри
|
||||
`uv run pytest`), стенда замеров `make bench*` и `make run_dev`;
|
||||
- свободные порты `127.0.0.1:8080` (LB), `127.0.0.1:5433` (Postgres) и
|
||||
`127.0.0.1:6380` (Valkey). Стенд лабы 2 занимает те же порты: перед
|
||||
запуском его нужно остановить (`make stop` в его каталоге). Другие
|
||||
порты — аргументом make (`make run_docker APP_OUT_PORT=8090`) или в
|
||||
`.env`, затем `make test BASE_URL=http://localhost:8090`.
|
||||
|
||||
**Подготовка и секреты.** `make env_setup` создаёт `.env` из
|
||||
`.env.example` и `config.toml` из `config_example.toml`, существующие
|
||||
файлы не трогает. В шаблоне пароли Postgres и Valkey пустые, в новый
|
||||
`.env` подставляются случайные (`openssl rand -hex 16`): общего пароля
|
||||
стенда в git нет. Отдельно запускать `env_setup` не обязательно, его
|
||||
вызывают `make run_docker`, `make run_dev`, `make test_isolated` и `make
|
||||
failure_checks`. Пароль Postgres задаётся только при создании volume:
|
||||
после смены `POSTGRES_PASSWORD` нужен `make wipe_data`.
|
||||
|
||||
Последовательность проверяющего — та, что прошла из настоящего `git
|
||||
clone` на портах по умолчанию (`evidence/tests/clean-clone-final.md`):
|
||||
|
||||
```sh
|
||||
make env_setup # .env (случайные POSTGRES_PASSWORD и VALKEY_PASSWORD) и config.toml из шаблонов; существующие не трогает
|
||||
git clone <fork> && cd <каталог clone> && git checkout solution/bvt2301-safronov
|
||||
make env_setup # .env (случайные POSTGRES_PASSWORD и VALKEY_PASSWORD) и config.toml из шаблонов
|
||||
make run_docker # docker compose build + up -d: postgres, valkey → migrate → api × API_REPLICAS (2) → haproxy
|
||||
docker compose ps # готовность — haproxy (healthy): через LB можно обслужить запрос
|
||||
docker compose ps # готовность — haproxy (healthy): через LB можно обслужить запрос; у api портов нет
|
||||
make check # структура skeleton
|
||||
uv sync && make validate PYTHON=.venv/bin/python # полная валидация OpenAPI 3.1
|
||||
make test # публичный smoke через LB на http://localhost:8080
|
||||
make student_test # свой набор через LB, тесты реплик выполняются (EXPECT_REPLICAS = API_REPLICAS)
|
||||
make instances # ≥2 X-Instance-Id одной сессии через LB (шаг 1 сценария защиты)
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.sh
|
||||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh
|
||||
make replicas # вернуть остановленную реплику (те же ID) перед следующим прогоном failover
|
||||
make bench_failover_quick # отказ каждой реплики под нагрузкой на своём стенде mtusi-bench, ~2 мин; полный — make bench_failover
|
||||
make rolling_update # новый код на реплики без простоя: сборка, миграции один раз, по одной реплике с выводом из LB
|
||||
make bench_rollout_quick # то же под нагрузкой на своём стенде с образа прежнего commit, ~2 мин; полный — make bench_rollout
|
||||
make stop # остановить; make down — удалить контейнеры, volume с данными остаётся
|
||||
make wipe_data # намеренно удалить учебные данные: только после ввода yes, только проект mtusi-lab3
|
||||
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановлена первая реплика
|
||||
make replicas # вернуть остановленную реплику (тот же контейнер и ID)
|
||||
curl -s -o /dev/null http://127.0.0.1:8080/health/live # сдвиг очереди round-robin, иначе тест выберет ту же реплику
|
||||
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh # остановлена вторая
|
||||
make replicas
|
||||
make student_test # свой набор через LB, тесты реплик выполняются (EXPECT_REPLICAS = API_REPLICAS)
|
||||
make failure_checks # проверки отказов на отдельном проекте mtusi-lab3-failures, ~70 с; рабочий стенд не трогается
|
||||
make test_isolated # образ на временной базе test_messenger, один контейнер API: smoke + свой набор, ~65 с
|
||||
```
|
||||
|
||||
Ожидаемо: `make check`, `make validate`, `make test`,
|
||||
`make test-persistence` и оба `make test-failover` — `PASS`;
|
||||
`make instances` — `instances: 2`; `make student_test` — `131 passed`;
|
||||
`make failure_checks` — `17 passed`; `make test_isolated` — `127
|
||||
passed, 4 skipped` (тесты реплик против одного процесса пропускаются с
|
||||
причиной). Строка `STOP_ONE_LOG` называет `TARGET_INSTANCE_ID`, который
|
||||
выбрал тест, и полный ID остановленного контейнера; `docker compose ps
|
||||
-a` показывает его `Exited`.
|
||||
|
||||
Порт API на хосте один — у HAProxy (`127.0.0.1:${APP_OUT_PORT}`, 8080).
|
||||
Число реплик — `API_REPLICAS` в `.env` (по умолчанию 2), разово —
|
||||
`make replicas API_REPLICAS=N`. В консоли (`make run_dev`) — один
|
||||
процесс без LB; свой набор против него — `make student_test
|
||||
процесс без LB на `127.0.0.1:8080`, с Postgres и Valkey из того же
|
||||
compose; свой набор против него — `make student_test
|
||||
EXPECT_REPLICAS=1`.
|
||||
|
||||
Проверено на одном API без балансировщика (change
|
||||
`instance-id-idempotency`): в настоящем `git clone` `docker build -t
|
||||
mtusi-messenger:lab3 .` проходит без `.env` и `config.toml`; после
|
||||
`make env_setup` на этом образе проходит smoke
|
||||
(`evidence/tests/clean-clone.md`). Стенд с LB из настоящего `git clone`
|
||||
(change `replicas-lb`): `make run_docker` сам создаёт `.env` и
|
||||
`config.toml` и поднимает две реплики за HAProxy; на нестандартных
|
||||
`APP_OUT_PORT`, `APP__PORT` и портах Postgres и Valkey проходят `make
|
||||
test` и `make student_test` (`evidence/replicas/clean-clone-ports.md`). Удаление учебных данных — `make
|
||||
wipe_data` с вводом `yes`, трогает только проект `mtusi-lab3`
|
||||
(`evidence/tests/stand-lab3.md`).
|
||||
### Сценарий защиты
|
||||
|
||||
```sh
|
||||
make run_docker && make instances # 1. ≥2 X-Instance-Id одной сессии через LB
|
||||
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh # 2. запись и чтение во время отказа
|
||||
cat /tmp/stop-one.log; docker compose ps -a # 3. какой контейнер остановлен: ID = TARGET_INSTANCE_ID
|
||||
make replicas; curl -s -o /dev/null http://127.0.0.1:8080/health/live
|
||||
STOP_ONE_LOG=/tmp/stop-one.log make test-failover ACTION_SCRIPT=scripts/stop-one.sh # то же для второй реплики
|
||||
make replicas
|
||||
make test-persistence ACTION_SCRIPT=scripts/restart.sh # 4. рестарт LB, реплик, Postgres и Valkey, тот же токен
|
||||
# уровень 4 — на своём стенде mtusi-bench, рабочий стенд перед ними: make stop
|
||||
make bench_failover_quick # отказ каждой реплики под нагрузкой (stop, kill), ~2 мин; полный — make bench_failover
|
||||
make bench_rollout_quick # поочерёдная замена под нагрузкой с образа прежнего commit, ~2 мин; полный — make bench_rollout
|
||||
make rolling_update # на рабочем стенде: новый код без простоя (под make load в соседнем терминале)
|
||||
# уровень 5, трек 1: самопроверка серий (~4 мин), полные серии — make bench_scaling SERIES=…
|
||||
make bench_scaling_quick
|
||||
```
|
||||
|
||||
Полные метки и графики трека 1 уже лежат в `evidence/bench/scaling-*/`,
|
||||
`evidence/plots/` и `evidence/compare/` (раздел «Цена
|
||||
масштабирования»); на защите показываются они, серии идут 25–100 мин.
|
||||
|
||||
### Остановка и удаление данных
|
||||
|
||||
- `make stop` — остановить контейнеры; `make down` — удалить
|
||||
контейнеры, volume `postgres_data` с данными остаётся, кэш Valkey
|
||||
теряется (он без volume, данные от этого не страдают);
|
||||
- `make wipe_data` — удалить контейнеры и volume, только после ввода
|
||||
`yes` и только проекта `mtusi-lab3` (`evidence/tests/stand-lab3.md`);
|
||||
следующий `make run_docker` поднимает пустую базу со схемой.
|
||||
|
||||
Ранние проверки из clone: один API без LB — сборка без `.env` и
|
||||
`config.toml`, smoke на образе (`evidence/tests/clean-clone.md`); стенд
|
||||
с LB на нестандартных `APP_OUT_PORT`, `APP__PORT` и портах Postgres и
|
||||
Valkey — `make test` и `make student_test`
|
||||
(`evidence/replicas/clean-clone-ports.md`).
|
||||
|
||||
## Архитектура и решения
|
||||
|
||||
TODO (этап 7): что перенесено из lab2 одним списком, транзакционные
|
||||
границы сводно.
|
||||
|
||||
```
|
||||
клиент → 127.0.0.1:APP_OUT_PORT → haproxy ──→ api (реплика 1) ──→ postgres (данные, сессии, ключи идемпотентности; volume)
|
||||
└─→ api (реплика 2) ──→ valkey (кэш неизменяемых карточек чатов)
|
||||
@@ -63,6 +154,70 @@ TODO (этап 7): что перенесено из lab2 одним списко
|
||||
Postgres. Реплики `api` одинаковы и взаимозаменяемы, порта на хосте у
|
||||
них нет; единственная точка входа — HAProxy.
|
||||
|
||||
**Что перенесено из лабы 2** (репозиторий `mtusi2026lab2-safronov`,
|
||||
ветка `solution/bvt2301-safronov`, commit `c6ad34d`), без изменения
|
||||
поведения, кроме перечисленного ниже:
|
||||
- PostgreSQL как источник истины, схема и миграции alembic отдельным
|
||||
сервисом `migrate`, ограниченный пул и таймауты, 503 при
|
||||
недоступности БД;
|
||||
- регистрация с паролем (Argon2id в потоке), вход по Basic только на
|
||||
`POST /auth/sessions`, остальное — Bearer-сессия в таблице `sessions`
|
||||
(SHA-256 токена, срок `[auth] session_ttl_seconds`, мгновенный отзыв);
|
||||
- Valkey — cache-aside неизменяемой карточки чата, отказ — обход в
|
||||
Postgres;
|
||||
- keyset-пагинация по `(created_at, id)`, формат ошибок контракта,
|
||||
JSON-журнал без содержимого сообщений;
|
||||
- свои тесты `student-tests/` (`make test_isolated`, `make
|
||||
failure_checks`) и стенд замеров `bench/` трека 2 лабы 2 (`make bench`,
|
||||
`make bench_restore`).
|
||||
|
||||
Что изменилось при переходе 2 → 3: переход API (`COURSE.md`) —
|
||||
`X-Instance-Id` в каждом ответе и обязательный `Idempotency-Key` у
|
||||
отправки сообщения; новые миграции только добавляют (таблица
|
||||
`idempotency_keys`, колонка `messages.instance_id`); проект compose
|
||||
`mtusi-lab3` вместо `mtusi-lab2`, чтобы не подключиться к данным
|
||||
второй лабы; HAProxy и реплики без портов; цепочка таймаутов (keep-alive
|
||||
uvicorn 60 с, `idle_in_transaction_session_timeout` 10 с); пул 10 + 0
|
||||
вместо 10 + 5 (`scaling-improvement`); отказ PostgreSQL «too many
|
||||
clients» (SQLSTATE 53300) — 503, а не 500. Стенды `make failure_checks`
|
||||
и `bench/` переведены на HAProxy перед API, `make test_isolated` остался
|
||||
одним контейнером API на временной базе.
|
||||
|
||||
**Транзакционные границы.** Одна `AsyncSession` на запрос, commit
|
||||
делает сервис, изоляция `READ COMMITTED`; реплики общих транзакций не
|
||||
имеют, гонки между ними решают ограничения PostgreSQL:
|
||||
|
||||
| Операция | Шаги в одной транзакции |
|
||||
|---|---|
|
||||
| регистрация | хэш пароля (до БД) → `INSERT … ON CONFLICT (username) DO NOTHING RETURNING`; конфликт → 409 |
|
||||
| вход | транзакция 1: `SELECT` учётных данных → commit; проверка пароля вне БД; транзакция 2: `INSERT sessions` → commit |
|
||||
| запрос с токеном | один `SELECT sessions JOIN users WHERE token_hash = … AND expires_at > now` |
|
||||
| выход | `DELETE FROM sessions WHERE id = …` → commit |
|
||||
| создание чата | проверка участников → `INSERT chats` → `INSERT chat_members` → commit; ошибка до commit — откат всего. Карточка пишется в Valkey после commit |
|
||||
| отправка сообщения | членство (карточка из Valkey или `SELECT`) → захват ключа `INSERT … ON CONFLICT … DO UPDATE WHERE просрочен RETURNING` → `INSERT messages` (с `instance_id` реплики) → commit с отложенной проверкой FK ключа на сообщение. Ключ занят — чтение сохранённого результата и commit (снять блокировку), тот же 201 или 409. Ошибка до commit — нет ни ключа, ни сообщения |
|
||||
| чтения | карточка чата — из Valkey или одним `SELECT`; история и список чатов — один `SELECT` по keyset-индексу |
|
||||
|
||||
Одновременная вставка того же ключа другой репликой ждёт на
|
||||
уникальном индексе commit или отката первой; явных блокировок и
|
||||
распределённых транзакций нет (раздел «Идемпотентность отправки
|
||||
сообщения»).
|
||||
|
||||
**Согласования с преподавателем** (AGENTS.md, «Согласования с
|
||||
преподавателем»), действуют и в этой лабе:
|
||||
- 2026-09-26 — лабы можно делать на FastAPI, несмотря на расхождения с
|
||||
контрактом: лишний 422 (у нас не отдаётся вообще, всё переводится в
|
||||
400) и другой порядок кодов ошибок. Публичный smoke при этом проходит.
|
||||
Где это видно в лабе 3 — порядок кодов у `Idempotency-Key` (раздел
|
||||
«Идемпотентность отправки сообщения»);
|
||||
- 2026-09-29 — конфигурация через pydantic-settings: окружение →
|
||||
`.env` → `config.toml` → дефолты. `config.toml` не в git и не в
|
||||
образе, монтируется read-only при запуске; это считается выполнением
|
||||
«конфигурация приходит из окружения» (README лабы 1, п. 3) и п. 6
|
||||
`Dockerfile.example`. Отсюда таблица «Соответствие переменных
|
||||
`.env.example`» ниже.
|
||||
|
||||
Новых согласований в лабе 3 не было.
|
||||
|
||||
### Балансировщик и реплики (change `replicas-lb`)
|
||||
|
||||
**Почему Compose + HAProxy** (выбор подтверждён 2026-10-07, `PLAN.md`):
|
||||
@@ -405,13 +560,24 @@ SHA-256 тела; `created_at` с индексом; `CHECK` формата и д
|
||||
|
||||
### Соответствие переменных `.env.example`
|
||||
|
||||
`.env.example` skeleton предлагает «логические» имена и просит
|
||||
сопоставить их с настоящими. Критерий — кто читает значение: то, что
|
||||
читают compose и контейнеры зависимостей, живёт в `.env`, то, что читает
|
||||
только приложение, — в секциях `config.toml` (согласование 2026-09-29).
|
||||
Адреса и порты Postgres и Valkey в compose — только переменные `.env`.
|
||||
|
||||
| Имя skeleton | Где у нас | Почему так |
|
||||
|---|---|---|
|
||||
| `APP_HOST` | режим `APP__RUN_MODE`: console — `127.0.0.1`, docker — `0.0.0.0` (литерал в `environment` compose и `ENV` в `Dockerfile`) | адрес следует из режима; в `.env` режим не хранится, чтобы консоль и docker работали из одного файла |
|
||||
| `APP_PORT` | `APP__PORT` в `.env` (8080) — порт, на котором слушает каждая реплика, на нём же healthcheck образа и проверки HAProxy (`API_PORT` контейнера LB); `APP_OUT_PORT` (8080) — порт на `127.0.0.1` хоста, его публикует только HAProxy | параметр приложения в формате настроек; внешний порт приложение не читает, поэтому без секции. Проверено на нестандартных портах (`evidence/replicas/clean-clone-ports.md`) |
|
||||
| `APP_ENV` | не используется | окружение одно — учебный стенд |
|
||||
| `SESSION_TTL_SECONDS` | `[auth] session_ttl_seconds` в `config.toml`, по умолчанию 3600; разовая подмена — `AUTH__SESSION_TTL_SECONDS` (так «тесный» API `make failure_checks` получает 2 с) | читает только приложение; мост из `.env` с этим именем окружение бы не перекрыло (`.claude/rules/settings.md`) |
|
||||
| `DATABASE_URL_FILE` | не используется: URL собирает приложение из `[database]`, адрес и порт в docker — `POSTGRES_HOST` / `POSTGRES_PORT` из `environment` compose, пароль — мостом из `POSTGRES_PASSWORD` в `.env` | пароль нужен ещё и контейнеру Postgres, поэтому один источник — `.env`; файл секрета с URL дал бы второй |
|
||||
| `SESSION_STORE` | `postgres`: таблица `sessions`, общая для всех реплик, без кэша — отзыв мгновенный. Отдельной настройки нет | другого хранилища сессий нет; Valkey сессий не хранит (без persistence рестарт стёр бы их) |
|
||||
| `CACHE_URL_FILE` | не используется: адрес и порт Valkey — `VALKEY_HOST`, `VALKEY_PORT` (сеть compose) и `VALKEY_OUT_PORT` (консоль) в `.env`, пароль — мостом из `VALKEY_PASSWORD` в `[cache] password`; таймаут, окно пропуска, срок записей и пул — `[cache]` в `config.toml` | как у Postgres: пароль нужен и серверу Valkey (`--requirepass`) |
|
||||
| `IDEMPOTENCY_TTL_SECONDS` | `[idempotency] ttl_seconds` в `config.toml`, по умолчанию 86400 (24 ч); разовая подмена — `IDEMPOTENCY__TTL_SECONDS` | значение читает только приложение; как `SESSION_TTL_SECONDS` (`.claude/rules/settings.md`). Срок меньше 86400 нарушает контракт и применяется только в проверках (2 с у «тесного» API стенда отказов) |
|
||||
| `API_REPLICAS` | `API_REPLICAS` в `.env` (шаблон — 2), `deploy.replicas: ${API_REPLICAS:-2}` сервиса `api`; Makefile — `API_REPLICAS ?= 2` (`make replicas`, `EXPECT_REPLICAS` тестов). Разово — `make replicas API_REPLICAS=N` | приложение его не читает, поэтому имя без секции; без строки в `.env` действует 2 (`.claude/rules/settings.md`) |
|
||||
|
||||
TODO: остальные имена skeleton (`APP_HOST`, `APP_PORT`, `APP_ENV`, `SESSION_TTL_SECONDS`, `DATABASE_URL_FILE`, `SESSION_STORE`, `CACHE_URL_FILE`).
|
||||
|
||||
## Доказательства критериев
|
||||
|
||||
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
|
||||
@@ -444,6 +610,7 @@ TODO: остальные имена skeleton (`APP_HOST`, `APP_PORT`, `APP_ENV`,
|
||||
| `X-Instance-Id` на каждом ответе, `instance_id` в журнале | тесты `api-conventions`, `curl`, `docker compose logs api` | заголовок у 2xx, 4xx, health, 404, 405, 500; значение = короткий ID контейнера; 85 из 85 записей журнала с `instance_id`, включая старт и shutdown; ключей и текста в журнале нет | `evidence/idempotency/instance-id.md` |
|
||||
| Стенд лабы 3 не трогает данные лабы 2 | `make run_docker`, `make wipe_data`, снова `make run_docker`; `docker volume inspect` до и после | `wipe_data` удалил только контейнеры, сеть и volume `mtusi-lab3`; `mtusi-lab2_postgres_data` с прежней датой создания | `evidence/tests/stand-lab3.md` |
|
||||
| Сборка из чистого clone | `git clone`, `docker build -t mtusi-messenger:lab3 .` до `make env_setup`; стенд на этом образе, `make test` | сборка без `.env` и `config.toml`, в образе их нет, процесс от UID 10001; `PASS: lab3 public API scenario` | `evidence/tests/clean-clone.md` |
|
||||
| Итоговая проверка из чистого clone по разделу «Запуск из чистого clone» (`PLAN.md`, этап 7; COURSE.md: «PR собирается из чистого clone») | настоящий `git clone` commit `67b4303`, проект `mtusi-lab3` на портах по умолчанию: `make env_setup`, `make run_docker`, `make check`, `make validate`, `make test`, `make instances`, `make test-persistence`, `make test-failover` для каждой реплики (`stop`, затем `make replicas`; плюс `kill`), `make student_test`, `make failure_checks`, `make test_isolated`; `docker build --no-cache` | все команды — код 0 без правки файлов клона: `PASS` у публичных проверок, `instances: 2`, остановлены по очереди `0089ca350b2b` и `437292ccaf78` (ID = `TARGET_INSTANCE_ID`), первая запись через 0,99–1,0 с, неудачных попыток 0; после `restart.sh` те же ID с новым `StartedAt` у LB, реплик, Postgres и Valkey; 131 passed через LB, 17 проверок отказов, 127 passed + 4 пропуска с причиной в изоляции; образ без `.env` и `config.toml`, UID 10001 | `evidence/tests/clean-clone-final.md` |
|
||||
| Стенд `bench/`: отправки с ключом при восстановлении | `make bench_restore_quick` (самопроверка, не замер) | 1000 отправок во время backup на каждом размере, 0 неудачных; сообщений в исходной базе = подтверждённых отправок; сверка баз прошла | `evidence/tests/bench-restore-quick.md` |
|
||||
| «4»: rolling update (поочерёдная замена) проверен под нагрузкой | `make bench_rollout ROLLOUT_LABEL=baseline` (commit `9dcea0b`, код `de654a1`, хост проверен, рабочий стенд остановлен): 100 записей с ключом и 100 чтений в секунду, две реплики образа `c50b721` заменяются на образ текущего checkout тем же `scripts/rolling-update.sh`; на рабочем стенде (итоговый код `84161c0`) — `make rolling_update`, откат `COMMIT=c50b721 MIGRATE=0`, снова вперёд и две замены подряд под `tests/load.py`; быстрый профиль `make bench_rollout_quick` на `84161c0` | замена 8,9 с; **0 ошибок** из 24 002 запросов, доля успешных 1,0 в каждой секунде, p95 5 → макс. 11 мс; по шагам: новая `UP` в LB через 2,0–2,1 с после старта, дренаж старой 0,14–0,16 с, остановка 0,3–0,4 с; после вывода из LB старая не получила ни одного запроса; сообщений 12 001 = ключей 12 001. Рабочий стенд: 0 неуспешных из 21 043 / 16 687 / 18 480 / 27 278 запросов `tests/load.py`; старые реплики завершаются за 0,1 с с кодом 0 («Finished server process»); контейнеров прежних реплик после замены нет. Быстрый профиль на итоговом коде: замена 8,1 с, 0 ошибок, 7 301 = 7 301 | `evidence/rollout/baseline/summary.md`, `evidence/rollout/compatibility.md`, `evidence/tests/rolling-update-checks.md` |
|
||||
| «4»: миграции однократно и совместимы с работающей версией | реплики образа `c50b721` + миграция нового образа в контейнере сервиса `migrate` (команда скрипта), без замены; `make test`, `make student_test`; замена; `SELECT instance_id, count(*)` по сообщениям; миграция под чужой блокировкой и нагрузкой | новая ревизия `e656d6bbe1a4` (колонка `messages.instance_id`, NULL) при прежних репликах: `PASS`, 131 passed; запись прежней версии — NULL, новой — её `X-Instance-Id`; при замене одна миграция в контейнере `migrate` до первой новой реплики, в журналах реплик alembic нет; повторный запуск — no-op; откат кода без отката схемы (после отката `migrate` прежнего образа падает на новой ревизии — ограничение, описано); под чужой транзакцией `lock_timeout` 2 с → миграция падает с кодом 1, схема и реплики не тронуты, 6 запросов из очереди за ней — успешны за 2,0 с (с 5 с в apply — все 6 получили 503), повтор проходит | `evidence/rollout/compatibility.md`, `evidence/rollout/script-failures.md` |
|
||||
@@ -463,11 +630,65 @@ TODO: остальные имена skeleton (`APP_HOST`, `APP_PORT`, `APP_ENV`,
|
||||
| Пул без переполнения: соединения не переоткрываются | `make failure_checks`: тест `test_pool_keeps_connections` (48 потоков × 5 запросов, пачки больше пула 10, счётчик `pg_stat_database.sessions` через hook `db-sessions`); рабочий `config.toml` с `max_overflow` 5 и 0 | 10 + 5 — красный: 18–21 новая сессия PostgreSQL за 720 запросов; 10 + 0 — 0, 17 проверок отказов прошли (4 прогона); регрессия на коде X: `make test`, `make student_test` (131 passed), `make test_isolated`, `make test-persistence`, `make test-failover` для обеих реплик — `PASS`; соединений приложения на рабочем стенде 17 ≤ 2 × 10 | `evidence/tests/scaling-improvement-checks.md` |
|
||||
| Цена нового соединения PostgreSQL и пинга | микропроба в реплике рабочего стенда (`cd88b48`): проверка сессии и страница истории через repo, из пула с пингом, без пинга и с новым соединением на итерацию | новое соединение — 11,7–11,8 мс CPU реплики (SCRAM-SHA-256 asyncpg в event loop) и 2,7 мс CPU PostgreSQL против 0,6 и 0,15 мс из пула; пинг при выдаче — +0,13 мс реплики и +0,05 мс PostgreSQL на запрос | `evidence/storage/connection-cost.md` |
|
||||
|
||||
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
|
||||
**Сверка с рубрикой README.** Каждому пункту — строка с командой,
|
||||
наблюдением и файлом:
|
||||
|
||||
| Уровень | Пункт README | Строки таблицы выше |
|
||||
|---|---|---|
|
||||
| 3 | стенд одной командой, ≥2 API, одна точка входа, общие БД и сессии | «3»: стенд одной командой…; итоговая проверка из чистого clone |
|
||||
| 3 | разные запросы одного пользователя — разные реплики без повторного входа, `X-Instance-Id`, LB — основной маршрут | «3»: разные запросы одного пользователя…; `X-Instance-Id` на каждом ответе |
|
||||
| 3 | отказ любой одной реплики: ≤10 с до новых чтений и записей, подтверждённые сообщения доступны, ошибки измерены | «3»: отказ любой одной реплики…; «3»: отказ процесса без graceful; «4»: последовательная остановка каждой реплики |
|
||||
| 3 | повтор с тем же `Idempotency-Key` без дублей: конкурентный, при переключении реплики, неподтверждённая запись | «3»: повтор `POST`…; другое тело с тем же ключом; повтор через другой процесс; при переключении реплики; ключ переживает рестарт; неподтверждённую запись можно повторить; «4»: идемпотентность под параллельными запросами |
|
||||
| 3 | `make test`, persistence и failover проходят, ≥2 наблюдаемых реплики; hook подтверждён составом перезапущенных процессов | публичный smoke; «3»: `make test-persistence` с LB (`StartedAt` всех контейнеров до и после); «3»: отказ любой одной реплики (`STOP_ONE_LOG`, `docker compose ps -a`); failover hook не трогает чужое |
|
||||
| 4 | health/readiness, таймауты, SIGTERM согласованы; LB исключает недоступный backend; период проверок и максимальное время обнаружения | «4» (часть): LB исключает недоступный backend; «4»: health/readiness, таймауты и прекращение приёма при SIGTERM |
|
||||
| 4 | каждая реплика по очереди с восстановлением: RPS, ошибки, время восстановления; идемпотентность параллельными запросами | «4»: последовательная остановка каждой реплики…; «4»: идемпотентность под параллельными запросами |
|
||||
| 4 | лимиты CPU/RAM, порты API не наружу, секреты только где нужно, нет `container_name` | «4»: лимиты CPU/RAM…; порты из `.env` со стендом за LB |
|
||||
| 4 | rolling update под нагрузкой; миграции однократно и совместимы | «4»: rolling update…; «4»: миграции однократно и совместимы; замена при сбое и неготовом стенде |
|
||||
| 5, трек 1 | 1/2/4 реплики при фиксированном бюджете; серия с ростом ресурсов | «5», трек 1: 1/2/4 реплики…; серия с ростом ресурсов |
|
||||
| 5, трек 1 | точка насыщения БД / LB / пула и почему рост перестаёт помогать | «5», трек 1: точка насыщения…; граница пула; точка насыщения БД |
|
||||
| 5, трек 1 | исходные данные, графики, одно подтверждённое улучшение; гипотеза, методика, ограничения | «5», трек 1: исходные данные и графики; уровень шума; одно подтверждённое улучшение (с оговоркой); раздел «Цена масштабирования» |
|
||||
|
||||
Пункты «Что сделать» README закрыты так же: миграции — один прогон
|
||||
сервиса `migrate` до реплик (в журналах реплик alembic нет), sticky
|
||||
session нет (`balance roundrobin` без cookie и stick-table, ответы
|
||||
одной сессии чередуются), новые реплики LB видит через DNS Docker без
|
||||
правки конфига (строка «Масштабирование без правки LB»).
|
||||
|
||||
**Что приложено к PR** (README, «Что должно быть в PR»):
|
||||
`docker-compose.yml`, конфигурация LB `infra/haproxy/haproxy.cfg`,
|
||||
`scripts/restart.sh`, `scripts/stop-one.sh` (и
|
||||
`scripts/rolling-update.sh`), `Dockerfile`, миграции `migrations/` с
|
||||
`alembic.ini`, результаты отказов — `evidence/failover/`,
|
||||
`evidence/rollout/`, `evidence/replicas/`, `evidence/tests/`.
|
||||
|
||||
## Эксперименты и отказы
|
||||
|
||||
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
|
||||
Три вида экспериментов: ручные отказы на рабочем стенде (таблица
|
||||
ниже), профили нагрузки уровня «4» и серии трека 1. Все замеры под
|
||||
нагрузкой — на отдельном проекте compose `mtusi-bench` с теми же
|
||||
образами и `haproxy.cfg`, что у рабочего стенда, генератор k6 — в сети
|
||||
стенда через LB. Хост общий: Apple M3 Pro (6 + 6 ядер, 18 ГиБ), Docker
|
||||
Desktop 29.8.2, ВМ 12 vCPU / 7,7 GiB; перед каждым замером проверены
|
||||
питание от сети, свободная память, отсутствие посторонних контейнеров
|
||||
и выгрузок в swap (паспорта `meta.json`). Версии — раздел «Запуск из
|
||||
чистого clone». Сырые итоги k6, журналы LB и посекундные таблицы лежат
|
||||
рядом со сводками, без токенов и паролей.
|
||||
|
||||
| | Отказ реплик (`failover`) | Поочерёдная замена (`rollout`) | Трек 1 (`scaling_*`) |
|
||||
|---|---|---|---|
|
||||
| Гипотеза | `stop` и `kill` без ошибок недоступности, `pause` исключается ≤ 6,5 с, восстановление ≤ 10 с, без потерь и дублей | 0 ошибок при плановой замене, старая реплика после дренажа запросов не получает | H1–H4 (раздел «Цена масштабирования»), записаны до прогонов |
|
||||
| Лимиты | API 1 CPU / 512 МиБ × 2, PostgreSQL 2 CPU / 1 ГиБ, HAProxy 1 CPU / 256 МиБ, Valkey 0,5 CPU / 128 МиБ — как у рабочего стенда | те же | реплики 1 × 4 … 6 × 1, PostgreSQL 2 или 0,5 CPU; k6 2 CPU / 1 ГиБ, сэмплер 0,25 CPU; сумма ≤ 12 vCPU |
|
||||
| Данные | чат чтения из 1 000 сообщений, отдельный чат записи | те же | чат чтения из 10 000 сообщений, 10 чатов записи |
|
||||
| Нагрузка | открытая модель, постоянная интенсивность: 100 записей с ключом + 100 чтений истории в секунду | та же | открытая модель 70/20/10 (история / запись / `users/me`): 250 и 500/с, затем поиск R* по ступеням |
|
||||
| Длительность, прогрев | фаза 15 с до действия (опорное окно) + 20 с до возврата + 15 с; 6 фаз, ~6 мин | 15 с до замены, замена 8,9 с, ≥ 15 с после; 24 002 запроса | прогрев 15 с (5 с подъёма между ступенями), окно 20 с |
|
||||
| Повторы | один прогон на фазу | один прогон | 3 повтора каждой конфигурации, свежий стенд на ячейку, A/A для шума |
|
||||
| Успешные RPS, ошибки | `stop`, `kill`: ~200/с, 0 ошибок; `pause`: 99–100/с в окне, 584–602 × 504 | 200/с, 0 ошибок | R* 630–2 034 запросов/с при ошибках ≤ 1 % |
|
||||
| p50 / p95 / p99 | фаза `stop` 1: 3,5 / 6,1 / 97,1 мс за прогон; p95 по секундам — до 505 мс в секунду действия | 3,3 / 5,0 / 9,7 мс за прогон | p95 / p99 на 500/с по конфигурациям — таблица R* |
|
||||
| CPU / RAM | только лимиты, использование не снималось | только лимиты | посекундно у каждого контейнера и ВМ (`samples.csv`), CPU на запрос по компонентам |
|
||||
| Файлы | `evidence/failover/baseline/` | `evidence/rollout/baseline/` | `evidence/bench/scaling-*/`, `evidence/plots/`, `evidence/compare/` |
|
||||
|
||||
Ограничения каждого замера — в конце его раздела, сводно — «Ограничения
|
||||
и следующие шаги».
|
||||
|
||||
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
|
||||
| --- | --- | --- | --- |
|
||||
@@ -1464,7 +1685,46 @@ CHANGE=scaling-improvement`
|
||||
|
||||
## Ограничения и следующие шаги
|
||||
|
||||
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
|
||||
**Сводно.**
|
||||
|
||||
- **Выдерживается:** отказ процесса API — остановка, убийство или
|
||||
зависание любой одной реплики при второй живой (измерено: `stop` и
|
||||
`kill` без ошибок недоступности, `pause` — 504 до исключения за
|
||||
≤ 6,5 с); рестарт всего стенда с volumes; отказ Valkey (обход в
|
||||
PostgreSQL); плановая замена реплик под нагрузкой без ошибок; повтор
|
||||
отправки с тем же ключом через любую реплику.
|
||||
- **Не выдерживается:** отказ хоста, HAProxy и PostgreSQL — это единые
|
||||
точки отказа, устойчивость к ним не заявляется (трек 2 не выбран).
|
||||
Отказ PostgreSQL — 503 на всё, данные целы, после его возврата
|
||||
стенд работает без рестарта.
|
||||
- **Не реализовано:** уборка таблицы ключей идемпотентности (до worker
|
||||
лабы 5), автоматический откат замены, contract-миграции,
|
||||
`429`/лимит частоты входа, HA для LB и БД.
|
||||
- **Учебные упрощения:** один Docker-host; все замеры — на нём же
|
||||
вместе с генератором; один прогон на фазу у профилей уровня «4»;
|
||||
`X-Instance-Id` — hostname контейнера (непрозрачный alias — лаба 7).
|
||||
- **Подтверждено:** цепочка таймаутов и время обнаружения (замер по
|
||||
режимам), отсутствие ошибок при плановой замене; в треке 1 — граница
|
||||
пула (H3), насыщение PostgreSQL управляемым опытом (серия `db`) и
|
||||
механизм H1 (один процесс не занимает больше ядра при лимите 4 CPU),
|
||||
хотя H1 по заранее записанным критериям целиком не подтверждена
|
||||
(2 × 2 = 1,65 × при пороге 1,7). H1б и H2 опровергнуты, вместо H2
|
||||
подтвердилась конкурирующая H2-хост. Улучшение «пул без
|
||||
переполнения» — механизм подтверждён, R* +18,3 % при шуме 5,4 %, но
|
||||
по букве заранее записанного критерия дрейфа не прошло; засчитано
|
||||
решением автора с оговоркой (ниже).
|
||||
- **Пока гипотеза:** почему на дефолтных лимитах рост останавливает
|
||||
хост (энергоэффективные ядра, частота, гипервизор — замер не
|
||||
разделяет); выигрыш пинга только после простоя соединения; эффект
|
||||
пула 10 + 0 на дефолтных лимитах PostgreSQL.
|
||||
|
||||
**Следующие шаги:** ранний обработчик SIGTERM или `init` для реплики
|
||||
(`KNOWN_ISSUES.md`); пинг соединения только после простоя (design
|
||||
`scaling-improvement`, решение 6); причинная проба хоста («грелка» на
|
||||
6 vCPU); фоновая уборка ключей в worker лабы 5; повтор замеров уровня
|
||||
«4» с несколькими прогонами на фазу; пункты `KNOWN_ISSUES.md`
|
||||
(evidence лабы 2 в исключениях сверки покрытия, буфер событий Docker в
|
||||
профиле `failover`).
|
||||
|
||||
Идемпотентность:
|
||||
|
||||
@@ -1782,3 +2042,117 @@ PostgreSQL 0,5 CPU база насыщается около 950–1 000/с (тр
|
||||
ошибками. Поэтому R* — максимальная интенсивность, которую стенд держит
|
||||
с p95 ≤ 200 мс и ошибками ≤ 1 %, а не число, подогнанное
|
||||
под скорость ответов.
|
||||
|
||||
## Источники, библиотеки и использование ИИ
|
||||
|
||||
**Документация** (официальные страницы; где точный адрес раздела не
|
||||
указан — корень документации, раздел назван словами):
|
||||
- HAProxy 3.4 — <https://docs.haproxy.org/>: Configuration Manual
|
||||
(`server-template`, `resolvers`, `init-state`, `option httpchk`,
|
||||
`inter` / `fastinter` / `downinter`, `fall` / `rise`, `timeout check`,
|
||||
`retry-on`, `option redispatch`, `http-reuse`, `http-error`,
|
||||
`monitor-uri`), Management Guide (stats socket, `set server … state`,
|
||||
`show servers state`, CSV статистики).
|
||||
- PostgreSQL 18 — <https://www.postgresql.org/docs/18/>:
|
||||
[клиентские параметры](https://www.postgresql.org/docs/18/runtime-config-client.html)
|
||||
(`statement_timeout`, `lock_timeout`,
|
||||
`idle_in_transaction_session_timeout`),
|
||||
[статистика](https://www.postgresql.org/docs/18/monitoring-stats.html)
|
||||
(`pg_stat_activity`, `pg_stat_database`, `pg_stat_wal`, `pg_stat_io`),
|
||||
[коды ошибок](https://www.postgresql.org/docs/18/errcodes-appendix.html)
|
||||
(53300), `max_connections`, `INSERT … ON CONFLICT`, отложенные
|
||||
ограничения (`DEFERRABLE INITIALLY DEFERRED`), явные блокировки
|
||||
`ALTER TABLE`.
|
||||
- SQLAlchemy 2.1 — <https://docs.sqlalchemy.org/>: Connection Pooling
|
||||
(`QueuePool`, `pool_size`, `max_overflow`, `pool_pre_ping`), asyncio
|
||||
extension; исходники `QueuePool` — почему соединения сверх
|
||||
`pool_size` закрываются при возврате.
|
||||
- asyncpg — <https://magicstack.github.io/asyncpg/>: параметры
|
||||
подключения; исходники аутентификации SCRAM-SHA-256 (цена нового
|
||||
соединения).
|
||||
- k6 — <https://grafana.com/docs/k6/latest/>: сценарии и executors
|
||||
`constant-arrival-rate` и `ramping-arrival-rate` (открытая модель),
|
||||
`preAllocatedVUs`, `dropped_iterations`, итоговый JSON.
|
||||
- FastAPI — <https://fastapi.tiangolo.com/>: параметры `Header`,
|
||||
зависимости, порядок валидации, обработчики исключений.
|
||||
- uvicorn — <https://www.uvicorn.org/settings/>: `timeout_keep_alive`,
|
||||
`timeout_graceful_shutdown`, поведение по SIGTERM.
|
||||
- Docker Compose — <https://docs.docker.com/reference/compose-file/>:
|
||||
[services](https://docs.docker.com/reference/compose-file/services/)
|
||||
(`depends_on` с условиями, `stop_grace_period`, `healthcheck`,
|
||||
`start_interval`),
|
||||
[deploy](https://docs.docker.com/reference/compose-file/deploy/)
|
||||
(`replicas`, `resources.limits`); CLI `docker compose up --scale
|
||||
--no-recreate --wait`, `docker events`, `docker stop` / `kill` /
|
||||
`pause` — <https://docs.docker.com/reference/cli/docker/>.
|
||||
- Linux — [cgroup v2](https://docs.kernel.org/admin-guide/cgroup-v2.html)
|
||||
(`cpu.stat`, троттлинг CFS, `memory.current`) и
|
||||
[PSI](https://docs.kernel.org/accounting/psi.html) для сэмплера
|
||||
трека 1.
|
||||
- Из лабы 2 — alembic, argon2-cffi, redis-py, Valkey (источники
|
||||
перечислены в отчёте лабы 2).
|
||||
|
||||
**Библиотеки и образы:** FastAPI, pydantic, pydantic-settings,
|
||||
structlog, SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py, uvicorn
|
||||
(версии — раздел «Запуск из чистого clone»); тесты — pytest, httpx;
|
||||
стенд — HAProxy, PostgreSQL, Valkey, k6 в закреплённых образах.
|
||||
Чужой код не копировался. Логгер и форма Makefile перенесены из
|
||||
собственного учебного проекта автора (bp_proxies,
|
||||
`.claude/rules/logging.md`).
|
||||
|
||||
**Использование ИИ.** Инструмент — Claude Code, модель Claude Opus 5.5.
|
||||
Работа велась по changes OpenSpec (`openspec/changes/archive/`, шесть
|
||||
changes лабы 3). Каждый change проходил этапы propose → apply → verify →
|
||||
правки по verify и archive. Каждый этап выполнял отдельный субагент,
|
||||
основная сессия координировала: передавала этапы, проверяла итоги,
|
||||
присылала автору прогресс. 77 из 81 commit после skeleton помечены
|
||||
`Co-Authored-By: Claude`; остальные четыре сделал скрипт `make bench_ab`
|
||||
по ходу замера.
|
||||
|
||||
Что делал ИИ:
|
||||
- код приложения, миграции, `docker-compose.yml`, `haproxy.cfg`,
|
||||
скрипты `restart.sh`, `stop-one.sh`, `rolling-update.sh`;
|
||||
- собственные тесты `student-tests/` и стенды проверок отказов;
|
||||
- стенд замеров `bench/` (профили `failover`, `rollout`, серии трека 1,
|
||||
сэмплер, графики, сравнение меток);
|
||||
- запуск замеров и проверок, evidence, этот отчёт, правила
|
||||
`.claude/rules/` и спеки OpenSpec.
|
||||
|
||||
Что решал автор:
|
||||
- выбор трека 1 «Цена масштабирования» и Compose + HAProxy без Swarm
|
||||
(2026-10-07, `PLAN.md`);
|
||||
- согласования с преподавателем (FastAPI, `config.toml`);
|
||||
- по verify `scaling-bench`: исправить ответ на «too many clients»
|
||||
(500 → 503, правка `68edc66`) и добавить серию `db` с насыщением
|
||||
PostgreSQL (`scaling-db`), потому что на дефолтных лимитах база не
|
||||
насыщалась;
|
||||
- сократить замеры улучшения до двух ячеек (`4x1-pg0.5`, `4x1-pg2`,
|
||||
профиль `db4`) до начала замеров;
|
||||
- переснять улучшение на тихом хосте после помех macOS (iCloud, Zoom)
|
||||
в попытке 1;
|
||||
- засчитать улучшение с оговоркой по пункту дрейфа после результатов
|
||||
попытки 2 (design `scaling-improvement`, п. 4);
|
||||
- коммиты и замеры в автономном режиме — с условием: перед каждым
|
||||
замером проверка хоста, при плохом состоянии — остановка и вопрос.
|
||||
|
||||
Как проверялось:
|
||||
- verify каждого change отдельным субагентом: сверка с задачами, спеками
|
||||
и рубрикой; найденное правилось и evidence переснималось с
|
||||
закоммиченного кода (например, `lock_timeout`, равный
|
||||
`statement_timeout`, давал 503 запросам в очереди за миграцией;
|
||||
уборка при Ctrl+C внутри `up --scale` оставляла третью реплику; см.
|
||||
разделы выше);
|
||||
- публичные проверки skeleton (`make test`, `make test-persistence`,
|
||||
`make test-failover`) и собственные тесты (`make student_test`,
|
||||
`make failure_checks`, `make test_isolated`) на итоговом коде каждого
|
||||
change и из чистого clone;
|
||||
- гипотезы трека 1 и критерии улучшения закоммичены до замеров, шум
|
||||
отделён A/A той же сессии; хост проверялся перед каждой серией;
|
||||
- ошибки ИИ, найденные по ходу, описаны в отчёте как есть: ошибочный
|
||||
пункт `KNOWN_ISSUES.md` о `make run_docker` (диагноз по digest
|
||||
конфигурации образа containerd), 500 вместо 503 на 53300, первая
|
||||
попытка замера улучшения на зашумлённом хосте.
|
||||
|
||||
Утверждения отчёта о поведении стенда подтверждены командами, выводы
|
||||
которых лежат в `evidence/`; решения, перечисленные выше, принимал
|
||||
автор.
|
||||
|
||||
@@ -0,0 +1,232 @@
|
||||
# Итоговая проверка из чистого clone: стенд с LB на портах по умолчанию
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Что проверялось | раздел `REPORT.md` «Запуск из чистого clone» — буквально, шаг за шагом, как у проверяющего |
|
||||
| Дата | 2026-10-11 18:41–18:47 UTC |
|
||||
| Commit | `67b4303` — `git clone --branch solution/bvt2301-safronov` локального репозитория во временный каталог; рабочее дерево клона чистое, `.env`, `config.toml` и `.venv` нет. Код итогового commit отличается от него только `REPORT.md` и этим файлом |
|
||||
| Стенд | проект compose `mtusi-lab3` (имя из `docker-compose.yml`, без `COMPOSE_PROJECT_NAME`), порты по умолчанию: LB `127.0.0.1:8080`, Postgres 5433, Valkey 6380. Рабочий стенд с тем же именем проекта перед проверкой удалён вместе с volume (`make wipe_data`), чтобы клон стартовал на пустой базе со своим паролем, как у проверяющего. После проверки стенд клона удалён (`docker compose down -v`), рабочий поднят заново `make run_docker` |
|
||||
| Хост | Docker Desktop 29.8.2, Compose v5.5.1, macOS arm64 (Apple M3 Pro); ВМ Docker: 12 CPU, 7,7 GiB RAM; `python3` 3.11.9, uv 0.12.17 |
|
||||
|
||||
Пароли из сгенерированного `.env` не выводились: проверялось только,
|
||||
что они есть (32 hex-символа).
|
||||
|
||||
## Подготовка и запуск
|
||||
|
||||
```text
|
||||
$ git clone --branch solution/bvt2301-safronov <репозиторий> clean-clone && cd clean-clone
|
||||
$ git log --oneline -1; git status --short | wc -l; ls .env config.toml
|
||||
67b4303 docs: archive scaling-improvement and sync its specs
|
||||
0
|
||||
ls: .env: No such file or directory
|
||||
ls: config.toml: No such file or directory
|
||||
|
||||
$ make env_setup # exit 0
|
||||
env ready: .env, config.toml
|
||||
$ grep -c -E '^(POSTGRES|VALKEY)_PASSWORD=.{32}$' .env
|
||||
2
|
||||
|
||||
$ make run_docker # exit 0, 4,3 с (слои — из кэша BuildKit)
|
||||
DOCKER_BUILDKIT=1 docker compose build
|
||||
Image mtusi-messenger:lab3 Building
|
||||
#4 [internal] load metadata for docker.io/library/python:3.12.14-slim-trixie@sha256:f77ac9e4…
|
||||
Container mtusi-lab3-postgres-1 Healthy
|
||||
Container mtusi-lab3-valkey-1 Healthy
|
||||
Container mtusi-lab3-migrate-1 Exited
|
||||
Container mtusi-lab3-api-1 Started
|
||||
Container mtusi-lab3-api-2 Started
|
||||
Container mtusi-lab3-haproxy-1 Started
|
||||
|
||||
$ docker compose ps -a --format 'table {{.Name}}\t{{.Status}}\t{{.Ports}}'
|
||||
NAME STATUS PORTS
|
||||
mtusi-lab3-api-1 Up 9 seconds (healthy) 8080/tcp
|
||||
mtusi-lab3-api-2 Up 9 seconds (healthy) 8080/tcp
|
||||
mtusi-lab3-haproxy-1 Up 9 seconds (healthy) 127.0.0.1:8080->8080/tcp
|
||||
mtusi-lab3-migrate-1 Exited (0) 10 seconds ago
|
||||
mtusi-lab3-postgres-1 Up 13 seconds (healthy) 127.0.0.1:5433->5432/tcp
|
||||
mtusi-lab3-valkey-1 Up 13 seconds (healthy) 127.0.0.1:6380->6379/tcp
|
||||
|
||||
$ docker compose logs migrate --no-log-prefix | tail -5 # поле event
|
||||
Running upgrade -> 16c279725564, added messenger tables
|
||||
Running upgrade 16c279725564 -> 42bc3b9be38f, added sessions and password hashes
|
||||
Running upgrade 42bc3b9be38f -> 7652184b7016, added idempotency keys
|
||||
Running upgrade 7652184b7016 -> e656d6bbe1a4, added message instance id
|
||||
Finished alembic
|
||||
```
|
||||
|
||||
`8080/tcp` у реплик — `EXPOSE` образа: опубликованного порта у них
|
||||
нет, API на хосте — только через HAProxy.
|
||||
|
||||
Сборка без кэша слоёв из того же клона (отдельный тег, затем удалён):
|
||||
|
||||
```text
|
||||
$ docker build --no-cache --pull -t mtusi-clean-check:nocache . # exit 0, 10,5 с
|
||||
$ docker run --rm --entrypoint sh mtusi-clean-check:nocache -c 'id -u; ls /app; …'
|
||||
10001
|
||||
alembic.ini
|
||||
migrations
|
||||
src
|
||||
no-.env
|
||||
no-config.toml
|
||||
```
|
||||
|
||||
Колёса зависимостей `uv sync --locked` берёт из cache mount BuildKit,
|
||||
поэтому 10 с; на машине без кэша добавится их загрузка.
|
||||
|
||||
## Контракт, smoke и распределение
|
||||
|
||||
```text
|
||||
$ make check # exit 0
|
||||
PASS: offline skeleton structure, local refs and Python syntax; application NOT tested.
|
||||
$ uv sync # .venv клона с группой dev
|
||||
$ make validate PYTHON=.venv/bin/python # exit 0
|
||||
PASS: full OpenAPI 3.1 and JSON Schema validation; application NOT tested.
|
||||
$ make test # exit 0
|
||||
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
|
||||
$ make instances
|
||||
11 GET /api/v1/users/me 200 x-instance-id: 437292ccaf78
|
||||
12 GET /api/v1/users/me 200 x-instance-id: 0089ca350b2b
|
||||
user lb_c34d4132: one login, 12 requests with one token
|
||||
437292ccaf78: 6
|
||||
0089ca350b2b: 6
|
||||
instances: 2
|
||||
```
|
||||
|
||||
## `make test-persistence`
|
||||
|
||||
```text
|
||||
$ docker inspect … (до) имя, ID, состояние, StartedAt
|
||||
/mtusi-lab3-api-1 0089ca350b2b running 2026-10-11T18:41:29Z
|
||||
/mtusi-lab3-api-2 437292ccaf78 running 2026-10-11T18:41:29Z
|
||||
/mtusi-lab3-haproxy-1 588c7fcc58e0 running 2026-10-11T18:41:29Z
|
||||
/mtusi-lab3-postgres-1 e4b53ac23602 running 2026-10-11T18:41:26Z
|
||||
/mtusi-lab3-valkey-1 fca2cb095076 running 2026-10-11T18:41:26Z
|
||||
|
||||
$ make test-persistence ACTION_SCRIPT=scripts/restart.sh # exit 0
|
||||
Executing explicit persistence hook; hook output suppressed to avoid leaking secrets.
|
||||
PASS: persistence preserved confirmed data and existing session. Hook scope needs operator evidence.
|
||||
|
||||
$ docker inspect … (после)
|
||||
/mtusi-lab3-api-1 0089ca350b2b running 2026-10-11T18:41:58Z
|
||||
/mtusi-lab3-api-2 437292ccaf78 running 2026-10-11T18:41:58Z
|
||||
/mtusi-lab3-haproxy-1 588c7fcc58e0 running 2026-10-11T18:41:58Z
|
||||
/mtusi-lab3-postgres-1 e4b53ac23602 running 2026-10-11T18:41:54Z
|
||||
/mtusi-lab3-valkey-1 fca2cb095076 running 2026-10-11T18:41:54Z
|
||||
$ docker volume inspect -f '{{.Name}} {{.CreatedAt}}' mtusi-lab3_postgres_data
|
||||
mtusi-lab3_postgres_data 2026-10-11T18:41:25Z
|
||||
```
|
||||
|
||||
Перезапущены LB, обе реплики, Postgres и Valkey: те же ID, новый
|
||||
`StartedAt`. Volume тот же, что создал `make run_docker`.
|
||||
|
||||
## `make test-failover` для каждой реплики
|
||||
|
||||
`STOP_ONE_LOG` — строка hook: какой `TARGET_INSTANCE_ID` выбрал тест и
|
||||
какой контейнер остановлен.
|
||||
|
||||
```text
|
||||
$ STOP_ONE_LOG=<файл> make test-failover ACTION_SCRIPT=scripts/stop-one.sh # exit 0
|
||||
{"observed_instances_before": 2, "successful_writes": 118, "failed_attempts": 0, "first_recovery_seconds": 1.0}
|
||||
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
|
||||
2026-10-11T18:42:05Z TARGET_INSTANCE_ID=0089ca350b2b container=0089ca350b2bcbee… mode=stop
|
||||
$ docker compose ps -a --format 'table {{.Name}}\t{{.ID}}\t{{.Status}}'
|
||||
mtusi-lab3-api-1 0089ca350b2b Exited (0) 14 seconds ago
|
||||
mtusi-lab3-api-2 437292ccaf78 Up 21 seconds (healthy)
|
||||
|
||||
$ make replicas # тот же контейнер api-1 снова healthy
|
||||
$ make lb_stats
|
||||
api-1 172.30.0.5:8080 UP L7OK …
|
||||
api-2 172.30.0.4:8080 UP L7OK …
|
||||
$ curl -s -o /dev/null -D - http://127.0.0.1:8080/health/live | grep -i x-instance-id
|
||||
x-instance-id: 437292ccaf78 # сдвиг очереди round-robin одним запросом
|
||||
|
||||
$ STOP_ONE_LOG=<файл> make test-failover ACTION_SCRIPT=scripts/stop-one.sh # exit 0
|
||||
{"observed_instances_before": 2, "successful_writes": 113, "failed_attempts": 0, "first_recovery_seconds": 0.991}
|
||||
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
|
||||
2026-10-11T18:42:31Z TARGET_INSTANCE_ID=437292ccaf78 container=437292ccaf78… mode=stop
|
||||
$ docker compose ps -a …
|
||||
mtusi-lab3-api-1 0089ca350b2b Up 20 seconds (healthy)
|
||||
mtusi-lab3-api-2 437292ccaf78 Exited (0) 14 seconds ago
|
||||
|
||||
$ make replicas
|
||||
$ STOP_MODE=kill STOP_ONE_LOG=<файл> make test-failover ACTION_SCRIPT=scripts/stop-one.sh # exit 0
|
||||
{"observed_instances_before": 2, "successful_writes": 114, "failed_attempts": 0, "first_recovery_seconds": 0.221}
|
||||
PASS: failover preserved confirmed data and existing session. Hook scope needs operator evidence.
|
||||
2026-10-11T18:42:56Z TARGET_INSTANCE_ID=437292ccaf78 container=437292ccaf78… mode=kill
|
||||
mtusi-lab3-api-2 437292ccaf78 Exited (137) 15 seconds ago
|
||||
|
||||
$ make replicas; make lb_stats
|
||||
api-1 172.30.0.5:8080 UP L7OK 0 205 0 0 5 0
|
||||
api-2 172.30.0.4:8080 UP L7OK 0 307 0 0 2 0
|
||||
BACKEND - UP - 0 507 2 0 7 2
|
||||
free slots: 6
|
||||
```
|
||||
|
||||
Остановлены по очереди обе реплики: ID остановленного контейнера
|
||||
совпадает с `TARGET_INSTANCE_ID`, остальные работают; первая запись
|
||||
после остановки — через 1,0 и 0,99 с (`stop`) и 0,22 с (`kill`),
|
||||
неудачных попыток 0. У слотов реплик 5xx нет; два `hrsp_5xx` у
|
||||
`BACKEND` — ответы самого LB. Счётчики обнулил рестарт LB в
|
||||
`restart.sh`, после него тест сохранности ждёт готовности опросом, а
|
||||
до проверок реплик LB отвечает 503 (так же в
|
||||
`evidence/replicas/test-persistence.md`). Журнал LB до уборки клона не
|
||||
сохранялся, так что это объяснение, а не сверка по журналу; клиенту
|
||||
тестов отказа ни одна ошибка не досталась (`failed_attempts` 0).
|
||||
|
||||
## Собственные тесты
|
||||
|
||||
```text
|
||||
$ make student_test # exit 0, 23,7 с
|
||||
coverage: 137 scenarios in 11 specs, 125 tested (18 by make failure_checks), 12 excluded
|
||||
one session, 20 requests: {'437292ccaf78': 10, '0089ca350b2b': 10}
|
||||
key race through replicas: {'437292ccaf78': 5, '0089ca350b2b': 5}
|
||||
===================== 131 passed, 17 deselected in 22.98s ======================
|
||||
|
||||
$ make failure_checks # exit 0, 69 с
|
||||
[failure_checks] project=mtusi-lab3-failures (working stand: mtusi-lab3)
|
||||
test_expired_token PASSED test_readiness_without_database PASSED
|
||||
test_use_does_not_extend_session PASSED test_readiness_without_cache PASSED
|
||||
test_token_while_database_stopped PASSED test_flush_cache PASSED
|
||||
test_members_failure_rolls_back_chat PASSED test_valkey_stopped PASSED
|
||||
test_database_stopped_and_back PASSED test_valkey_paused PASSED
|
||||
test_pool_exhausted PASSED test_valkey_back PASSED
|
||||
test_connection_limit_reached PASSED test_message_failure_keeps_key_free PASSED
|
||||
test_pool_keeps_connections PASSED test_database_outage_keeps_key_free PASSED
|
||||
test_key_free_after_ttl PASSED
|
||||
================ 17 passed, 131 deselected in 60.82s (0:01:00) =================
|
||||
Volume mtusi-lab3-failures_postgres_data Removed
|
||||
Network mtusi-lab3-failures_default Removed
|
||||
|
||||
$ make test_isolated # exit 0, 65 с
|
||||
PASS: lab3 public API scenario; infrastructure and grading evidence remain separate.
|
||||
SKIPPED [1] student-tests/test_idempotency.py:282: one API process (EXPECT_REPLICAS=1): replica checks need the stand with the load balancer
|
||||
… (ещё 3 теста реплик с той же причиной)
|
||||
================ 127 passed, 4 skipped, 17 deselected in 58.11s ================
|
||||
[test_isolated] cleanup
|
||||
[test_isolated] results: {'test': 0, 'student_test': 0}
|
||||
```
|
||||
|
||||
## Уборка и рабочий стенд
|
||||
|
||||
```text
|
||||
$ docker compose down -v # в каталоге клона, проект mtusi-lab3
|
||||
Volume mtusi-lab3_postgres_data Removed
|
||||
Network mtusi-lab3_default Removed
|
||||
$ docker ps -a --filter name=failures -q | wc -l
|
||||
0
|
||||
$ make run_docker # в каталоге рабочего репозитория, exit 0
|
||||
$ docker compose ps --format '{{.Name}} {{.Status}}'
|
||||
mtusi-lab3-api-1 Up 6 seconds (healthy)
|
||||
mtusi-lab3-api-2 Up 6 seconds (healthy)
|
||||
mtusi-lab3-haproxy-1 Up 6 seconds (healthy)
|
||||
mtusi-lab3-postgres-1 Up 9 seconds (healthy)
|
||||
mtusi-lab3-valkey-1 Up 9 seconds (healthy)
|
||||
$ make lb_stats
|
||||
api-1 172.30.0.5:8080 UP L7OK …
|
||||
api-2 172.30.0.4:8080 UP L7OK …
|
||||
free slots: 6
|
||||
```
|
||||
|
||||
Итог: все шаги инструкции из настоящего clone прошли с кодом 0 без
|
||||
правки файлов клона; дефектов не найдено. Стенд лабы 2
|
||||
(`mtusi-lab2_postgres_data`) не затронут.
|
||||
Reference in New Issue
Block a user