trafficanalytics

## 개요 Traffic Analytics는 Ghost 사이트를 위해 설계된 웹 분석 프록시입니다. Ghost의 `ghost-stats.js` 스크립트가 호출하는 `POST /api/v1/page_hit` 요청을 가로채어 페이로드를 강화(User-Agent 파싱, 리퍼러 분석, 사용자 서명 생성)하고, 이를 Tinybird의 `/v0/events` API로 전달하여 ClickHouse 데이터베이스에 저장합니다. ## 아키텍처 및 실행 모드 - **배치 모드 (기본값)** – ingest 서비스가 요청을 검증하고 봇을 필터링한 후, 원시 이벤트를 Google Cloud Pub/Sub 토픽으로 발행합니다. 별도의 워커가 구독을 소비하여 각 이벤트를 강화하고 배치 처리하여 Tinybird로 전달합니다. 이는 요청 처리와 수집 과정을 분리하여 처리량을 향상시킵니다. - **프록시 모드 (동기식)** – Pub/Sub 토픽이 설정되지 않은 경우, ingest 서비스가 인라인으로 강화 작업을 수행하고 동일한 HTTP 사이클 내에서 요청을 Tinybird로 직접 프록시합니다. 모드는 `WORKER_MODE` 환경 변수와 `PUBSUB_TOPIC_PAGE_HITS_RAW` 존재 여부에 따라 선택됩니다. ## 주요 기능 - OS, 브라우저 및 기기 감지를 위한 User-Agent 파싱. - 리퍼러 URL 파싱 및 분류. - 매일 교체되는 솔트(salt)를 사용한 개인정보 보호 사용자 서명. - 필터링된 봇 트래픽을 위한 선택적 `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`를 실행하고 Ghost 저장소에서 `pnpm dev:analytics:local`을 실행하십시오. 이를 통해 두 컨테이너가 공유 Docker 네트워크로 연결됩니다. ### 멀티 워크트리(Multi-Worktree) 지원 이 프로젝트는 여러 Git 워크트리를 동시에 실행할 수 있습니다. 각 워크트리는 고유한 `.env` 파일을 사용하여 포트, Docker compose 프로젝트 이름 및 격리된 볼륨을 설정하므로 포트 충돌 없이 병렬 개발이 가능합니다. ## 테스트 및 린팅 - `pnpm test:types` – TypeScript 타입 체크. - `pnpm test:unit` – 유닛 테스트. - `pnpm test:integration` – 통합 테스트. - `pnpm test:e2e` – WireMock을 이용한 엔드-투-엔드 테스트. - `pnpm lint` – ESLint 린팅. 모든 테스트 명령은 환경 일관성을 위해 Docker 컨테이너 내부에서 실행됩니다. ## 배포 파이프라인 - **브랜치 워크플로우** – PR을 생성하고, 선택적으로 `deploy-staging` 라벨을 붙여 스테이징 배포를 트리거합니다. - **머지 액션** – 자동 패치 버전 업데이트, Git 태그 생성, Docker Hub 이미지 게시, 스테이징 및 프로덕션 Cloud Run 배포, 상태 확인 및 Slack 알림이 수행됩니다. - **수동 트리거** – GitHub Actions UI의 `workflow_dispatch`를 통해 "Deploy" 워크플로우를 실행할 수 있습니다. 전체 CI/CD 세부 사항은 `docs/deployment.md`에 있습니다. ## 문서 - `docs/architecture.md` – 배치 vs 프록시 모드, Pub/Sub 파이프라인, OpenTelemetry 및 워커 설계에 대한 상세 다이어그램. - `docs/deployment.md` – CI/CD 파이프라인, 스테이징/프로덕션 흐름 및 롤백 절차. ## 라이선스 MIT © Ghost Foundation (2013‑2026).