BackgroundTileServer

Архитектура

BackgroundTileServer состоит из 3 контейнеров:

• Nginx — reverse proxy, 5 ГБ дисковый кэш тайлов, WebSocket upgrade, gzip
• FastAPI — обработка запросов, проксирование к внешним провайдерам, Redis-кэш
• Redis — кэш тайлов, атомарные счётчики, реестр инстансов

Жизненный цикл запроса

Двухуровневый кэш: Nginx (диск, 5 ГБ, 24 ч) → Redis (память, TTL настраивается). При повторном запросе тайл отдаётся из Nginx за <1 мс.

Провайдеры

Быстрый старт

# Клонировать и запустить
git clone <repo-url>
cd BackgroundTileServer

# Запустить
docker compose up -d --build

# Проверить
curl http://localhost:8083/health
curl http://localhost:8083/providers

После запуска доступны:

• Просмотр — интерактивная карта с Leaflet
• Мониторинг — дашборд состояния в реальном времени
• Swagger — интерактивная API-документация

API — Тайлы

Получить тайл

Возвращает тайл-изображение (PNG, JPEG) от выбранного провайдера.

Заголовки ответа

curl -o tile.png "http://localhost:8083/tiles/osm/14/9876/5432"

const resp = await fetch('/tiles/google-satellite/14/9876/5432');
const blob = await resp.blob();

import httpx

resp = httpx.get("http://localhost:8083/tiles/osm/14/9876/5432")
with open("tile.png", "wb") as f:
    f.write(resp.content)

Leaflet интеграция

L.tileLayer('/tiles/osm/{z}/{x}/{y}', {
    minZoom: 0,
    maxZoom: 19,
}).addTo(map);

Список провайдеров

Возвращает список всех доступных провайдеров с метаданными.

[
  {
    "id": "osm",
    "name": "OpenStreetMap",
    "min_zoom": 0,
    "max_zoom": 19,
    "attribution": "© OpenStreetMap contributors"
  },
  ...
]

API — Мониторинг

Статистика (JSON)

Полная статистика: uptime, RPS, latency, Redis, провайдеры, клиенты, инстансы.

WebSocket мониторинг

Пушит статистику каждые 2 секунды.

Health Check

Возвращает {"status": "ok"}.

Кэширование

Redis кэш (L1)

Все тайлы кэшируются в Redis. TTL настраивается:

Ключи Redis: tile:{provider}:{z}:{x}:{y}

Nginx кэш (L2)

Nginx кэширует ответы /tiles/ на диске (до 5 ГБ, 24 ч).

Масштабирование

Горизонтальное масштабирование

docker compose up -d --scale app=4

Реестр инстансов

Каждый инстанс публикует heartbeat в Redis каждые 10 секунд.

Деплой

Docker Compose

docker compose up -d --build

Переменные окружения

Kubernetes

kubectl apply -f k8s/

Обработка ошибок

Swagger / ReDoc

• Swagger UI — /docs
• ReDoc — /redoc
• OpenAPI JSON — /openapi.json