Photo Map Service � ������������ ������ ���������� ���� �� ������������� ����� (EXIF GPS)
|
|
||
|---|---|---|
| .gitea/workflows | ||
| app | ||
| demo_photos | ||
| deploy | ||
| docs/wiki | ||
| scripts | ||
| tests | ||
| .gitignore | ||
| allure-results.zip | ||
| Dockerfile | ||
| README.md | ||
| requirements-dev.txt | ||
| requirements.txt | ||
| sonar-project.properties | ||
Photo Map Service
Веб-сервис для визуализации личной библиотеки фотографий на интерактивной карте. Сканирует файловую систему (NAS / локальный диск), извлекает GPS-координаты и метаданные из EXIF, сохраняет в PostgreSQL и отображает точки на карте.
Архитектура
┌─ разработчик ─┐ push ┌──────────────┐ ┌────────────┐
│ git / IDE ├──────────►│ Gitea :3000 ├───────►│ act_runner │
└───────────────┘ └──────────────┘ └─────┬──────┘
│ job-контейнер
CI: pytest (unit + интеграция на реальном PG) ◄───┘
→ Allure :5050 → SonarQube :9090 Quality Gate → ntfy :8090
┌─ docker network devstack_devnet (VM 192.168.2.112) ──────────┐
│ photomap :8000 ──► PostgreSQL 16 (база `photomap`) │
│ │ │
│ └── читает /photos (RO) ── библиотека фото на NAS │
│ └── пишет /data/thumbnails ── кэш миниатюр │
└───────────────────────────────────────────────────────────────┘
Ключевые решения:
- FastAPI — OpenAPI-документация (
/docs) из коробки: контракт API всегда актуален, по нему удобно писать тесты. - Отдельная БД в общем PostgreSQL — принцип devstack «одна СУБД,
изолированные базы». Координаты —
float8+ B-tree: выборки по прямоугольнику карты (bbox) этого достаточно, PostGIS не нужен. - Библиотека фото монтируется read-only — сервис физически не может испортить пользовательские файлы.
- Инкрементальное сканирование по
(path, mtime)— повторный прогон не перечитывает неизменённые файлы. - Ленивые миниатюры — генерируются при первом запросе и кэшируются на диске; сканирование остаётся быстрым.
- Фоновое сканирование —
POST /api/scanотвечает 202 сразу, фронт поллит/api/scans/{id}; счётчики коммитятся каждые 25 файлов. Параллельный запуск отклоняется (409); зависшие после рестарта прогоны помечаются failed при старте. - Bbox-запросы — фронт получает только точки видимой области, карта не деградирует при росте библиотеки.
- Фронтенд без сборки — Leaflet + markercluster завендорены, сервис полностью автономен в LAN (кроме тайлов OSM).
API
| Метод | Путь | Назначение |
|---|---|---|
| GET | /api/health |
liveness |
| GET | /api/health/db |
readiness (проверка БД) |
| GET | /api/photos?min_lat=…&max_lat=…&min_lon=…&max_lon=… |
точки в bbox |
| GET | /api/photos/{id} |
карточка фото |
| GET | /api/photos/{id}/thumbnail |
миниатюра (ленивая генерация) |
| GET | /api/photos/{id}/file |
оригинал |
| POST | /api/scan |
запустить сканирование (202 Accepted, фон) |
| GET | /api/scans |
история сканирований |
| GET | /api/scans/{id} |
статус/прогресс (поллинг раз в секунду) |
Структура
app/
main.py — FastAPI-приложение, эндпоинты
config.py — настройки из env (12-factor)
db.py — SQLAlchemy (ленивая инициализация движка)
models.py — ORM: Photo, ScanJob
exif_utils.py — парсинг EXIF (exifread, без декодирования пикселей)
scanner.py — инкрементальный сканер библиотеки
thumbnails.py — ленивая генерация миниатюр (Pillow)
static/ — карта (Leaflet, завендорен)
tests/
test_health.py — smoke-контракты API (SQLite)
test_scanner.py — сканер на реальных EXIF-файлах (piexif)
test_thumbnails.py — миниатюры и отдача файлов
test_integration.py — настоящий PostgreSQL (в CI; локально skip)
deploy/ — docker-compose.yml для VM (+ .env.example)
scripts/ — генератор демо-библиотеки с GPS EXIF
CI (Gitea Actions)
push → pytest (unit + интеграция на реальном PostgreSQL) → Allure → SonarQube Scan → Quality Gate → ntfy
Секреты репозитория: SONAR_TOKEN, SONAR_HOST_URL,
PHOTOMAP_TEST_DATABASE_URL, NTFY_TOPIC.
Деплой на NAS
cd /volume1/docker/photomap
cp deploy/.env.example .env # заполнить пароль БД
sudo docker-compose --env-file .env up -d --build
Сервис: http://192.168.2.112:8000 (карта), http://192.168.2.112:8000/docs (API).
Локальная разработка
pip install -r requirements.txt -r requirements-dev.txt
uvicorn app.main:app --reload --port 8000
pytest --cov=app -q