Перейти к содержанию

Глава 11: Обзор архитектуры

Аудитория: DevOps, платформенные инженеры

Топология системы

                                    Internet
                                       │
                                 ┌─────┴─────┐
                                 │   nginx    │  :443 (TLS termination)
                                 └──┬──────┬──┘
                                    │      │
                          ┌─────────┘      └─────────┐
                          │                          │
                  ┌───────┴────────┐       ┌─────────┴─────────┐
                  │  OAuth2 Proxy  │       │  Next.js Dashboard │  :3000
                  │  (Google SSO)  │       │  (static + SSR)    │
                  └───────┬────────┘       └───────────────────┘
                          │
                  ┌───────┴────────┐
                  │   FastAPI API  │  :8000
                  │  (118+ routes) │
                  └───────┬────────┘
                          │
              ┌───────────┴───────────┐
              │                       │
    ┌─────────┴──────────┐   ┌────────┴────────┐
    │ Cloud SQL Proxy    │   │   BigQuery       │
    │ (Postgres sidecar) │   │ (batch analytics)│
    └─────────┬──────────┘   └─────────────────┘
              │
    ┌─────────┴──────────┐
    │  Cloud SQL         │
    │  (Postgres 15)     │
    └────────────────────┘

Компоновка контейнеров

Production-среда работает на одной GCP VM (catscan-production-sg, зона asia-southeast1-b) с использованием docker-compose.gcp.yml.

Контейнер Образ Порт Назначение
catscan-api asia-southeast1-docker.pkg.dev/.../api:sha-XXXXXXX 8000 FastAPI-бэкенд
catscan-dashboard asia-southeast1-docker.pkg.dev/.../dashboard:sha-XXXXXXX 3000 Next.js-фронтенд
oauth2-proxy стандартный образ oauth2-proxy 4180 Аутентификация через Google OAuth2
cloudsql-proxy Google Cloud SQL Auth Proxy 5432 Прокси подключения к Postgres
nginx стандартный nginx с конфигурацией 80/443 Обратный прокси, TLS, маршрутизация

Цепочка доверия аутентификации

Browser → nginx → OAuth2 Proxy → sets X-Email header → nginx → API
  1. Браузер обращается к nginx.
  2. nginx маршрутизирует /oauth2/* на OAuth2 Proxy.
  3. OAuth2 Proxy аутентифицирует пользователя через Google и устанавливает заголовок X-Email.
  4. Последующие запросы проходят через nginx с сохранённым заголовком X-Email.
  5. API считывает X-Email и доверяет ему (при OAUTH2_PROXY_ENABLED=true).

Важно: API доверяет заголовку X-Email только из внутреннего трафика. Внешние запросы с поддельным заголовком X-Email отклоняются nginx.

Почему две базы данных

Cat-Scan использует одновременно Postgres и BigQuery для разных задач:

Аспект Postgres (Cloud SQL) BigQuery
Роль Операционная база данных: обслуживает приложение Хранилище данных: хранит сырые данные, выполняет пакетную аналитику
Модель стоимости Фиксированная стоимость хостинга, неограниченные запросы Оплата за запрос в зависимости от объёма просканированных данных
Задержка Ответы за миллисекунды Накладные расходы 1–3 секунды даже для простых запросов
Конкурентность Обрабатывает сотни API-подключений Не рассчитан на одновременные обновления дашборда
Данные Предагрегированные сводки, конфигурации, пользовательские данные Сырые гранулярные строки (миллионы в день)

Принцип: BigQuery — это архивный склад; Postgres — витрина магазина. Вы не отправляете покупателей рыться на складе.

Ключевая структура кодовой базы

/api/routers/       FastAPI route handlers (118+ endpoints)
/services/          Business logic layer
/storage/           Database access (Postgres repos, BigQuery clients)
/dashboard/src/     Next.js 14 frontend (App Router)
/scripts/           Operational and diagnostic scripts
/docs/              Architecture docs and AI agent logs

Бэкенд следует паттерну Router -> Service -> Repository. Роутеры обрабатывают HTTP; сервисы содержат бизнес-логику; репозитории выполняют SQL.

Связанные разделы