Files
mtusi2026lab4/REPORT.md
T
ricoromaandClaude Opus 5.5 f57635a5fb fix: address s3-storage verify findings
- s3 healthcheck and fault hook probe wait for the volume server to
  register with master (first write after restart no longer waits ~5 s)
- s3-bootstrap mounts /data as tmpfs: no anonymous volume per container
- S3 client: NoSuchBucket and AccessDenied are 503 with their own error
  logs, not a missing object or rejected credentials; delete ignores only
  a missing key
- test_isolated verifies prefix removal (weed shell exits 0 on errors)
- s3_check derives ports from listening sockets in the s3 container
- readiness without S3 is also checked with s3 paused

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 21:23:38 +03:00

221 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Отчёт — лабораторная 4
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
### S3 (change `s3-storage`)
`make env_setup` создаёт новый `.env` из `.env.example` со случайными
паролями PostgreSQL и Valkey и пятью секретами S3 и печатает только их
имена. Существующий `.env` он не трогает.
**Шаг оператора для `.env`, созданного до change `s3-storage`.**
Перенесите блок S3 из `.env.example` руками. Пять пустых секретов
(`S3_ROOT_ACCESS_KEY`, `S3_ROOT_SECRET_KEY`, `S3_JWT_SIGNING_KEY`,
`S3_API_ACCESS_KEY`, `S3_API_SECRET_KEY`) заполните значениями `openssl
rand -hex 32`. Без них любая команда compose останавливается с
сообщением «… is empty, copy S3 lines from .env.example».
- `make run_docker`. Порядок старта:
- postgres, valkey и s3 до `healthy`;
- одноразовые `migrate` и `s3-bootstrap` (приватный bucket,
пользователь API, проверки приватности);
- `api` × 2 после успешного завершения обоих;
- haproxy на `127.0.0.1:8080`.
Проверки — `make test`, `make student_test`, `make s3_check`.
- `make run_dev`. Цепочка `make upgrade`, `make start_cache` и `make
start_s3`: `up -d --wait s3`, затем `up --no-deps --exit-code-from
s3-bootstrap s3-bootstrap`, код bootstrap — код цели. Затем сервис на
`127.0.0.1:8080`. В консоли S3 доступен на `127.0.0.1:8334`.
- `make stop` останавливает S3 плавно, ~15 с. `make down` volumes не
трогает.
- `make wipe_data` удаляет volumes `mtusi-lab4_postgres_data` и
`mtusi-lab4_s3_data` только после ввода `yes`, оба тома запрос
называет по имени.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
```
клиент → 127.0.0.1:8080 → haproxy → api × 2 → postgres (метаданные, сессии, ключи идемпотентности)
→ valkey (кэш карточек чатов)
→ s3 (байты вложений; SeaweedFS, приватный bucket)
migrate (один раз) ──→ postgres
s3-bootstrap (один раз, в сетевом пространстве s3) ──→ s3
```
### Роль S3 и её граница
S3 хранит только байты вложений, метаданные лежат в PostgreSQL. Пишет и
читает S3 только API своим ключом. Ручки вложений, `attachment_ids`,
компенсация и уборщик — следующие changes (`attachments`,
`upload-consistency`, `upload-memory`). Change `s3-storage` даёт сервер,
bootstrap, клиент `src/infra/s3/` и стенды.
Сервер — SeaweedFS 4.48. Выбор и проба — `PLAN.md` (решение 1) и
design change `s3-storage`. Три места, где SeaweedFS по умолчанию не
приватен, закрыты:
- без учётных записей S3 открыт анониму — административная пара задана
в окружении сервера с первого старта;
- master, filer и volume слушают все интерфейсы — `-ip.bind=127.0.0.1`;
- gRPC шлюза без ключа подписи принимает учётную запись администратора
— ключ подписи обязателен.
Телеметрия, Iceberg, Lance и встроенный IAM API выключены.
### Сервисы стенда
| Роль | Сервис | Версия / digest индекса | Health / readiness | Volume | Сеть / порт | Credentials |
| --- | --- | --- | --- | --- | --- | --- |
| load_balancer | `haproxy` | `haproxy:3.4.6-trixie@sha256:e2739156…db26` | `/lb/ready` на `:8404` изнутри: есть готовая реплика | — | `127.0.0.1:8080` → `8080`; `:8404` только в сети | нет |
| api × 2 | `api` | образ из `Dockerfile`, база `python:3.12.14-slim-trixie@sha256:f77ac9e4…e51f` | HEALTHCHECK образа: `/health/ready` | — (`config.toml` read-only) | `8080` только в сети | пароли PostgreSQL и Valkey, ключи пользователя API в S3 — мосты `DATABASE__PASSWORD`, `CACHE__PASSWORD`, `S3__ACCESS_KEY_ID`, `S3__SECRET_ACCESS_KEY` из `.env` |
| миграции | `migrate` | образ API | код выхода 0 (`service_completed_successfully`) | — | сеть | пароль PostgreSQL |
| postgres | `postgres` | `postgres:18.6-trixie@sha256:5a5a84b1…9722` | `pg_isready -h 127.0.0.1` | `postgres_data` | `127.0.0.1:5433` → `5432` | `POSTGRES_PASSWORD` |
| кэш (необязательная роль) | `valkey` | `valkey/valkey:9.1.2-trixie@sha256:418652cf…9dfd` | `valkey-cli ping` с паролем | — (persistence выключен) | `127.0.0.1:6380` → `6379` | `VALKEY_PASSWORD` |
| s3 | `s3` | `chrislusf/seaweedfs:4.48@sha256:4e61d15f…7872d` | `wget`: `/cluster/healthz` master, том зарегистрирован (`DataNodes` в `/dir/status`), `/healthz` filer и шлюза (loopback) | `s3_data:/data` | `127.0.0.1:8334` → `8333` (только API S3); в сети — `8333` и gRPC шлюза `18333`, служебные порты на loopback | административная пара (`AWS_*` из `S3_ROOT_*`) и ключ подписи (`WEED_JWT_FILER_SIGNING_KEY` из `S3_JWT_SIGNING_KEY`) — окружением |
| bootstrap S3 | `s3-bootstrap` | тот же образ S3 | код выхода 0; реплики ждут `service_completed_successfully` | — (`/tmp` и `/data` — tmpfs) | `network_mode: service:s3`, портов нет | ключ подписи и ключи API — окружением; в `weed shell` через stdin, в `curl` файлом на tmpfs |
Лимиты:
- postgres 2 CPU / 1 ГБ, valkey 0,5 / 128 МБ, s3 1 / 512 МБ;
- `s3-bootstrap` 0,5 / 128 МБ, `migrate` 0,5 / 256 МБ;
- `api` 1 / 512 МБ на реплику, haproxy 1 / 256 МБ.
Сумма — 7,5 CPU / 3,25 ГиБ, без одноразовых сервисов — 6,5 CPU /
2,9 ГиБ. Секреты по сервисам проверены в `evidence/s3/privacy.md`
(раздел 4).
### Bootstrap S3 и его безопасный повтор
Сервис `s3-bootstrap` выполняет `infra/s3/bootstrap.sh` в режиме
`apply`. Каждый шаг можно повторять:
1. Bucket: есть — «exists», нет — создаётся.
2. Анонимный доступ — `none`. Если он открыт, bootstrap его закрывает.
3. Политика `api-objects` (`s3:GetObject`, `s3:PutObject`,
`s3:DeleteObject` на `arn:aws:s3:::<bucket>/*`) создаётся или
обновляется.
4. Пользователь `api`: если его нет, создаётся с ключами из `.env`;
политика привязывается.
5. Чужие ключи пользователя удаляются, нужный создаётся, если его нет.
6. Проверка ключом API: PUT, GET и DELETE проверочного объекта.
`SignatureDoesNotMatch` значит, что секрет в `.env` сменился, —
ключ пересоздаётся.
7. Проверки приватности: ключ API получает 403 на список и создание
bucket, аноним — 403 на чтение и список. Расхождение — `FAILED:
<шаг>`, код 1, реплики не стартуют.
Повтор не меняет правильное состояние: bucket и объекты сохраняются,
пользователь не пересоздаётся (`evidence/s3/bootstrap.md`, раздел 2).
Смена секрета API: новое значение в `.env`, затем `make run_docker`.
Bootstrap пересоздаёт ключ, прежний секрет перестаёт действовать
(раздел 3), а реплики с новым окружением пересоздаёт compose.
Bootstrap работает не административной парой S3, а `weed shell` на
loopback сервера с ключом подписи. Административная пара есть только у
сервера. `make rolling_update` bootstrap не запускает: он, как
миграции, только расширяет права. Его изменения применяет `docker
compose up -d s3-bootstrap` или `make run_docker`.
### Критичные и некритичные зависимости готовности
- PostgreSQL **критичен**: в нём источник истины и сессии.
`/health/ready` выполняет `SELECT 1` со сроком 2 с, без него — 503.
- Valkey **не критичен**: это кэш, без него обязательные запросы идут в
PostgreSQL.
- S3 **не критичен**: без него недоступны только пути вложений (503
`unavailable`), текст работает. `/health/ready` к S3 не обращается:
иначе отказ S3 вывел бы из LB все реплики, и текст перестал бы
работать тоже. Проверка — `test_readiness_without_object_storage` в
`make failure_checks`.
### Соответствие имён skeleton `S3_*`
| Имя `.env.example` skeleton | Реальная конфигурация |
| --- | --- |
| `S3_ENDPOINT` | `S3__HOST` и `S3__PORT`: в консоли — мосты `127.0.0.1` и `${S3_OUT_PORT}`, в docker — `S3_HOST` и `S3_PORT` через `x-s3-env` |
| `S3_REGION` | `[s3] region` в `config.toml` (`us-east-1`, нужен подписи SigV4) |
| `S3_BUCKET` | `S3__BUCKET` в `.env`: читают приложение и bootstrap |
| `S3_ACCESS_KEY_ID_FILE`, `S3_SECRET_ACCESS_KEY_FILE` | мосты `S3__ACCESS_KEY_ID=${S3_API_ACCESS_KEY}` и `S3__SECRET_ACCESS_KEY=${S3_API_SECRET_KEY}`: значения из `.env`, а не файлы, как с `DATABASE_URL_FILE` |
| `MAX_UPLOAD_BYTES`, `MAX_IMAGE_PIXELS` | change `attachments` |
## Доказательства критериев
Строки S3 (change `s3-storage`) сняты с commit `2e997f9` на стенде `make
run_docker`, если не сказано иное.
**До change `attachments` красные:**
- публичный smoke, `make test-persistence` и `make test-failover`: они
загружают вложение;
- тесты схемы `Message` в `make student_test` и `make failure_checks` —
список уточнён в шапке `tasks.md` change `s3-storage`.
Причина одна: контракт лабы 4 требует `attachment_ids`, а код лабы 3 его
не отдаёт. Чинит change `attachments` (ответ пользователя 2026-10-20,
`PLAN.md`). Строки про вложения появятся с ним.
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO после `attachments`; сейчас `FAIL: response: missing required fields` (нет `attachment_ids`) | `evidence/tests/test-isolated-s3-cleanup.md` |
| «3»: S3-сервер в общем стенде, закреплённая версия | `make run_docker`, `docker compose ps` | `s3` на `chrislusf/seaweedfs:4.48@sha256:…` в состоянии `healthy`, `s3-bootstrap` — `Exited (0)`, реплики стартуют после него | `evidence/s3/privacy.md` (раздел 3), `evidence/s3/bootstrap.md` (раздел 1) |
| «3»: persistent volume S3 | `scripts/restart.sh`; `docker kill -s KILL` сервера S3 | ID контейнеров прежние, `StartedAt` новый, hook — 25 с; объекты клиента читаются с тем же SHA-256: 3/3 после рестарта, 20/20 после SIGKILL | `evidence/s3/restart.md` |
| «3»: создание приватного bucket описано | `docker compose logs s3-bootstrap` на пустом volume | «bucket messenger created», «user api created», «checks passed» | `evidence/s3/bootstrap.md` (раздел 1), «Архитектура и решения» → «Bootstrap S3» |
| «4»: bootstrap идемпотентен | `docker compose run --rm s3-bootstrap` дважды; повтор с новым секретом; `S3_BUCKET=Bad_Bucket` | повтор — «exists», код 0, объекты на месте; новый секрет работает, прежний — 503; ошибка — код 1, «FAILED: bucket create», реплики не стартуют | `evidence/s3/bootstrap.md` |
| «4»: отдельные ограниченные credentials API | `make s3_check` (строки `api key …`); секреты по сервисам из `docker compose config` | ключ API: объекты своего bucket — 200 / 204; список, bucket, политика, ACL, чужой bucket — 403; административной пары у API нет | `evidence/s3/privacy.md` (разделы 1, 4) |
| «4»: административная консоль не в общей сети | `nc -z` из сети стенда (`make s3_check`); `docker port`; gRPC без токена | открыты только 8333 и 18333; master, filer, volume и admin UI закрыты; на хосте — только `127.0.0.1:8334`; `PutIdentity` без токена — `UNAUTHENTICATED` | `evidence/s3/privacy.md`, `evidence/s3/grpc-admin.md` |
| «4»: проверка private bucket вне API | `make s3_check`; затем открыть чтение `s3.anonymous.set -access Read` | 52 проверки, код 0; после открытия чтения — 10 FAIL с названиями; следующий bootstrap закрывает доступ, снова PASS | `evidence/s3/privacy.md` |
| «4»: S3 недоступен — ограниченная ошибка, текст работает | `make failure_checks` (`test_readiness_without_object_storage`); клиент при `pause` и `stop` S3 | без S3 `/health/ready` и `/health/live` — 200 быстрее 1 с; вызов клиента — 503 за 8 мс (`stop`) или за срок 5 с (`pause`), после возврата проходит | `evidence/tests/failure-checks.md`, `evidence/s3/client.md` |
| «4»: память S3 при одновременных загрузках | 20 одновременных PUT по 10 MiB ключом API | все подтверждены, анонимная память не больше 379 MiB из 512, OOM нет; подбор лимитов API — `upload-memory` | `evidence/s3/memory.md` |
| Логи без секретов S3 | `grep -F` значений секретов по журналу клиента и `make run_dev` | 0 совпадений; отказ в учётных данных — одна запись `error` без секрета | `evidence/s3/client.md` |
| Остальные пункты уровня 3 | TODO (`attachments`) | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO (`attachments`, `upload-consistency`, `upload-memory`) | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| `docker pause` сервера S3 | вызов клиента — 503 не позже срока 5 с | 5 007–5 008 мс, `TimeoutError` → 503, без повторов | после `unpause` следующий вызов — 9 мс; потерь нет |
| `docker compose stop s3` | плавная остановка без SIGKILL; вызовы — 503 сразу | остановка 15,6 с, код 0; вызов — 503 за 2–8 мс | после `start` первый вызов тем же клиентом проходит |
| SIGKILL сервера S3 сразу после 20 подтверждённых PUT | подтверждённое не теряется | 20/20 с тем же SHA-256 | `healthy` через 3 с; потерь нет |
| `scripts/restart.sh` | все хранилища и реплики перезапущены, данные целы | 25 с; bootstrap — «exists»; 3/3 объекта с тем же SHA-256 | — |
| Неверный секрет API у приложения | 503 и запись `error` без секрета | `SignatureDoesNotMatch` → 503, одна запись `error` | — |
| 20 одновременных PUT по 10 MiB | без OOM | анонимная память не больше 379 MiB; последний PUT подтверждён через 7,2 с (очередь лимита загрузок 64 МБ) | — |
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
S3 (change `s3-storage`):
- **Одна нода S3 без репликации и fsync.** SIGKILL процесса
подтверждённых объектов не теряет (`evidence/s3/restart.md`). Отказ
диска или ВМ теряет объекты, и запись, подтверждённая перед падением
ВМ, может пропасть. Учебное упрощение, как один PostgreSQL.
- **Плавная остановка SeaweedFS ~15 с**: срок зашит в filer. Поэтому
`stop_grace_period: 20s`, а `make stop` и `scripts/restart.sh` дольше
на ~15 с. На стенде отказов — 2 с: там проверяется отказ.
- **gRPC шлюза открыт в сети стенда**: отдельно его не закрыть, он
защищён ключом подписи (`evidence/s3/grpc-admin.md`).
- **Секреты S3 видны в `docker inspect`** контейнеров `s3` и
`s3-bootstrap`, как `POSTGRES_PASSWORD`. Стенд локальный, порты только
на `127.0.0.1`. TLS — лаба 7.
- **Лимит загрузок шлюза ставит запросы в очередь.** 20 одновременных
загрузок по 10 MiB заканчиваются через 7,2 с, это больше срока вызова
клиента (5 с). Подбор лимитов и сроков — change `upload-memory`.
- **Отказ S3 — 503 на путях вложений, а не отказ сервиса.** Отказ хоста,
LB и PostgreSQL стенд не переживает (`.claude/rules/balancer.md`).
- **Профиль `rollout` стенда `bench/` ссылается на commit лабы 3**
(`KNOWN_ISSUES.md`), чинится в change `attachments`.