⚙️ تثبيت Temporal — تنسيق مسارات العمل والتنفيذ المتين للخدمات المصغرة على Docker
نشر منصة Temporal على Ubuntu باستخدام Docker — المنصة مفتوحة المصدر الرائدة عالمياً لتنسيق مسارات العمل (Workflow Orchestration) والتنفيذ البرمجي المتين (Durable Execution) مع واجهة الويب على المنفذ 8242 ومنفذ gRPC 7233.
📦 الملفات والأكواد المطلوبة
قبل البدء، يرجى التأكد من تحميل الأكواد المطلوبة من مستودعنا على GitHub لتتمكن من تطبيق الخطوات مع الفيديو بسهولة.
التثبيت السريع:
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/temporal/temporal-ubuntu.sh
chmod +x temporal-ubuntu.sh
./temporal-ubuntu.sh
خطوات التنفيذ
1 تحميل سكريبت التثبيت من مستودع GitHub إلى سيرفر Ubuntu باستخدام wget أو curl.
wget https://raw.githubusercontent.com/mhmdali94/Docker/main/dev/temporal/temporal-ubuntu.sh
2 منح صلاحيات التنفيذ للسكريبت باستخدام الأمر `chmod +x temporal-ubuntu.sh`.
chmod +x temporal-ubuntu.sh
3 تشغيل المثبت لتهيئة Docker ومجلدات قاعدة البيانات وتطبيق الميجريشنز وإطلاق خدمات Temporal.
./temporal-ubuntu.sh
4 فتح الرابط http://ip-سيرفرك:8242 لاستعراض لوحة Temporal وربط حزم المطورين SDK بمنفذ gRPC 7233.
http://your-server-ip:8242
المنافذ المستخدمة
| المنفذ | الغرض |
|---|---|
| 7233 | Temporal server gRPC frontend — workers and clients connect here |
| 8242 | Temporal Web UI (mapped from container port 8080) |
| 5432 | PostgreSQL — internal to the Docker network, not exposed to the host |
نظرة عامة
تعد Temporal المنصة مفتوحة المصدر الرائدة عالمياً لتنسيق مسارات العمل (Workflow Orchestration) والتنفيذ البرمجي المتين (Durable Execution) لبناء تطبيقات موزعة وخدمات مصغرة (Microservices) فائقة الموثوقية. تعمل المنصة عبر منفذ الواجهة البرمجية gRPC 7233 ولوحة الويب على المنفذ 8242 بالاعتماد على قاعدة بيانات PostgreSQL 15، لتتيح للمطورين كتابة مسارات عمل معقدة بلغات البرمجة القياسية (Go وTypeScript وPython وJava و.NET). ويتم حفظ كل انتقال للحالة، ومؤقتات الانتظار، ومحاولات إعادة الطلب تلقائياً، واستئناف التنفيذ بسلاسة عبر انقطاعات الشبكة وانهيارات السيرفرات وإعادة التشغيل.
لماذا تستخدمه
يتطلب بناء الأنظمة الموزعة الموثوقة باستخدام طوابير الرسائل التقليدية (مثل RabbitMQ وKafka) كتابة آلاف الأسطر البرمجية المكررة لإدارة محاولات إعادة الطلب، ومنع تكرار العمليات، وإلغاء المعاملات الفاشلة (Saga Rollbacks). يقضي Temporal على هذا التعقيد بالكامل: اكتب كوداً تسلسلياً عادياً بالدورات البرمجية وأوامر النوم (Sleep)، ويضمن Temporal تنفيذ الكود حتى اكتماله بنجاح حتى لو تعطل السيرفر في منتصف العملية.
متى تحتاجه
- تبني خدمات مصغرة (Microservices) وتحتاج لتنسيق معاملات مالية أو عمليات متعددة الخطوات وموثوقة بنمط Saga
- تحتاج إلى مسارات عمل تدوم لفترات طويلة (أيام أو شهور) مع الاحتفاظ بكامل المتغيرات وحالة النظام
- تريد إدارة مؤتمتة لإعادة المحاولة (Retries) مع التراجع الأسي لطلبات الـ API وبوابات الدفع الخارجية
- تحتاج إلى سجل زمني بصري كامل يوضح تسلسل تنفيذ كل خطوة في معاملات العملاء لتشخيص المشكلات
- تبحث عن بديل مفتوح المصدر ومستضاف ذاتياً لـ AWS Step Functions أو Temporal Cloud
من يحتاجه
- مهندسو البرمجيات ومطورو الخلفية لبناء خدمات مصغرة شديدة الموثوقية ومعاملات برمجية متينة
- الفرق الهندسية لشركات التكنولوجيا المالية والتجارة الإلكترونية لإدارة عمليات الفوترة والمدفوعات والمستردات
- فرق الـ DevOps وهندسة الموثوقية (SRE) لأتمتة تجهيز البنية التحتية السحابية وخطوط الـ CI/CD المعقدة
- مؤسسو مشاريع الـ SaaS لتنظيم مسارات تسجيل المستخدمين الجدد وحملات البريد المجدولة
- أصحاب السيرفرات المنزلية وهواة هندسة النظم لدراسة وتطبيق معمارية البرمجة المتينة
حالات الاستخدام الشائعة
- تنسيق عملية الشراء في المتاجر: خصم البطاقة الائتمانية، وحجز المخزون، وإرسال بريد التأكيد، وتجهيز الشحن
- إدارة عمليات التعويض والتراجع (Saga): إعادة أموال العميل تلقائياً عند فشل حجز المنتج بالمستودع
- إدارة دورات الاشتراكات الشهرية المتكررة مع فترات السماح والمحاولات الآلية لخصم الرسوم
- أتمتة النسخ الاحتياطي للسيرفرات: أخذ لقطة لقاعدة البيانات، ورفعها للسحابة، والتحقق من الـ Checksum، وإرسال إشعار
- تنسيق خطوط معالجة وتدريب الذكاء الاصطناعي على مصفوفات كروت الشاشة ومراقبة اكتمال المهام
الميزات الرئيسية
- تنسيق المسارات بالكود الصرف: كتابة مسارات العمل بلغات Go وTypeScript وPython وJava وC# وPHP
- ضمانات التنفيذ المتين: مسارات عمل تنجو من إعادة تشغيل الحاويات وانهيار السيرفرات وتستأنف عملها آلياً
- لوحة ويب تفاعلية على المنفذ 8242: فحص مسارات العمل قيد التشغيل، والمدخلات، وشجرة تاريخ الأحداث
- واجهة gRPC فائقة السرعة على المنفذ 7233: اتصالات منخفضة التأخير بين عمال المعالجة وسيرفر Temporal
- أتمتة المحاولات والمؤقتات: سياسات إعادة محاولة معلنة ومراقبة نبضات النشاط ومؤقتات تدوم لسنوات
- أرشفة الأحداث الحتمية: سجل تدقيق غير قابل للتعديل يوثق كل استدعاء وتعديل طرأ على المعاملة
- عزل مساحات العمل (Namespaces): فصل مسارات بيئات التطوير والتجربة والإنتاج على سيرفر واحد
- معمارية Docker Compose تجمع Temporal Auto-Setup مع قاعدة PostgreSQL 15 ولوحة الويب
كيفية الاستخدام بعد التثبيت
- افتح المتصفح وانتقل إلى الرابط http://ip-سيرفرك:8242 لعرض لوحة تحكم Temporal
- تأكد من وجود وتفعيل مساحة العمل الافتراضية `default` من قائمة Namespaces
- في كود تطبيقك، اضبط عميل حزمة Temporal SDK ليتصل بالرابط `your-server-ip:7233`
- شغل برنامج عامل المعالجة (Worker) الخاص بتطبيقك وابدأ أول مسار عمل تجريبي
- شاهد تقدم مسار العمل وتفاصيل المهام التاريخية مباشرة من لوحة الويب
- ضع لوحة الويب (منفذ 8242) خلف وكيل عكسي مشفر بـ HTTPS (مثل Nginx) مع حمايتها بكلمة مرور
- أعد سكريبت نسخ احتياطي دوري لمجلد قاعدة البيانات `./temporal-db-data`
أفضل ممارسات الأمان
- تنبيه أمني حاسم: لا تحتوي لوحة الويب وواجهة gRPC على مصادقة مدمجة؛ احرص على عزلهما بالشبكة الداخلية أو حمايتهما بـ mTLS وNginx Basic Auth
- استخدم تشفير HTTPS دائماً للوصول للوحة الويب عن بُعد عبر وكيل عكسي
- أبقِ منفذ قاعدة البيانات الداخلي PostgreSQL 5432 مغلقاً في جدار الحماية الخارجي
- فعل تشفير mTLS المتبادل لمنفذ gRPC 7233 عند اتصال عمال المعالجة عبر شبكات خارجية
- احمِ مجلد قاعدة البيانات بصلاحيات نظام مناسبة بالسيرفر
- حدّث صورة الحاوية دورياً للحصول على التحديثات الأمنية وإصلاحات محرك التنفيذ
المنافذ وإعدادات جدار الحماية
يقدم Temporal واجهة gRPC البرمجية عبر منفذ TCP 7233 ولوحة الويب عبر منفذ TCP 8242 (المحول من 8080 الداخلي). اسمح بالمنفذ 7233 للشبكة الداخلية الموثوقة (`ufw allow from 192.168.1.0/24 to any port 7233 proto tcp`). وفي الإنتاج، وجه حركة لوحة الويب عبر وكيل عكسي مشفر بـ SSL على المنفذ 443 وأبقِ منفذ قاعدة البيانات 5432 مغلقاً خارجياً.
النسخ الاحتياطي والصيانة
- انسخ مجلد `./temporal-db-data` احتياطياً، والذي يحتوي على كامل قاعدة بيانات PostgreSQL وسجلات مسارات العمل
- استخرج نسخة احتياطية يومية لقاعدة البيانات عبر pg_dump: `docker exec temporal-postgresql pg_dump -U temporal temporal > temporal_backup.sql`
- احتفظ بنسخة من ملف `docker-compose.yml` الذي يحتوي على المتغيرات والإعدادات
- أتمت النسخ الاحتياطي اليومي للمجلدات وارفعه إلى مساحة تخزين سحابية عبر restic أو rsync
- اختبر الاستعادة بربط مجلد البيانات بحاوية تجريبية للتأكد من استرجاع مسارات العمل التاريخية بنجاح
الأخطاء الشائعة
- كتابة كود غير حتمي داخل دوال الـ Workflows (مثل استخدام الأرقام العشوائية أو استدعاء APIs مباشرة بدلاً من استخدام Activities)
- كشف منفذ gRPC 7233 أو لوحة الويب للإنترنت العام مباشرة بدون مصادقة
- عدم ربط مجلد التخزين الدائم لقاعدة البيانات، مما يسبب فقدان مسارات العمل قيد التشغيل عند تحديث الحاوية
- محاولة تشغيل Temporal على سيرفر بذاكرة RAM أقل من 2 جيجابايت مما يسبب انهيار الحاويات
- نسيان تشغيل برنامج العامل (Worker) مما يترك مسارات العمل معلقة بحالة 'Running' للأبد
استكشاف الأخطاء وإصلاحها
- مسارات العمل معلقة بحالة 'Running' — تأكد من تشغيل برنامج العامل (Worker) واتصاله بالمنفذ 7233 والاستماع للطابور الصحيح
- خطأ غير حتمي (Non-deterministic error) — تأكد من عزل كافة استعلامات قواعد البيانات والـ APIs داخل دوال Activities
- ظهور خطأ 502 Bad Gateway في الواجهة — افحص سجلات الحاوية بالأمر: `docker logs temporal-ui -f`
- فشل الاتصال بقاعدة البيانات — تأكد من عمل حاوية `temporal-postgresql` واكتمال الميجريشنز بأمر `docker compose ps`
- رفض اتصال برنامج العامل — تأكد من فتح منفذ gRPC 7233 في جدار الحماية
البدائل
خدمة AWS Step Functions السحابية. محرك Netflix Conductor المبني بـ Java. مشروع Cadence المفتوح من Uber. محرك Camunda لمسارات الـ BPMN. أدوات خطوط البيانات Airflow وPrefect.
متى لا تستخدمه
تجنب استخدام Temporal إذا كنت تبحث فقط عن طابور مهام خلفية بسيط لخطوة واحدة (مثل استخدام Redis مع Celery أو BullMQ لإرسال بريد إلكتروني واحد). وإذا كانت شركتك تتطلب رسومات ومخططات XML بصرية بنظام BPMN للمحللين غير التقنيين، فإن Camunda مخصصة لذلك.
هل تحتاج مساعدة احترافية؟
توفر PrismaTechWork خدمات بنية تحتية شاملة — من النشر الأولي وتصليب الأمان إلى المراقبة المستمرة والنسخ الاحتياطي التلقائي والدعم المخصص. سواء كنت تحتاج إعداد سيرفر واحد أو شبكة متعددة المواقع، يضمن فريقنا بناء بنيتك التحتية بشكل صحيح وتأمينها بالشكل المناسب وصيانتها باستمرار.
- التثبيت وتجهيز السيرفر
- الإعداد المتقدم وإعداد التوجيه
- تصليب الأمان وتحسين جدار الحماية
- إعداد شهادات SSL/TLS مع Let's Encrypt
- ربط النطاق المخصص والوكيل العكسي
- جدولة النسخ الاحتياطي التلقائي والتعافي من الكوارث
- المراقبة الفورية وتنبيهات الجاهزية
- الترحيل من المنصات القائمة
- استكشاف مشكلات الاتصال والأداء وإصلاحها
- سكريبتات أتمتة مخصصة وعقود دعم مستمر
الأسئلة الشائعة
ما هي منصة Temporal وما المقصود بالتنفيذ المتين (Durable Execution)؟
تعد Temporal منصة لتنسيق مسارات العمل البرمجية. ويعني التنفيذ المتين أن كود تطبيقك مضمون التنفيذ حتى نهايته بغض النظر عن تعطل العتاد أو انهيار السيرفرات أو انقطاع الشبكة دون فقدان أي متغيرات أو حالات.
ما الفرق بين مسارات العمل (Workflows) والأنشطة (Activities)؟
تحدد الـ Workflows منطق التنسيق العام ويجب أن تكون حتمية تماماً (بدون استدعاء مباشر للشبكة أو أرقام عشوائية)، بينما تنفذ الـ Activities المهام الفعلية (مثل استدعاء APIs، وتعديل قواعد البيانات، وإرسال الرسائل) وتدعم إعادة المحاولة التلقائية.
ما هي لغات البرمجة المدعومة في Temporal؟
توفر Temporal حزم تطوير برمجية (SDKs) رسمية لكل من Go وTypeScript/JavaScript وPython وJava و.NET (C#) وPHP.
كم من الوقت يمكن أن يستمر مسار عمل Temporal في العمل؟
يمكن لمسارات عمل Temporal أن تستمر في العمل لفترات غير محدودة — من بضع ميلي ثوانٍ إلى ساعات أو شهور أو حتى سنوات، باستخدام أوامر الانتظار المتينة (`workflow.sleep()`).
كم يستهلك Temporal من الذاكرة العشوائية (RAM)؟
تستهلك حزمة Temporal بالكامل (الخادم ولوحة الويب وقاعدة PostgreSQL 15) ما بين 400 إلى 800 ميجابايت من الذاكرة العشوائية داخل Docker.