منصوبے کے بارے میں

Theia – Privacy-First Server-Side Analytics Overview Theia بغیر کسی کلائل سائیڈ جاوا اسکرپٹ کے ویب سائٹ ٹریفک شماریات فراہم کرتی ہے۔ یہ nginx ایسیس لاگز کو ریئل ٹائم میں دیکھتی ہے، ہر لائن کو parse کر کے path، referrer، user-agent، IP، status code اور bytes sent نکالتی ہے، IPs کو hash کر کے پرائیویسی محفوظ رکھتی ہے، اور نتائج مقامی SQLite ڈیٹا بیس میں ذخیرہ کرتی ہے۔ چونکہ تمام پروسیسنگ سرور پر ہوتی ہے، ڈیٹا ad-blockers سے محفوظ ہوتا ہے اور تیسرے فریق کے خدمات پر انحصار نہیں کرتا۔ Installation تیز انسٹالیشن: install script کو curl یا wget سے ڈاؤن لوڈ کریں اور sudo bash کے ساتھ چلائیں۔ Script architecture کی شناخت کرتی ہے، binary کو /usr/local/bin/theia پر انسٹال کرتی ہے، multi-domain tracking کے لیے custom nginx log format شامل کرتی ہے (اختیاری)، ایک systemd service بناتی ہے اور /var/lib/theia کو data storage کے لیے تیار کرتی ہے۔ Manual install بھی معاون ہے — repository clone کریں، go build سے build کریں، binary کاپی کریں، data directory بنائیں اور دی گئی systemd unit انسٹال کریں۔ Running the daemon Daemon nginx access log کو tails کرتا ہے اور parsed records کو SQLite ڈیٹا بیس میں لکھتا ہے۔ مثال: sudo theia daemon --log-path /var/log/nginx/access.log --db-path /var/lib/theia/theia.db اہم flags: --log-path (default /var/log/nginx/access.log) اور --db-path (default ./theia.db) Command-line statistics stats sub-command ڈیٹa بیس پڑھتا ہے اور summary table یا JSON output print کرتا ہے۔ عام استعمال: theia stats --db-path /var/lib/theia/theia.db Options میں look-back period (--days)، host کے لحاظ سے فلٹرنگ (--host)، output format (--format json|table) اور top entries کی تعداد (--top) شامل ہیں۔ HTTP API service serve command bearer-token سے محفوظ HTTP/JSON (یا CSV) API کو 127.0.0.1:8081 پر چلاتی ہے۔ اسے nginx کے ذریعے proxy کر کے بیرونی طور پر قابل رسائی بنایا جا سکتا ہے۔ Authentication token file، environment variable، یا command-line flag کے ذریعے فراہم کی جا سکتی ہے۔ Endpoints میں شامل ہیں: GET /api/v1/stats – time-series data GET /api/v1/stats/paths – top paths GET /api/v1/stats/referrers – top referrers GET /api/v1/stats/status-codes – status-code breakdown Common query parameters: host, from, to, format, group_by, top。 Shell completion theia completion چلانے سے موجودہ shell کی شناخت ہوتی ہے اور bash، zsh یا fish کے لیے completion scripts انسٹال کرنے کا آپشن ملتا ہے۔ Service management Theia ایک systemd unit کے طور پر چلتی ہے۔ start، stop，restart، status دیکھنے اور logs follow کرنے کے لیے معیاری systemctl commands استعمال کریں۔ How it works internally 1. nginx log file کو ریئل ٹائم میں tail کریں۔ 2. متعلقہ fields کے لیے ہر لائن parse کریں۔ 3. anonymitry برقرار رکھنے کے لیے IP + user-agent + date کو hash کریں۔ 4. bots اور static-asset requests کو خودکار طور پر detect کریں۔ 5. WAL mode میں SQLite کو asynchronous طریقے سے records لکھیں تاکہ concurrent readers کی اجازت ہو۔ 6. 60 دن سے پرانے hourly stats کی periodic cleanup کریں۔ Security considerations daemon کو nginx logs پڑھنے کے لیے root یا sudo access درکار ہے۔ API token کو process list میں ظاہر ہونے سے بچانے کے لیے command line پر نہیں بلکہ file میں store کرنا چاہیے۔ noisy scanners کے لیے rate-limiting اور fail2ban rules ملاحظہ کرنا چاہیے (docs/nginx-hardening.md دیکھیں)。 Limitations * صرف page-view counts collect ہوتے ہیں؛ کوئی کلائل سائیڈ events نہیں۔ * اچانک crashes پر data loss ممکن ہے۔ * کوئی built-in web dashboard نہیں — users CLI output، HTTP API، یا SQLite کو براہ راست query کر سکتے ہیں。 License Apache License 2.0。