trafficanalytics

## 概要 Traffic Analyticsは、Ghostサイト向けに設計されたウェブ解析プロキシです。Ghostの`ghost-stats.js`スクリプトによって行われる`POST /api/v1/page_hit`コールをインターセプトし、ペイロードを充実（ユーザーエージェント解析、リファラー分析、ユーザー署名の生成）させ、Tinybirdの`/v0/events` APIにデータを転送します。データはそこでClickHouseデータベースに保存されます。 ## アーキテクチャと実行モード - **バッチモード（デフォルト）** – インジェストサービスがリクエストを検証し、ボットをフィルタリングして、生のイベントをGoogle Cloud Pub/Subトピックにパブリッシュします。別のワーカーがサブスクリプションを消費し、各イベントを充実させ、バッチ処理してTinybirdに転送します。これにより、リクエスト処理とインジェストが切り離され、スループットが向上します。 - **プロキシモード（同期）** – Pub/Subトピックが設定されていない場合、インジェストサービスがインラインで充実処理を行い、同じHTTPサイクル内でリクエストを直接Tinybirdにプロキシします。 モードは、環境変数`WORKER_MODE`および`PUBSUB_TOPIC_PAGE_HITS_RAW`の有無によって選択されます。 ## 主な機能 - OS、ブラウザ、デバイス検出のためのユーザーエージェント解析。 - リファラー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`を、Ghostリポジトリで`pnpm dev:analytics:local`を実行します。これにより、共有Dockerネットワークを介して2つのコンテナが接続されます。 ### マルチワークツリー（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` – バッチモード対プロキシモード、Pub/Subパイプライン、OpenTelemetry、およびワーカー設計の詳細な図解。 - `docs/deployment.md` – CI/CDパイプライン、ステージング/本番フロー、およびロールバック手順。 ## ライセンス MIT © Ghost Foundation (2013‑2026).