- 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>
221 lines
21 KiB
Markdown
221 lines
21 KiB
Markdown
# Отчёт — лабораторная 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`.
|