104 lines
4.0 KiB
Markdown
104 lines
4.0 KiB
Markdown
# ADa Workshop
|
||
|
||
Минимальный каталог сервисов для CTF Attack-Defense. Пользователь видит
|
||
сервисы, фильтрует их, выбирает для игры и загружает ZIP-архив. Метаданные
|
||
хранятся в PostgreSQL, а сам ZIP — в S3-совместимом хранилище Backblaze B2.
|
||
|
||
## Что необходимо
|
||
|
||
- Python 3.11 или новее;
|
||
- запущенный PostgreSQL и созданная пустая база данных;
|
||
- бакет Backblaze B2 и Application Key с правами **Read and Write**;
|
||
- файлы проекта:
|
||
|
||
```text
|
||
Workshop/
|
||
├── main.py # Запуск FastAPI и отдача страницы
|
||
├── routers.py # API каталога, проверка ZIP и загрузка в B2
|
||
├── database.py # Модели и подключение PostgreSQL
|
||
├── workshop.html # Интерфейс мастерской
|
||
├── requirements.txt # Python-зависимости
|
||
└── .evn # Локальные настройки и секреты, в Git не добавлять
|
||
```
|
||
|
||
Папки `.venv/` и `backups/` для запуска не нужны: первая создаётся командами
|
||
ниже, вторая содержит резервные копии разработки.
|
||
|
||
## Настройка `.evn`
|
||
|
||
Создай в папке `Workshop` файл именно с именем `.evn` и заполни его:
|
||
|
||
```env
|
||
DATABASE_URL=postgresql+psycopg://POSTGRES_USER:POSTGRES_PASSWORD@localhost:5432/WORKSHOP_DB
|
||
|
||
S3_ENDPOINT_URL=https://s3.YOUR_REGION.backblazeb2.com
|
||
S3_REGION=YOUR_REGION
|
||
S3_BUCKET=YOUR_BUCKET_NAME
|
||
S3_ACCESS_KEY=YOUR_B2_keyID
|
||
S3_SECRET_KEY=YOUR_B2_applicationKey
|
||
```
|
||
|
||
Для Backblaze B2:
|
||
|
||
- `S3_ACCESS_KEY` — поле **keyID** созданного Application Key;
|
||
- `S3_SECRET_KEY` — поле **applicationKey**;
|
||
- `S3_REGION` — регион из S3 Endpoint, например `eu-central-003`;
|
||
- `S3_BUCKET` — имя бакета, например `workshop-ada`.
|
||
|
||
Не публикуй `.evn`, `keyID` или `applicationKey`.
|
||
|
||
## Запуск на Windows
|
||
|
||
Открой PowerShell в папке проекта и выполни:
|
||
|
||
```powershell
|
||
cd C:\путь\к\Workshop
|
||
py -m venv .venv
|
||
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
|
||
.\.venv\Scripts\python.exe -m uvicorn main:app --reload
|
||
```
|
||
|
||
Открой в браузере: http://127.0.0.1:8000
|
||
|
||
## Запуск на macOS
|
||
|
||
Открой Terminal в папке проекта и выполни:
|
||
|
||
```bash
|
||
cd /путь/к/Workshop
|
||
python3 -m venv .venv
|
||
source .venv/bin/activate
|
||
python -m pip install -r requirements.txt
|
||
python -m uvicorn main:app --reload
|
||
```
|
||
|
||
Открой в браузере: http://127.0.0.1:8000
|
||
|
||
Для остановки сервера в обоих случаях нажми `Ctrl+C`.
|
||
|
||
## Формат загружаемого ZIP
|
||
|
||
Архив должен содержать файлы в корне архива, без внешней папки `ada/`:
|
||
|
||
```text
|
||
ada.zip
|
||
├── checker/
|
||
│ └── checker.py
|
||
└── service/
|
||
├── docker-compose.yml
|
||
├── Dockerfile.api
|
||
└── ...
|
||
```
|
||
|
||
Обязательны `checker/checker.py`, `service/docker-compose.yml` и
|
||
`service/Dockerfile.api`. Максимальный размер ZIP — 5 МБ; все файлы должны
|
||
лежать только внутри `checker/` или `service/`.
|
||
|
||
## Если что-то не работает
|
||
|
||
- `503 S3-хранилище недоступно` — проверь значения B2 в `.evn` и перезапусти
|
||
сервер.
|
||
- `InvalidAccessKeyId` — в `S3_ACCESS_KEY` нужен `keyID`, а не имя ключа.
|
||
- `422` при загрузке — проверь структуру ZIP и обязательные файлы.
|
||
- Карточки сервисов не пропадают после очистки БД — обнови страницу браузера.
|