feat: provision private S3 storage and attachment schema

This commit is contained in:
Самохвалов Андрей Ремович
2026-10-02 13:01:50 +03:00
parent bd41f2d93d
commit 22f7bcddf5
14 changed files with 309 additions and 25 deletions
+1
View File
@@ -4,6 +4,7 @@
.env
.env.*
!.env.example
/compose.local.yaml
secrets/
certs/private/
*.key
+37 -19
View File
@@ -1,37 +1,55 @@
# Отчёт — лабораторная 4
- Автор, группа: TODO
- Целевая оценка; выбранный трек 5, если нужен: TODO
- Commit/PR: TODO после публикации
- Использованные источники, библиотеки и помощь ИИ: TODO
- Автор, группа: Самохвалов Андрей Ремович, БПИ-2302.
- Целевая оценка: 5, трек 2 «Согласованность двух хранилищ». Пока реализованы перенос lab3 и приватное S3; остальные блоки выполняются далее.
- Ветка: `solution/bpi2302-samohvalov`; commit/PR указываются после публикации.
- Источники: `README.md`, `COURSE.md`, `contracts/README.md`, `contracts/openapi.json`, публичные тесты, [MinIO release](https://github.com/minio/minio/releases/tag/RELEASE.2025-10-15T17-29-55Z), [образ](https://hub.docker.com/r/alpine/minio/tags), документация MinIO для IAM. Python/FastAPI, PostgreSQL, MinIO Python SDK; проект подготовлен с помощью ИИ Codex с локальной проверкой ниже.
## Запуск из чистого clone
TODO: версии runtime/образов, prerequisites, команды создания локальных secrets/.env, build, миграций, запуска, ожидания готовности, тестов и остановки. Указать необходимые действия оператора. Не вставлять секреты. Отдельно указать безопасную остановку и команду намеренного удаления учебных данных.
Требуются Docker Compose и Python 3.9+. Стенд использует только синтетические данные и слушает `127.0.0.1` на `APP_PORT` (по умолчанию 8080). В репозитории нет паролей:
```sh
cp .env.example .env
python3 scripts/setup-local-secrets.py
docker compose --env-file .env config --quiet
docker compose --env-file .env up -d --build --wait --scale api=2
make check
# make test — после реализации upload в следующем блоке
```
`setup-local-secrets.py` создаёт отсутствующие secret-файлы с правами 0600 и не перезаписывает существующие. Миграции выполняет одноразовый `migrate` под PostgreSQL advisory lock. `s3-volume-init` задаёт владельца нового volume, затем MinIO стартует без root; одноразовый `s3-bootstrap` идемпотентно создаёт закрытый bucket и две ограниченные учётные записи. Повторный `docker compose --env-file .env run --rm s3-bootstrap` безопасен. Для остановки — `docker compose --env-file .env down` без `-v`; для намеренного удаления **только учебных данных** после проверки — `docker compose --env-file .env down -v`.
Версии: Python 3.12.12, PostgreSQL 17.6, HAProxy 3.0.11, MinIO `RELEASE.2025-10-15T17-29-55Z` (образ закреплён digest), MinIO Client `2025.7.21-debian-12-r3` (digest). Проверенный локальный стенд — Colima/arm64 macOS, 2 CPU, 2 054 840 320 байт памяти. Локальная сеть не разрешала DNS `files.pythonhosted.org`, поэтому сборка для проверки использовала **только локальный ignored** `compose.local.yaml` с временным IP CDN; в чистом clone он не нужен при обычном доступе к PyPI.
## Архитектура и решения
TODO: схема процессов/хранилищ, источник истины, транзакционные границы, ограничения. Что перенесено из lab3, что изменено в этой работе. Соответствие переменных из .env.example реальной конфигурации.
Клиент → HAProxy → две API-реплики. PostgreSQL хранит пользователей, сессии, чаты, сообщения, ключи идемпотентности и метаданные вложений. MinIO хранит только байты оригиналов в private bucket `messenger-attachments`; локальная файловая система API не хранит оригиналы. Миграция `004_attachments.sql` связывает вложение с чатом; состав сообщения хранится в `message_attachments` с FK по паре `(id, chat_id)`, чтобы исключить межчатовые ссылки на уровне БД. Статусы таблицы допускают дальнейший переход к асинхронной lab5, но lab4 будет возвращать только `ready` после обеих устойчивых записей.
| Сервис | Образ/роль | Health и volume | Секреты и доступ |
| --- | --- | --- | --- |
| `lb` | HAProxy 3.0.11, единственный host port | проверка backend, без volume | секретов нет |
| `api ×2` | Python 3.12.12, 0,5 CPU/256 MiB на реплику | `/health/ready`, без volume | только DB URL и ограниченные S3 credentials |
| `postgres` | PostgreSQL 17.6 | `pg_isready`, `postgres_data` | только DB password |
| `migrate` | одноразовый Python | завершение 0 | только DB URL |
| `s3` | MinIO security release, 0,5 CPU/384 MiB | `/minio/health/ready`, `s3_data` | только root credentials, наружный порт и консоль не опубликованы |
| `s3-bootstrap` | одноразовый MinIO Client | завершение 0 | root и создаваемые ограниченные credentials |
| `s3-volume-init` | одноразовая настройка владельца volume | завершение 0 | секретов нет |
`infra/minio-api-policy.json` разрешает только операции над объектами одного bucket и чтение его location; создание bucket, изменение IAM и административные операции не разрешены. Отдельная maintenance policy добавляет list для будущей сверки. Bucket не имеет анонимного чтения. Приватность bucket не заменяет проверку членства в чате на API: эта проверка добавляется в блоках upload/download.
## Доказательства критериев
| Критерий README | Команда/сценарий | Наблюдаемый результат | Файл доказательства |
| Критерий README | Команда/сценарий | Наблюдаемый результат | Доказательство |
| --- | --- | --- | --- |
| Публичный smoke | make test | TODO | TODO |
| Остальные пункты уровня 3 | TODO | TODO | TODO |
| Все пункты уровня 4, если заявлен | TODO | TODO | TODO |
| Выбранный трек 5, если заявлен | TODO | TODO | TODO |
TODO: добавить отдельную строку для каждого заявленного критерия. PASS без команды и наблюдения не является доказательством. Проверка инфраструктурного hook требует подтверждения, какие реальные процессы/хранилища перезапущены.
| Перенос lab3 | Compose ×2, текстовая часть `make test`, `make test-persistence`, адресный failover обеих реплик | Текстовый API совместим, прежний токен/сообщение после restart; восстановление записи после остановки каждой реплики 3,123 и 3,149 с | локальные тесты U1; полный smoke остановился на ещё не реализованном upload |
| Приватный S3 и bootstrap | `docker compose run --rm s3-bootstrap` дважды; `docker compose exec -T api python - < student-tests/test_storage_bootstrap.py` | Два повтора завершились 0; S3 PUT/GET ограниченным API пользователем совпадают по байтам, анонимный GET — 403, создание чужого bucket — AccessDenied | `evidence/storage-bootstrap-2026-10-02.txt` |
| Миграция и транзакции | `docker compose exec -T api python - < student-tests/test_database.py`; `... test_auth.py` | Миграции 1–4 применены повторяемо, 2 DB и 3 auth теста PASS | `evidence/storage-bootstrap-2026-10-02.txt` |
## Эксперименты и отказы
TODO: гипотеза, hardware/лимиты, версии, объём данных, профиль нагрузки, concurrency/arrival rate, длительность/прогрев, повторы, успешные RPS, ошибки, p50/p95/p99, CPU/RAM. Сохранить raw summary без tokens и объяснить ограничения измерения.
| Воздействие | Что ожидаем | Что наблюдали | Время восстановления / потеря данных |
| --- | --- | --- | --- |
| TODO | TODO | TODO | TODO |
Запись S3/БД, компенсация после ошибки, ACL, failover файла, параллельные upload и reconciler ещё должны быть проверены. Пока `GET /health/ready` отражает обязательную PostgreSQL зависимость, а готовность MinIO проверяет Compose при запуске; после появления attachment path доступность S3 будет явно учтена в сценариях.
## Ограничения и следующие шаги
TODO: какие отказы выдерживаются и какие нет; что не реализовано; где учебное упрощение; какое улучшение подтверждено, а какое пока гипотеза.
Полный `make test` сейчас ожидаемо получает 415 на `POST attachments`: синхронный upload, скачивание и привязка ещё не реализованы. Проверки уровня 4 и трека 5 не заявляются завершёнными до отдельных fault tests и воспроизводимых измерений. Один MinIO/PostgreSQL/LB и один Docker-host остаются одиночными точками отказа. Локальный HTTP допустим только для изолированного стенда с синтетическими данными; удалённой демонстрации нужен TLS.
+68 -1
View File
@@ -26,6 +26,54 @@ services:
condition: service_healthy
restart: "no"
s3-volume-init:
image: alpine/minio:RELEASE.2025-10-15T17-29-55Z@sha256:cf23643a6cf9ce159c57643ceb88279e431262282428c9e0bf3a7ef1a97e84b4
user: "0:0"
entrypoint: ["/bin/sh", "-c"]
command: ["chown -R 100:100 /data"]
volumes: [s3_data:/data]
restart: "no"
s3:
image: alpine/minio:RELEASE.2025-10-15T17-29-55Z@sha256:cf23643a6cf9ce159c57643ceb88279e431262282428c9e0bf3a7ef1a97e84b4
command: ["server", "/data", "--console-address", ":9001"]
environment:
MINIO_ROOT_USER_FILE: /run/secrets/minio_root_user
MINIO_ROOT_PASSWORD_FILE: /run/secrets/minio_root_password
secrets: [minio_root_user, minio_root_password]
volumes: [s3_data:/data]
depends_on:
s3-volume-init:
condition: service_completed_successfully
healthcheck:
test: ["CMD-SHELL", "wget -q -O /dev/null http://127.0.0.1:9000/minio/health/ready"]
interval: 2s
timeout: 2s
retries: 30
cpus: 0.5
mem_limit: 384m
s3-bootstrap:
image: bitnamilegacy/minio-client:2025.7.21-debian-12-r3@sha256:73bd39f7899a0cef12b8dd5df13aa93a3ed1aaa44236542442e9ac76819ac158
user: "0:0"
entrypoint: ["/bin/sh", "/bootstrap.sh"]
command: []
volumes:
- ./infra/bootstrap-s3.sh:/bootstrap.sh:ro
- ./infra/minio-api-policy.json:/policies/minio-api-policy.json:ro
- ./infra/minio-maintenance-policy.json:/policies/minio-maintenance-policy.json:ro
secrets:
- minio_root_user
- minio_root_password
- s3_access_key_id
- s3_secret_access_key
- s3_maintenance_key_id
- s3_maintenance_secret_key
depends_on:
s3:
condition: service_healthy
restart: "no"
api:
build: .
scale: 2
@@ -34,10 +82,16 @@ services:
APP_PORT: 8080
DATABASE_URL_FILE: /run/secrets/database_url
SESSION_TTL_SECONDS: ${SESSION_TTL_SECONDS:-3600}
secrets: [database_url]
S3_ENDPOINT: s3:9000
S3_BUCKET: messenger-attachments
S3_ACCESS_KEY_ID_FILE: /run/secrets/s3_access_key_id
S3_SECRET_ACCESS_KEY_FILE: /run/secrets/s3_secret_access_key
secrets: [database_url, s3_access_key_id, s3_secret_access_key]
depends_on:
migrate:
condition: service_completed_successfully
s3-bootstrap:
condition: service_completed_successfully
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8080/health/ready', timeout=2).close()"]
interval: 2s
@@ -65,6 +119,19 @@ secrets:
file: ./secrets/postgres_password
database_url:
file: ./secrets/database_url
minio_root_user:
file: ./secrets/minio_root_user
minio_root_password:
file: ./secrets/minio_root_password
s3_access_key_id:
file: ./secrets/s3_access_key_id
s3_secret_access_key:
file: ./secrets/s3_secret_access_key
s3_maintenance_key_id:
file: ./secrets/s3_maintenance_key_id
s3_maintenance_secret_key:
file: ./secrets/s3_maintenance_secret_key
volumes:
postgres_data:
s3_data:
+12
View File
@@ -0,0 +1,12 @@
Lab 4 U2 local Colima/arm64; 2 CPU, 2054840320 bytes RAM; synthetic data only.
Image: alpine/minio:RELEASE.2025-10-15T17-29-55Z, digest sha256:cf23643a6cf9ce159c57643ceb88279e431262282428c9e0bf3a7ef1a97e84b4.
The official minio/minio tag could not be pulled (repository unavailable); pinned alpine/minio security-release build was used.
Build used ignored local compose.local.yaml with temporary PyPI CDN DNS override; ordinary compose.yaml remains independent of this host workaround.
docker compose --env-file .env config --quiet: PASS.
docker compose --env-file .env up -d --wait --scale api=2: PASS after adding one-time s3-volume-init for non-root MinIO write permissions.
docker compose --env-file .env run --rm s3-bootstrap: PASS, repeated twice after initial bootstrap, no duplicate/failure.
docker compose --env-file .env exec -T api python - < student-tests/test_storage_bootstrap.py: 1 PASS; PUT/GET exact bytes, anonymous GET 403, foreign bucket create AccessDenied.
docker compose --env-file .env exec -T api python - < student-tests/test_database.py: 2 PASS; migrations 1-4, race/rollback/keyset history.
docker compose --env-file .env exec -T api python - < student-tests/test_auth.py: 3 PASS; Basic/Bearer and short TTL.
No credentials, session tokens or object keys are included in this evidence.
+16
View File
@@ -0,0 +1,16 @@
#!/bin/sh
set -eu
read_secret() {
tr -d '\n' < "/run/secrets/$1"
}
mc alias set local http://s3:9000 "$(read_secret minio_root_user)" "$(read_secret minio_root_password)" >/dev/null
mc mb --ignore-existing local/messenger-attachments >/dev/null
mc anonymous set none local/messenger-attachments >/dev/null
mc admin policy create local messenger-api /policies/minio-api-policy.json >/dev/null
mc admin policy create local messenger-maintenance /policies/minio-maintenance-policy.json >/dev/null
mc admin user add local "$(read_secret s3_access_key_id)" "$(read_secret s3_secret_access_key)" >/dev/null
mc admin policy attach local messenger-api --user "$(read_secret s3_access_key_id)" >/dev/null
mc admin user add local "$(read_secret s3_maintenance_key_id)" "$(read_secret s3_maintenance_secret_key)" >/dev/null
mc admin policy attach local messenger-maintenance --user "$(read_secret s3_maintenance_key_id)" >/dev/null
+15
View File
@@ -0,0 +1,15 @@
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:GetBucketLocation"],
"Resource": ["arn:aws:s3:::messenger-attachments"]
},
{
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
"Resource": ["arn:aws:s3:::messenger-attachments/*"]
}
]
}
+15
View File
@@ -0,0 +1,15 @@
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:GetBucketLocation", "s3:ListBucket"],
"Resource": ["arn:aws:s3:::messenger-attachments"]
},
{
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
"Resource": ["arn:aws:s3:::messenger-attachments/*"]
}
]
}
+32
View File
@@ -0,0 +1,32 @@
CREATE TABLE attachments (
id uuid PRIMARY KEY,
chat_id uuid NOT NULL REFERENCES chats(id) ON DELETE CASCADE,
filename text NOT NULL,
object_key text NOT NULL UNIQUE,
content_type text NOT NULL CHECK (content_type IN ('image/png', 'image/jpeg')),
size_bytes bigint NOT NULL CHECK (size_bytes BETWEEN 1 AND 10485760),
sha256 text NOT NULL CHECK (sha256 ~ '^[0-9a-f]{64}$'),
status text NOT NULL DEFAULT 'ready' CHECK (status IN ('queued', 'processing', 'ready', 'failed')),
error_code text,
created_at timestamptz NOT NULL DEFAULT clock_timestamp(),
UNIQUE (id, chat_id)
);
CREATE INDEX attachments_chat_idx ON attachments (chat_id, created_at);
ALTER TABLE messages DROP CONSTRAINT messages_text_check;
ALTER TABLE messages ADD CONSTRAINT messages_text_check CHECK (char_length(text) BETWEEN 0 AND 4000);
ALTER TABLE messages ADD CONSTRAINT messages_id_chat_unique UNIQUE (id, chat_id);
CREATE TABLE message_attachments (
message_id uuid NOT NULL,
chat_id uuid NOT NULL,
attachment_id uuid NOT NULL,
position smallint NOT NULL CHECK (position BETWEEN 0 AND 9),
PRIMARY KEY (message_id, attachment_id),
UNIQUE (message_id, position),
FOREIGN KEY (message_id, chat_id) REFERENCES messages(id, chat_id) ON DELETE CASCADE,
FOREIGN KEY (attachment_id, chat_id) REFERENCES attachments(id, chat_id)
);
CREATE INDEX message_attachments_attachment_idx ON message_attachments (attachment_id);
+1
View File
@@ -4,3 +4,4 @@ uvicorn==0.38.0
psycopg[binary,pool]==3.2.12
psycopg-pool==3.3.3
argon2-cffi==25.1.0
minio==7.2.20
+42
View File
@@ -0,0 +1,42 @@
"""Create local Compose secrets without printing or overwriting existing values."""
import os
import secrets
from pathlib import Path
ROOT = Path(__file__).resolve().parents[1] / "secrets"
def write(name: str, value: str) -> None:
fd = os.open(ROOT / name, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, "w") as out:
out.write(value)
def main() -> None:
ROOT.mkdir(mode=0o700, exist_ok=True)
db_names = {"postgres_password", "database_url"}
s3_names = {
"minio_root_user", "minio_root_password", "s3_access_key_id", "s3_secret_access_key",
"s3_maintenance_key_id", "s3_maintenance_secret_key",
}
for names in (db_names, s3_names):
existing = {name for name in names if (ROOT / name).exists()}
if existing and existing != names:
raise SystemExit(f"Incomplete secret group: {', '.join(sorted(names - existing))}")
if not (ROOT / "postgres_password").exists():
password = secrets.token_urlsafe(32)
write("postgres_password", password)
write("database_url", f"postgresql://messenger:{password}@postgres:5432/messenger")
if not (ROOT / "minio_root_user").exists():
write("minio_root_user", "lab4admin")
write("minio_root_password", secrets.token_urlsafe(32))
write("s3_access_key_id", secrets.token_hex(10))
write("s3_secret_access_key", secrets.token_urlsafe(32))
write("s3_maintenance_key_id", secrets.token_hex(10))
write("s3_maintenance_secret_key", secrets.token_urlsafe(32))
if __name__ == "__main__":
main()
+25
View File
@@ -0,0 +1,25 @@
"""Private S3 access shared by attachment routes and maintenance jobs."""
import os
from functools import lru_cache
from pathlib import Path
from minio import Minio
BUCKET = "messenger-attachments"
def secret(name: str) -> str:
return Path(os.environ[f"{name}_FILE"]).read_text(encoding="utf-8").strip()
@lru_cache(maxsize=1)
def storage() -> Minio:
return Minio(
os.environ.get("S3_ENDPOINT", "s3:9000"),
access_key=secret("S3_ACCESS_KEY_ID"),
secret_key=secret("S3_SECRET_ACCESS_KEY"),
secure=False,
region="us-east-1",
)
+3 -2
View File
@@ -14,12 +14,13 @@ import urllib.request
from uuid import uuid4
import psycopg
from src.db import database_url
URL = os.environ.get("DATABASE_URL")
URL = database_url() if os.environ.get("DATABASE_URL") or os.environ.get("DATABASE_URL_FILE") else None
@unittest.skipUnless(URL, "set DATABASE_URL to a disposable PostgreSQL database")
@unittest.skipUnless(URL, "set DATABASE_URL or DATABASE_URL_FILE to a disposable PostgreSQL database")
class AuthTests(unittest.TestCase):
@classmethod
def setUpClass(cls):
+4 -3
View File
@@ -9,13 +9,14 @@ from uuid import uuid4
import psycopg
from src.db import database_url
from src.store import Store
URL = os.environ.get("DATABASE_URL")
URL = database_url() if os.environ.get("DATABASE_URL") or os.environ.get("DATABASE_URL_FILE") else None
@unittest.skipUnless(URL, "set DATABASE_URL to a disposable PostgreSQL database")
@unittest.skipUnless(URL, "set DATABASE_URL or DATABASE_URL_FILE to a disposable PostgreSQL database")
class DatabaseTests(unittest.TestCase):
@classmethod
def setUpClass(cls):
@@ -30,7 +31,7 @@ class DatabaseTests(unittest.TestCase):
def test_migration_and_unique_username_race(self):
with psycopg.connect(URL) as conn:
versions = conn.execute("SELECT version FROM schema_migrations").fetchall()
self.assertEqual(versions, [(1,), (2,), (3,)])
self.assertEqual(versions, [(1,), (2,), (3,), (4,)])
name = "u_" + uuid4().hex[:16]
def register(_):
+38
View File
@@ -0,0 +1,38 @@
"""Run inside an API container after S3 bootstrap."""
import io
import unittest
from uuid import uuid4
from urllib.error import HTTPError
from urllib.request import urlopen
from minio.error import S3Error
from src.attachments import BUCKET, storage
class StorageBootstrapTests(unittest.TestCase):
def test_private_bucket_and_scoped_api_credentials(self):
client = storage()
key = "test-bootstrap/" + uuid4().hex
data = b"private attachment fixture"
client.put_object(BUCKET, key, io.BytesIO(data), len(data), content_type="application/octet-stream")
try:
response = client.get_object(BUCKET, key)
try:
self.assertEqual(response.read(), data)
finally:
response.close()
response.release_conn()
with self.assertRaises(HTTPError) as denied:
urlopen(f"http://s3:9000/{BUCKET}/{key}", timeout=3)
self.assertEqual(denied.exception.code, 403)
with self.assertRaises(S3Error) as forbidden:
client.make_bucket("forbidden-" + uuid4().hex)
self.assertEqual(forbidden.exception.code, "AccessDenied")
finally:
client.remove_object(BUCKET, key)
if __name__ == "__main__":
unittest.main()