forked from mtusi2026/mtusi2026lab3
748 lines
45 KiB
Python
748 lines
45 KiB
Python
# -*- coding: utf-8 -*-
|
||
"""Собрать шпаргалку к защите lab3 (кириллица, Windows Arial)."""
|
||
from pathlib import Path
|
||
|
||
from fpdf import FPDF
|
||
|
||
ROOT = Path(__file__).resolve().parents[1]
|
||
OUT = ROOT / "DEFENSE.pdf"
|
||
FONT = Path(r"C:\Windows\Fonts\arial.ttf")
|
||
FONT_B = Path(r"C:\Windows\Fonts\arialbd.ttf")
|
||
FONT_I = Path(r"C:\Windows\Fonts\ariali.ttf")
|
||
FONT_C = Path(r"C:\Windows\Fonts\consola.ttf")
|
||
if not FONT_C.exists():
|
||
FONT_C = Path(r"C:\Windows\Fonts\cour.ttf")
|
||
|
||
|
||
class Pdf(FPDF):
|
||
def header(self):
|
||
if self.page_no() == 1:
|
||
return
|
||
self.set_font("Body", "", 8)
|
||
self.set_text_color(90, 90, 90)
|
||
self.set_x(self.l_margin)
|
||
self.cell(0, 6, "Lab3 zashchita | Shcherbatsevich | BPI2302 | 5 track 1", align="L")
|
||
self.ln(8)
|
||
self.set_text_color(0, 0, 0)
|
||
self.set_x(self.l_margin)
|
||
|
||
def footer(self):
|
||
self.set_y(-12)
|
||
self.set_font("Body", "", 8)
|
||
self.set_text_color(90, 90, 90)
|
||
self.set_x(self.l_margin)
|
||
self.cell(0, 8, str(self.page_no()), align="C")
|
||
self.set_text_color(0, 0, 0)
|
||
|
||
|
||
def _w(pdf):
|
||
pdf.set_x(pdf.l_margin)
|
||
return pdf.epw
|
||
|
||
|
||
def h1(pdf, text):
|
||
pdf.ln(4)
|
||
pdf.set_font("Body", "B", 16)
|
||
pdf.multi_cell(_w(pdf), 8, text)
|
||
pdf.ln(1)
|
||
|
||
|
||
def h2(pdf, text):
|
||
pdf.ln(3)
|
||
pdf.set_font("Body", "B", 13)
|
||
pdf.multi_cell(_w(pdf), 7, text)
|
||
pdf.ln(1)
|
||
|
||
|
||
def h3(pdf, text):
|
||
pdf.ln(2)
|
||
pdf.set_font("Body", "B", 11)
|
||
pdf.multi_cell(_w(pdf), 6, text)
|
||
|
||
|
||
def body(pdf, text):
|
||
pdf.set_font("Body", "", 10)
|
||
pdf.multi_cell(_w(pdf), 5.2, text)
|
||
pdf.ln(0.8)
|
||
|
||
|
||
def speak(pdf, text):
|
||
pdf.set_fill_color(235, 243, 255)
|
||
pdf.set_font("Body", "I", 10)
|
||
pdf.multi_cell(_w(pdf), 5.2, "ГОВОРИТЬ: " + text, fill=True)
|
||
pdf.ln(1.5)
|
||
|
||
|
||
def warn(pdf, text):
|
||
pdf.set_fill_color(255, 243, 220)
|
||
pdf.set_font("Body", "B", 10)
|
||
pdf.multi_cell(_w(pdf), 5.2, "НЕ ВРАТЬ: " + text, fill=True)
|
||
pdf.ln(1.5)
|
||
|
||
|
||
def show(pdf, text):
|
||
pdf.set_fill_color(232, 245, 233)
|
||
pdf.set_font("Body", "B", 10)
|
||
pdf.multi_cell(_w(pdf), 5.2, "ПОКАЗАТЬ: " + text, fill=True)
|
||
pdf.ln(1.5)
|
||
|
||
|
||
def code(pdf, text):
|
||
pdf.set_font("Code", "", 7.5)
|
||
pdf.set_fill_color(245, 245, 245)
|
||
pdf.multi_cell(_w(pdf), 4.0, text.rstrip() + "\n", fill=True)
|
||
pdf.ln(1.2)
|
||
|
||
|
||
def bullet(pdf, text):
|
||
pdf.set_font("Body", "", 10)
|
||
pdf.multi_cell(_w(pdf), 5.2, "- " + text)
|
||
pdf.ln(0.3)
|
||
|
||
|
||
def qa(pdf, q, a):
|
||
pdf.set_font("Body", "B", 10)
|
||
pdf.multi_cell(_w(pdf), 5.2, "В: " + q)
|
||
pdf.set_font("Body", "", 10)
|
||
pdf.multi_cell(_w(pdf), 5.2, "О: " + a)
|
||
pdf.ln(1.5)
|
||
|
||
|
||
def build():
|
||
pdf = Pdf(format="A4", unit="mm")
|
||
pdf.set_auto_page_break(auto=True, margin=16)
|
||
pdf.add_font("Body", "", str(FONT))
|
||
pdf.add_font("Body", "B", str(FONT_B))
|
||
pdf.add_font("Body", "I", str(FONT_I))
|
||
pdf.add_font("Code", "", str(FONT_C))
|
||
pdf.add_page()
|
||
pdf.set_font("Body", "B", 22)
|
||
pdf.multi_cell(_w(pdf), 10, "Методичка к защите")
|
||
pdf.set_font("Body", "B", 16)
|
||
pdf.multi_cell(_w(pdf), 8, "Лабораторная 3 — балансировка и отказ API-реплики")
|
||
pdf.ln(2)
|
||
pdf.set_font("Body", "", 11)
|
||
for line in [
|
||
"Автор: Щербацевич Владислав Сергеевич",
|
||
"Группа: БПИ2302",
|
||
"Целевая оценка: 5",
|
||
"Трек: 1 — цена масштабирования (Compose + HAProxy, не Swarm, не трек 2)",
|
||
"Вход: http://127.0.0.1:8080 и http://localhost:8080 (оба должны отвечать)",
|
||
"Этот файл — шпаргалка. Не читать с листа целиком: открывать нужный раздел.",
|
||
]:
|
||
pdf.multi_cell(_w(pdf), 6, line)
|
||
pdf.ln(3)
|
||
body(
|
||
pdf,
|
||
"Как пользоваться на защите. Сначала 90 секунд «что это за система». Потом живой стенд: "
|
||
"два X-Instance-Id, docker ps, stop-one. Код показывают только когда спрашивают «где». "
|
||
"Цифры трека 1 — из REPORT.md и evidence/, не из головы. Если не помните число — откройте JSON.",
|
||
)
|
||
|
||
h1(pdf, "0. Карта выступления (10–15 минут)")
|
||
bullet(pdf, "1 мин — задача лабы и схема Клиент → HAProxy → api×2 → Postgres + Redis.")
|
||
bullet(pdf, "1 мин — живой стенд: curl/браузер, два разных X-Instance-Id, одна сессия.")
|
||
bullet(pdf, "2 мин — docker compose ps: API без host-порта, имена api-N, лимиты.")
|
||
bullet(pdf, "2 мин — идемпотентность: ключ в заголовке, таблица в Postgres, гонка 12 потоков.")
|
||
bullet(pdf, "2 мин — отказ: stop-one, recovery ~2.5 с, вторая реплика.")
|
||
bullet(pdf, "2 мин — уровень 4: ready 1 с fall 2, SIGTERM, rolling, migrate one-shot.")
|
||
bullet(pdf, "3 мин — трек 1: гипотеза, 128/107/69 и 49/105/221, честно про saturation, IPv6.")
|
||
bullet(pdf, "Оставшееся — вопросы.")
|
||
|
||
h1(pdf, "1. Что говорить в первые 90 секунд")
|
||
speak(
|
||
pdf,
|
||
"Это мессенджер с lab2: пользователи, чаты, сообщения, сессии. В lab3 я не размножаю данные, "
|
||
"а размножаю процессы API. Снаружи одна дверь — HAProxy на порту 8080. За ней минимум два "
|
||
"одинаковых контейнера api. Сообщения пишет PostgreSQL, сессии лежат в Redis, не в памяти "
|
||
"процесса. Поэтому можно убить один api — логин не слетает, дублей сообщения нет, если клиент "
|
||
"повторил тот же Idempotency-Key. Sticky-сессий нет: один пользователь разными запросами "
|
||
"попадает на разные реплики — это видно по заголовку X-Instance-Id. Для пятёрки выбран трек 1: "
|
||
"не «ещё узлов», а цена лишних реплик при фиксированном CPU.",
|
||
)
|
||
warn(
|
||
pdf,
|
||
"Не говорить «у нас высокая доступность системы». Выдерживается отказ ОДНОГО процесса API. "
|
||
"Хост, HAProxy, Postgres, Redis — точки отказа. Трек 2 не делался.",
|
||
)
|
||
|
||
h1(pdf, "2. Схема и роли файлов")
|
||
body(
|
||
pdf,
|
||
"Клиент (браузер, smoke, level3) бьёт в localhost:8080. Контейнер lb — HAProxy. Он round-robin "
|
||
"раздаёт на контейнеры сервиса api. Имя api в Docker DNS имеет несколько IP. Postgres — источник "
|
||
"истины (users, chats, messages, idempotency_records, schema_migrations). Redis — сессии, AOF "
|
||
"appendfsync always. Контейнер migrate один раз накатывает SQL и выходит. API сами DDL не гоняют.",
|
||
)
|
||
h3(pdf, "Куда ткнуть курсор, если просят «покажи файл»")
|
||
bullet(pdf, "compose.yaml — весь стенд: сервисы, реплики, лимиты, секреты, нет ports у api, нет container_name.")
|
||
bullet(pdf, "infra/haproxy.cfg — roundrobin, httpchk /health/ready, inter 1s fall 2, live отвечает сам LB.")
|
||
bullet(pdf, "src/app/middleware.py — X-Request-Id и X-Instance-Id, 503 при shutdown.")
|
||
bullet(pdf, "src/app/config.py — instance_id из HOSTNAME.")
|
||
bullet(pdf, "src/app/api/health.py — live vs ready.")
|
||
bullet(pdf, "src/app/main.py — accepting, lifespan SIGTERM.")
|
||
bullet(pdf, "src/app/__main__.py — uvicorn timeout_graceful_shutdown=5.")
|
||
bullet(pdf, "src/app/sessions.py — Redis PXAT, не память процесса.")
|
||
bullet(pdf, "src/app/api/messages.py и src/app/crud/messages.py — Idempotency-Key.")
|
||
bullet(pdf, "migrations/002_idempotency.sql — таблица ключей.")
|
||
bullet(pdf, "src/app/migrate.py и сервис migrate в compose — one-shot.")
|
||
bullet(pdf, "scripts/stop-one.sh (.cmd) — стоп по X-Instance-Id.")
|
||
bullet(pdf, "scripts/rolling-update.sh — новый контейнер до удаления старого.")
|
||
bullet(pdf, "student-tests/level3.py — две реплики + гонка ключа.")
|
||
bullet(pdf, "student-tests/track1.py и evidence/track1.json — пятёрка.")
|
||
bullet(pdf, "REPORT.md — цифры, которые можно зачитать.")
|
||
|
||
h1(pdf, "3. Команды: стенд, тесты, доказательства")
|
||
body(
|
||
pdf,
|
||
"Защита на Windows. В PowerShell из корня репозитория. PYTHONUTF8=1 — чтобы make/python не падали на кириллице. "
|
||
"Секреты не печатать в чат и не открывать на проекторе содержимое secrets/.",
|
||
)
|
||
h3(pdf, "3.1. Поднять с нуля (если стенд ещё нет)")
|
||
code(
|
||
pdf,
|
||
"cd C:\\Users\\Admin\\PycharmProjects\\mtusi2026lab3\n"
|
||
"powershell -ExecutionPolicy Bypass -File scripts\\bootstrap.ps1\n"
|
||
"docker compose --env-file .env config --quiet\n"
|
||
"docker compose --env-file .env up -d --build --wait --scale api=2",
|
||
)
|
||
body(
|
||
pdf,
|
||
"bootstrap создаёт .env и файлы секретов, не коммитятся. config --quiet проверяет compose. "
|
||
"--wait ждёт healthcheck. scale api=2 обязательно: дефолт тоже 2, но на защите произнесите число.",
|
||
)
|
||
h3(pdf, "3.2. Живой пульс")
|
||
code(
|
||
pdf,
|
||
"curl.exe -i http://127.0.0.1:8080/health/live\n"
|
||
"curl.exe -i http://127.0.0.1:8080/health/ready\n"
|
||
"docker compose --env-file .env ps",
|
||
)
|
||
body(
|
||
pdf,
|
||
"live с улицы отдаёт HAProxy: X-Instance-Id: load-balancer — это касса, не реплика. "
|
||
"ready идёт на API. В ps у api колонка PORTS должна быть 8080/tcp БЕЗ 0.0.0.0:xxxx — порты на хост не проброшены. "
|
||
"Доказательство уже снято: evidence/compose-ps.txt.",
|
||
)
|
||
warn(pdf, "Не доказывать разные реплики через /health/live. Только /api/v1/users/me или POST сообщения.")
|
||
|
||
h3(pdf, "3.3. Два instance id одной сессией (сценарий README пункт 1)")
|
||
body(pdf, "Проще всего готовый тест — он логинится сам и 40 раз бьёт /users/me:")
|
||
code(pdf, "$env:PYTHONUTF8='1'\npython student-tests/level3.py")
|
||
body(
|
||
pdf,
|
||
"PASS и evidence/level3.json: unique_instance_ids длина ≥2. Если хотят руками: зарегистрировать пользователя "
|
||
"(examples/requests.http), взять Bearer, повторять GET /api/v1/users/me — заголовок X-Instance-Id должен чередоваться.",
|
||
)
|
||
h3(pdf, "3.4. Публичные проверки курса")
|
||
code(
|
||
pdf,
|
||
"python tests/smoke.py --base-url http://127.0.0.1:8080\n"
|
||
"python student-tests/persistence_hook.py\n"
|
||
"python student-tests/failover.py\n"
|
||
"scripts\\restore-api.cmd\n"
|
||
"python student-tests/failover.py\n"
|
||
"python student-tests/rolling.py",
|
||
)
|
||
body(
|
||
pdf,
|
||
"smoke — контракт lab3 (ключ, replay, 409). persistence — restart стенда, тот же токен, volumes на месте "
|
||
"(scripts/restart.cmd внутри хука). failover — stop-one.cmd по TARGET_INSTANCE_ID. "
|
||
"После первого failover реплик станет 1 — restore-api.cmd возвращает scale 2, второй прогон бьёт уже другую. "
|
||
"На POSIX в README: make test-failover ACTION_SCRIPT=scripts/stop-one.sh. У вас Windows, поэтому .cmd.",
|
||
)
|
||
show(pdf, "Готовые логи: evidence/smoke.txt, persistence.txt, failover.txt, sequential_failover.json, rolling.json, level3.json.")
|
||
|
||
h3(pdf, "3.5. Трек 1 (долго, на защите обычно НЕ гонять заново)")
|
||
code(
|
||
pdf,
|
||
"python student-tests/track1.py\n"
|
||
"python tests/load.py --duration 20 --concurrency 8 --output evidence/load_ipv4.json",
|
||
)
|
||
body(pdf, "Открыть evidence/track1.json и SVG. Повтор прогона — много минут и сменит цифры; для защиты достаточно снятого замера 2026-10-30.")
|
||
|
||
h3(pdf, "3.6. Остановить / поднять")
|
||
code(
|
||
pdf,
|
||
"docker compose --env-file .env down # данные в volumes остаются\n"
|
||
"docker compose --env-file .env down -v # учебное обнуление БД — на защите не делать",
|
||
)
|
||
|
||
h1(pdf, "4. Оценка 3 — что говорить и какой код")
|
||
|
||
h2(pdf, "4.1. Стенд в одном compose, две реплики, одна дверь")
|
||
speak(
|
||
pdf,
|
||
"Весь стенд в compose.yaml, не Swarm. Имя проекта mtusi-lab3. Сервисы: postgres, redis, migrate, api, lb. "
|
||
"Реплик api две. С хоста торчит только lb 127.0.0.1:8080 и [::1]:8080. База и redis на loopback для отладки, "
|
||
"это не API. Образы с digest, не latest.",
|
||
)
|
||
show(pdf, "compose.yaml — services api и lb; блок deploy.replicas; отсутствие ports у api.")
|
||
code(
|
||
pdf,
|
||
" api:\n"
|
||
" deploy:\n"
|
||
" replicas: ${API_REPLICAS:-2}\n"
|
||
" # НЕТ ports: и НЕТ container_name\n"
|
||
" lb:\n"
|
||
" ports:\n"
|
||
" - \"127.0.0.1:8080:8080\"\n"
|
||
" - \"[::1]:8080:8080\"",
|
||
)
|
||
body(
|
||
pdf,
|
||
"Зачем нет container_name: имя контейнера в Docker уникально. Если написать messenger-api, вторую реплику "
|
||
"scale не создаст. Compose сам даёт mtusi-lab3-api-1, api-2.",
|
||
)
|
||
|
||
h2(pdf, "4.2. HAProxy: очередь без прилипания")
|
||
speak(
|
||
pdf,
|
||
"HAProxy — касса с одной дверью. Клиент не знает про два официанта. Алгоритм roundrobin: запросы по кругу. "
|
||
"Cookie нет, IP не клеим — sticky запрещён заданием, иначе скрыли бы, что сессия не общая. "
|
||
"Список бэкендов не руками: server-template спрашивает Docker DNS имя api, до 4 слотов. "
|
||
"Проверка живости — GET /health/ready каждые 1 с, два провала — вон из круга.",
|
||
)
|
||
show(pdf, "infra/haproxy.cfg целиком, особенно backend api.")
|
||
code(
|
||
pdf,
|
||
"frontend public\n"
|
||
" bind *:8080\n"
|
||
" http-request return status 200 ... hdr X-Instance-Id \"load-balancer\" ... if { path /health/live }\n"
|
||
" default_backend api\n"
|
||
"backend api\n"
|
||
" balance roundrobin\n"
|
||
" option httpchk\n"
|
||
" http-check send meth GET uri /health/ready ...\n"
|
||
" http-check expect status 200\n"
|
||
" default-server inter 1s fall 2 rise 1 resolvers docker ...\n"
|
||
" server-template api 4 api:8080 check",
|
||
)
|
||
body(
|
||
pdf,
|
||
"Почему не Nginx: свободный выбор, взяли HAProxy 3.2 с docker resolvers. Почему live на LB: контракт хочет, "
|
||
"чтобы публичный live проверял процесс ВХОДА. Ready — можно ли давать работу этой реплике (БД+Redis+accepting).",
|
||
)
|
||
|
||
h2(pdf, "4.3. X-Instance-Id и X-Request-Id")
|
||
speak(
|
||
pdf,
|
||
"Request-Id — имя письма, каждый запрос новый UUID, его клеит middleware. Instance-Id — имя почтальона: "
|
||
"пока жив процесс, строка одна. Берётся из переменной INSTANCE_ID, иначе HOSTNAME контейнера. "
|
||
"В базу не пишется. Нужен, чтобы доказать две реплики и чтобы stop-one нашёл контейнер. "
|
||
"Request-Id для docker stop бесполезен.",
|
||
)
|
||
show(pdf, "src/app/config.py функция _instance_id; src/app/middleware.py; src/app/main.py app.state.instance_id")
|
||
code(
|
||
pdf,
|
||
"# config.py\n"
|
||
"configured = os.environ.get(\"INSTANCE_ID\", \"\").strip()\n"
|
||
"if configured: return configured\n"
|
||
"host = os.environ.get(\"HOSTNAME\", \"\").strip() or socket.gethostname()\n"
|
||
"return host\n"
|
||
"\n"
|
||
"# middleware.py\n"
|
||
"response.headers[\"X-Request-Id\"] = request_id\n"
|
||
"response.headers[\"X-Instance-Id\"] = _instance_id(request)",
|
||
)
|
||
|
||
h2(pdf, "4.4. Общие сессии — почему не память API")
|
||
speak(
|
||
pdf,
|
||
"Если сессию хранить в словаре Python, второй контейнер не узнает токен — после round-robin будет 401, "
|
||
"придётся логиниться снова. Redis общий. Ключ sess:sha256(token), TTL абсолютный PXAT, чтобы после "
|
||
"рестарта Redis из AOF срок не продлился. AOF appendfsync always — учебная сохранность при restart.",
|
||
)
|
||
show(pdf, "src/app/sessions.py create_session / resolve_session; compose redis command --appendonly yes")
|
||
code(
|
||
pdf,
|
||
"token = secrets.token_urlsafe(32)\n"
|
||
"await redis.set(session_key(token), payload, pxat=int(expires_at.timestamp() * 1000))",
|
||
)
|
||
|
||
h2(pdf, "4.5. Идемпотентность POST сообщения")
|
||
speak(
|
||
pdf,
|
||
"Ключ придумывает клиент, не человек в UI и не сервер. Сервер только читает заголовок Idempotency-Key. "
|
||
"Без него 400. Область: пользователь + POST + путь чата + строка ключа. Хранится в Postgres таблица "
|
||
"idempotency_records. Повтор того же текста — тот же message id. Другой текст — 409. Другой пользователь "
|
||
"с тем же ключом — другое сообщение. Параллель: pg_advisory_xact_lock, чтобы два API не вставили два сообщения. "
|
||
"Пишем Message, flush, потом запись ключа — в одной транзакции. 5xx не сохраняем: если упали до INSERT ключа, "
|
||
"клиент может повторить тот же ключ.",
|
||
)
|
||
show(pdf, "src/app/api/messages.py require_idempotency_key; crud/messages.py create_message; migrations/002_idempotency.sql")
|
||
code(
|
||
pdf,
|
||
"# api: без заголовка — 400\n"
|
||
"value = request.headers.get(\"idempotency-key\")\n"
|
||
"\n"
|
||
"# crud: замок по user+path+key, потом SELECT ключа\n"
|
||
"SELECT pg_advisory_xact_lock(:a, :b)\n"
|
||
"# тот же hash текста → вернуть старое сообщение\n"
|
||
"# другой hash → 409\n"
|
||
"# нет записи → INSERT messages, INSERT idempotency_records status 201",
|
||
)
|
||
body(
|
||
pdf,
|
||
"Генерация ключа в тестах: tests/client.py — uuid.uuid4().hex если вызывающий не передал key. "
|
||
"Гонка: student-tests/level3.py функция test_concurrent_key — Barrier на 12 потоков, один ключ, "
|
||
"ожидаем 12×201 и один id, в истории одна копия. Запускается внутри python student-tests/level3.py.",
|
||
)
|
||
|
||
h2(pdf, "4.6. Failover ≤ 10 секунд")
|
||
speak(
|
||
pdf,
|
||
"Тест читает X-Instance-Id из ответа, кладёт в TARGET_INSTANCE_ID, вызывает scripts/stop-one.cmd. "
|
||
"Скрипт сверяет hostname/имя/id контейнера и docker stop -t 5. HAProxy за ~2 с (1 с × fall 2) выкидывает "
|
||
"труп из круга. Живая реплика продолжает. Сессия в Redis, сообщения в Postgres — повторный логин не нужен. "
|
||
"Измеренный recovery 2.46 с, ошибок 2 из 93. Курс просит не больше 10 с. Краткие ошибки в момент обнаружения допустимы.",
|
||
)
|
||
show(pdf, "scripts/stop-one.sh и stop-one.cmd; student-tests/failover.py; evidence/failover.txt и sequential_failover.json")
|
||
code(
|
||
pdf,
|
||
"# stop-one.sh\n"
|
||
"hostname=$(docker inspect -f '{{.Config.Hostname}}' \"$id\")\n"
|
||
"if [ \"$TARGET_INSTANCE_ID\" = \"$hostname\" ] || ...; then found=$id; fi\n"
|
||
"docker stop -t 5 \"$found\"",
|
||
)
|
||
body(
|
||
pdf,
|
||
"После первого стопа restore-api.cmd поднимает вторую реплику. Повтор failover.py бьёт уже её. "
|
||
"Отдельно в отчёте docker stop второй: пишет оставшийся api, recovery почти 0, потому что касса уже на живом. "
|
||
"Показать docker compose ps — один Exited, второй healthy.",
|
||
)
|
||
|
||
h1(pdf, "5. Оценка 4")
|
||
|
||
h2(pdf, "5.1. Health, таймауты, SIGTERM, период проверки")
|
||
speak(
|
||
pdf,
|
||
"Live — процесс существует. Ready — принимаем работу: accepting=True, SELECT 1 в Postgres, ping Redis. "
|
||
"HAProxy проверяет ready, не live: иначе труп без базы остался бы в круге. "
|
||
"Период проверок: inter 1s. Максимум обнаружения отказа: fall 2 → около 2 секунд; с DNS hold valid 2s верхняя оценка около 4 с. "
|
||
"SIGTERM: compose stop_signal SIGTERM, stop_grace_period 8s, uvicorn timeout_graceful_shutdown 5. "
|
||
"В finally lifespan accepting=False — ready и бизнес отдают 503, касса выкидывает бэкенд до убийства процесса.",
|
||
)
|
||
show(pdf, "health.py; main.py lifespan; __main__.py uvicorn; compose stop_grace_period; haproxy inter/fall")
|
||
code(
|
||
pdf,
|
||
"# health.py ready\n"
|
||
"if not request.app.state.accepting: 503\n"
|
||
"SELECT 1; redis.ping()\n"
|
||
"\n"
|
||
"# main.py finally\n"
|
||
"app.state.accepting = False\n"
|
||
"\n"
|
||
"# middleware: если not accepting и путь не /health/live → 503",
|
||
)
|
||
|
||
h2(pdf, "5.2. По очереди обе реплики, RPS, идемпотентность параллельно")
|
||
body(
|
||
pdf,
|
||
"Цифры зачитать из REPORT / sequential_failover.json, не путать с 128 RPS трека 1 — другой клиент.",
|
||
)
|
||
bullet(pdf, "stop той, что ответила: recovery 2.46 с, 91 успех / 2 ошибки, 6.07 RPS, окно 15 с.")
|
||
bullet(pdf, "restore + ещё раз: 2.74 с, 90/2, 6.00 RPS.")
|
||
bullet(pdf, "stop второй: ~0.03 с, 46/1, 3.83 RPS.")
|
||
bullet(pdf, "параллельный ключ: level3, 12 потоков, один id.")
|
||
|
||
h2(pdf, "5.3. Лимиты, секреты, нет порта API")
|
||
speak(
|
||
pdf,
|
||
"У каждого сервиса deploy.resources.limits. api 0.50 CPU / 256M каждая. Секреты Docker: postgres_password "
|
||
"только postgres, database_url — migrate и api, cache_url только api. HAProxy паролей не видит. "
|
||
"Volume только postgres_data и redis_data — у api своего диска с чатами нет.",
|
||
)
|
||
show(pdf, "compose.yaml secrets, volumes, deploy.resources, отсутствие ports у api, отсутствие container_name.")
|
||
|
||
h2(pdf, "5.4. Rolling и миграции один раз")
|
||
speak(
|
||
pdf,
|
||
"Rolling не равен failover. Failover — убили живого. Rolling — сначала подняли нового, потом стопнули старого, "
|
||
"по одной штуке, под нагрузкой. Скрипт: scale N+1, wait, docker stop -t 5 старого, rm, вернуть scale N. "
|
||
"Замер: rolling.json, 1980 ok / 24 err (1.2%), оба старых instance id исчезли. Ненулевые ошибки на стыке DNS нормальны.",
|
||
)
|
||
show(pdf, "scripts/rolling-update.sh; student-tests/rolling.py")
|
||
speak(
|
||
pdf,
|
||
"Миграции: сервис migrate, restart no, python -m app.migrate, API depends_on service_completed_successfully, "
|
||
"RUN_MIGRATIONS=0. API ждут schema_migrations. Совместимость: rolling одной версии API; схему заранее накатил migrate. "
|
||
"Не обещаем lab2 и lab3 одновременно. Ограничение честно: откат схемы не делали.",
|
||
)
|
||
show(pdf, "compose.yaml service migrate; src/app/migrate.py pg_advisory_xact_lock; main.py wait_for_schema")
|
||
|
||
h1(pdf, "6. Оценка 5 — трек 1")
|
||
|
||
h2(pdf, "6.1. Речь 2–3 минуты")
|
||
speak(
|
||
pdf,
|
||
"Трек 1 — цена масштабирования. Гипотеза: при фиксированном суммарном CPU добавление реплик не ускоряет POST, "
|
||
"потому что режется CPU каждого процесса, а не потому что кончилась база. "
|
||
"Методика: один профиль, 8 closed-loop клиентов через HAProxy, прогрев 5 с, замер 20 с. "
|
||
"Серия A: всегда 1.0 CPU и 512 MiB на все API, реплик 1, 2, 4. "
|
||
"Серия B: всегда 2 реплики, CPU растёт 0.5 → 1 → 2 суммарно. "
|
||
"A: 128 → 107 → 69 RPS. Четыре реплики на том же ватте почти вдвое медленнее одной. Ошибок 0. "
|
||
"B: 49 → 105 → 221. Дали CPU — почти линейно. Значит запас по Postgres был. "
|
||
"Улучшение: bind [::1]:8080, иначе Windows localhost давал p50 две секунды.",
|
||
)
|
||
|
||
h2(pdf, "6.2. Где цифры")
|
||
show(pdf, "REPORT.md таблица; evidence/track1.json; графики track1_fixed_budget.svg и track1_growing_cpu.svg")
|
||
bullet(pdf, "fixed-1: 1×1.00 CPU, 128.1 RPS, p50 52 мс")
|
||
bullet(pdf, "fixed-2: 2×0.50, 107.5 RPS, p50 72 мс")
|
||
bullet(pdf, "fixed-4: 4×0.25, 69.3 RPS, p50 95 мс")
|
||
bullet(pdf, "grow-2×0.25: сумма 0.50 CPU, 49.1 RPS")
|
||
bullet(pdf, "grow-2×0.50: сумма 1.00, 105.5 RPS")
|
||
bullet(pdf, "grow-2×1.00: сумма 2.00, 221.0 RPS")
|
||
body(
|
||
pdf,
|
||
"Скрипт student-tests/track1.py: scale_api, docker update --cpus/--memory, run_load 8 потоков POST /messages. "
|
||
"Closed-loop: следующий запрос только после ответа, RPS ≈ 8 / среднее время.",
|
||
)
|
||
|
||
h2(pdf, "6.3. Saturation point — как не попасть")
|
||
warn(
|
||
pdf,
|
||
"В README написано «найдите saturation point БД/LB/пула». Классического плато этих трёх НЕТ. "
|
||
"Серия B ещё растёт до 221, postgres в docker stats доли процента, пул 10+10 на реплику, при 4 репликах до 80 "
|
||
"соединений при max_connections 100, ошибок 0. Мы НЕ дожали базу до потолка. Это дырка по букве задания. "
|
||
"Закрываем её честным текстом, не выдуманным «Postgres на 100%».",
|
||
)
|
||
speak(
|
||
pdf,
|
||
"Искали насыщение Postgres, HAProxy и пула. На этом профиле они не насытились: stats пустые, при росте CPU "
|
||
"RPS ещё линейный. То, что видно: при фиксированном бюджете рост ЧИСЛА реплик перестаёт помогать и вредит — "
|
||
"это нарезка CPU API. Чтобы поймать плато базы, нужен более жёсткий профиль, его нет в evidence. "
|
||
"Это ограничение опыта, записано в конце REPORT.md.",
|
||
)
|
||
body(
|
||
pdf,
|
||
"Где «показано» в работе: абзац под таблицей в REPORT.md и массивы docker_stats в track1.json "
|
||
"(имена postgres-1, lb-1, api-*). Отрицательный результат: они не bottleneck. "
|
||
"Не ищите слайд «база 100%» — его нет.",
|
||
)
|
||
|
||
h2(pdf, "6.4. Подтверждённое улучшение")
|
||
body(
|
||
pdf,
|
||
"Задание не требует конкретно IPv6. Требует одно измеренное до/после. В отчёте взяли вход. "
|
||
"Было только 127.0.0.1:8080. Windows localhost идёт в ::1, p50 ≈ 2 с, ≈1.9 RPS. "
|
||
"Добавили [::1]:8080. После: localhost 87.6 RPS p50 75 мс, 127.0.0.1 94.7 RPS. "
|
||
"Файлы: compose.yaml ports lb; evidence/load_localhost.json. "
|
||
"Это не «серия B». Серия B — обязательный второй опыт, не фикс.",
|
||
)
|
||
|
||
h2(pdf, "6.5. Ограничения трека, которые сами назвать первым")
|
||
bullet(pdf, "Один Docker-host. Отказ VM/ноутбука не переживается.")
|
||
bullet(pdf, "Один HAProxy, одна Postgres, один Redis — SPOF.")
|
||
bullet(pdf, "Closed-loop занижает абсолютный RPS; сравнивать отношения точек, не 128 с одногруппником.")
|
||
bullet(pdf, "docker stats --no-stream — кадр в конце, не среднее; не объяснять 24% vs 0.7% как «вторая не работала».")
|
||
bullet(pdf, "Две реплики для failover, не для скорости при 1 CPU. Это разные оси.")
|
||
bullet(pdf, "Гипотеза в исходнике track1.py чуть старая про Postgres; в JSON и REPORT исправлена — читать REPORT.")
|
||
|
||
h1(pdf, "7. Живой сценарий защиты (чеклист)")
|
||
bullet(pdf, "Стенд уже up --scale api=2, ready 200.")
|
||
bullet(pdf, "docker compose ps — два api healthy без host-порта, lb 8080.")
|
||
bullet(pdf, "python student-tests/level3.py — две реплики + идемпотентность. Открыть level3.json.")
|
||
bullet(pdf, "По желанию: два curl GET /api/v1/users/me с одним Bearer — разные X-Instance-Id.")
|
||
bullet(pdf, "python student-tests/failover.py — не паниковать из-за 1–2 ошибок. Потом docker ps: один Exited.")
|
||
bullet(pdf, "scripts\\restore-api.cmd, второй failover или руками docker stop второго имени из ps.")
|
||
bullet(pdf, "Открыть REPORT таблицу трека 1 и два SVG. Произнести 128/107/69 и 49/105/221.")
|
||
bullet(pdf, "Если просят код HAProxy / идемпотентности / stop-one — разделы 4–5 этой методички.")
|
||
bullet(pdf, "Не гонять track1.py с нуля, если нет 15+ минут.")
|
||
|
||
h1(pdf, "8. Примерные вопросы и ответы")
|
||
|
||
qa(
|
||
pdf,
|
||
"Чем отказ процесса отличается от отказа узла?",
|
||
"Процесс — один контейнер api, docker stop. Второй api на том же host + общие Redis/Postgres живут. "
|
||
"Узел — вся ВМ/ноутбук/Docker Desktop: вместе падают LB, обе реплики, база. Это трек 2, мы его не заявляем.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Почему depends_on и healthcheck — не балансировщик?",
|
||
"depends_on решает порядок СТАРТА (сначала postgres healthy, потом api). Healthcheck Compose красит контейнер "
|
||
"healthy для --wait. Трафик клиентов они не делят. Делит HAProxy: у него свой httpchk и roundrobin. "
|
||
"Без LB клиент должен был бы сам знать два IP.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Какие POST можно повторять после timeout и что защищает Idempotency-Key?",
|
||
"Клиент не знает, записалось ли сообщение. Имеет право повторить ТОТ ЖЕ POST с ТЕМ ЖЕ ключом и тем же телом. "
|
||
"Сервер вернёт старый id. Другое тело с тем же ключом — 409, это уже другое сообщение, новый ключ. "
|
||
"Ключ обязателен только у POST сообщения. Регистрацию/чаты так не защищали.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Что сломается, если сессии в локальной памяти, а API станет больше?",
|
||
"Round-robin отправит следующий запрос на соседний процесс — токена там нет — 401. Sticky это запрещённый костыль: "
|
||
"убили «свою» реплику — сессия всё равно умерла. Поэтому Redis.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Зачем X-Instance-Id, если есть X-Request-Id?",
|
||
"Request-Id уникален на каждый хит даже на одном процессе. Им нельзя доказать две реплики и нельзя docker stop. "
|
||
"Instance-Id стабилен на жизнь процесса и равен hostname.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Как HAProxy выбирает первое или второе API?",
|
||
"Счётчик round-robin + кто проходит ready. «Второе вместо первого» — следующий слот, не баг. "
|
||
"Порядок слотов из DNS, не «api-1 важнее».",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Период проверок и максимальное время обнаружения отказа?",
|
||
"inter 1s, fall 2 → типично ~2 с после 503/смерти. timeout check 1s. DNS hold valid 2s → верх ~4 с. "
|
||
"Измерили recovery 2.46 с. Бюджет курса 10 с.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Где генерируется Idempotency-Key?",
|
||
"На клиенте. В сервере генерации нет, иначе сервер не отличит повтор от нового. Тесты: uuid4 в tests/client.py "
|
||
"и student-tests/level3.py. Человек в чате ключ не печатает.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Почему 12 параллельных POST не делают 12 сообщений?",
|
||
"Оба API идут в одну таблицу. Замок advisory на время транзакции: второй ждёт и видит ключ первого. "
|
||
"UNIQUE на (user, method, path, key) — страховка. Тест test_concurrent_key.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Почему публичный live отвечает HAProxy?",
|
||
"Live входа = жива ли касса. Если live отдавать API, при мёртвом LB клиент не достучится, а при живом LB и мёртвых "
|
||
"API live всё равно можно отдать с кассы. Ready специально идёт на API.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Зачем два одинаковых контейнера, если трек 1 показал, что один быстрее?",
|
||
"Скорость при фиксированном 1 CPU и выживаемость — разные цели. Один толстый процесс быстрее на этом профиле. "
|
||
"Два нужны, чтобы docker stop одного не обнулил сервис. На защите развести оси.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Где saturation point БД/LB/пула?",
|
||
"Не найден как плато. Stats postgres/lb ≈0%, серия grow ещё линейна до 221 RPS, пул не упёрся. "
|
||
"Нашли другое: при фиксированном CPU рост реплик вреден. Классическое насыщение склада не показали — "
|
||
"ограничение профиля 8×20с. Так и написано в REPORT.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Почему не нулевые ошибки на failover/rolling?",
|
||
"Между SIGTERM и исключением из LB есть запросы в умирающий процесс. Курс это разрешает, если измеряли. "
|
||
"У нас единицы процентов, recovery секунды.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Миграции на каждой реплике?",
|
||
"Нет. Отдельный one-shot migrate, API RUN_MIGRATIONS=0. Иначе гонка CREATE TABLE.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Почему нет sticky?",
|
||
"Sticky прячет раздельное состояние. Задание прямо запрещает чинить им локальные сессии. "
|
||
"Состояние общее — прилипать незачем.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Что будет, если убить Postgres?",
|
||
"Все api станут unready (ping БД падает), HAProxy перестанет слать бизнес-трафик, сервис ляжет. "
|
||
"Две реплики API базу не спасают. Не заявлять обратное.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Что будет, если убить Redis?",
|
||
"Новые логины и проверка Bearer не работают (503). Старые сообщения в Postgres живы, но API без сессии их не отдаст. "
|
||
"Redis SPOF для аутентификации.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Closed-loop / coordinated omission?",
|
||
"Клиент ждёт ответа, медленные запросы уменьшают число попыток. Для сравнения 1/2/4 одним клиентом ок. "
|
||
"Это не абсолютный потолок стенда как open-loop.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Почему в stats одна реплика 24%, сосед 0.7%?",
|
||
"Один кадр docker stats в конце прогона, не интеграл за 20 с. Не строить на этом теорию. Смотреть RPS и лимиты.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Зачем [::1], это же не про реплики?",
|
||
"На Windows localhost ≠ 127.0.0.1. Без IPv6-bind измерение «через localhost» врало бы ~2 с на запрос. "
|
||
"Это подтверждённое улучшение входа, без него трек 1 на localhost не про API.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Можно ли сравнить ваш 128 RPS с чужим ноутбуком?",
|
||
"Нет. Курс: универсального проходного RPS нет. Сравнивают отношения на одной машине: 128:107:69.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"workers uvicorn больше 1?",
|
||
"workers=1. Несколько воркеров в одном контейнере — уже не наш X-Instance-Id=hostname на всех. "
|
||
"Горизонталь — отдельные контейнеры.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Как stop-one понимает, кого убивать?",
|
||
"Тест передаёт TARGET_INSTANCE_ID = значение заголовка. Скрипт сравнивает с Hostname контейнера "
|
||
"(мы как раз кладём hostname в заголовок).",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Rolling под нагрузкой зачем, если есть failover?",
|
||
"Обновление образа без «выключить всех». Сначала лишний здоровый, потом убрать старого. Иначе дыра на время сборки.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Совместимы ли миграции с работающей версией?",
|
||
"Additive: новая таблица ключей. Rolling гоняет одну версию API после migrate. Не заявляем blue-green двух схем.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Почему Postgres слушает 5433 на хосте, это же дырка?",
|
||
"Учебный отладочный bind на 127.0.0.1, не публикация API. Снаружи интернет не торчит. Можно признать упрощением.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Аргон2 и lab2?",
|
||
"Пароли как в lab2, Basic только на создание сессии, дальше Bearer. Это не тема lab3, но контракт сохранён.",
|
||
)
|
||
qa(
|
||
pdf,
|
||
"Что в PR / отчёте ещё TODO?",
|
||
"В REPORT строка Commit/PR: TODO после публикации. Если PR не открыт — сказать как есть, не выдумывать номер.",
|
||
)
|
||
|
||
h1(pdf, "9. Мини-шпаргалка чисел")
|
||
bullet(pdf, "Реплики: 2. Вход: 8080. Ready LB: 1 с, fall 2, обнаружение ~2 с (верх ~4 с). Failover recovery ~2.5 с.")
|
||
bullet(pdf, "Grace: stop -t 5, uvicorn 5, compose 8 с.")
|
||
bullet(pdf, "TTL сессии 3600, ключа идемпотентности 86400.")
|
||
bullet(pdf, "Лимит api: 0.50 CPU / 256M. Трек1 fixed сумма всегда 1 CPU / 512M.")
|
||
bullet(pdf, "Трек1 RPS: 128 / 107 / 69 и 49 / 105 / 221. Ошибки 0.")
|
||
bullet(pdf, "IPv6 фикс: ~1.9 RPS → ~88 RPS на localhost.")
|
||
bullet(pdf, "Гонка: 12 POST, 1 message id. Rolling: ~1.2% ошибок.")
|
||
|
||
h1(pdf, "10. Если что-то пойдёт не так на защите")
|
||
bullet(pdf, "Стенд не ready: docker compose ps, логи docker compose logs api --tail 80, часто migrate не прошёл или Docker Desktop спал.")
|
||
bullet(pdf, "Один instance id: реплика одна — compose up --scale api=2; или смотрите live вместо /users/me.")
|
||
bullet(pdf, "localhost тупит, 127.0.0.1 быстрый: проверяйте, что в compose есть [::1]:8080 и контейнер lb пересоздан.")
|
||
bullet(pdf, "failover не находит TARGET: instance id должен совпасть с hostname (inspect). Не сравнивать с load-balancer.")
|
||
bullet(pdf, "Не лезьте чинить публичные tests/ и contracts/ на глазах — это запрещено курсом.")
|
||
|
||
pdf.ln(4)
|
||
body(
|
||
pdf,
|
||
"Конец методички. Источник цифр: REPORT.md и evidence/ на дату 2026-10-30. Если перегоните тесты — замените числа, "
|
||
"не зубрите старые. Код открывать из репозитория, не из памяти.",
|
||
)
|
||
pdf.output(str(OUT))
|
||
print("wrote", OUT)
|
||
|
||
|
||
if __name__ == "__main__":
|
||
build()
|