इस प्रोजेक्ट के बारे में

## अवलोकन Traffic Analytics Ghost साइटों के लिए डिज़ाइन किया गया एक वेब-एनालिटिक्स प्रॉक्सी है। यह Ghost के `ghost-stats.js` स्क्रिप्ट द्वारा किए गए `POST /api/v1/page_hit` कॉल्स को इंटरसेप्ट करता है, पेलोड को समृद्ध करता है (user-agent पार्सिंग, रेफरर विश्लेषण, यूजर सिग्नेचर जनरेशन) और डेटा को Tinybird के `/v0/events` API पर भेजता है, जहाँ इसे ClickHouse डेटाबेस में स्टोर किया जाता है। ## आर्किटेक्चर और रन मोड - **बैच मोड (डिफ़ॉल्ट)** – इनजेस्ट सेवा अनुरोधों को मान्य करती है, बॉट्स को फ़िल्टर करती है, और रॉ इवेंट्स को Google Cloud Pub/Sub टॉपिक पर पब्लिश करती है। एक अलग वर्कर सब्सक्रिप्शन का उपभोग करता है, प्रत्येक इवेंट को समृद्ध करता है, उन्हें बैच करता है और Tinybird को भेजता है। यह अनुरोध हैंडलिंग को इनजेशन से अलग करता है और थ्रूपुट में सुधार करता है। - **प्रॉक्सी मोड (सिंक्रोनस)** – जब कोई Pub/Sub टॉपिक कॉन्फ़िगर नहीं होता है, तो इनजेस्ट सेवा इनलाइन समृद्धिकरण करती है और उसी HTTP साइकिल में अनुरोध को सीधे Tinybird पर प्रॉक्सी करती है। मोड का चयन `WORKER_MODE` एनवायरनमेंट वेरिएबल और `PUBSUB_TOPIC_PAGE_HITS_RAW` की उपस्थिति के माध्यम से किया जाता है। ## मुख्य विशेषताएं - OS, ब्राउज़र और डिवाइस डिटेक्शन के लिए 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` और Ghost रेपो में `pnpm dev:analytics:local` चलाएं। यह साझा Docker नेटवर्क के माध्यम से दोनों कंटेनरों को एक साथ जोड़ता है। ### मल्टी-वर्कट्री सपोर्ट प्रोजेक्ट एक साथ कई Git वर्कट्री चला सकता है। प्रत्येक वर्कट्री अद्वितीय पोर्ट, Docker compose प्रोजेक्ट नाम और अलग वॉल्यूम सेट करने के लिए अपनी स्वयं की `.env` फ़ाइल का उपयोग करता है, जिससे पोर्ट संघर्ष के बिना समानांतर विकास संभव होता है। ## टेस्टिंग और लिंटिंग - `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 नोटिफिकेशन। - **मैनुअल ट्रिगर** – `workflow_dispatch` के माध्यम से "Deploy" वर्कफ़्लो चलाने के लिए GitHub Actions UI का उपयोग करें। पूर्ण CI/CD विवरण `docs/deployment.md` में हैं। ## दस्तावेज़ीकरण - `docs/architecture.md` – बैच बनाम प्रॉक्सी मोड, Pub/Sub पाइपलाइन, OpenTelemetry और वर्कर डिज़ाइन के विस्तृत आरेख। - `docs/deployment.md` – CI/CD पाइपलाइन, स्टेजिंग/प्रोडक्शन फ्लो और रोलबैक प्रक्रियाएं। ## लाइसेंस MIT © Ghost Foundation (2013‑2026).