132 lines
9.4 KiB
Markdown
132 lines
9.4 KiB
Markdown
# Proposal
|
||
|
||
## Why
|
||
|
||
Лаба 4 требует S3-совместимое хранилище в общем стенде: закреплённая
|
||
версия, persistent volume, приватный bucket с описанным созданием
|
||
(рубрика «3»). Рубрика «4» добавляет идемпотентный bootstrap, отдельные
|
||
ограниченные учётные данные API, консоль не в общей сети и проверку
|
||
приватности bucket вне API (`README.md`). Вложения (change
|
||
`attachments`) строятся поверх этого: сначала хранилище, клиент и
|
||
стенды, потом домен.
|
||
|
||
Сервер выбран заранее — SeaweedFS (`PLAN.md`, решение 1). Проба
|
||
закреплённой версии показала три места, где он по умолчанию не
|
||
приватен. Без учётных записей S3 открыт анониму целиком. Служебные
|
||
серверы (master, filer, volume) слушают все интерфейсы. gRPC-порт S3
|
||
без ключа подписи принимает от любого контейнера сети учётную запись
|
||
администратора. Change закрывает все три, а не только создаёт bucket.
|
||
|
||
## What Changes
|
||
|
||
- В стенде появляется S3: сервис `s3` на SeaweedFS 4.48 с тегом и
|
||
digest индекса, именованным volume, healthcheck, лимитами CPU и памяти
|
||
и плавной остановкой.
|
||
- Служебные серверы слушают только loopback контейнера, наружу и в
|
||
сеть compose выходит один порт S3.
|
||
- Порт S3 публикуется только на `127.0.0.1` хоста для запуска в
|
||
консоли. Консоль и UI не публикуются и в сети недоступны.
|
||
- Учётная запись администратора задана с первого старта: анонимного
|
||
окна нет.
|
||
- Административные RPC закрыты ключом подписи, телеметрия и
|
||
необязательные эндпоинты выключены.
|
||
- Одноразовый сервис `s3-bootstrap` на том же образе создаёт приватный
|
||
bucket, запрещает анонимный доступ и заводит пользователя API с
|
||
политикой «только объекты своего bucket: чтение, запись, удаление».
|
||
- Реплики API ждут его успешного завершения, как миграций.
|
||
- Повторный запуск ничего не ломает и сводит состояние к `.env`.
|
||
- В конце каждого запуска bootstrap проверяет права и приватность вне
|
||
API и завершается ошибкой, если bucket не приватен.
|
||
- `make s3_check` — та же проверка приватности вне API отдельной
|
||
командой, для защиты и evidence. Она добавляет проверки с хоста и из
|
||
сети стенда, против чужого bucket и административных операций.
|
||
- Учётные данные разделены по ролям. Административная пара ключей S3
|
||
есть только у сервера `s3`, ключ подписи — у `s3` и `s3-bootstrap`,
|
||
ключи API — у `s3-bootstrap` и реплик API. LB, миграции, PostgreSQL
|
||
и Valkey секретов S3 не получают. Значения лежат в `.env`, `make env_setup`
|
||
генерирует их для нового `.env`, в приложение они приходят мостами
|
||
`S3__*`.
|
||
- Секция `[s3]` настроек: адрес, порт, bucket, ключи API, регион, сроки
|
||
и пул. Значения из `config.toml` — в `config_example.toml`.
|
||
- Клиент хранилища в `src/infra/s3/` на aiobotocore для следующих
|
||
changes. Операции — запись, чтение потоком, метаданные, удаление; у
|
||
каждого вызова свой срок, повторов нет. Отказ, таймаут и отказ в
|
||
учётных данных — 503 `unavailable`. Ключи объектов начинаются с имени
|
||
базы, как ключи кэша. Клиент создаётся при старте и закрывается при
|
||
остановке.
|
||
- `/health/ready` от S3 не зависит (`PLAN.md`, решение 3): S3 не
|
||
нужен обязательному синхронному пути.
|
||
- Все стенды знают о S3:
|
||
- `scripts/restart.sh` перезапускает и S3;
|
||
- `make run_dev` поднимает S3 и bootstrap;
|
||
- `make test_isolated` работает с S3 рабочего стенда, его объекты
|
||
лежат под префиксом временной базы и удаляются при уборке;
|
||
- у `make failure_checks` свой S3 и новая проверка «S3 недоступен —
|
||
готовность 200»;
|
||
- `bench/` получает секреты S3 на прогон, а профили лаб 2–3 S3 не
|
||
запускают, и их методика не меняется;
|
||
- `make wipe_data` удаляет и volume S3.
|
||
- **BREAKING (для оператора):** в существующий `.env` нужно перенести
|
||
строки S3 из `.env.example`, без них compose не стартует. `make
|
||
env_setup` существующий `.env` не меняет. Для нового `.env` секреты
|
||
генерируются сами.
|
||
|
||
Не входит: таблица и ручки вложений, домен `attachment`,
|
||
`attachment_ids` — это change `attachments`. Намерение `pending`,
|
||
компенсация и уборщик с его S3-пользователем — `upload-consistency`.
|
||
Лимиты памяти и сроки загрузки — `upload-memory`. Reconciler — трек 2.
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `object-storage`: S3-хранилище стенда — сервер и его закрепление,
|
||
служебные интерфейсы вне сети, идемпотентный bootstrap приватного
|
||
bucket, запрет анонимного доступа, ограниченные права API, проверка
|
||
приватности вне API, сохранность при рестарте и клиент приложения
|
||
(сроки, ошибки, ключи по имени базы).
|
||
|
||
### Modified Capabilities
|
||
|
||
- `container-run`: S3 и bootstrap в стенде compose, порты S3 из `.env`,
|
||
публикация только порта S3 на `127.0.0.1`, рестарт hook-ом, лимиты и
|
||
секреты по сервисам, запуск в консоли с S3, удаление данных вместе с
|
||
volume S3.
|
||
- `service-configuration`: подключение к S3 (секция `[s3]`, секреты
|
||
из `.env`, генерация в `make env_setup`), консоль и docker без правки
|
||
файлов.
|
||
- `health`: готовность не зависит от S3.
|
||
- `service-logging`: учётные данные S3 и подписи запросов к нему в
|
||
журнал не попадают.
|
||
- `student-tests`: прогон на временной базе с префиксом объектов и его
|
||
уборкой; стенд отказов со своим S3 и проверкой готовности без него.
|
||
|
||
## Impact
|
||
|
||
- Код: `src/infra/s3/` (клиент, глобал), `src/config/settings.py`
|
||
(`[s3]`), `src/main.py` (старт, закрытие, запись о старте),
|
||
`src/infra/logger.py` (журналы botocore — `WARNING`), доменное
|
||
исключение отсутствующего объекта.
|
||
- Зависимости: `aiobotocore` (тянет `botocore` и `aiohttp`), `uv.lock`.
|
||
- Инфраструктура:
|
||
- `docker-compose.yml` — сервисы `s3`, `s3-bootstrap`, якорь `x-s3-env`
|
||
и volume;
|
||
- `infra/s3/bootstrap.sh`;
|
||
- `.env.example` и `config_example.toml`;
|
||
- `Makefile` — `env_setup`, `start_s3`, `stop_s3`, `s3_check`,
|
||
`run_dev`, `test_isolated`, `wipe_data`;
|
||
- `scripts/restart.sh`.
|
||
- Стенды:
|
||
- `student-tests/run_isolated.py`, `run_failures.py`,
|
||
`failures.compose.yml`, `fault_hook.py`, `test_failures.py`;
|
||
- `bench/run.py` — секреты, фильтр секретов в паспорте;
|
||
- `bench/bench.compose.yml`, `bench/bench.env`.
|
||
- Документы:
|
||
- правила `infra.md`, `docker.md`, `settings.md`, `run-modes.md`,
|
||
`logging.md`, `student-tests.md`, `bench.md`, `balancer.md`;
|
||
- `AGENTS.md`, скилл `run-mtusi-messenger`;
|
||
- `REPORT.md` — роль S3, таблица роль → сервис → версия → healthcheck
|
||
→ volume → порт → credentials, bootstrap и его повтор, критичные
|
||
зависимости, соответствие имён skeleton `S3_*`;
|
||
- `evidence/s3/`.
|