Об этом проекте

## Обзор Traffic Analytics — это веб-аналитика-прокси, предназначенный для сайтов на Ghost. Он перехватывает вызовы `POST /api/v1/page_hit`, выполняемые скриптом `ghost-stats.js` Ghost, обогащает полезную нагрузку (анализ user-agent, анализ рефереров, генерация подписей пользователей) и пересылает данные в API Tinybird `/v0/events`, где они сохраняются в базе данных ClickHouse. ## Архитектура и режимы работы - **Пакетный режим (по умолчанию)** — сервис приема запросов проверяет их, фильтрует ботов и публикует необработанные события в тему Google Cloud Pub/Sub. Отдельный рабочий процесс потребляет эту подписку, обогащает каждое событие, группирует их и пересылает в Tinybird. Это разделяет обработку запросов и прием данных, повышая пропускную способность. - **Режим прокси (синхронный)** — если тема Pub/Sub не настроена, сервис приема выполняет обогащение данных непосредственно и пересылает запрос напрямую в Tinybird в рамках одного HTTP-цикла. Режим выбирается через переменную окружения `WORKER_MODE` и наличие `PUBSUB_TOPIC_PAGE_HITS_RAW`. ## Ключевые функции - Анализ user-agent для определения ОС, браузера и устройства. - Парсинг и категоризация URL рефереров. - Приватные подписи пользователей с ежедневно меняющимся солью. - Необязательный заголовок `x-ghost-bot-detected: true` для отфильтрованного трафика ботов. ## Конфигурация Скопируйте `.env.example` в `.env` и измените значения. Важные переменные: - `WORKER_MODE` — `worker` или `ingest`. - `PUBSUB_TOPIC_PAGE_HITS_RAW` — определяет пакетный режим. - `ENABLE_BOT_DETECTION_HEADER` — включает заголовок ответа для обнаружения ботов. ## Рабочий процесс разработки 1. **Необходимые условия** — Docker (Desktop или Orbstack) и Docker Compose. 2. Клонируйте репозиторий и запустите `pnpm dev`, чтобы запустить все сервисы; API аналитики будет доступен по адресу `http://localhost:3000`. 3. Для локальной интеграции с Ghost выполните `pnpm dev:ghost` в этом репозитории и `pnpm dev:analytics:local` в репозитории Ghost. Это соединяет два контейнера через общую Docker-сеть. ### Поддержка нескольких рабочих деревьев Проект может одновременно работать с несколькими Git-рабочими деревьями. Каждое дерево использует свой файл `.env` для установки уникальных портов, имен проектов Docker Compose и изолированных томов, позволяя параллельной разработке без конфликтов портов. ## Тестирование и линтинг - `pnpm test:types` — проверка типов TypeScript. - `pnpm test:unit` — модульные тесты. - `pnpm test:integration` — интеграционные тесты. - `pnpm test:e2e` — end-to-end тесты с WireMock. - `pnpm lint` — линтинг ESLint. Все команды тестирования выполняются внутри Docker-контейнеров для обеспечения согласованности среды. ## Конвейер развертывания - **Рабочий процесс веток** — откройте PR, при желании добавьте метку `deploy-staging` для запуска развертывания в стейджинг. - **Действия при слиянии** — автоматическое увеличение версии патча, создание Git-тега, публикация образа Docker Hub, развертывание в Cloud Run на стейджинге и продакшене, проверки состояния и уведомления в Slack. - **Ручный запуск** — используйте интерфейс GitHub Actions для запуска рабочего процесса «Deploy» через `workflow_dispatch`. Полная информация о CI/CD находится в `docs/deployment.md`. ## Документация - `docs/architecture.md` — подробные диаграммы пакетного и прокси-режимов, конвейера Pub/Sub, OpenTelemetry и дизайна рабочего процесса. - `docs/deployment.md` — CI/CD, поток стейджинг/продакшен и процедуры отката. ## Лицензия MIT © Ghost Foundation (2013–2026).