🐛 تثبيت Sentry — منصة تتبع الأخطاء البرمجية ومراقبة أداء التطبيقات APM على Docker

نشر منصة Sentry Self-Hosted على Ubuntu باستخدام Docker — المنصة مفتوحة المصدر الرائدة عالمياً لتتبع الأخطاء البرمجية وانهيار التطبيقات ومراقبة الأداء (APM) بدعم ClickHouse وKafka لأكثر من 100 لغة برمجية.

⚠️ راجع أي سكريبت دائمًا قبل تشغيله على سيرفرك، واختبره في بيئة تجريبية أولاً.

📦 الملفات والأكواد المطلوبة

قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.

سكريبت تثبيت مؤتمت — أمر واحد ينشر حزمة Sentry الرسمية على المنفذ 9002 مع ClickHouse وKafka وPostgreSQL (يتطلب 16 جيجابايت RAM).
عرض على GitHub

التثبيت السريع:

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/sentry/sentry-ubuntu.sh
chmod +x sentry-ubuntu.sh
sudo bash sentry-ubuntu.sh

خطوات التنفيذ

1 تحميل السكريبت

wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/sentry/sentry-ubuntu.sh

2 منح صلاحية التنفيذ

chmod +x sentry-ubuntu.sh

3 تشغيل المثبت

يقوم السكريبت بفحص توفر 16 جيجابايت RAM على الأقل، واستنساخ مستودع Sentry الرسمي، وضبط المنفذ 9002 (المحول من 9000 الداخلي)، وتنفيذ ترحيلات ClickHouse وPostgreSQL، وإطلاق كافة الحاويات.

sudo bash sentry-ubuntu.sh

4 إنشاء حساب المشرف وربط مفتاح DSN

افتح متصفحك وانتقل إلى الرابط http://ip-سيرفرك:9002. سجل دخولك ببيانات المشرف، وأنشئ مشروعاً، وانسخ رابط الـ DSN الخاص بك، واربط مكتبة Sentry SDK في تطبيقك البرمجي.

docker compose run --rm web createuser  # then open http://:9002

المنافذ المستخدمة

المنفذالغرض
9002Web UI (host) — no default login; create the first admin with createuser
40+ containersOfficial self-hosted stack: web, workers, Kafka, ClickHouse, PostgreSQL, Redis
16 GB RAMMinimum — the installer warns below ~15 GB

نظرة عامة

تعد Sentry Self-Hosted المعيار الذهبي عالمياً في تتبع الأخطاء البرمجية والتعامل مع الاستثناءات اللحظية ومراقبة أداء التطبيقات (APM). تعمل المنصة عبر المنفذ 9002 (المحول من 9000 الداخلي)، وتعالج ملايين الأحداث عبر منظومة مؤسسية ضخمة تشمل قاعدة ClickHouse للتحليلات اللحظية، ومنصة Apache Kafka لطوابير الأحداث فائقة الكثافة، وخدمة Snuba، وقاعدة PostgreSQL، وكاش Redis. وتوفر تفاصيل دقيقة للأخطاء البرمجية (Stack Traces)، ومسارات الكود، وسجلات تتبع المستخدم (Breadcrumbs)، وإعادة تشغيل جلسات المستخدم (Session Replay)، وتتبع المعاملات الموزعة لأكثر من 100 منصة برمجية.

لماذا تستخدمه

تفرض منصات تتبع الأخطاء السحابية التجارية (مثل Sentry.io وDatadog) اشتراكات شهرية باهظة جداً تحسب بعدد الأخطاء، مما يجبر الفرق البرمجية على تقييد وتجاهل الأخطاء أو رفع سجلات المستخدمين الحساسة لسيرفرات سحابية خارجية. تمنحك الاستضافة الذاتية لـ Sentry السيادة الكاملة بنسبة 100% على بياناتك، واستقبالاً غير محدود للأخطاء بدون أي رسوم، ومراقبة شاملة لكافة مشاريعك على سيرفرك الخاص.

متى تحتاجه

  • تبحث عن بديل مفتوح المصدر ومستقل لـ Sentry.io أو Datadog مع استقبال غير محدود للأخطاء وبدون رسوم اشتراك للمستخدمين
  • تحتاج إلى تقارير انهيار فورية توضح أسطر الكود البرمجي، وخرائط المصدر (Source Maps)، وسجلات خطوات المستخدم السابقة
  • تشترط لوائح الخصوصية الصارمة (GDPR وHIPAA) حظر إرسال سجلات الأخطاء وبيانات المستخدمين للسيرفرات السحابية الخارجية
  • تريد مراقبة أداء التطبيقات (APM) والتتبع الموزع لاكتشاف استعلامات قواعد البيانات البطيئة ونقاط الاختناق في الـ API
  • تمتلك سيرفر Ubuntu قوياً بمواصفات لا تقل عن 16 جيجابايت RAM ومستعداً لاستضافة منظومة مراقبة مؤسسية متكاملة

من يحتاجه

  • فرق التطوير والـ DevOps لمراقبة واكتشاف أخطاء تطبيقات الويب والهواتف والخدمات المصغرة في الإنتاج
  • المؤسسات المالية والطبية والحكومية التي تتطلب تتبع الأخطاء محلياً مع الامتثال التام لقوانين توطين البيانات
  • مطورو تطبيقات الهواتف لمراقبة انهيارات تطبيقات iOS وAndroid وتقارير تجمد الواجهة (ANR)
  • مطورو الواجهات الأمامية لحل وتتبع أخطاء جافاسكريبت المجمعة باستخدام خرائط المصدر (Source Maps)
  • مديرو الهندسة البرمجية لقياس استقرار الإصدارات ومعدلات الجلسات الخالية من الانهيارات (Crash-Free Sessions)

حالات الاستخدام الشائعة

  • التقاط أخطاء تطبيقات React وNode.js في بيئة الإنتاج مع تفاصيل أسطر الكود الدقيقة وتاريخ نقرات المستخدم
  • اكتشاف استعلامات SQL البطيئة في PostgreSQL والاتصالات الخارجية المتأخرة عبر ميزة Sentry Distributed Tracing
  • استقبال إشعارات وتنبيهات فورية على Slack أو تيليجرام فور تسبب إصدار برمجي جديد في ارتفاع نسبة الأخطاء
  • رفع ملفات Source Maps تلقائياً أثناء مسارات الـ CI/CD لفك ضغط أخطاء جافاسكريبت في بيئة الإنتاج
  • استعراض ميزة Session Replay لمشاهدة فيديو يعيد تمثيل حركات ونقرات المستخدم التي سبقت انهيار التطبيق

الميزات الرئيسية

  • تتبع الأخطاء اللحظي: التقاط الاستثناءات مع أسماء الملفات، وأرقام الأسطر، والمتغيرات المحلية، وسياق التنفيذ
  • مراقبة أداء التطبيقات (APM): تتبع المعاملات الموزعة، ومقاييس زمن الاستجابة (p50/p95/p99)، وتفاصيل فترات المعالجة
  • محرك تحليلي عملاق بـ ClickHouse وKafka: معالجة وفهرسة ملايين الأحداث والاستعلامات في الدقيقة الواحدة
  • فك خرائط المصدر (Source Maps): دعم ملفات جافاسكريبت، وتطبيقات أندرويد (ProGuard)، ورموز dSYM لـ iOS
  • إعادة تشغيل الجلسات (Session Replay): استعراض مرئي لتفاعل المستخدم وطلبات الشبكة قبل حدوث الانهيار
  • قياس صحة الإصدارات: تتبع نسب تبني التحديثات، والجلسات والمستخدمين الخالين من الأخطاء لكل إصدار
  • تنبيهات متعددة القنوات: تكامل مباشر مع Slack وDiscord وTelegram وPagerDuty وJira والبريد الإلكتروني
  • حزمة Docker Compose متكاملة مع أدوات نسخ احتياطي واستعادة آلية مدمجة (`sentry-admin backup`)

كيفية الاستخدام بعد التثبيت

  • افتح المتصفح وانتقل إلى الرابط http://ip-سيرفرك:9002 لعرض واجهة تسجيل دخول Sentry
  • سجل الدخول بالبريد الإلكتروني وكلمة المرور للمشرف التي أنشأتها أثناء تشغيل `./install.sh` (أو عبر أمر `createuser`)
  • اضغط على 'Create Project' واختر المنصة البرمجية لتطبيقك (مثل React أو Python أو Go أو Node.js)
  • انسخ مفتاح DSN المخصص لمشروعك (`https://publicKey@your-domain.com/1`)
  • ثبت مكتبة Sentry SDK في تطبيقك البرمجي (`npm install @sentry/react` أو `pip install sentry-sdk`) والصق مفتاح الـ DSN
  • أطلق خطأ تجريبياً في تطبيقك وتأكد من ظهوره فورياً في لوحة تحكم Issues في Sentry
  • ضع Sentry خلف وكيل عكسي مشفر بـ HTTPS (مثل Nginx) مع شهادة SSL صالحة

أفضل ممارسات الأمان

  • تنبيه أمني حاسم: استخدم تشفير HTTPS دائماً في الإنتاج — فحزم الأخطاء واستدعاءات DSN قد تحتوي على بيانات جلسات حساسة
  • أبقِ كافة منافذ قواعد البيانات وطوابير الرسائل (ClickHouse 9000/8123 وKafka 9092 وPostgreSQL 5432 وRedis 6379) معزولة تماماً
  • اضبط قواعد تنظيف البيانات (Data Scrubbing) من إعدادات المشروع لمسح كلمات المرور وأرقام البطاقات آلياً
  • افرض تفعيل المصادقة الثنائية (2FA) لكافة حسابات المطورين والمشرفين من إعدادات الأمان
  • احمِ مجلدات البيانات الرئيسية على السيرفر بصلاحيات نظام مناسبة
  • حدّث الحزمة دورياً بسحب أحدث إصدار من مستودع getsentry/self-hosted الرسمي

المنافذ وإعدادات جدار الحماية

يقدم Sentry واجهة الويب والواجهة البرمجية ونقطة استقبال DSN عبر منفذ TCP 9002 (المحول من 9000 الداخلي). في الإنتاج، قم بتهيئة وكيل عكسي مشفر بـ SSL على المنفذ 443 ووجهه لمنفذ 9002، مع إبقاء المنفذ 9002 ومنافذ المنظومة الداخلية (ClickHouse وKafka وPostgres وRedis) مغلقة تماماً في جدار الحماية الخارجي.

النسخ الاحتياطي والصيانة

  • استخدم أداة النسخ الاحتياطي الرسمية المدمجة: `docker compose run --rm web backup export /etc/sentry/backup.json`
  • انسخ مجلد قاعدة بيانات PostgreSQL الذي يحتوي على حسابات المستخدمين والمنظمات والمشاريع
  • انسخ ملفي الإعدادات `sentry/config.yml` و`sentry/sentry.conf.py` اللذين يحتويان على المفاتيح السرية
  • أتمت النسخ الاحتياطي اليومي للمجلدات وارفعه إلى مساحة تخزين سحابية عبر restic أو rsync
  • اختبر الاستعادة بتشغيل أمر: `docker compose run --rm web backup import /etc/sentry/backup.json` في بيئة تجريبية

الأخطاء الشائعة

  • محاولة تثبيت Sentry على سيرفر برامات أقل من 16 جيجابايت RAM (حيث يفشل المثبت أو تنهار الحاويات بسبب نفاد الذاكرة)
  • التشغيل في بيئة الإنتاج عبر بروتوكول HTTP غير المشفر مما يعطل استقبال أحداث الـ SDK ويسرب البيانات
  • نسيان إنشاء حساب المشرف الأول عبر أمر `docker compose run --rm web createuser` بعد اكتمال التثبيت
  • عدم ربط مجلدات التخزين الدائم، مما يسبب فقدان سجلات ClickHouse وحسابات PostgreSQL عند إعادة البناء
  • ترك المفتاح السري الافتراضي `system.secret-key` في ملف `config.yml` دون تغيير على سيرفرات الإنتاج

استكشاف الأخطاء وإصلاحها

  • المثبت يفشل ويظهر 'Not enough RAM' — قم بترقية الذاكرة أو أنشئ ملف ذاكرة مبادلة مؤقت بحجم 8 جيجابايت (`swapon`) لتجاوز الفحص
  • ظهور خطأ 502 Bad Gateway في Nginx — تأكد من عمل كافة الحاويات الـ 40 (`docker compose ps`) وانتظر دقيقتين لاكتمال إقلاع خادم الويب
  • الأخطاء لا تظهر في لوحة التحكم — تأكد من صحة رابط الـ DSN وراجع سجلات حاوية Relay بالأمر `docker compose logs relay`
  • انهيار حاوية Kafka أو ClickHouse — تأكد من سرعة القرص وتوافق حدود الذاكرة في النواة عبر `sysctl vm.max_map_count`
  • نسيان كلمة مرور المشرف — أعد تعيينها أو أنشئ مستخدماً جديداً بالأمر: `docker compose run --rm web createuser`

البدائل

منصة GlitchTip البديلة الخفيفة المتوافقة مع Sentry (تعمل بـ 1 جيجابايت RAM). منصة Signoz مفتوحة المصدر لمراقبة المؤشرات والسجلات. منصة Highlight.io لمراقبة الأخطاء وإعادة تشغيل الجلسات. منصة Datadog السحابية التجارية. منصة Rollbar لمراقبة الأخطاء.

متى لا تستخدمه

تجنب استخدام Sentry Self-Hosted إذا كان سيرفرك يمتلك مواصفات متواضعة أقل من 16 جيجابايت RAM و4 أنوية معالج (حيث تتكون حزمة Sentry من أكثر من 40 حاوية مع ClickHouse وKafka وتستهلك موارد ضخمة؛ استخدم GlitchTip كبديل خفيف متوافق يعمل بـ 1 جيجابايت RAM). وإذا كنت تبحث فقط عن أداة بسيطة لفحص عمل المواقع وجاهزيتها، فإن Uptime Kuma أبسط بكثير.

هل تحتاج مساعدة احترافية؟

توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.

  • التثبيت وتجهيز السيرفر
  • الإعداد المتقدم وإعداد التوجيه
  • تصليب الأمان وتحسين جدار الحماية
  • إعداد شهادات SSL/TLS مع Let's Encrypt
  • ربط النطاق المخصص والوكيل العكسي
  • جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
  • المراقبة الفورية وتنبيهات الجاهزية
  • الترحيل من المنصات القائمة
  • استكشاف مشكلات الاتصال والأداء وإصلاحها
  • سكريبتات أتمتة مخصصة وعقود دعم مستمر
تواصل مع PrismaTechWork

الأسئلة الشائعة

ما هي متطلبات العتاد الدنيا لتشغيل Sentry Self-Hosted؟

يتطلب Sentry Self-Hosted سيرفر مخصصاً بمواصفات لا تقل عن 16 جيجابايت RAM، و4 أنوية معالج، ومساحة تخزين سريعة NVMe/SSD لا تقل عن 40 جيجابايت. ويتوقف مثبت البرنامج تلقائياً إذا وجد ذاكرة أقل من 15 جيجابايت.

كيف أقوم بإنشاء حساب المشرف الأول في Sentry؟

إذا تخطيت المطالبة أثناء التثبيت، يمكنك إنشاء مستخدم مشرف جديد في أي وقت بتنفيذ أمر: `docker compose run --rm web createuser` داخل مجلد المستودع بالسيرفر.

هل يمكن استخدام مكتبات Sentry SDK الحالية مع Sentry المستضاف ذاتياً؟

نعم! يستخدم Sentry المستضاف ذاتياً نفس مكتبات SDK الرسمية تماماً (JavaScript وPython وGo وجافا وFlutter وiOS وAndroid)، وكل ما عليك هو وضع رابط الـ DSN الخاص بسيرفرك في `Sentry.init`.

لماذا يعتمد Sentry على ClickHouse وApache Kafka؟

يعتمد Sentry على Apache Kafka لاستقبال وطابرة آلاف أحداث الأخطاء المتزامنة في الثانية دون فقدانها، وعلى ClickHouse لتخزين وفهرسة ملايين السجلات التحليلية واسترجاعها في أجزاء من الثانية.

هل يوجد بديل خفيف لمنصة Sentry للسيرفرات الصغيرة؟

نعم! إذا لم تكن تمتلك 16 جيجابايت RAM، يمكنك تثبيت منصة GlitchTip مفتوحة المصدر، وهي متوافقة بنسبة 100% مع مكتبات Sentry SDK وتعمل بسلاسة تامة على 1 إلى 2 جيجابايت RAM فقط.