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

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

الطريقة المُوصى بها لاستضافته ذاتيًا هي عن طريق Docker Composeتُتيح هذه الطريقة نشر الواجهة وواجهة برمجة التطبيقات (API)، والعمال المسؤولين عن تنفيذ العمليات، وقاعدة بيانات PostgreSQL، وقاعدة بيانات Redis بشكل منفصل. كما يتوفر تثبيت مُبسط في حاوية واحدة، ولكنه يقتصر على المشاريع الشخصية والاختبار.

يُحسّن استضافة المنصة ذاتيًا التحكم في البنية التحتية، لكن هذا لا يعني بقاء جميع البيانات تلقائيًا على الخادم. فعندما يستخدم سير العمل Gmail أو Slack أو OpenAI أو أي واجهة برمجة تطبيقات خارجية أخرى، ستظل المعلومات الضرورية تُرسل إلى ذلك المزوّد. لذا، ينبغي عليك أيضًا ربط الوكلاء والأتمتة دون الكشف عن بيانات الاعتماد.

أي نظام من أنظمة Activepieces يجب أن تختار؟

توفر Activepieces مسارين رئيسيين باستخدام Docker. يعتمد الاختيار على الاستخدام المقصود، وعدد عمليات التنفيذ، وإمكانية توسيع البنية التحتية لاحقًا.

منشأة	عناصر	الاستخدام الموصى به
حاوية واحدة	التطبيق، وPGLite، وقائمة انتظار الذاكرة	الاختبارات والمشاريع الشخصية
Docker Compose	التطبيق، العامل، PostgreSQL و Redis	خادم ومعدات مستقرة
هندسة الإنتاج	التطبيقات، والعمال، وPostgreSQL، وRedis، وتخزين S3	عمليات نشر عالية التزامن وقابلة للتوسع

يستخدم الحاوية الواحدة PGlite كقاعدة بيانات متكاملة ويحتفظ بقائمة انتظار المهام في الذاكرة. وهو يدعم نسخة واحدة فقط لكل جهاز، ولا يمكن تحويله مباشرةً إلى تثبيت مؤسسي. إذا احتجت لاحقًا إلى الترقية إلى البنية الكاملة، فسيتعين عليك إعداد عملية نشر جديدة.

يُعد Docker Compose أكثر ملاءمة عندما تريد الحفاظ على التدفقات في PostgreSQL، واستخدام Redis لقوائم الانتظار، وفصل تنفيذ عمليات التشغيل الآلي باستخدام العمال.

متطلبات تثبيت Activepieces باستخدام Docker

يتطلب التثبيت الرسمي باستخدام Docker Compose الموارد التالية:

• Docker و Docker Compose الإصدار 2.
• ما لا يقل عن 2 وحدة معالجة مركزية افتراضية و 4 جيجابايت من ذاكرة الوصول العشوائي.
• Un نظام لينكس أو خادم متوافق مع Docker.
• WSL2 إذا كنت ستشغل برنامج التثبيت من نظام ويندوز.
• الوصول إلى طرفية مع صلاحيات لإدارة Docker.
• نطاق إذا كنت بحاجة إلى استقبال إشعارات الويب من الإنترنت.
• بروتوكول HTTPS للتثبيت العام أو الإنتاجي.

تأكد من توفر Docker Compose v2:

docker compose version

يحتوي الأمر الصحيح على مسافة بين docker y composeالأداة القديمة docker-compose يتوافق هذا مع الإصدار الأول من Compose ولا يعمل مع النشر الحالي.

إذا كنت تستخدم نظام ويندوز، فقم بتشغيل توزيعة لينكس باستخدام WSL2، ثم نفّذ أوامر التثبيت هناك. يجب تهيئة Docker Desktop للتكامل مع تلك التوزيعة.

تركيب سريع للمشاريع الشخصية

إذا كنت ترغب فقط في اختبار Activepieces على جهاز واحد ولا تحتاج إلى التوسع، فيمكنك بدء الإصدار المبسط بحاوية واحدة:

docker run -d --name activepieces -p 8080:80 \
  -v ~/.activepieces:/root/.activepieces \
  -e AP_DB_TYPE=PGLITE \
  -e AP_REDIS_TYPE=MEMORY \
  -e AP_FRONTEND_URL="http://localhost:8080" \
  activepieces/activepieces:latest

هذا الأمر:

• انشر أعمالاً تفاعلية عبر الميناء 8080.
• احفظ الإعدادات وقاعدة البيانات en ~/.activepieces.
• يستخدم PGlite كقاعدة بيانات متكاملة.
• يدير قائمة انتظار التنفيذ داخل ذاكرة العملية.

بمجرد بدء تشغيل الحاوية، افتح:

http://localhost:8080

سيصبح أول مستخدم تقوم بتسجيله هو المسؤول. لا يوجد اسم مستخدم أو كلمة مرور افتراضية..

هذا الأسلوب غير مناسب للإنتاج، أو عمليات النسخ المتعددة، أو عمليات التثبيت التي قد تتطلب ميزات على مستوى المؤسسات. إذا كان هناك إمكانية لتوسيع نطاق المشروع، فابدأ مباشرةً باستخدام Docker Compose.

كيفية تثبيت Activepieces بأمر واحد

توصي الوثائق الرسمية باستخدام سكربت يقوم بإنشاء الإعدادات، وتوليد البيانات السرية، وتشغيل الحاويات. أولاً، انتقل إلى المجلد الذي ترغب في حفظ ملفات النشر فيه، ثم قم بتشغيل السكربت التالي:

curl -fsSL https://get.activepieces.com | sh

إذا كنت تفضل مراجعة المحتوى قبل تشغيله، يمكنك عرضه في الطرفية:

curl -fsSL https://get.activepieces.com

يقوم برنامج التثبيت بإنشاء مجلد يسمى activepiecesقم بإعداد الملف .env ويقوم بنشر الخدمات اللازمة.

إذا كان المنفذ 8080 قيد الاستخدام بالفعل، فحدد منفذًا آخر:

curl -fsSL https://get.activepieces.com | sh -s -- --port 8090

يمكنك أيضاً اختيار مجلد آخر:

curl -fsSL https://get.activepieces.com | sh -s -- --dir /ruta/activepieces

عند الانتهاء، افتح http://localhost:8080 أو يحل محل localhost عن طريق عنوان IP الخاص بالخادم.

كيفية تثبيت Activepieces يدويًا باستخدام Docker Compose

يُتيح لك التثبيت اليدوي مراجعة ملف Compose والمتغيرات قبل تشغيل أي حاويات. ابدأ باستنساخ المستودع:

git clone --depth 1 https://github.com/activepieces/activepieces.git
cd activepieces

ثم قم بتشغيل البرنامج النصي الذي يقوم بإعداد الملف .env ويقوم بإنشاء كلمات المرور:

sh tools/deploy.sh

هذه العملية تحتاج opensslإذا لم يكن البرنامج مثبتًا، فقد يتوقف البرنامج النصي دون إظهار خطأ واضح، وقد يؤدي ذلك إلى فقدان بعض البيانات السرية. تحقق منها قبل المتابعة.

grep -E '^(AP_ENCRYPTION_KEY|AP_JWT_SECRET|AP_POSTGRES_PASSWORD)=' .env

يجب أن تحتوي جميع المتغيرات الثلاثة على قيمة:

• AP_ENCRYPTION_KEY قم بتشفير الاتصالات المحفوظة.
• AP_JWT_SECRET يوقع على رموز المصادقة.
• AP_POSTGRES_PASSWORD يحمي الوصول إلى PostgreSQL.

يستخدم التثبيت إصدار Community افتراضيًا. إذا كان لديك ترخيص تجاري وترغب في تفعيله لاحقًا، فيجب عليك تجهيز الإصدار المناسب قبل بدء التثبيت واستخدام وضع تشغيل متوافق.

في عملية التثبيت اليدوي، الخدمة worker يجب أن يكون قادراً على التواصل مع التطبيق باستخدام الاسم الداخلي للحاوية. تأكد من أن قسمه يحتوي على ما يلي:

worker:
  environment:
    - AP_CONTAINER_TYPE=WORKER
    - AP_FRONTEND_URL=http://app

هذا العنوان خاص بالعامل فقط. المتغير AP_FRONTEND_URL عام الملف .env يجب عليك الاحتفاظ بعنوان URL العام الذي ستستخدمه المتصفحات والخدمات الخارجية.

وأخيراً، ابدأ تشغيل الحاويات:

docker compose -p activepieces up -d

ما هي الحاويات التي يقوم Activepieces بتثبيتها؟

يؤدي النشر باستخدام Docker Compose إلى إنشاء أربعة أنواع من الخدمات:

حاوية	وظيفة
app	يوفر واجهة المستخدم، وواجهة برمجة التطبيقات، وإدارة المنصة.
worker	يقوم النظام بجمع المهام من قائمة الانتظار وتنفيذ سير العمل.
postgres	يقوم بتخزين التدفقات والاتصالات والمستخدمين وعمليات التنفيذ.
redis	إدارة قائمة المهام وعمليات التنفيذ المعلقة.

لا يتم حفظ بيانات PostgreSQL مباشرة في المجلد المستنسخ، بل تبقى داخل وحدة تخزين Docker. postgres_data. لذلك، لا يؤدي نسخ مجلد Activepieces فقط إلى إنشاء نسخة احتياطية كاملة.

كيفية التحقق من أن Activepieces يعمل

تحقق من حالة الحاويات:

docker compose -p activepieces ps

يجب أن تظهر جميع الخدمات وكأنها تعمل. ثم تحقق من نقطة نهاية الحالة الصحية:

curl http://localhost:8080/api/v1/health

قم بتسجيل الدخول وافتح إدارة المنصة > البنية التحتية > العماليجب أن يكون هناك عامل واحد على الأقل متاحًا. إذا كانت القائمة فارغة، فمن المحتمل أن العامل غير قادر على التواصل مع التطبيق.

يمكنك أيضًا الاطلاع على السجلات في الوقت الفعلي:

docker compose -p activepieces logs -f app
docker compose -p activepieces logs -f worker

كيفية تكوين النطاق وخطافات الويب

تستخدم Activepieces AP_FRONTEND_URL لإنشاء عناوين webhook، وعمليات إعادة توجيه OAuth، وروابط عامة. إذا كان يحتوي على localhostلن تتمكن خدمات مثل Stripe أو GitHub أو Slack من إرسال البيانات من الإنترنت.

قم بتحرير الملف .env ويُدخل الملكية العامة:

AP_FRONTEND_URL=https://automatizaciones.tudominio.com

ثم أعد إنشاء الخدمات لتنفيذ التغيير:

docker compose -p activepieces up -d

لإجراء الاختبارات من جهاز كمبيوتر بدون عنوان عام، يمكنك استخدام نفق مؤقت:

ngrok http 8080

أدخل عنوان HTTPS الذي يوفره النفق في AP_FRONTEND_URL ويعيد تشغيل الحاويات. يُعدّ Ngrok مفيدًا للاختبار، ولكن قد يتغير عنوانه. لا ينبغي اعتبارها تكوين إنتاج دائم.

يمكن أيضًا استخدام Cloudflare Tunnel لنشر المثيل دون فتح المنفذ 8080 مباشرةً. ومع ذلك، ستحتاج إلى تكوين النطاق وHTTPS ودعم WebSockets بشكل صحيح.

كيفية حماية Activepieces باستخدام HTTPS

يجب أن تستخدم النسخة العامة بروتوكول HTTPS. يمكنك إنهاء التشفير باستخدام خادم وكيل عكسي مثل Nginx، أو موازن تحميل، أو خدمة الوكيل التي يوفرها مزود خدمة الإنترنت الخاص بك.

يجب أن يقوم تكوين Nginx الأساسي بإعادة توجيه الطلبات إلى المنفذ 8080 والسماح باتصالات WebSocket:

location / {
    proxy_pass http://localhost:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_cache_bypass $http_upgrade;
}

يمكنك الحصول على الشهادة من خلال Let's Encrypt أو Certbot أو Cloudflare أو مزود البنية التحتية الخاص بك. بمجرد تفعيل HTTPS، تحقق من ذلك. AP_FRONTEND_URL يبدأ بـ https://.

لا تنشر قواعد بيانات PostgreSQL أو Redis مباشرةً على الإنترنت. كذلك، قلّل من الوصول عبر SSH، وحافظ على تحديث Docker، واستخدم كلمات مرور مختلفة للخادم والتطبيقات المتصلة به.

كيفية عمل نسخة احتياطية

قبل تحديث Activepieces، قم بتصدير قاعدة البيانات:

docker compose -p activepieces exec postgres \
  pg_dump -U postgres activepieces > backup.sql

احتفظ أيضاً بنسخة آمنة من الملف .envبدون نفس الشيء AP_ENCRYPTION_KEYلن تتمكن Activepieces من فك تشفير الاتصالات المخزنة، حتى إذا نجحت في استعادة PostgreSQL.

في حالة التثبيت الشخصي باستخدام PGLite، يجب عليك نسخ المجلد التالي احتياطيًا:

~/.activepieces

لا تقم بتخزين النسخ الاحتياطية على نفس الخادم فقط. استخدم جهاز كمبيوتر مختلفًا، أو وحدة تخزين مشفرة، أو نظام نسخ احتياطي مُعَدّ مسبقًا.

كيفية تحديث Activepieces

أولاً، تحقق من وجود تغييرات غير متوافقة منشورة للإصدار الجديد. بعد إنشاء النسخة الاحتياطية، قم بتشغيل:

curl -fsSL https://get.activepieces.com | sh -s -- --upgrade

يحتفظ برنامج التثبيت بالملف .envالبيانات والتعديلات التي أُجريت في docker-compose.ymlتم تثبيت الإصدار المستخدم بواسطة AP_VERSIONيمنع هذا التحديثات العرضية في كل مرة يتم فيها إعادة تشغيل الحاويات.

في الحاوية الشخصية، يجب عليك إيقافها، والتراجع عنها ~/.activepieces، احذف الحاوية القديمة، وقم بتنزيل الصورة الجديدة وأعد إنشائها باستخدام نفس وحدة التخزين.

الأخطاء الشائعة عند تثبيت Activepieces

أمر docker compose غير موجود

تحقق من الإصدار:

docker compose version

إذا فشل الأمر، فقم بتثبيت Docker Compose v2. لا تقم باستبدال الأمر تلقائيًا بـ docker-compose، لأن النشر الحالي لا يدعم Compose v1.

الميناء 8080 مشغول بالفعل

التثبيت على منفذ مختلف:

curl -fsSL https://get.activepieces.com | sh -s -- --port 8090

في التركيبات القائمة، يتغير الأمر AP_HOST_PORT داخل .env ويعيد إنشاء الحاويات. لا تقم بتغيير AP_PORTلأنه يتوافق مع المنفذ الداخلي ويمكن أن يعطل عملية الربط.

صفحة العمال تبدو فارغة

تحقق من السجلات:

docker compose -p activepieces logs worker | grep -i socket

تشير أخطاء Socket.IO المتكررة عادةً إلى أن العامل يحاول الاتصال بـ localhost أو إلى المجال العام من داخل Docker. قم بتكوين ما يلي لتلك الخدمة:

AP_FRONTEND_URL=http://app

يعرض Webhooks المضيف المحلي

أدخل المجال العام في المتغير AP_FRONTEND_URL من الملف .env ثم أعد تشغيل الخدمات. يجب أن يكون العنوان قابلاً للوصول إليه من التطبيق الخارجي الذي سيرسل إشعار الويب.

أزرار الاختبار أو التحديثات في الوقت الفعلي لا تعمل

ربما لا يقوم الخادم الوكيل العكسي بإعادة توجيه اتصالات WebSocket بشكل صحيح. تحقق من ترويسات الطلب. Upgrade y Connection وقم بتمكين HTTPS، حيث أن بعض المتصفحات تحظر WebSockets غير المشفرة.

المفاتيح في ملف .env فارغة.

ثَبَّتَ openssl ثم أعد تشغيله:

sh tools/deploy.sh

لا تبدأ عملية التثبيت حتى تتأكد من ذلك. AP_ENCRYPTION_KEY, AP_JWT_SECRET y AP_POSTGRES_PASSWORD إنها تحتوي على قيم.

يستمر التطبيق في إعادة التشغيل

تحقق من خطأ بدء التشغيل:

docker compose -p activepieces logs app | grep -i "failed to start"

أحد الأسباب المحتملة هو استخدام AP_EDITION=ee جنبا إلى جنب مع AP_EXECUTION_MODE=UNSANDBOXEDيرفض إصدار المؤسسات هذا المزيج؛ فهو يستخدم وضع الحماية المتوافق كـ SANDBOX_CODE_ONLY.

تختفي التدفقات بعد إعادة إنشاء الحاويات.

تأكد من مستوى الصوت postgres_data لا يزال موجودًا ولم تقم بحذفه نهائيًا. لا ينبغي أن يؤدي حذف الحاويات إلى حذف وحدة التخزين، ولكن الأوامر التي تحذف وحدات التخزين قد تدمر قاعدة البيانات بشكل دائم.

عندما يتوقف نظام التشغيل الآلي عن العمل، فإنه يتحقق أولاً من سجلات التطبيق وسجلات العامل. وتُعد هذه المنهجية نفسها مفيدة لتحديد ماذا تفعل عندما تفشل عملية أتمتة؟ وفصل المشكلة عن مسار فشل البنية التحتية.

متى تحتاج إلى بنية إنتاجية؟

يُعد Docker Compose كافيًا للبدء باستخدام خادمك الخاص، ولكن ستحتاج المؤسسة التي لديها العديد من عمليات التشغيل المتزامنة إلى فصل المكونات وتوسيع نطاقها.

تستخدم بنية الإنتاج الموصى بها عمال مستقلون، نسخ متعددة من التطبيق، PostgreSQL، Redis، وتخزين متوافق مع S3ينبغي حساب السعة بناءً على الحد الأقصى لعدد التدفقات المتزامنة، وليس فقط على عدد عمليات التنفيذ اليومية.

ينبغي عليك أيضاً ضبط إعدادات المراقبة، والاحتفاظ بالسجلات، والنسخ الاحتياطية الموثقة، وعزل التنفيذ. يوفر الاستضافة الذاتية تحكماً كاملاً، لكنها في الوقت نفسه تنقل مسؤولية التوافر والتحديثات والأمان إلى المسؤول.

يُتيح لك تثبيت ActivePieces باستخدام Docker Compose امتلاك منصة أتمتة يتم التحكم بها من بنيتك التحتية الخاصة. لا يكمن الجزء الأهم في إعداد الحاويات، بل في اختيار الحاوية المناسبة من بين PGLite و PostgreSQL، وحماية البيانات السرية، وتكوين عنوان URL عام مستقر، والحفاظ على نسخ احتياطية من قاعدة البيانات ومفتاح التشفير.

مع اتخاذ هذه الاحتياطات، يمكنك تشغيل التدفقات، واستقبال روابط الويب، وربط التطبيقات دون الاعتماد على البنية التحتية المستضافة لـ Activepieces، مع القدرة على توسيع نطاق النظام مع زيادة حجم العمل.