docs: report track 2 backup and restore
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -4,10 +4,12 @@ REST API мессенджера (пользователи, чаты, истор
|
||||
переносится через все семь лабораторных курса и на каждой обрастает
|
||||
инфраструктурой. Текущая работа — **лаба 2** (`lab.json`): PostgreSQL
|
||||
как источник истины, вход по Basic → Bearer-сессия, на «4» — Redis или
|
||||
Valkey (выбран Valkey — кэш карточек чатов). Код перенесён из лабы 1,
|
||||
переход на lab2 идёт через changes OpenSpec (раздел «Переходное
|
||||
состояние»). Стек: Python 3.12, uv, FastAPI, pydantic v2,
|
||||
pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey).
|
||||
Valkey (выбран Valkey — кэш карточек чатов), на «5» — трек 2 (план
|
||||
запроса и восстановление). Код перенесён из лабы 1 (commit `7b775a2`,
|
||||
её правила — `git show 7b775a2:.claude/rules/<файл>`). Переход на lab2
|
||||
завершён changes OpenSpec, они в `openspec/changes/archive/`. Стек:
|
||||
Python 3.12, uv, FastAPI, pydantic v2, pydantic-settings, structlog
|
||||
(JSON в stdout), redis-py (клиент Valkey).
|
||||
|
||||
Репозиторий — fork skeleton преподавателя. Задание, контракт и публичные
|
||||
проверки уже лежат в нём. Реализацию, Dockerfile, compose, собственные
|
||||
@@ -77,28 +79,6 @@ pydantic-settings, structlog (JSON в stdout), redis-py (клиент Valkey).
|
||||
варианты — каждое по имени, последним — «все». То же при нескольких
|
||||
подходящих спеках (capability).
|
||||
|
||||
## Переходное состояние
|
||||
|
||||
Код перенесён из лабы 1 (commit `7b775a2`), хранилище переведено на
|
||||
PostgreSQL (change `postgres-storage`), вход и Bearer-сессии — change
|
||||
`session-auth`, кэш Valkey — change `membership-cache`, автоматические
|
||||
проверки отказов — change `failure-checks`, нагрузочный стенд на
|
||||
PostgreSQL с планами запроса — change `bench-postgres`, трек 2 часть 1
|
||||
(индексы и запросы на чатах разного размера, стоимость записи) —
|
||||
change `track2-query-plans`. Этот файл и `.claude/rules/` описывают
|
||||
целевое состояние лабы 2, поэтому в остальном код с ними пока
|
||||
расходится:
|
||||
|
||||
- в `track2-backup-restore` — `FLUSHALL` Valkey после восстановления
|
||||
базы: иначе в кэше останутся карточки чатов, созданных после снятия
|
||||
backup (design change `membership-cache`, Risks);
|
||||
- в `REPORT.md` нет трека «5» №2, часть 2: backup с восстановлением
|
||||
(`track2-backup-restore`). Уровень 4 и часть 1 трека в отчёте
|
||||
заполнены целиком.
|
||||
|
||||
Правила лабы 1 — `git show 7b775a2:.claude/rules/<файл>`. Закрытый
|
||||
пункт убрать отсюда, закрытый переход — удалить раздел.
|
||||
|
||||
## Согласования с преподавателем
|
||||
|
||||
Договорённости, которых нет в skeleton. Каждую упомянуть в `REPORT.md`
|
||||
|
||||
@@ -5,15 +5,17 @@
|
||||
- Commit/PR: TODO после публикации
|
||||
- Использованные источники, библиотеки и помощь ИИ: раздел «Источники, библиотеки и использование ИИ» в конце отчёта
|
||||
|
||||
Отчёт заполняется по мере работы. Готово: хранение в PostgreSQL (change
|
||||
`postgres-storage`), пароли, вход по Basic и Bearer-сессии
|
||||
(`session-auth`), кэш карточки чата в Valkey (`membership-cache`),
|
||||
автоматические проверки отказов уровня 4 (`failure-checks`),
|
||||
нагрузочный стенд на PostgreSQL и обоснование индекса истории планами
|
||||
`EXPLAIN (ANALYZE, BUFFERS)` (`bench-postgres`), трек 2 часть 1 —
|
||||
индексы и запросы истории на чатах разного размера и стоимость записи
|
||||
(`track2-query-plans`). Впереди: трек 2 часть 2 — backup и
|
||||
восстановление (`track2-backup-restore`).
|
||||
Сделано по changes OpenSpec:
|
||||
- хранение в PostgreSQL — `postgres-storage`;
|
||||
- пароли, вход по Basic и Bearer-сессии — `session-auth`;
|
||||
- кэш карточки чата в Valkey — `membership-cache`;
|
||||
- автоматические проверки отказов уровня 4 — `failure-checks`;
|
||||
- нагрузочный стенд на PostgreSQL и обоснование индекса истории планами
|
||||
`EXPLAIN (ANALYZE, BUFFERS)` — `bench-postgres`;
|
||||
- трек 2, часть 1: индексы и запросы истории на чатах разного размера и
|
||||
стоимость записи — `track2-query-plans`;
|
||||
- трек 2, часть 2: backup, восстановление в новое хранилище и сверка —
|
||||
`track2-backup-restore`.
|
||||
|
||||
## Запуск из чистого clone
|
||||
|
||||
@@ -129,8 +131,17 @@ docker compose exec valkey sh -c 'valkey-cli -p "$VALKEY_PORT" --scan --pattern
|
||||
docker compose exec valkey sh -c 'valkey-cli -p "$VALKEY_PORT" INFO stats' | grep keyspace_
|
||||
docker compose stop valkey # чат, сообщения и /health/ready — те же ответы; make logs: warning
|
||||
docker compose start valkey # через 5 с кэш снова работает; make logs: info
|
||||
# уровень 4, план SQL: evidence/bench/baseline/explain-*.txt (раздел «Индекс истории»)
|
||||
# трек 2 — на своём стенде mtusi-bench, рабочий стенд не трогается:
|
||||
make bench_quick # ~3 мин: чаты разного размера, планы вариантов индекса и запроса, стоимость записи
|
||||
make bench_restore_quick # ~1,5 мин: backup под записью → восстановление в новое хранилище → сверка,
|
||||
# потерянные после снимка сообщения, кэш до и после FLUSHALL
|
||||
```
|
||||
|
||||
Полные метки трека 2 — `make bench BENCH_LABEL=track2` (~35 мин) и
|
||||
`make bench_restore` (~20 мин); на защите достаточно коротких профилей:
|
||||
та же процедура на 1k–10k сообщений.
|
||||
|
||||
`valkey-cli` в контейнере берёт пароль из переменной `VALKEYCLI_AUTH`, в
|
||||
командной строке его нет.
|
||||
|
||||
@@ -377,6 +388,9 @@ Redis / Valkey выбран Valkey 9.1, клиент — redis-py (`redis.asynci
|
||||
Восстановление из backup (трек 2) откатывает базу, и в кэше остаются
|
||||
карточки чатов, созданных после снятия backup. Поэтому процедура
|
||||
восстановления заканчивается `FLUSHALL` (change `track2-backup-restore`).
|
||||
Это измерено: без очистки такой чат читается из кэша (200), а запись
|
||||
в него падает с 500; после `FLUSHALL` — 404 (раздел «Трек 2, часть
|
||||
2»).
|
||||
- **Отказ Valkey — обход, а не ошибка.** Вся команда кэша — ожидание
|
||||
пула, соединение и ответ — ограничена 0,2 с (`asyncio.timeout`).
|
||||
redis-py по умолчанию повторяет команду с backoff, и замороженный
|
||||
@@ -467,7 +481,7 @@ Valkey приходят из `environment` compose. В compose нет литер
|
||||
| Уровень 4: параметризованные запросы | код repo | SQLAlchemy Core/ORM с параметрами, SQL из строк нет | `src/core/repos/` |
|
||||
| Уровень 4: индекс истории обоснован запросом и EXPLAIN (ANALYZE, BUFFERS) на ≥10 000 сообщениях; пагинация без полного scan | `make bench BENCH_LABEL=baseline`: `auto_explain` запроса приложения на 10k / 100k / 500k; тот же запрос без индекса в откатываемой транзакции | `Index Scan` по `(chat_id, created_at, id)`: 3–4 буфера на первую страницу, 47–55 на среднюю и последнюю на любом размере, около 0,05 мс. Без индекса — скан всей таблицы: 9 678 буферов и 20 мс на 500k. p50 чтения на 500k выше, чем на 10k, на 1–4% | `evidence/bench/baseline/explain-*.txt`, `summary.md`; раздел «Индекс истории» |
|
||||
| Трек 5 №2, часть 1: ≥100 000 сообщений в чатах разного размера, ≥2 индекса и запроса, стоимость записи | `make bench BENCH_LABEL=track2`: 110 000 / 200 000 / 600 000 сообщений в 1 111 чатах от 10 до 500 000; планы приложения по уровням чатов, 6 вариантов страницы сравнения в откатываемой транзакции, пробы записи по 4 вариантам индекса | индекс приложения — 5–55 буферов на любой странице любого чата; `or-cursor` — 252 338 буферов и 44 мс на середине чата 500k; `chat_only` — до 11 590; `covering` — 5 буферов, но +100 байт индекса и +17–34% WAL на сообщение, а сообщение из 4000 символов не вставляется. Индекс и запрос приложения оставлены по правилу выбора, записанному до замера | `evidence/bench/track2/summary.md`, `explain-*.txt`; раздел «Трек 2, часть 1» |
|
||||
| Трек 5 №2, часть 2: backup → восстановление в новое хранилище → сверка | — | TODO (change `track2-backup-restore`) | TODO |
|
||||
| Трек 5 №2, часть 2: backup → восстановление в новое хранилище → сверка количества и выбранных сообщений; время восстановления и граница потери | `make bench_restore`: на 110 000 / 200 000 / 600 000 сообщений `pg_dump -Fc` во время записи через HTTP, активность после backup, `pg_restore -j 4` в новый контейнер Postgres на новом volume, сверка БД построчно и через HTTP, переключение API, `FLUSHALL` | сверка прошла на всех размерах: число строк таблиц совпало, md5 всех полей каждого сообщения совпал, всё до backup восстановлено; потеряны только 4 842–4 868 сообщений, закоммиченных после снимка, и активность «после backup» (сессия — 401); 10 страниц истории через API те же; RTO 2,9–4,8 с, backup 37–43 байт на сообщение; без `FLUSHALL` удалённый откатом чат — 200 из кэша, запись — 500, после — 404 | `evidence/bench/restore/summary.md`, `meta.json`; раздел «Трек 2, часть 2» |
|
||||
|
||||
## Эксперименты и отказы
|
||||
|
||||
@@ -835,8 +849,8 @@ bench_restore_quick` (~1,5 мин). Методика — design change
|
||||
- потерянные — только из чата записи и чата «после backup»;
|
||||
- индексы и ревизия схемы совпадают.
|
||||
6. API переключается на восстановленную базу. Через HTTP:
|
||||
- 30 страниц истории разных чатов совпадают с исходными
|
||||
поэлементно;
|
||||
- 10 страниц истории разных чатов (страницы этапа плана) совпадают
|
||||
с исходными поэлементно;
|
||||
- прежняя сессия действует;
|
||||
- сессия «после backup» — 401;
|
||||
- ответы на чат «после backup» записываются.
|
||||
@@ -858,6 +872,109 @@ bench_restore_quick` (~1,5 мин). Методика — design change
|
||||
| R4 | Backup в формате custom (сжатый, без индексов) — меньше трети от байт в БД на сообщение (~300 в части 1) | больше 100 байт на сообщение |
|
||||
| R5 | Без `FLUSHALL` чат, созданный после backup, отдаётся из кэша (200), а запись в него — 500; после `FLUSHALL` — 404 | до `FLUSHALL` не 200 (вред не показан) или после — не 404 |
|
||||
|
||||
**Результаты.** Метка `evidence/bench/restore/`: commit `67cb4d7`,
|
||||
2026-10-02, 17,5 минуты.
|
||||
- Хост в начале и в конце — от сети, swap 0, свободно 79% и 75%
|
||||
памяти; сна во время прогона нет (`slept_seconds` = 0).
|
||||
- Посторонних контейнеров нет.
|
||||
- Сверка шагов 5–7 прошла на всех трёх размерах.
|
||||
|
||||
Таблица — из раздела «Backup и восстановление» `summary.md` и
|
||||
`meta.json` (`sizes[].restore`):
|
||||
|
||||
| Сообщений в таблице | До backup | Записано во время backup (попало в снимок) | Исходная в конце | Восстановлено | Потеряно (из них «после backup») | Backup, МиБ / байт на сообщение | dump, с | Новое хранилище, с | Копия, с | `pg_restore`, с | `ANALYZE`, с | API, с | RTO, с | Сверка, с |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| 110 000 | 110 000 | 5 000 (132) | 115 001 | 110 132 | 4 869 (1) | 4,5 / 42,6 | 0,32 | 0,85 | 0,06 | 0,30 | 0,14 | 1,55 | 2,90 | 0,51 |
|
||||
| 200 000 | 200 000 | 5 000 (144) | 205 001 | 200 144 | 4 857 (1) | 7,5 / 39,5 | 0,50 | 0,89 | 0,07 | 0,50 | 0,15 | 2,27 | 3,88 | 0,72 |
|
||||
| 600 000 | 600 000 | 5 000 (158) | 605 001 | 600 158 | 4 843 (1) | 21,0 / 36,6 | 1,30 | 0,89 | 0,15 | 1,43 | 0,17 | 2,12 | 4,76 | 1,74 |
|
||||
|
||||
Сверка на каждом размере:
|
||||
- **Число строк** в восстановленной базе — `users` 11, `chats` 1 112,
|
||||
`chat_members` 12 232, `sessions` 11. Как в исходной в момент backup.
|
||||
Пользователя, сессии и чата «после backup» нет.
|
||||
- **Поля сообщений:** md5 всех полей каждого восстановленного
|
||||
сообщения совпал с исходным, расхождений 0.
|
||||
- **Потери:** все сообщения, бывшие до backup, на месте. Потеряны только
|
||||
сообщения чата записи, закоммиченные после снимка, и одно сообщение
|
||||
«после backup».
|
||||
- **Схема:** индексы `messages` и ревизия alembic совпадают.
|
||||
|
||||
Через HTTP на восстановленной базе:
|
||||
- 10 страниц истории совпали с исходными до и после `FLUSHALL`;
|
||||
- прежний токен читателя — 200, токен «после backup» — 401;
|
||||
- чат «после backup» до `FLUSHALL` — `GET` 200 из кэша, `POST`
|
||||
сообщения в него — 500; после `FLUSHALL` — 404.
|
||||
|
||||
Итог по гипотезам:
|
||||
|
||||
| | Итог | Числа |
|
||||
| --- | --- | --- |
|
||||
| R1 | подтверждена | 5 000 записей во время `pg_dump` на каждом размере, неуспешных 0 |
|
||||
| R2 | подтверждена | сверка прошла: всё, что было до backup, восстановлено с теми же полями; потеряны 4 842–4 868 сообщений нагрузки после снимка и активность «после backup» |
|
||||
| R3 | подтверждена | время БД (хранилище + копия + `pg_restore` + `ANALYZE`): 1,35 → 1,61 → 2,64 с, на 600 000 в 1,96 раза больше, чем на 110 000 (порог ×10); сам `pg_restore` — 0,30 → 1,43 с (×4,8 при данных ×5,5); RTO на 600 000 — 4,76 с (порог 30 с) |
|
||||
| R4 | подтверждена | 36,6–42,6 байт на сообщение против 301–304 байт в БД — 12–14% |
|
||||
| R5 | подтверждена | до `FLUSHALL` `GET` 200, `POST` 500; после — 404 |
|
||||
|
||||
**Время восстановления (RTO).** На этих объёмах RTO — 2,9–4,8 с. Больше
|
||||
половины — постоянные слагаемые:
|
||||
- запуск нового контейнера Postgres — 0,85–0,89 с;
|
||||
- пересоздание API и его готовность — 1,55–2,27 с.
|
||||
|
||||
`pg_restore` растёт почти линейно с данными: загрузка строк и сборка
|
||||
индексов, `-j 4` параллелит их по таблицам и индексам. Экстраполяция
|
||||
на большие базы ненадёжна: здесь всё в памяти ВМ, а реальное
|
||||
восстановление упирается в диск и в доставку файла backup. Сверка в RTO
|
||||
не входит, но её стоит делать до переключения: 0,5–1,7 с здесь.
|
||||
|
||||
**Граница потери данных (RPO).** `pg_dump` — один снимок на старте.
|
||||
Теряется всё, что закоммичено после начала backup:
|
||||
- в замере это 4 842–4 868 сообщений нагрузки: из 5 000 в снимок
|
||||
попали первые 132–158, остальные закоммичены после его начала;
|
||||
- пользователь, его сессия, чат и сообщение, созданные после backup.
|
||||
|
||||
При регулярном логическом backup RPO — время с начала последнего
|
||||
backup, при ежесуточном до суток. Сузить его можно так:
|
||||
- архивация WAL (`archive_mode`, `archive_command` или
|
||||
`pg_receivewal`) с базовой копией `pg_basebackup` — восстановление на
|
||||
момент последнего архивного сегмента (PITR), RPO — секунды;
|
||||
- синхронная потоковая реплика — RPO 0 при потере основного сервера.
|
||||
|
||||
Ни то ни другое не реализовано: это ограничение решения. Backup здесь
|
||||
лежит на том же хосте, что и база, и от потери хоста не защищает. В
|
||||
эксплуатации его хранят вне хоста.
|
||||
|
||||
**Процедура восстановления и кэш.** Порядок, проверенный стендом:
|
||||
1. backup `pg_dump -Fc`;
|
||||
2. новое хранилище на новом volume;
|
||||
3. `pg_restore -j`;
|
||||
4. `ANALYZE`;
|
||||
5. сверка;
|
||||
6. переключение API (`POSTGRES_HOST`);
|
||||
7. **`FLUSHALL` Valkey до приёма запросов.**
|
||||
|
||||
Без шага 7 кэш нарушает требование `chat-cache` «кэш не содержит
|
||||
карточку, которой нет в PostgreSQL»: несуществующий чат читается (200),
|
||||
а запись в него падает с 500 (FK `messages` → `chat_members`). Очистка
|
||||
ничего не теряет: в Valkey только копии карточек, после неё — 404, и
|
||||
кэш заполняется заново из восстановленной базы.
|
||||
|
||||
Ограничения:
|
||||
- Один хост и одна ВМ Docker: потерю хоста, диска и сети не
|
||||
моделирует. Файл backup — на том же диске.
|
||||
- Объёмы небольшие (backup до 21 МиБ), всё в памяти. RTO на этих
|
||||
размерах определяют постоянные слагаемые, а не данные.
|
||||
- Только логический backup, без PITR и реплики. Восстановление — в тот
|
||||
же образ Postgres; восстановление в другую версию не проверялось.
|
||||
- Переключение API — пересоздание контейнера с другим адресом базы
|
||||
(около 2 с без ответа). Без балансировщика и второй реплики, это
|
||||
лаба 3.
|
||||
- Первая попытка снять метку прервана и удалена: хост ушёл в сон по
|
||||
простою (`pmset sleep 1`), ВМ Docker стояла на паузе посреди
|
||||
наполнения. После этого цели `bench*` идут под `caffeinate -isu`, а
|
||||
`run.py` пишет `slept_seconds` и предупреждает, если реальное и
|
||||
монотонное время прогона расходятся. `baseline` и `track2` сон не
|
||||
задел: они закончились до первого сна по журналу питания.
|
||||
|
||||
## Ограничения и следующие шаги
|
||||
|
||||
- Сервер, замёрзший при открытом соединении, держит запрос 8 с, а не
|
||||
@@ -905,8 +1022,10 @@ bench_restore_quick` (~1,5 мин). Методика — design change
|
||||
- Планы и нагрузка сняты с настройками Postgres по умолчанию, вся
|
||||
таблица в памяти: выигрыш покрывающего индекса при холодном кэше не
|
||||
измерялся (раздел «Трек 2, часть 1», ограничения).
|
||||
- Не реализовано: трек 2, часть 2 — backup с восстановлением (change
|
||||
`track2-backup-restore`).
|
||||
- Backup — только логический (`pg_dump`), на том же хосте, без
|
||||
архивации WAL: RPO — время с начала последнего backup, PITR нет.
|
||||
Восстановление и сверка проверены на стенде `mtusi-bench`, на рабочем
|
||||
стенде процедура не выполнялась (раздел «Трек 2, часть 2»).
|
||||
|
||||
## Источники, библиотеки и использование ИИ
|
||||
|
||||
@@ -925,12 +1044,17 @@ bench_restore_quick` (~1,5 мин). Методика — design change
|
||||
и `WAL`, `auto_explain`, `plan_cache_mode`, индексы с `INCLUDE` и
|
||||
`Index Only Scan`, предел размера строки B-дерева, сравнение
|
||||
кортежей в условиях), k6 (`SharedArray`, `shared-iterations`).
|
||||
- Документация по backup: PostgreSQL 18 (`pg_dump` в формате custom и
|
||||
его снимок, `pg_restore -j`, continuous archiving и PITR как способ
|
||||
сузить RPO), образ `postgres` (переменные инициализации), macOS
|
||||
`caffeinate` и `pmset -g log` (сон хоста во время замера).
|
||||
- Библиотеки: FastAPI, pydantic, pydantic-settings, structlog,
|
||||
SQLAlchemy, asyncpg, alembic, argon2-cffi, redis-py, uvicorn; в тестах —
|
||||
pytest и httpx; в нагрузочном стенде — k6.
|
||||
- ИИ: Claude (Claude Code) помогал проектировать changes
|
||||
`postgres-storage`, `session-auth`, `membership-cache`,
|
||||
`failure-checks`, `bench-postgres` и `track2-query-plans` (OpenSpec),
|
||||
`failure-checks`, `bench-postgres`, `track2-query-plans` и
|
||||
`track2-backup-restore` (OpenSpec),
|
||||
писать код, правила и отчёт, а также проверял поведение на стенде. Решения и все правки
|
||||
просмотрены автором; поведение подтверждено командами, выводы которых
|
||||
лежат в `evidence/`.
|
||||
|
||||
@@ -86,7 +86,7 @@
|
||||
- сверка прошла на 10k, 100k и 500k.
|
||||
- [x] 5.3 Закоммитить `evidence/bench/restore/` (`docs: add track 2
|
||||
backup and restore evidence`).
|
||||
- [ ] 5.4 `REPORT.md`, трек 2, часть 2:
|
||||
- [x] 5.4 `REPORT.md`, трек 2, часть 2:
|
||||
- процедура восстановления по шагам, включая `FLUSHALL`;
|
||||
- сверка;
|
||||
- время по размерам и RTO;
|
||||
@@ -99,6 +99,6 @@
|
||||
результат. В `AGENTS.md` закрыть «Переходное состояние» трека 2 и
|
||||
пункт `FLUSHALL`. Проверка: каждое число есть в `summary.md` или
|
||||
`meta.json` метки `restore`.
|
||||
- [ ] 5.5 Закоммитить отчёт (`docs: report track 2 backup and
|
||||
- [x] 5.5 Закоммитить отчёт (`docs: report track 2 backup and
|
||||
restore`). `openspec validate track2-backup-restore --strict`
|
||||
проходит, `git status` чистый.
|
||||
|
||||
Reference in New Issue
Block a user