140 lines
7.7 KiB
Markdown
140 lines
7.7 KiB
Markdown
## Первый запуск / чистый clone
|
||
|
||
При обновлении уже работающего стенда с прежней объединённой SeaweedFS-службой перед командой `docker compose up` сначала остановите старый контейнер: оба варианта используют один `seaweed_data` volume, и старый и новый процессы не должны работать одновременно.
|
||
|
||
```sh
|
||
cd mtusi2026lab4
|
||
cp .env.example .env
|
||
scripts/bootstrap-secrets.sh
|
||
# If localhost:8080 is occupied, use an alternate HAProxy port for all following commands.
|
||
export APP_PORT=18080
|
||
|
||
# Только при обновлении прежнего стека:
|
||
docker compose stop s3
|
||
|
||
# Проверить итоговую Compose-конфигурацию.
|
||
docker compose config --quiet
|
||
|
||
# Build, PostgreSQL + изолированное SeaweedFS core/S3 gateway + bucket bootstrap,
|
||
# миграции, периодический reconciler, 2 API и HAProxy.
|
||
docker compose up -d --build --scale api=2
|
||
|
||
# Проверить статусы и readiness.
|
||
docker compose ps
|
||
curl --fail --silent http://localhost:18080/health/ready
|
||
```
|
||
|
||
Миграции запускаются сервисом `migrate` до API. Для ожидания старта:
|
||
|
||
```sh
|
||
until curl --fail --silent http://localhost:18080/health/ready >/dev/null; do sleep 2; done
|
||
```
|
||
|
||
Если порт 8080 свободен, удалите `export APP_PORT=18080` и замените `18080` на `8080` в `BASE_URL` и `curl`.
|
||
|
||
Bucket приватный; порты API, PostgreSQL и S3 API не опубликованы. `s3-bootstrap` использует admin S3 identity только для создания bucket, а API получает credentials с действиями Read/Write/List только для `messenger-attachments`.
|
||
|
||
## Статические и локальные проверки
|
||
|
||
```sh
|
||
make check
|
||
python3 -m venv .venv
|
||
.venv/bin/python -m pip install -r requirements-dev.txt
|
||
make validate PYTHON=.venv/bin/python
|
||
|
||
# Обязательный public smoke; сервер должен быть поднят.
|
||
make test BASE_URL=http://localhost:18080
|
||
|
||
# 12 одновременных одинаковых POST через две API-реплики должны создать одно сообщение.
|
||
.venv/bin/python student-tests/test_idempotency_race.py --base-url http://localhost:18080
|
||
|
||
# Негативные проверки вложений, без дополнительных зависимостей в тестовом клиенте.
|
||
make test-attachments BASE_URL=http://localhost:18080
|
||
|
||
# Детерминированные unit checks для решений reconciler (без реальных изменений хранилищ).
|
||
make test-reconcile PYTHON=.venv/bin/python
|
||
|
||
# Интеграционный Track 2: повреждает только тестовые данные; ждёт grace period 60 секунд.
|
||
make test-reconcile-integration BASE_URL=http://localhost:18080
|
||
```
|
||
|
||
Публичные сценарии создают пользователей/чаты/сообщения и не удаляют их. Повторять на учебном стенде; не использовать производственные данные.
|
||
|
||
## Сохранность, отказ API и параллельная загрузка
|
||
|
||
```sh
|
||
chmod +x scripts/restart.sh scripts/stop-one.sh
|
||
|
||
# Restart API, PostgreSQL и SeaweedFS с сохранением volumes и прежней сессии.
|
||
make test-persistence ACTION_SCRIPT=scripts/restart.sh BASE_URL=http://localhost:18080
|
||
|
||
# Нужны минимум 2 API. Тест останавливает одну реплику; после теста восстановить:
|
||
make test-failover ACTION_SCRIPT=scripts/stop-one.sh BASE_URL=http://localhost:18080
|
||
docker compose up -d --scale api=2 api
|
||
|
||
# 10 одновременных 1400×1400 PNG; sampler выводит baseline/peak/delta памяти API.
|
||
make test-upload-concurrency BASE_URL=http://localhost:18080
|
||
```
|
||
|
||
Публичные и собственные тесты не очищают данные. Persistence hook не удаляет volumes. Failover hook оставляет выбранную API-реплику остановленной до явного `docker compose up -d --scale api=2 api`.
|
||
|
||
## Track 2: reconciliation
|
||
|
||
После `docker compose up` сервис `reconciler` автоматически запускает проход с `--apply` каждые 900 секунд. Grace period по умолчанию — 3600 секунд: удаляются только старые orphan-объекты; missing metadata фиксируется как incident. Без настроенного restore directory скрипт не может восстановить missing bytes.
|
||
|
||
```sh
|
||
# Смотреть результат каждого периодического прохода.
|
||
docker compose logs -f reconciler
|
||
|
||
# Остановить автоматические проходы.
|
||
docker compose stop reconciler
|
||
|
||
# Период и grace period задаются в локальном .env до запуска Compose:
|
||
# RECONCILE_INTERVAL_SECONDS=900
|
||
# RECONCILE_GRACE_SECONDS=3600
|
||
```
|
||
|
||
Read-only scan:
|
||
|
||
```sh
|
||
docker compose exec -T api python3 src/reconcile.py
|
||
```
|
||
|
||
Удаление только stale orphan objects (по умолчанию возраст не менее 3600 секунд; минимально разрешено 60):
|
||
|
||
```sh
|
||
docker compose exec -T api python3 src/reconcile.py --grace-seconds 3600 --apply
|
||
```
|
||
|
||
Восстановление отсутствующего S3 object разрешается только из доверенной копии exact original. Имя файла — UUID attachment, содержимое должно совпасть с записанными размером и SHA-256. Сначала проверить кандидатов (без `--apply`), затем применить:
|
||
|
||
```sh
|
||
docker compose exec -T api python3 src/reconcile.py --restore-dir /path/visible/in/api
|
||
docker compose exec -T api python3 src/reconcile.py --restore-dir /path/visible/in/api --apply
|
||
```
|
||
|
||
Каталог восстановления должен быть доступен внутри API-контейнера и содержать только намеренно выбранные файлы. Путь можно смонтировать в API на время стендового эксперимента; не включать backup originals в Git. Если точной копии нет, metadata сохраняется и записывается incident для оператора.
|
||
|
||
Каждый запуск выводит JSON с `objects_seen`, `metadata_seen`, количеством orphan/missing/restored objects и `duration_ms`. Сохранить JSON для нескольких размеров dataset и указать CPU/RAM и версии в `REPORT.md`; dry-run использовать до каждого `--apply`.
|
||
|
||
## Нагрузка сообщений
|
||
|
||
```sh
|
||
make load BASE_URL=http://localhost:18080
|
||
# Или задать duration/concurrency/output согласно tests/load.py:
|
||
python3 tests/load.py --base-url http://localhost:18080 --duration 30 --concurrency 4 --output evidence/load.json
|
||
```
|
||
|
||
## Bucket / Compose lifecycle
|
||
|
||
```sh
|
||
# Идемпотентно проверить создание приватного bucket без сброса данных.
|
||
docker compose up -d s3-bootstrap
|
||
|
||
# Безопасная остановка, persistent volumes остаются:
|
||
docker compose down
|
||
|
||
# Намеренно удалить учебную БД и оригиналы (не выполнять для проверки persistence):
|
||
docker compose down --volumes
|
||
```
|