سير عمل n8n الأول: Docker وWebhook ووكيل AI

نسخة n8n المستضافة ذاتيًا هي محرر سير عمل على port 5678، volume لقاعدة بيانات، و login تنشئ عند الفتح الأول. هذا المختبر يبدأ تلك الحاوية، يبني Webhook إلى HTTP Request إلى If إلى Slack أو بريد إلكتروني، يثبتها مع curl، ينشرها، ثم يعلّق وكيل AI وأداة واحدة على نفس المحرر.

شغّل n8n مع Docker

صفحة تثبيت n8n Docker لا تزال تطبع docker run، وتقول أيضًا أن تلك الصفحة قديمة لصالح Docker Compose. الأمر أدناه هو الذي تطبعه تلك الصفحة. اعتبارًا من أكتوبر 2026، تلك الصفحة سردت سلوك image مستقر في 2.44.7 و beta في 2.45.4، وقالت minor جديد يشحن معظم الأسابيع. ثبّت tag من إصدارات n8n عندما تهمك أي build. n8nio/n8n بدون tag يتابع مستقر.

أنشئ volume أولاً. بدونه، حاوية جديدة لها قاعدة بيانات فارغة ومفتاح تشفير جديد.

docker volume create n8n_data

توليد مفتاح وأمرره عند البدء الأول. n8n يكتب مفتاح عشوائي في ~/.n8n إذا تخطيت. تحصل على اختيار المفتاح فقط قبل أن يكون الملف موجود.

openssl rand -hex 32

docker run -it --rm \
  --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="America/New_York" \
  -e TZ="America/New_York" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -e N8N_ENCRYPTION_KEY="paste-the-hex-here" \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n

TZ هو ساعة الحاوية. GENERIC_TIMEZONE هو ما تستخدمه العقد style-schedule. N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true هي الضبط الذي تضعه صفحة التثبيت حتى لا يُترك ملف الإعدادات قابل للقراءة من قبل الجميع. --rm يحذف الحاوية عند الخروج. Volume المسمّى يبقى. افتح http://localhost:5678.

لعملية يجب أن تبقى البيانات عند مغادرة الطرفية، أسقط --rm و -it، وأضف -d، الذي هو كيفية docs نفس restart حاوية بعد pull image. أوامر يومية docker run و docker ps و volume موجودة في Docker CLI cheat sheet.

التخزين الافتراضي هو SQLite داخل ذلك volume. Postgres اختياري: عيّن DB_TYPE=postgresdb بالإضافة إلى متغيرات DB_POSTGRESDB_* من صفحة التثبيت. احتفظ بـ volume على أي حال. مع Postgres، المجلد لا يزال يحتفظ بـ encryption key والسجلات وأصول source-control.

حدّث مع pull، ثم أعد إنشاء الحاوية ضد نفس volume:

docker pull n8nio/n8n
docker stop n8n
docker rm n8n

ابدأ مرة أخرى مع نفس -v، نفس N8N_ENCRYPTION_KEY، و -d.

compose.yaml

هذا الملف يستخدم نفس image و port و volume path و متغيرات environment كما Docker install. ليست stack sandbox من دليل n8n Compose الكامل. شكل Compose file و docker compose up موجودة في Docker Compose cheat sheet.

ضع المفتاح في ملف .env بجوار ملف compose، ولا تقم commit ذلك الملف.

services:
  n8n:
    image: n8nio/n8n
    restart: always
    ports:
      - "127.0.0.1:5678:5678"
    environment:
      GENERIC_TIMEZONE: America/New_York
      TZ: America/New_York
      N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"
      N8N_ENCRYPTION_KEY: ${N8N_ENCRYPTION_KEY}
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:

docker compose up -d
docker compose ps

ربط 127.0.0.1 يطابق مثال cloud Compose: المحرر محلي حتى proxy ينشره. حدّث Compose install مع docker compose pull، docker compose down، ثم docker compose up -d. down لا يحذف volume مسمّى ما لم تمرر flag يحذف volumes. لا تمرّ ذلك الـ flag.

حساب المالك، وليس basic auth

n8n 1.0 حذف basic auth و external JWT. لا يوجد مفتاح مدعوم يخفي شاشة login. عند الفتح الأول، نموذج signup ينشئ المالك. كلمة المرور يجب أن تكون على الأقل ثمان أحرف وتشمل أربعة وحرف كبير واحد.

من n8n 2.17.0 يمكنك pre-provision ذلك المالك مع متغيرات environment. المفتاح هو N8N_INSTANCE_OWNER_MANAGED_BY_ENV=true. حقول المالك الأخرى تعيش على صفحة environment إدارة المستخدمين. عيّنها قبل الاعتماد على signup UI.

N8N_ENCRYPTION_KEY يشفّر البيانات قبل أن تضرب قاعدة البيانات. في queue mode كل worker يحتاج نفس المتغير. إذا غيّرت المفتاح بعد أن توجد البيانات، تلك الصفوف شُفرت بالمفتاح القديم. احتفظ بنسخة من المفتاح خارج volume. backup من الأسلاف بدون هذا المفتاح لا يمكنه فك تشفير البيانات. أوامر CLI backup أيضًا تحذف المفتاح. انسخ volume، أو احتفظ بـ env var، كذلك كـ n8n export:workflow.

Reverse proxy

n8n يبني webhook URLs من N8N_PROTOCOL و N8N_HOST و N8N_PORT. خلف proxy العملية لا تزال تستمع على 5678، بينما المتصفحات تستخدم 443. عيّن public origin بنفسك.

N8N_WEBHOOK_URL تستبدل WEBHOOK_URL. الاسم القديم مُستهلك من n8n 2.35.0 ويسجل تحذير. عيّن N8N_PROXY_HOPS=1 عندما يكون هناك proxy واحد. آخر proxy على المسار يجب أن يُرسل X-Forwarded-For و X-Forwarded-Host و X-Forwarded-Proto.

export N8N_WEBHOOK_URL=https://n8n.example.com/
export N8N_PROXY_HOPS=1

Docs أيضًا تقول أن دمج N8N_PATH مع reverse proxy يكسر ملاحة المجلد. فضّل subdomain مثل n8n.example.com.

بناء سير العمل الأول

flowchart LR
  W[Webhook] --> H[HTTP Request]
  H --> I[If]
  I -->|true| S[Slack]
  I -->|false| E[Send Email]

أنشئ سير عمل. أضف عقدة Webhook. اضبط HTTP Method إلى POST. اضبط Respond to When Last Node Finishes حتى curl يطبع إخراج آخر عقدة بدلاً من body “workflow got started” عام. أنماط respond الأخرى هي Immediately و Using ‘Respond to Webhook’ Node و Streaming response.

العقدة تعرض عنوانا URL. اختبار للمحرر. الإنتاج مسجل عند النشر. بادئات مسار الافتراضية هي webhook-test و webhook. يمكنك تغيير تلك مع N8N_ENDPOINT_WEBHOOK_TEST و N8N_ENDPOINT_WEBHOOK. docs Webhook يحدّ الجسم في 16 MB. على خادمك الخاص، N8N_PAYLOAD_SIZE_MAX يرفع ذلك الحد.

أضف عقدة HTTP Request. تستدعي أي REST API، و docs العقدة أيضًا تقول يمكنك لصق أمر curl لملء المعاملات. وجّهها إلى عنوان URL صحة تتحكم به يعيد JSON مع حقل status. Method GET كافية للاختبار الأول.

أضف عقدة If. docs تتهجى العقدة If. اختر String، المقارنة تساوي، ومقارن health JSON status إلى ok. شروط إضافية تتحد مع AND أو OR. أكثر من إخراجين يعني Switch node، وليس stack من If nodes. مقارنات String تشمل contains و starts with و matches regex. الإخراج false هو الفرع تستخدمه عندما يفشل الفحص.

على الإخراج true، أضف عقدة Slack. Resource Message، operation Send. تلك العملية تستدعي chat.postMessage من Slack. تحتاج بيانات Slack. صفحة عقدة Slack تسرد الطريقة لكل عملية وتخبرك بأخذ scopes من صفحة بيانات Slack. لا تخمّن سلاسل scope.

على الإخراج false، أضف عقدة Send Email. تُرسل عبر SMTP. Operation Send. امل From Email و To Email و Subject و Email Format: Text أو HTML أو Both. نفس العقدة يمكن أن تكون أداة AI لاحقًا. لا يمكنها ضبط In-Reply-To أو References. ردود مُخيّط تحتاج عملية reply عقدة Gmail، والتي تسميها صفحة Send Email كحل بديل.

احفظ سير العمل.

اختبر مع curl، ثم انشر

انقر Listen for test event على عقدة Webhook. صفحة common-issues تقول عنوان URL الاختبار يستمع لـ 120 ثانية ويعرض الجسم في المحرر. انسخ عنوان URL الاختبار من العقدة. يبدو مثل هذا، مع المسار الخاص بك:

curl -X POST http://localhost:5678/webhook-test/health-check \
  -H "Content-Type: application/json" \
  -d "{\"service\":\"checkout\"}"

إذا لم يصل شيء، انتظرت طويلاً أو سير العمل لم يكن يستمع. انقر Listen for test event مرة أخرى. عنوان URL الإنتاج لا يعيد شيء مفيد حتى تنشر. النشر هو الضبط الحالي. أوصاف قديمة تقول “activate”. docs Executions تقول تنشر نسخة، وتُلغي النشر لإيقاف حركة الإنتاج.

بعد Publish، استدعِ عنوان URL الإنتاج. المحرر لا يعرض ذلك التشغيل مباشر. افتح تبويب Executions. التشغيل اليدوي من المحرر لا يُحسب نحو حصة خطة مدفوعة. webhook منشور يحسب: عملية تنفيذ واحدة لكل طلب يبدأ بالفعل سير العمل، بما فيها جسم {}. الطلبات التي تشوّهت والتي تفشل قبل بدء سير العمل لا تُحسب. كيف تلك الحصة تقارن مع Make credits و Zapier tasks موجودة في n8n vs Make vs Zapier.

أضف وكيل AI ونموذج دردشة وأداة

عقدة AI Agent هي root node. تربط نموذج دردشة وأداة فرعية واحدة على الأقل. الوكيل يقرر أي أداة يستدعي. docs تتطلب أداة. نموذج وحده ليس setup صحيح.

من n8n 1.82.0 dropdown agent-type القديم مستهلك. كل عقدة AI Agent تتصرف كـ Tools Agent. عقدة v1 لا تزال تعرض dropdown مقررة أن تختفي في n8n 3.0. حدّث العقدة بدلاً من اختيار type موروث. لـ database-style agent، صفحة AI Agent تقول استخدم Postgres أو MySQL tool على عقدة Agent حالية.

صفحة Tools Agent تسرد نماذج دردشة هذه:

• OpenAI Chat Model
• Groq Chat Model
• Mistral Cloud Chat Model
• Anthropic Chat Model
• Microsoft Foundry Chat Model

ربط واحد من تلك إلى إدخال النموذج، وأنشئ بيانات ذلك الموفر. على إدخال الأداة، Calculator كافية لإثبات الحلقة، لأنها لا تحتاج حساب. HTTP Request و Slack أيضًا أدوات على تلك القائمة، لذا نفس حساب Slack يمكن أن يكون أداة بدلاً من فرع ثابت.

عيّن مصدر prompt إلى Define below واكتب رسالة المستخدم، أو اختر Take from previous node automatically، الذي يتوقع حقل إدخال مسمّى chatInput. خيارات تستحق المعرفة: System Message و Max Iterations، الذي يفتقر إلى 10. Enable Streaming على بشكل افتراضي ويجرّ فقط عندما يكون response mode من الزناد الـ Streaming، على سبيل المثال Webhook أو Chat Trigger.

Chat Trigger بالإضافة إلى sub-node ذاكرة يمكنه عقد محادثة عبر turns. صفحة Tools Agent تقول أن الذاكرة لا تستمر بين الجلسات.

ما “tool calling” يعني خارج n8n موجود في what is agentic AI. docs AI Agent من n8n أيضًا يشير إلى توصيل خادم MCP كأداة. كيف تشكّل تلك الخوادم موجودة في MCP servers explained.

تصدير واستيراد

Workflows هي JSON. في المحرر، افتح Workflow menu في رأس canvas:

• Download يحفظ سير العمل الحالي.
• Import from File يقرأ ملف JSON من جهازك.
• Import from URL يقرأ JSON من عنوان يمكنك الوصول إليه.

النسخ واللصق أيضًا يعمل: اختر nodes، Ctrl + c، Ctrl + v.

الملف يحتوي على أسماء البيانات و IDs. IDs ليست السر. الأسماء لا تزال حساسة إذا سمّيت بيانات بعد عميل. عقد HTTP Request المملوءة من curl يمكنها تخزين رؤوس Authorization في JSON العقدة. اشطب تلك قبل أن ترسل الملف لشخص آخر.

على الخادم، أوامر backup تكتب ملف واحد لكل سير عمل:

n8n export:workflow --backup --output=backups/workflows/
n8n export:credentials --backup --output=backups/credentials/

داخل Docker، ذلك مسار backups/ ليس volume. ركّب مجلد host أو انسخ الملفات. استخدم مجلد مختلف للبيانات. صفحة backup تقول import:credentials --separate يفشل إذا جلست ملفات workflow في نفس المجلد. --decrypted يكتب أسرار البيانات في نصوص عادية حتى يمكنك نقلها إلى نسخة بـ مفتاح تشفير مختلف. تعامل تلك الملفات كأسرار.

--published يصدّر النسخة المنشورة بدلاً من المسودة. --version يصدّر نسخة تاريخية واحدة بـ version id. لا يمكنك دمج --version مع --all.

n8n أيضًا له packages (.n8np) عبر n8n-cli package. هي مُعلمة Preview. package يحمل id البيانات والاسم والنوع، أبدًا السر. الاستيراد إما يطابق بيانات لديك بالفعل أو ينشئ placeholder فارغ.

استيراد workflow JSON لا يستورد SMTP password أو Slack token. أنشئ تلك البيانات مرة أخرى، ثم أعد تحديدها على العقد.

الفشل الذي ستصادفه فعلاً

404 على webhook. استدعيت المسار الإنتاج قبل Publish، أو مستمع الاختبار قد انتهى بالفعل في 120 ثانية.

عنوان URL في العقدة localhost:5678 على موقع عام. عيّن N8N_WEBHOOK_URL و N8N_PROXY_HOPS. إذا IP allowlist على عقدة Webhook يرفض عملاء يجب أن يمرروا، صفحة common-issues تخبرك عيّن N8N_PROXY_HOPS إلى عدد proxies.

البيانات لن تفتح بعد إعادة إنشاء. الحاوية الجديدة لا لديها المفتاح القديم. استعد volume أو عيّن نفس N8N_ENCRYPTION_KEY استخدمت عند البدء الأول.

متغيرات environment basic-auth تفعل لا شيء. تم حذفها في 1.0. استخدم حساب المالك.

عقدة AI Agent لن تشتغل. ربط أداة. الإشارة على صفحة AI Agent صريح.

Slack يُرسل في المحرر وأبدًا في الإنتاج، أو العكس. تلك الحدود موثقة لـ Slack Trigger، الذي يمكنه تسجيل عنوان URL webhook واحد فقط لكل تطبيق Slack. عقدة Slack action التي تنشر رسالة ليس لديها ذلك القيد. حالة الزناد تُثبّت بـ unpublishing، pointing Slack إلى عنوان URL الاختبار، ثم النشر مرة أخرى مع عنوان URL الإنتاج.

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

كيف أشغّل n8n في Docker حتى تبقى البيانات بعد إعادة البدء؟

أنشئ volume مسمّى وركّبه في /home/node/.n8n. ذلك المجلد يحتفظ بـ SQLite database ومفتاح تشفير البيانات. عيّن N8N_ENCRYPTION_KEY قبل البدء الأول إذا أردت مفتاح تتحكم به، واحتفظ بـ volume عند استبدال الحاوية.

لماذا webhook n8n الخاص بي يعيد 404؟

عنوان URL الاختبار يستمع فقط لحوالي 120 ثانية بعد أن تضغط Listen for test event. عنوان URL الإنتاج مسجل عند نشر سير العمل. خلف proxy عكسي، عيّن N8N_WEBHOOK_URL إلى https public origin و N8N_PROXY_HOPS إلى 1، أو المحرر يعرض عنوان URL داخلي.

هل N8N_BASIC_AUTH لا يزال يحمي n8n المستضاف ذاتيًا؟

لا. تمّ حذف Basic auth و external JWT login في n8n 1.0. الإصدارات الحالية تظهر دائمًا شاشة login. الحساب الأول الذي تنشئه هو المالك. كلمة المرور تحتاج على الأقل ثمان أحرف وأربعة أرقام وحرف كبير واحد.

هل ملفات JSON لسير عمل n8n المصدّرة تضمّن مفاتيح API؟

تضمّن أسماء البيانات والـ IDs، وليس قيم السر. تعيد إنشاء البيانات على نسخة الوجهة. عقدة HTTP Request المستوردة من أمر curl قد تحتفظ برأس Authorization في JSON العقدة، لذا اقرأ الملف قبل المشاركة.