فريق المنتج Product Team في أي تطبيق يصل عاجلاً أو آجلاً إلى قائمة طويلة من الإشعارات Notifications: الطلب خرج للتوصيل، وتعليق جديد على منتجك، ودخول إلى حسابك من جهاز جديد، وفشل الدفع. والمطلوب في كل واحد منها مختلف، فخروج الطلب يظهر في جرس التطبيق ويصل بالبريد Email وعلى الهاتف كإشعار Push، والتعليقات لا يصح أن تصل واحداً واحداً فتزعج المستخدم وإنما تجمع في رسالة واحدة كل فترة، والمستخدم نفسه يريد أن يطفئ البريد للتعليقات ويبقيه للطلبات، أما تنبيه الأمان فلا يحق له أن يطفئه أصلاً. وأول ما يفكر فيه المطور هو أن يرسل البريد من الكود مباشرة بعد حفظ الطلب، ثم يضيف جدولاً للإشعارات داخل التطبيق، ثم طابوراً Queue لأن مزود البريد يتأخر أحياناً، ثم جدولاً للتفضيلات Preferences، ثم منطقاً للتجميع، وبعد أشهر يجد نفسه قد بنى نظام إشعارات كاملاً لم يكن في الخطة.
وقد شرحنا في مقال كيف تبني نظام إشعارات يصل إلى ملايين المستخدمين هذا النظام من الداخل: الطوابير المنفصلة بحسب الأولوية، وإعادة المحاولة، والمزود الاحتياطي، والتفضيلات وساعات الهدوء. وهذا المقال عن الطريق الآخر: أن تأخذ هذه البنية جاهزة من مشروع مفتوح المصدر Open Source اسمه Novu، وتشغله على سيرفرك بدل أن تكتبه من الصفر، وبدل أن ترسل أسماء عملائك وبريدهم وتفاصيل طلباتهم إلى خدمة SaaS في الخارج. وكل ما في المقال من مخرجات جاء من تشغيل حقيقي للنسخة المجتمعية على Docker، بمتجر تجريبي ومشترك تجريبي واحد.
وسوف نناقش في هذا المقال ما يلي:
- ما هو Novu، والفرق بين الخدمة السحابية Novu Cloud والنسخة المجتمعية Community Edition التي تستضيفها بنفسك، وما الذي ينقص الثانية.
- كيف يعمل من الداخل: الخدمات الأربع وقاعدة البيانات MongoDB وطوابير Redis، ثم المصطلحات التي تحتاجها: Workflow وStep وSubscriber وTopic وIntegration.
- التثبيت بملف Docker Compose الرسمي، والتعديلات التي يحتاجها، ومشكلة التشغيل الأول، والتسجيل المفتوح للجميع.
- ربط البريد عبر SMTP وربط Push عبر Webhook، ولماذا رفض Novu الإرسال إلى سيرفراتك الداخلية في البداية.
- بناء ثلاثة Workflows عبر واجهة API، وإرسال إشعار في ثلاث قنوات، وتجميع خمسة تعليقات في رسالة واحدة، وتفضيلات المستخدم والإشعار الحرج.
- مكون صندوق الإشعارات Inbox داخل صفحتك، وحمايته، وما يحدث إذا توقف العامل Worker.
- الموارد التي يحتاجها، وملاحظات الإنتاج Production، والأخطاء الشائعة، ومتى تختاره بدل ntfy أو بدل أن تبني النظام بنفسك.
ما هو Novu؟ بنية إشعارات Notification Infrastructure جاهزة
يصف Novu نفسه بأنه بنية تحتية للإشعارات Notification Infrastructure، والمعنى العملي أنه خدمة مستقلة يرسل إليها تطبيقك حدثاً Event واحداً مثل «الطلب 1042 خرج للتوصيل لهذا المستخدم»، وهي تقرر الباقي: في أي قنوات Channels يذهب، وبأي نص، وعبر أي مزود Provider، وهل يجمع مع غيره، وهل سمح المستخدم بهذه القناة أصلاً. والقنوات التي يدعمها خمس: داخل التطبيق In-App، والبريد Email، والرسائل القصيرة SMS، وإشعارات الهاتف Push، والمحادثة Chat مثل Slack وTelegram. وتطبيقك لا يعرف شيئاً عن هذه التفاصيل، فلو قرر فريق المنتج غداً أن يضيف SMS لإشعار الطلب، أو أن يغير نص البريد، فإن ذلك يتم من لوحة التحكم Dashboard دون أن يتغير سطر في كود التطبيق ودون نشر Deployment جديد.
وهذه الفكرة هي نفسها خدمة الإشعارات المستقلة التي رسمناها في مقال نظام الإشعارات، والفرق أن Novu يعطيك فوقها أشياء يصعب أن يكتبها فريق صغير في وقت قصير: محرراً للقوالب Templates، وخطوة تجميع Digest جاهزة، ومكون واجهة Inbox تضعه في صفحتك بسطرين، وتفضيلات لكل مستخدم مع واجهة يغيرها منها، وسجل نشاط Activity Feed يريك ما حدث لكل إشعار في كل قناة.
Novu Cloud أم النسخة المجتمعية Community Edition؟
يعمل Novu بطريقتين: خدمة سحابية مدفوعة تديرها الشركة، ونسخة مجتمعية Community Self-Hosted تشغلها على سيرفرك بنفس Docker Images. والكود في مستودع GitHub بترخيص MIT، إلا مجلد enterprise/packages الذي يخضع لترخيص تجاري خاص بحسب ملف LICENSE-ENTERPRISE، لذلك عندما تقرأ «مفتوح المصدر» فالمقصود هو النواة التي نشغلها هنا. وقد يتساءل البعض: هل النسخة المجتمعية هي نفسها السحابية؟ والإجابة لا، فصفحة الفرق بين النسختين تذكر أشياء تنقص المجتمعية، وأهمها لفريق صغير ما يلي:
| الميزة Feature | النسخة المجتمعية | Novu Cloud |
|---|---|---|
| القنوات الخمس وال Digest وال Workflows من الواجهة أو الكود | متوفرة | متوفرة |
| مكون Inbox وواجهة التفضيلات | متوفرة | متوفرة |
| عدد أعضاء الفريق Team Members | عضو واحد | بحسب الخطة |
| التحقق بخطوتين MFA والصلاحيات RBAC والدخول الموحد SSO | غير متوفرة | متوفرة |
| البيئات المخصصة Custom Environments | Development وProduction فقط | متوفرة |
| تتبع استلام البريد وفتحه Email Activity Tracking | غير متوفر | متوفر |
| التأجيل Snooze في ال Inbox وإزالة شعار Novu | غير متوفرة | متوفرة |
والسطر الثالث هو الذي يفاجئ الفرق عادة: لوحة التحكم في النسخة المجتمعية لحساب واحد، فإذا كان عندكم مطوران ومدير منتج يريدون الدخول فسوف يتشاركون الحساب نفسه، أو يعمل المطورون بالكود عبر واجهة API ويبقى الحساب مع شخص واحد. ولاحظ أيضاً أن التسجيل بحسابات Google وGitHub غير موجود في النسخة المستضافة، والدخول بالبريد وكلمة المرور فقط كما في صفحة الاستضافة الذاتية.
كيف يعمل Novu من الداخل؟ المعمارية Architecture
النسخة المجتمعية ستة Containers: أربع خدمات من كود Novu نفسه، وقاعدة بيانات MongoDB، وRedis. والصورة التالية تبين من يكلم من:

- api: الواجهة البرمجية REST على المنفذ Port رقم 3000، وهي التي يكلمها تطبيقك ولوحة التحكم ومكون Inbox. عندما يصلها حدث تتحقق من المشترك وال Workflow، ثم تضعه في الطابور وترد فوراً، ولا تنتظر أي إرسال.
- worker: العامل الذي يسحب الأحداث من الطابور، وينشئ لكل خطوة مهمة Job، ثم ينفذها: يبني النص من القالب، ويطبق التفضيلات، ويكلم مزود البريد أو Push. وهو الخدمة الوحيدة التي تتصل بالخارج.
- ws: سيرفر WebSocket على المنفذ 3002، يحفظ اتصالاً مفتوحاً مع كل Inbox مفتوح في متصفح أحد مستخدميك، فيظهر الإشعار الجديد دون تحديث الصفحة. وإذا أردت أن تفهم لماذا WebSocket وليس الاستطلاع Polling فقد شرحنا ذلك في التواصل اللحظي: Polling وSSE وWebSockets.
- dashboard: لوحة التحكم على المنفذ 4000، وهي تطبيق ويب يعمل في متصفح فريقك ويكلم api مباشرة، ولهذا تحتاج أن يصل المتصفح نفسه إلى api وws، وهذه نقطة سوف نعود إليها عند الإنتاج.
- mongodb: كل البيانات الدائمة: ال Workflows، والمشتركون، والرسائل، والتفضيلات، والمفاتيح، وسجل التنفيذ. وإذا كنت جديداً عليها فلدينا مقال عن MongoDB ومتى تناسبك.
- redis: الطوابير التي تنتقل فيها المهام بين api وworker، وهي مبنية على مكتبة BullMQ كما في ملف
package.jsonلخدمة worker، ومعها ذاكرة مؤقتة Cache. وكيف تضيع المهام في طوابير Redis ومتى لا تضيع شرحناه في طوابير المهام فوق Redis وValkey.
وهذا الفصل بين api وworker هو ما يجعل الرد على تطبيقك سريعاً مهما تأخر مزود البريد، وهو أيضاً ما يجعل رد api لا يكفي لتعرف أن الإرسال تم، كما سوف نرى في التجربة.
المصطلحات: Workflow وStep وSubscriber وTopic وIntegration
قبل أن نثبت شيئاً، هذه الكلمات التي سوف تراها في كل شاشة وفي كل طلب API، وأغلبها يبقى بالإنجليزية لأنك سوف تكتبه في الكود كما هو:
- ال Workflow: وصف إشعار واحد من أوله لآخره، مثل «خروج الطلب للتوصيل»، وله معرف Identifier ثابت مثل
order-shippedيستخدمه تطبيقك عند الإرسال، ومعه درجة أهمية Severity ووسوم Tags وإعدادات التفضيلات الافتراضية. - الخطوة Step: كل Workflow سلسلة خطوات، بعضها قنوات (in_app وemail وpush وsms وchat) وبعضها إجراءات Actions مثل التجميع digest والتأخير delay والتحكم في التكرار throttle. وكل خطوة لها محتوى Control Values مثل العنوان والنص، وتكتب فيه متغيرات بصيغة
{{payload.orderId}}. - المشترك Subscriber: المستخدم الذي يستقبل الإشعار، وله معرف
subscriberIdتختاره أنت، والأفضل أن يكون معرف المستخدم في قاعدة بيانات تطبيقك، ومعه الاسم والبريد واللغة Locale وبيانات القنوات مثل توكنات الأجهزة Device Tokens. - الموضوع Topic: مجموعة مشتركين باسم واحد، مثل كل من يتابع منتجاً معيناً، فترسل إلى الموضوع مرة واحدة ويوزع Novu الحدث على أعضائه، كما في توثيق Topics.
- التكامل Integration: ربط قناة بمزود معين ومفاتيحه، مثل البريد عبر Amazon SES أو عبر سيرفر SMTP خاص بك، وPush عبر FCM. ويمكن أن يكون للقناة أكثر من تكامل وواحد منها أساسي Primary.
- الحمولة Payload: البيانات التي يرسلها تطبيقك مع كل حدث، مثل رقم الطلب واسم السائق، وتستخدمها القوالب.
بيئتا Development وProduction
كل حساب في Novu يبدأ ببيئتين Environments: التطوير Development والإنتاج Production، ولكل بيئة مفتاح سري Secret Key ومعرف تطبيق Application Identifier ومشتركون وتكاملات خاصة بها. والتعديل على ال Workflows يتم في Development، ثم تنقله إلى Production بزر «Publish changes»، والإنتاج للعرض فقط في لوحة التحكم كما في توثيق البيئات. وهذه الطريقة مفيدة لأن تغيير نص إشعار يصل إلى عشرات آلاف المستخدمين لا يصح أن يتم مباشرة على الإنتاج، ولكنها تعني أيضاً أن الإعداد يتكرر مرتين: تكامل البريد الذي أضفته في Development لا يعمل في Production حتى تضيفه هناك أيضاً، والمشترك الذي أنشأته في بيئة لا يوجد في الأخرى. والنسخة المجتمعية تتوقف عند هاتين البيئتين، فلا توجد بيئة Staging ثالثة.
من الحدث Trigger إلى مهمة Job لكل خطوة
عندما يرسل تطبيقك طلب POST /v1/events/trigger يحدث التالي بحسب صفحة شرح Trigger: تتحقق api من المشتركين ومن أن ال Workflow مفعل، ثم تضع الحدث في طابور الأحداث وترد. بعدها يسحب worker الحدث، فينشئ المشترك أو يحدثه من بيانات الطلب، وينشئ سجل إشعار Notification لكل مشترك، ثم ينشئ مهمة لكل خطوة في ال Workflow. وكل مهمة تمر بحالات: PENDING ثم QUEUED ثم RUNNING ثم COMPLETED أو FAILED، وهناك حالتان خاصتان سوف نراهما: CANCELED عندما تمنع التفضيلات الخطوة، وMERGED عندما يدمج حدث في تجميع حدث سابق. والصورة التالية تبين ما سوف نراه في التجربة لإشعار الطلب:

التثبيت بملف Docker Compose المجتمعي
الطريقة الرسمية هي ملف docker-compose.yml وملف .env.example في مجلد docker/community من المستودع، وقد أخذناهما من الوسم v3.20.0، وفيهما Docker Images الخدمات الأربع بالإصدار Version 3.19.0، وmongo:8.0.17، وredis بالوسم alpine دون رقم. ويقترح دليل التثبيت بـ Docker أيضاً سكربت setup.sh ينزل الملفين ويولد الأسرار ويشغل كل شيء بأمر واحد، ولكننا نفضل أن تقرأ الملفين وتعدلهما بيدك، لأن فيهما أشياء لا تريدها كما هي على سيرفر حقيقي.
الأسرار Secrets والمنافذ: التعديلات التي تحتاجها
ملف .env.example يترك ثلاثة أسرار فارغة، ويطلب منك أن تولدها قبل التشغيل، وهذه هي الأوامر التي استخدمناها، والأطوال من تعليقات الملف نفسه:
cp .env.example .env
# JWT_SECRET: signs the dashboard and Inbox sessions
sed -i "s|^JWT_SECRET=.*|JWT_SECRET=$(openssl rand -hex 32)|" .env
# STORE_ENCRYPTION_KEY: encrypts provider credentials in MongoDB, must be exactly 32 characters
sed -i "s|^STORE_ENCRYPTION_KEY=.*|STORE_ENCRYPTION_KEY=$(openssl rand -hex 16)|" .env
sed -i "s|^NOVU_SECRET_KEY=.*|NOVU_SECRET_KEY=$(openssl rand -hex 32)|" .env
# the example ships MONGO_INITDB_ROOT_PASSWORD=secret
sed -i "s|^MONGO_INITDB_ROOT_PASSWORD=.*|MONGO_INITDB_ROOT_PASSWORD=$(openssl rand -hex 24)|" .envفي الأوامر أعلاه لاحظ التالي:
STORE_ENCRYPTION_KEYهو المفتاح الذي تشفر به مفاتيح المزودين داخل قاعدة البيانات، أي كلمة مرور SMTP ومفتاح FCM وغيرها، لذلك يجب أن يكون 32 حرفاً بالضبط، وopenssl rand -hex 16يعطي 16 بايت تكتب ب 32 حرفاً. وإذا ضاع هذا المفتاح فلن تقرأ Novu مفاتيح المزودين التي حفظتها، فاحفظه مع النسخة الاحتياطية Backup.- كلمة مرور MongoDB في الملف الأصلي هي
secret، ولا يوجد سبب لتبقى كذلك حتى لو لم يكن المنفذ مفتوحاً للخارج. REDIS_PASSWORDفارغ في الملف الأصلي، وRedis في هذا الملف لا يفتح منفذاً على السيرفر، فيصل إليه فقط ما في شبكة Docker نفسها. فإذا نقلته يوماً إلى سيرفر منفصل فضع له كلمة مرور.
أما في docker-compose.yml فالتعديل الأهم هو المنافذ، فالملف الأصلي ينشر 3000 و3002 و4000 على كل واجهات السيرفر، أي على الإنترنت إذا لم يكن أمامه جدار ناري Firewall. ونحن ربطناها بالعنوان المحلي، وال Reverse Proxy هو من يفتحها للخارج بشهادة TLS كما سوف نرى:
api:
image: "ghcr.io/novuhq/novu/api:3.19.0"
container_name: sc6-novu-api
ports:
- 127.0.0.1:${API_PORT}:${API_PORT}
ws:
image: "ghcr.io/novuhq/novu/ws:3.19.0"
container_name: sc6-novu-ws
ports:
- 127.0.0.1:${WS_PORT}:${WS_PORT}
dashboard:
image: "ghcr.io/novuhq/novu/dashboard:3.19.0"
container_name: sc6-novu-dashboard
ports:
- 127.0.0.1:4000:4000وثبتنا Redis على وسم محدد redis:8.10.3-alpine بدل redis:alpine، والسبب أن الوسم دون رقم يتغير تحتك عند أي docker compose pull، فتتغير نسخة قاعدة الطوابير دون أن تقرر ذلك. والبادئة sc6-novu- في الأسماء اختيارية، وفائدتها أن تعرف Containers هذا المشروع بين غيرها على السيرفر نفسه.
التشغيل الأول: dependency failed وسجلات ClickHouse
الآن نشغل كل شيء:
docker compose up -dوفي المرة الأولى توقف الأمر برسالة تبدو كأن التثبيت فشل:
dependency failed to start: container sc6-novu-worker is unhealthyوالسبب أن dashboard تنتظر أن يصبح api وworker بحالة healthy، وworker في التشغيل الأول يأخذ وقتاً أطول من مهلة فحص الصحة Health Check وهو ينشئ الفهارس Indexes في MongoDB ويتصل بكل شيء، فيعلن Docker أنه غير سليم ويتوقف عن تشغيل ما يعتمد عليه. وعندما فتحنا سجلات worker بالأمر docker logs sc6-novu-worker وجدنا فيها أخطاء متكررة عن جدول ClickHouse لم يستطع إنشاءه، وسببها connect ECONNREFUSED 127.0.0.1:8123، وهذه أخطاء لا تهمك: ClickHouse قاعدة بيانات تستخدمها الخدمة السحابية للتحليلات، وهي غير موجودة في الملف المجتمعي أصلاً، والعامل يسجل الخطأ ثم يكمل عمله. وبعد نحو دقيقة ظهر في السجل Redis ready وأصبح worker سليماً بعد أن أعاد Docker تشغيله مرة واحدة، فأعدنا الأمر نفسه:
docker compose up -dفاشتغلت dashboard، وكان الزمن من أول أمر حتى أصبحت الخدمات كلها تعمل 3 دقائق و48 ثانية، وهذا يشمل الفشل الأول. لذلك إذا رأيت هذه الرسالة في التشغيل الأول فلا تحذف شيئاً ولا تعيد التثبيت، وإنما انتظر حتى يصبح worker سليماً في docker compose ps ثم أعد الأمر. وإذا كتبت سكربتاً للتثبيت الآلي فاجعله ينتظر حالة healthy ويعيد المحاولة بدل أن يعتبر أول فشل نهائياً.
S3_LOCAL_STACK=${HOST_NAME}:4566 ولكنه لا يشغل LocalStack، وبحسب دليل التثبيت فكل حدث يحمل مرفقات Attachments سوف يفشل لأن api تحاول رفعها إلى مخزن غير موجود، أما الأحداث دون مرفقات فتعمل. فإذا كان بريدك يحتاج مرفقات مثل الفاتورة فاربطه بمخزن S3 حقيقي أو متوافق مثل MinIO قبل الإنتاج.التسجيل مفتوح للجميع: DISABLE_USER_REGISTRATION
بعد التشغيل تفتح http://localhost:4000 فتجد صفحة تسجيل حساب Sign-up، وأنشأنا الحساب الأول عبر POST /v1/auth/register ومعه مؤسسة Organization باسم «Example Store»، فظهرت البيئتان ولكل واحدة مفتاحها. والمشكلة هنا أن هذه الصفحة تبقى مفتوحة بعد حسابك الأول، والتوثيق يقولها صراحة: «Anyone who can reach the dashboard can create an account by default». أي أن أي شخص يصل إلى لوحة التحكم يستطيع أن ينشئ حساباً ومؤسسة خاصة به على سيرفرك، ويستخدم مزوديك إذا أضافهم لنفسه، ويرسل من سيرفرك. والحل متغير واحد في خدمة api بعد أن تنشئ حسابك:
# .env, then pass it to the api service in docker-compose.yml
DISABLE_USER_REGISTRATION=trueولاحظ أن الملف المجتمعي لا يمرر هذا المتغير إلى api، فإضافته في .env وحدها لا تكفي، ويجب أن تضيف السطر DISABLE_USER_REGISTRATION: ${DISABLE_USER_REGISTRATION} تحت environment في خدمة api. وبعد إعادة التشغيل ترد api على أي طلب تسجيل ب 400 Bad Request ورسالة Account creation is disabled، ويبقى دخول الحسابات الموجودة كما هو.
ربط المزودين Providers: البريد وPush وداخل التطبيق
Novu لا يرسل البريد بنفسه ولا يوصل Push إلى الهاتف بنفسه، وإنما يكلم مزوداً لكل قناة. وفي التجربة أضفنا تكاملين عبر API في بيئة Development، وكان تكامل In-App موجوداً من البداية باسم Novu Inbox، والصورة التالية من صفحة Integration Store بعد الإضافة:

البريد عبر Custom SMTP
للبريد اخترنا المزود nodemailer الذي يظهر في اللوحة باسم Custom SMTP، لأنه يعمل مع أي سيرفر SMTP: سيرفر بريد مؤسستك، أو Postfix على سيرفر الإرسال، أو خدمة مثل Amazon SES عبر SMTP. وفي التجربة وجهناه إلى Mailpit، وهو سيرفر SMTP للاختبار يحفظ كل رسالة ويعرضها في واجهة ويب دون أن يرسلها لأحد، باسم Container هو sc6-mailpit على المنفذ 1025 في شبكة Docker نفسها. والرد على إنشاء التكامل أكد الحقول المهمة: providerId هو nodemailer، والقناة email، والاسم «SMTP (Mailpit)» بالمعرف smtp-mailpit، وهو مفعل active وأساسي primary. وإعدادات الأمان مثل TLS وطريقة المصادقة في صفحة Custom SMTP، وما يجعل البريد التفاعلي يصل إلى صندوق الوارد وليس إلى البريد المزعج Spam شرحناه في مقال البريد التفاعلي Transactional Email، فNovu لا يغير شيئاً من ذلك: سمعة نطاقك وسجلات SPF وDKIM مسؤوليتك.
Push عبر Webhook، ولماذا لا يوجد Push حقيقي دون FCM وAPNs
هنا نقطة يجب أن تكون واضحة قبل أن تختار Novu لسبب «لا نريد أن نعتمد على Google»: Novu يدير قناة Push من جهتك فقط، أي توكنات الأجهزة والقوالب والتفضيلات، أما التوصيل إلى الهاتف فيتم عبر مزود خارجي من قائمة مزودي Push: FCM من Google، وAPNs من Apple، وExpo، وOneSignal وغيرها. وهذا ليس نقصاً في Novu، وإنما هو حال كل إشعار يصل إلى iPhone أو إلى Android فيه خدمات Google، كما فصلنا في إشعارات Push بدون Firebase. لذلك لا تتوقع من الاستضافة الذاتية لNovu أن تخرج إشعارات تطبيق الجوال من Google وApple، فهي تخرج منهما فقط بيانات المستخدمين والقوالب وسجل الإرسال.
ولأن مفاتيح FCM وAPNs تحتاج مشروعاً وحساب مطور، استخدمنا في التجربة المزود Push Webhook، وهو مزود لا يعتمد على أي خدمة خارجية: يرسل Novu طلب POST فيه الإشعار إلى رابط تملكه أنت، ومعه توقيع HMAC في الترويسة Header x-novu-signature إذا وضعت مفتاحاً سرياً في إعداد التكامل. وهذا المزود مفيد في الواقع أيضاً، فإذا كان عندك سيرفر Push خاص مثل ntfy أو بوابة داخلية توزع الإشعارات على أجهزة الموظفين، فإن Novu يسلمها الإشعار وهي تكمل الطريق. ووجهناه إلى Container صغير اسمه sc6-hook يطبع كل ما يصله على المسار /push. ولهذا المزود شرط واحد: لا يولد توكن الجهاز بنفسه، فأنت تضع للمشترك أي معرف تريده ليصل معه في الطلب، وهذا ما سوف نفعله في السكربت.
بناء ال Workflows عبر API v2
تستطيع أن تنشئ ال Workflows من لوحة التحكم بالسحب والإفلات، ولكننا أنشأناها بسكربت عبر POST /v2/workflows، وهو الطلب نفسه الذي ترسله اللوحة، لسببين: أن السكربت يحفظ في مستودع الكود فتراجع تغييراته كأي كود، وأن إعادة بناء البيئة على سيرفر جديد تصبح أمراً واحداً بدل نصف ساعة من النقر. والملف workflows.mjs كاملاً:
// Creates the lab workflows through the Novu API v2 (the same thing the dashboard does when you click "Create workflow")
// NOVU_API=http://127.0.0.1:3000 NOVU_KEY=<secret key of the Development environment> node workflows.mjs
const API = process.env.NOVU_API, KEY = process.env.NOVU_KEY;
const call = async (method, path, body) => {
const r = await fetch(API + path, { method, headers: { Authorization: `ApiKey ${KEY}`, 'Content-Type': 'application/json' }, body: body && JSON.stringify(body) });
const j = await r.json(); if (!r.ok) throw new Error(`${r.status} ${JSON.stringify(j).slice(0, 300)}`); return j.data;
};
const html = (h, p) => `<div dir="rtl" style="font-family:Tahoma,Arial;font-size:15px;line-height:1.8"><h2 style="margin:0 0 8px">${h}</h2><p>${p}</p></div>`;
const workflows = [
{
workflowId: 'order-shipped', name: 'خروج الطلب للتوصيل', tags: ['orders'], severity: 'medium',
steps: [
{ name: 'in-app', type: 'in_app', controlValues: { subject: 'طلبك {{payload.orderId}} خرج للتوصيل', body: 'السائق {{payload.driver}} في الطريق، والوصول المتوقع {{payload.eta}}.', primaryAction: { label: 'تتبع الطلب', redirect: { url: '/orders/{{payload.orderId}}' } } } },
{ name: 'email', type: 'email', controlValues: { subject: 'طلبك {{payload.orderId}} في الطريق', editorType: 'html', body: html('مرحباً {{subscriber.firstName}}', 'طلبك رقم {{payload.orderId}} خرج للتوصيل مع {{payload.driver}}، والوصول المتوقع {{payload.eta}}.') } },
{ name: 'push', type: 'push', controlValues: { subject: 'طلبك خرج للتوصيل', body: 'الطلب {{payload.orderId}} يصل {{payload.eta}}' } },
],
},
{
workflowId: 'new-comment', name: 'تعليقات جديدة على منتجك', tags: ['social'], severity: 'low',
steps: [
{ name: 'digest', type: 'digest', controlValues: { type: 'regular', amount: 1, unit: 'minutes', digestKey: '{{payload.productId}}' } },
{ name: 'in-app', type: 'in_app', controlValues: { subject: '{{steps.digest.eventCount}} تعليقات جديدة', body: 'آخرها من {{payload.author}}: {{payload.text}}' } },
{ name: 'email', type: 'email', controlValues: { subject: '{{steps.digest.eventCount}} تعليقات جديدة على {{payload.productName}}', editorType: 'html',
body: '<div dir="rtl" style="font-family:Tahoma,Arial">{% for e in steps.digest.events %}<p><b>{{ e.payload.author }}</b>: {{ e.payload.text }}</p>{% endfor %}</div>' } },
],
},
{
workflowId: 'backup-failed', name: 'فشل النسخ الاحتياطي', tags: ['ops'], severity: 'high',
// critical: subscribers cannot switch it off (readOnly), every channel stays on
preferences: { user: { all: { enabled: true, readOnly: true }, channels: { in_app: { enabled: true }, email: { enabled: true } } } },
steps: [
{ name: 'in-app', type: 'in_app', controlValues: { subject: '{{payload.host}}: فشل {{payload.job}}', body: 'رمز الخروج {{payload.code}}: {{payload.error}}' } },
{ name: 'email', type: 'email', controlValues: { subject: '[عاجل] {{payload.host}}: فشل {{payload.job}}', editorType: 'html', body: html('فشل {{payload.job}} على {{payload.host}}', 'رمز الخروج {{payload.code}}: {{payload.error}}') } },
],
},
];
for (const w of workflows) {
const d = await call('POST', '/v2/workflows', w);
console.log('created', d.workflowId, d.status, d.steps.map((s) => `${s.type}:${s.stepId}`).join(' '), d.issues ? JSON.stringify(d.issues).slice(0, 200) : '');
}في السكربت أعلاه لاحظ التالي:
- المصادقة Authentication بالترويسة
Authorization: ApiKeyومعها المفتاح السري لبيئة Development، وهذا المفتاح للسيرفر فقط ولا يوضع في كود الواجهة أبداً. order-shippedثلاث خطوات متتالية، وكل خطوة تستخدم متغيرات الحمولة مثل{{payload.orderId}}ومتغيرات المشترك مثل{{subscriber.firstName}}، ولخطوة in_app زر أساسي «تتبع الطلب» يفتح رابطاً داخل تطبيقك.new-commentيبدأ بخطوةdigestمن النوعregularلمدة دقيقة، ومفتاح التجميعdigestKeyهو{{payload.productId}}، أي أن تعليقات المنتج الواحد تجمع معاً وتعليقات منتج آخر تجمع وحدها. وفي قالب البريد حلقة{% for e in steps.digest.events %}بلغة القوالب Liquid تمر على كل الأحداث المجمعة.backup-failedبدرجة أهميةhigh، ومعه إعدادpreferencesفيهreadOnly: true، أي أن المشترك لا يستطيع أن يغير قنواته، وهذا ما يجعل ال Workflow حرجاً Critical كما سوف نجرب.- كل قالب HTML للبريد يبدأ ب
dir="rtl"، فبدونه يظهر البريد العربي محاذياً لليسار في أغلب برامج البريد. وتفاصيل الاتجاه في النصوص المختلطة في مقال التعريب والنص ثنائي الاتجاه.
وعند تشغيله كان المخرج كما يلي:
created order-shipped ACTIVE in_app:in-app email:email push:push
created new-comment ACTIVE digest:digest in_app:in-app email:email
created backup-failed ACTIVE in_app:in-app email:email الثلاثة بحالة ACTIVE، وكل خطوة أخذت معرفاً من اسمها، وهذه المعرفات هي التي نستخدمها لاحقاً في المتغيرات مثل steps.digest.events. وفي لوحة التحكم ظهرت ال Workflows الثلاثة بأسمائها العربية، وروابطها في المتصفح حروف لاتينية مكتوبة من الاسم العربي مثل khrwj-altlb-lltwsyl، والصورة التالية ل Workflow التعليقات كما يرسمه محرر اللوحة:

ولاحظ الرقم 3 بجانب «Publish changes» في أعلى الصفحة: ال Workflows الثلاثة موجودة في Development فقط، وإذا أرسل تطبيقك حدثاً بمفتاح Production فلن يجدها حتى تنشرها. وهذا خطأ يقع فيه كثيرون في الأسبوع الأول.
أول إشعار: فشل البريد وPush بسبب الحماية من SSRF
بقي أن ننشئ المشترك ونرسل الحدث. والسكربت run.mjs فيه خطوات التجربة كلها، وهذه الخطوتان الأوليان منه:
if (step === 'subscriber') {
console.log(await call('POST', '/v2/subscribers', { subscriberId: 'user-1042', firstName: 'سارة', email: '[email protected]', locale: 'ar' }).then((s) => `subscriber ${s.subscriberId} ${s.email}`));
await call('PUT', '/v1/subscribers/user-1042/credentials', { providerId: 'push-webhook', integrationIdentifier: 'push-webhook', credentials: { deviceTokens: ['lab-phone-token-1'] } });
console.log('push credentials set');
}
if (step === 'order') {
const t0 = Date.now();
const r = await call('POST', '/v1/events/trigger', { name: 'order-shipped', to: { subscriberId: 'user-1042' }, payload: { orderId: '1042', driver: 'خالد', eta: 'خلال 25 دقيقة' } });
console.log('trigger ->', JSON.stringify(r), `${Date.now() - t0} ms`);
}المشترك user-1042 ببريد تجريبي ولغة عربية، ومعه توكن جهاز وهمي lab-phone-token-1 لمزود Push Webhook. ثم الحدث نفسه: اسم ال Workflow، والمشترك، والحمولة. والمخرج سوف يكون كما يلي:
subscriber user-1042 [email protected]
push credentials set
trigger -> {"acknowledged":true,"status":"processed","transactionId":"txn_6affad2clhdlo3ad8zox"} 148 msرد api في 148 ms ب acknowledged وprocessed، ومعه معرف عملية transactionId تستطيع أن تبحث به في سجل النشاط، أو تلغي به الحدث إذا كان ما زال ينتظر في خطوة تأخير أو تجميع. ولكن هذا الرد لا يقول شيئاً عن الإرسال، فعندما سألنا عن حالة الإشعار من GET /v1/notifications كانت النتيجة:
02:15:08 خروج الطلب للتوصيل | in_app:completed email:failed push:failedالإشعار داخل التطبيق وصل، والبريد وPush فشلا. والصورة التالية من سجل النشاط في اللوحة لهذا التشغيل نفسه:

وتفاصيل الخطأين داخل كل خطوة كانت كما يلي:
email: Unexpected provider error {"reason":"PRIVATE_IP","resolvedAddress":"172.25.0.8","hostname":"sc6-mailpit","name":"SsrfBlockedError"}
push: Push webhook URL blocked: Requests to private or reserved IP addresses are not allowed (resolved: 172.25.0.9).والسبب ليس في Mailpit ولا في نقطة الاستقبال، وإنما في حماية داخل worker من هجوم تزوير الطلبات من جهة السيرفر SSRF أي Server-Side Request Forgery. والفكرة أن Novu يقبل من المستخدم روابط يتصل بها: رابط Webhook، وعنوان سيرفر SMTP، ورابط خطوة HTTP. فلو سمح بأي عنوان لاستطاع أي شخص له حساب أن يضع عنواناً داخلياً مثل قاعدة بيانات أو خدمة إدارة أو عنوان البيانات الوصفية Metadata للسحابة 169.254.169.254، فيجعل سيرفرك يطلب منه ويعيد له النتيجة، وهذه من أشهر طرق سرقة مفاتيح السحابة. لذلك يترجم worker الاسم إلى عنوان IP أولاً، فإذا كان العنوان خاصاً Private مثل 172.25.0.8 رفض الاتصال. والصورة التالية تبين ما حدث وما أصلحه:

الإصلاح: NOVU_SAFE_OUTBOUND_ALLOW
وهذه المشكلة سوف تقابلك في كل تثبيت حقيقي تقريباً، لأن أفضل مكان لسيرفر SMTP الداخلي ولبوابة Push هو الشبكة الخاصة نفسها. والحل في توثيق التثبيت تحت أسئلة الشبكة: المتغير NOVU_SAFE_OUTBOUND_ALLOW، وهو قائمة سماح Allow-list مفصولة بفواصل، تقبل أسماء سيرفرات، أو نطاقات تبدأ بنقطة مثل .svc.cluster.local، أو عناوين IP، أو شبكات CIDR مثل 10.0.0.0/8. والملف المجتمعي لا يمرره، فأضفناه إلى worker:
worker:
image: "ghcr.io/novuhq/novu/worker:3.19.0"
environment:
# hosts on the private network that Novu may call: SMTP relay and push gateway
NOVU_SAFE_OUTBOUND_ALLOW: ${NOVU_SAFE_OUTBOUND_ALLOW:-}# .env
NOVU_SAFE_OUTBOUND_ALLOW=sc6-mailpit,sc6-hook
docker compose up -d workerوعاد worker سليماً بعد 29 ثانية. ولاحظ أننا سمحنا بالاسمين فقط، ولم نسمح بالشبكة كلها 172.16.0.0/12 مع أنها أسهل، والسبب أن السماح بالشبكة يعيد الثغرة التي جاءت الحماية لتغلقها: أي حساب يستطيع حينها أن يكلم MongoDB وRedis وكل ما في شبكة Docker. والتوثيق يذكر أن المتغير نفسه يوضع على api أيضاً إذا كنت تستخدم خطوات الكود عبر Bridge URL داخلي، وأن عناوين 169.254.0.0/16 وmetadata.google.internal لا يمكن السماح بها مهما كتبت.
PRIVATE_IP في سجل النشاط فلا تبحث عن متغير يطفئ الحماية كلها، وأضف إلى القائمة الأسماء التي تملكها فقط. والسبب أن قائمة الروابط في Novu يكتبها كل من له حساب في اللوحة، وأي رابط يكتبه يتصل به سيرفرك من داخل شبكتك.القنوات الثلاث بعد الإصلاح: ماذا وصل فعلاً؟
أعدنا إرسال الحدث نفسه:
trigger -> {"acknowledged":true,"status":"processed","transactionId":"txn_6affae15ewmbotlbhgpj"} 118 msوهذه المرة كانت الحالة في سجل النشاط:
02:15:08 خروج الطلب للتوصيل | in_app:completed email:failed push:failed
02:19:01 خروج الطلب للتوصيل | in_app:completed email:completed push:completedالسطر الأول هو المحاولة الفاشلة، والثاني بعد الإصلاح وفيه القنوات الثلاث مكتملة. وفي Mailpit وصلت رسالة واحدة:
Example Store [email protected] -> [email protected] | طلبك 1042 في الطريق | مرحباً سارة طلبك رقم 1042 خرج للتوصيل مع خالد، والوصول المتوقع خلال 25 دقيقة.المرسل «Example Store» كما في إعداد التكامل، والعنوان من قالب البريد بعد أن استبدلت المتغيرات، والنص يبدأ ب «مرحباً سارة» من {{subscriber.firstName}}، أي أن القالب أخذ اسم المشترك من سجله في Novu ولم يرسله تطبيقك مع الحدث. وهذه فائدة عملية للمشتركين: بياناتهم تحفظ مرة واحدة، والأحداث تحمل ما يخص الحدث فقط.
ولقياس السرعة أرسلنا التنبيه نفسه خمس مرات وقسنا ثلاثة أزمنة، والمخرج كما يلي:
novu trigger answered ms 40 31 25 24 28 | median 28
novu trigger -> in-app (API) ms 734 655 550 599 785 | median 655
novu trigger -> email (Mailpit) ms 1003 1041 941 888 1074 | median 1003رد api بوسيط 28 ms، أما ظهور الإشعار داخل التطبيق فاستغرق نحو ثلثي ثانية، ووصول البريد إلى Mailpit نحو ثانية. وهذا الفرق هو الثمن الطبيعي للطابور: تطبيقك لا ينتظر، والإرسال يتم بعده بمهمة في الخلفية. وثانية للبريد التفاعلي سرعة ممتازة، ولكنها تعني أيضاً أن Novu ليس الأداة المناسبة إذا كنت تحتاج تنبيهاً يصل خلال أجزاء من الثانية، مثل إشعارات المراقبة على هاتف فريق التشغيل، فهناك أدوات أبسط وأسرع سوف نذكرها في جدول القرار.
ماذا استلمت نقطة Push Webhook؟ انتبه للخصوصية Privacy
أما Push فقد وصل إلى نقطة الاستقبال Endpoint هذا الطلب، كما طبعه Container الاستقبال:
POST /push | Content-Type: application/json | User-Agent: novu-safe-outbound/1.0 | X-Team: None
{"target": ["lab-phone-token-1"], "title": "طلبك خرج للتوصيل", "content": "الطلب 1042 يصل خلال 25 دقيقة", "messageId": "6affae19db2eaea45a231551", "overrides": {}, "payload": {"orderId": "1042", "driver": "خالد", "eta": "خلال 25 دقيقة", "__nvMessageId": "6affae19db2eaea45a231551", "subscriber": {"_id": "6affad2bdb85a15e685c0fc3", "_organizationId": "6affac7edb85a15e685c0dcb", "_environmentId": "6affac7edb85a15e685c0dd2", "firstName": "سارة", "subscriberId": "user-1042", "email": "[email protected]", "locale": "ar", "channels": [{"credentials": {"deviceTokens": ["lab-phone-token-1"]}, "_integrationId": "6affacd7db85a15e685c0e2f", "providerId": "push-webhook"}], "isOnline": false, "deleted": false, "createdAt": "2026-11-20T02:15:07.917Z", "updatedAt": "2026-11-20T02:15:08.002Z", "__v": 0, "id": "6affad2bdb85a15e685c0fc3"}, "step": {"digest": false, "events": [], "total_count": 0}}}في الطلب أعلاه لاحظ التالي:
targetفيه توكن الجهاز الذي وضعناه للمشترك، وtitleوcontentهما العنوان والنص بعد القالب، وهذا ما تحتاجه بوابتك لترسل الإشعار إلى الجهاز.User-Agentهوnovu-safe-outbound/1.0، أي أن الطلب خرج من طبقة الاتصال المحمية التي رأينا حمايتها من SSRF قبل قليل.- داخل
payloadيوجد سجل المشترك كاملاً: بريده، واسمه، ولغته، ومعرفاته الداخلية في MongoDB، وقنواته وتوكناته، وتواريخ إنشائه وتحديثه. أي أن أي جهة تضع رابطها في تكامل Push Webhook تستلم بيانات شخصية لكل مستخدم يصله إشعار، وليس فقط نص الإشعار.
وهذه نقطة يجب أن تنتبه لها إذا كانت نقطة الاستقبال عند طرف ثالث، أو إذا كانت بوابتك تحفظ ما يصلها في السجلات Logs، لأن البريد الإلكتروني بيانات شخصية تحكمها أنظمة حماية البيانات، وقد ذكرنا ما يلزمك منها في حماية البيانات الشخصية PDPL للخدمات المستضافة. وتحقق دائماً من التوقيع x-novu-signature في نقطة الاستقبال قبل أن تثق بالطلب، بالطريقة التي شرحناها في مقال Webhooks، فرابط الاستقبال يمكن أن يكتشفه أحد ويرسل إليه طلبات مزورة.
التجميع Digest: خمسة تعليقات في رسالة واحدة
الآن ال Workflow الثاني، وفكرته أن المستخدم الذي يصله خمسون تعليقاً على منتج نشره لا يريد خمسين بريداً. والخطوة digest تجمع الأحداث التي تصل خلال نافذة زمنية Window، ثم تكمل ال Workflow مرة واحدة بكل ما جمعته، كما في توثيق خطوة Digest. وأرسلنا خمسة تعليقات على المنتج نفسه بين كل تعليق والذي بعده ثلاث ثوان:
const authors = ['نورة', 'فهد', 'ريم', 'سلطان', 'هند'];
for (const [i, a] of authors.entries()) {
const r = await call('POST', '/v1/events/trigger', { name: 'new-comment', to: { subscriberId: 'user-1042' }, payload: { productId: 'p-77', productName: 'سماعة لاسلكية', author: a, text: `تعليق رقم ${i + 1}` } });
console.log(new Date().toISOString().slice(11, 19), 'comment from', a, '->', r.status, r.transactionId);
await sleep(3000);
}02:19:23 comment from نورة -> processed txn_6affae2bwolnrks9pgfw
02:19:27 comment from فهد -> processed txn_6affae2ff5ajbrdply0p
02:19:30 comment from ريم -> processed txn_6affae32unbo64d7d9cp
02:19:33 comment from سلطان -> processed txn_6affae353hrvbckf88wj
02:19:36 comment from هند -> processed txn_6affae3897j1a6h54qszكل حدث أخذ معرف عملية مستقلاً، ورد api على كل واحد ب processed كالعادة. أما ما حدث بعدها فيظهر في سجل النشاط:
02:19:24 تعليقات جديدة على منتجك | digest:completed in_app:completed email:completed
02:19:27 تعليقات جديدة على منتجك | digest:merged in_app:merged email:merged
02:19:30 تعليقات جديدة على منتجك | digest:merged in_app:merged email:merged
02:19:33 تعليقات جديدة على منتجك | digest:merged in_app:merged email:merged
02:19:36 تعليقات جديدة على منتجك | digest:merged in_app:merged email:mergedالتشغيل الأول فتح نافذة التجميع وأكمل خطواته، والأربعة بعده حالتها merged في كل الخطوات، أي أنها دمجت في التشغيل الأول ولم ترسل شيئاً بنفسها. والصورة التالية تبين التوقيت:

وفي ال Inbox ظهر إشعار واحد للتعليقات فوق إشعاري الطلب:
unread | 5 تعليقات جديدة | آخرها من نورة: تعليق رقم 1
unread | طلبك 1042 خرج للتوصيل | السائق خالد في الطريق، والوصول المتوقع خلال 25 دقيقة.
unread | طلبك 1042 خرج للتوصيل | السائق خالد في الطريق، والوصول المتوقع خلال 25 دقيقة.وفي Mailpit بريد واحد بالتعليقات الخمسة، ومعه بريد الطلب من قبل:
02:20:25 [email protected] | 5 تعليقات جديدة على سماعة لاسلكية | نورة: تعليق رقم 1 فهد: تعليق رقم 2 ريم: تعليق رقم 3 سلطان: تعليق رقم 4 هند: تعليق رقم 5
02:19:04 [email protected] | طلبك 1042 في الطريق | مرحباً سارة طلبك رقم 1042 خرج للتوصيل مع خالد، والوصول المتوقع خلال 25 دقيقة.البريد وصل في 02:20:25، أي بعد نحو دقيقة من أول تعليق وصل في 02:19:23، وليس بعد دقيقة من آخر تعليق. وهذا هو معنى النوع regular: النافذة تبدأ مع أول حدث وتغلق بعد المدة، وما يصل بعد إغلاقها يفتح نافذة جديدة. وإذا أردت أن يصل أول حدث فوراً ثم يجمع ما بعده، فالتوثيق يذكر خياراً لذلك، وهناك أيضاً التجميع المجدول Scheduled Digest الذي يرسل في وقت ثابت كل يوم بتوقيت المشترك، وهو المناسب لملخص يومي.
خطأ شائع: payload بعد التجميع هو الحدث الأول
انظر مرة أخرى إلى نص الإشعار داخل التطبيق: «آخرها من نورة: تعليق رقم 1». ونورة كانت أول من علق وليست آخر من علق. والقالب الذي كتبناه كان آخرها من {{payload.author}}، وافترضنا أن payload بعد التجميع هو آخر حدث، والحقيقة أن الخطوات بعد ال Digest تعمل في سياق التشغيل الذي فتح النافذة، فتأخذ حمولة الحدث الأول. والأحداث كلها موجودة في steps.digest.events وعددها في steps.digest.eventCount كما في مرجع خطوة Digest، وهذا ما استخدمه قالب البريد فجاء صحيحاً. لذلك إذا أردت آخر تعليق فاكتب في قالب in_app شيئاً مثل:
{% assign last = steps.digest.events | last %}
آخرها من {{ last.payload.author }}: {{ last.payload.text }}وهذا الخطأ لا يظهر في الاختبار السريع بحدث واحد، لأن الأول والأخير حينها واحد، ولذلك جرب كل قالب بعد ال Digest بثلاثة أحداث على الأقل.
العدد والجمع في العربية: «1 تعليقات جديدة»
وفي آخر التجربة، بعد أن أطفأنا البريد كما في القسم التالي، وصل تعليق واحد فقط في نافذة، فظهر في ال Inbox بعنوان «1 تعليقات جديدة»، وتراه في أسفل صورة ال Inbox بعد قليل. والسبب أن القالب {{steps.digest.eventCount}} تعليقات جديدة يضع الرقم أمام كلمة الجمع دائماً، والعربية تحتاج المفرد للواحد والمثنى للاثنين والجمع من ثلاثة إلى عشرة والمفرد المنصوب من أحد عشر فما فوق. والحل شروط Liquid في القالب، كما في توثيق الشروط في Liquid:
{% assign n = steps.digest.eventCount %}
{% if n == 1 %}تعليق جديد
{% elsif n == 2 %}تعليقان جديدان
{% elsif n <= 10 %}{{ n }} تعليقات جديدة
{% else %}{{ n }} تعليقاً جديداً{% endif %}ولا تعتمد على ميزة الترجمات Translations في Novu لحل هذا، فهي غير متوفرة في النسخة المجتمعية بحسب صفحة الفرق بين النسختين، فالشروط داخل القالب هي الطريق هنا.
تفضيلات المشترك Preferences والإشعار الحرج Critical
التفضيلات في Novu طبقات بحسب توثيق التفضيلات: إعداد ال Workflow الافتراضي، ثم تفضيلات المشترك العامة Global لكل ال Workflows، ثم تفضيلاته لكل Workflow على حدة، والأكثر تحديداً يفوز. والاستثناء هو ال Workflow الحرج: تهمل فيه تفضيلات المشترك كلها، ولا يظهر له في قائمة التفضيلات أصلاً، وهذا مناسب لإعادة تعيين كلمة المرور وتنبيهات الأمان وما في حكمها. ولنجرب ذلك: المشترك يطفئ البريد للتعليقات، ثم يحاول أن يطفئه لتنبيه فشل النسخ الاحتياطي:
if (step === 'prefs-off') {
const p = await call('PATCH', '/v2/subscribers/user-1042/preferences', { workflowId: 'new-comment', channels: { email: false } });
console.log('new-comment channels now:', JSON.stringify(p.workflows?.find((w) => w.workflow.identifier === 'new-comment')?.channels ?? p));
try { await call('PATCH', '/v2/subscribers/user-1042/preferences', { workflowId: 'backup-failed', channels: { email: false } }); console.log('critical changed?!'); }
catch (e) { console.log('try to turn off backup-failed email ->', e.message.slice(0, 200)); }
}new-comment channels now: {"email":false,"in_app":true}
critical changed?!السطر الأول متوقع: البريد مطفأ وداخل التطبيق باق. أما الثاني فطبعه السكربت لأن الطلب على ال Workflow الحرج رد بنجاح ولم يرفض كما توقعنا. وقد يتساءل البعض: هل تغير شيء إذن؟ والإجابة في قراءة التفضيلات بعدها:
global {"enabled":true,"channels":{"email":true,"in_app":true,"push":true}}
new-comment {"email":false,"in_app":true} overrides: [{"channel":"in_app","source":"subscriber"},{"channel":"email","source":"subscriber"}]
order-shipped {"email":true,"in_app":true,"push":true} overrides: [{"channel":"in_app","source":"subscriber"},{"channel":"email","source":"subscriber"},{"channel":"push","source":"subscriber"}]backup-failed غير موجود في القائمة أصلاً، أي أن الواجهة لا تعرضه للمشترك، وnew-comment فيه البريد مطفأ ومصدر القرار subscriber. ولكن الذي يهم هو ما يحدث عند الإرسال، فأرسلنا تنبيه نسخة احتياطية فاشلة وتعليقاً جديداً، وكانت النتيجة:
02:21:28 فشل النسخ الاحتياطي | in_app:completed email:completed
02:21:28 تعليقات جديدة على منتجك | digest:completed in_app:completed email:canceledوتفاصيل الخطوات من سجل التنفيذ:
# تعليقات جديدة على منتجك
## digest completed
Pending | Step queued
Pending | Step digested
Success | Digest triggered events
## in_app completed
Pending | Step queued
Pending | Message created
Success | Message sent
## email canceled
Pending | Step queued
Success | Step filtered by subscriber workflow preferences
# فشل النسخ الاحتياطي
## in_app completed
Pending | Step queued
Pending | Message created
Success | Message sent
## email completed
Pending | Step queued
Pending | Custom SMTP provider was selected
Pending | Message created
Success | Message sentخطوة البريد للتعليقات ألغيت بالرسالة «Step filtered by subscriber workflow preferences»، ولم يحاول أي مزود أن يرسل، أما تنبيه النسخة الاحتياطية فاختير له مزود Custom SMTP ووصل البريد رغم أن المشترك طلب إيقافه. والصورة التالية تجمع التجربتين:

والدرس العملي هنا ليس في Novu وحده: لا تحكم على التفضيلات من رد الطلب الذي يغيرها، وإنما من سجل الإرسال بعدها. والطلب الذي رد بنجاح على ال Workflow الحرج حفظ شيئاً لا أثر له، ولو كانت واجهتك تعرض للمستخدم «تم إيقاف البريد» بناء على هذا الرد لكانت تكذب عليه. وانتبه أيضاً إلى أن الإشعار الحرج سلاح بحدين، فإذا وضعت علامة Critical على الإشعارات التسويقية لتتجاوز اختيار المستخدم فأنت تخالف موافقته، وقد تخالف أنظمة حماية البيانات التي تشترط أن يستطيع المستخدم إيقاف الرسائل غير الضرورية.
صندوق الإشعارات Inbox داخل تطبيقك
قناة in_app تحتاج مكاناً تظهر فيه، وNovu يعطيك مكون Inbox جاهزاً لـ React وVue وAngular وJavaScript دون إطار. وأبسط طريقة لتجربته صفحة HTML واحدة تحمل المكتبة @novu/js بالإصدار 3.20.0 وتوجهها إلى سيرفرك بدل خدمة Novu السحابية:
<!doctype html>
<html lang="ar" dir="rtl">
<head><meta charset="utf-8"><title>صندوق الإشعارات</title>
<style>body{font-family:Tahoma,Arial;background:#f6f7f9;margin:0;padding:24px} header{display:flex;justify-content:space-between;align-items:center;background:#fff;border:1px solid #dde2ea;border-radius:12px;padding:12px 18px}</style>
</head>
<body>
<header><b>متجر المثال</b><div id="inbox"></div></header>
<script type="module">
// The Inbox UI from @novu/js, pointed at our self-hosted API and WebSocket server
import { NovuUI } from 'https://esm.sh/@novu/[email protected]/ui';
const novu = new NovuUI({
options: {
applicationIdentifier: 'QOq1I_bYkiek', // Development environment identifier
subscriberId: 'user-1042',
backendUrl: 'http://localhost:3000',
socketUrl: 'ws://localhost:3002',
},
});
novu.mountComponent({ name: 'Inbox', props: { open: true }, element: document.getElementById('inbox') });
</script>
</body>
</html>في الصفحة أعلاه لاحظ التالي:
backendUrlوsocketUrlهما ما يجعل المكون يكلم سيرفرك، وبدونهما يحاول الاتصال بالخدمة السحابية ويفشل لأن معرف تطبيقك غير موجود هناك. وفي الإنتاج يصبحان روابط HTTPS وWSS بنطاقاتك.applicationIdentifierمعرف عام لبيئة Development، وليس سراً، فهو يظهر في كود الصفحة لأي زائر.- خدمنا الصفحة من nginx، ولا تفتحها كملف من القرص مباشرة، لأن المتصفح يعامل الصفحة المفتوحة من القرص بقيود مختلفة في الطلبات إلى api.
والصورة التالية للمكون كما ظهر، وعلى اليمين لوحة التفضيلات التي يفتحها المستخدم من زر الإعدادات:

وفي الصورة عدة أشياء تستحق الملاحظة. فإشعارات فشل النسخ الاحتياطي بخلفية حمراء وخط أحمر لأن درجة أهمية ال Workflow high، أي أن المكون يميز الدرجات دون أن تكتب CSS. وفي الأسفل إشعار «1 تعليقات جديدة» الذي تحدثنا عنه. وفي لوحة التفضيلات يظهر order-shipped وnew-comment فقط، ولا يظهر backup-failed لأنه حرج. وفيها أيضاً مفتاح الجدول Schedule الذي يحدد فيه المستخدم ساعات استقبال الإشعارات، ويكتب المكون في قسم الجدول أن الإشعارات الحرجة وإشعارات داخل التطبيق تصل خارج الجدول أيضاً، أي أن الجدول يمنع البريد وPush والرسائل القصيرة فقط، كما في توثيق الجدول. وفي التذييل «Development mode» لأننا استخدمنا معرف بيئة التطوير، وعبارة «Inbox by Novu» التي لا تستطيع إزالتها في النسخة المجتمعية.
حماية ال Inbox: subscriberHash وHMAC
والآن السؤال الأهم: كيف عرف المكون أن هذا المستخدم هو user-1042؟ الجواب أنه لم يتحقق من شيء، فقد فتح الصندوق بمعرف التطبيق العام ومعرف المشترك فقط. وهذا يعني أن أي شخص يعرف معرف مشترك آخر، أو يخمنه إذا كانت معرفاتكم أرقاماً متسلسلة، يستطيع أن يغير الرقم في الصفحة ويقرأ إشعارات غيره، وقد تحمل هذه الإشعارات أرقام طلبات وعناوين وأسماء. والتوثيق يحذر من هذا صراحة في صفحة التجهيز للإنتاج، والحل تفعيل التشفير بالهاش HMAC في تكامل Novu Inbox لبيئة الإنتاج، ثم يحسب سيرفرك لكل مستخدم مسجل الدخول قيمة subscriberHash بالمفتاح السري ويرسلها إلى الصفحة:
import { createHmac } from 'crypto';
// on your server, after the user logs in: never in the browser
const subscriberHash = createHmac('sha256', process.env.NOVU_SECRET_KEY)
.update(subscriberId)
.digest('hex');وبعدها يرفض Novu أي طلب من ال Inbox لا يحمل هاشاً صحيحاً للمعرف، فلا يكفي أن يغير المهاجم الرقم لأنه لا يملك المفتاح الذي يحسب به الهاش. ولاحظ أن الحساب على السيرفر فقط، لأن المفتاح السري يرسل الإشعارات ويقرأ كل البيانات، ووضعه في كود الواجهة أسوأ من عدم استخدام HMAC أصلاً.
ماذا يحدث إذا توقف worker؟
قلنا إن api ترد قبل الإرسال، فماذا لو كان العامل الذي يرسل متوقفاً؟ أوقفنا worker، ثم أرسلنا تنبيه فشل نسخة احتياطية على سيرفر آخر، وانتظرنا 20 ثانية، ثم شغلناه:
worker stopped
{"data":{"acknowledged":true,"status":"processed","transactionId":"txn_6affb1e7g1zvhk37bl13"}} http=201
inbox before worker start:
web-01: فشل نسخة قاعدة البيانات
worker healthy again after 44 s
inbox now: web-02: فشل worker-down test 2026-11-20T02:35:58.846Zوالمخرج يقول ثلاثة أشياء. الأول أن api ردت ب 201 وprocessed والعامل متوقف، أي أن تطبيقك لن يلاحظ شيئاً. والثاني أن ال Inbox بقي على آخر إشعار قبل التوقف، أي أن شيئاً لم يرسل. والثالث أن العامل بعد أن عاد سليماً خلال 44 ثانية أرسل الحدث الذي كان ينتظر، فظهر في ال Inbox. والصورة التالية تلخص ذلك:

وهذا هو سبب وجود الطابور، ولكن انتبه لما لا يحميك منه. فالمهام التي تنتظر محفوظة في Redis، وإذا توقف Redis نفسه أو أعيد تشغيله دون حفظ على القرص ضاعت. لذلك يوصي توثيق الاستضافة الذاتية بتفعيل الحفظ بطريقة AOF على Redis الطوابير، وهي طريقة تكتب كل عملية في ملف على القرص كما في توثيق الحفظ في Redis، والملف المجتمعي لا يفعلها ولا يضع Volume لبيانات Redis أصلاً. وإذا أردت أن تفهم أين تضيع المهام في Redis بالتفصيل وماذا يحدث للمهمة التي تفشل دائماً فهذا في إعادة المحاولة Retry وDead Letter Queue. والأهم من ذلك أن توقف worker لا يظهر لتطبيقك، فراقبه بفحص /v1/health-check على المنفذ 3004 داخل الشبكة، وراقب عدد المهام التي تنتظر في الطابور، وإلا اكتشفت التوقف من شكوى مستخدم.
سجل النشاط Activity Feed: كيف تتابع كل إشعار؟
رأينا سجل النشاط في صورة التشغيل الفاشل، وهو أول مكان تذهب إليه عندما يقول لك مستخدم «لم يصلني البريد». وتستطيع أن تبحث فيه بمعرف المشترك، أو بمعرف العملية transactionId الذي رجع لتطبيقك عند الإرسال، أو بال Workflow والقناة ودرجة الأهمية، ثم تفتح التشغيل لترى كل خطوة: هل ألغيت بالتفضيلات، وأي مزود اختير، ورسالة الخطأ من المزود كما هي، كما في توثيق المتابعة وتصحيح الأخطاء. ولهذا السبب احفظ transactionId في سجلات تطبيقك بجانب رقم الطلب، فيصبح الربط بين «الطلب 1042» و«ما أرسله Novu عنه» بحثاً واحداً.
ولكن لاحظ حدين. الأول أن السجل يقول إن Novu سلم الرسالة للمزود، ولا يقول إنها وصلت إلى صندوق الوارد، فتتبع الاستلام والفتح Email Activity Tracking غير متوفر في النسخة المجتمعية، وإذا رفض سيرفر المستلم البريد بعد أن قبله سيرفر SMTP لديك فلن تراه هنا وإنما في سجلات سيرفر البريد. والثاني أن السجل يكبر في MongoDB مع كل إشعار، ومدة الاحتفاظ به في النسخة المجتمعية تعتمد على بنيتك كما تقول صفحة الفرق بين النسختين، أي أن مساحة القرص مسؤوليتك.
كم يستهلك Novu؟ الذاكرة RAM والقرص وزمن الإقلاع
قبل الإنتاج يجب أن تعرف ما الذي سوف تضعه على السيرفر، وهذه الأرقام من التجربة نفسها:
| الخدمة | حجم ال Image | الذاكرة بعد التشغيل الأول | الذاكرة بعد إعادة التشغيل ودقيقة دون عمل |
|---|---|---|---|
| api | 2.4 GB | 421 MiB | 376.5 MiB |
| worker | 2.19 GB | 655 MiB | 254.7 MiB |
| ws | 2.12 GB | 507 MiB | 268.7 MiB |
| dashboard | 402 MB | 16.7 MiB | 16.5 MiB |
| mongodb | 1.24 GB | 212.7 MiB | 203.3 MiB |
| redis | 162 MB | 14.7 MiB | 11 MiB |
| المجموع | نحو 7.8 GB | نحو 1.83 GB | نحو 1.13 GB |
والذي يلفت النظر هو حجم ال Images: الخدمات الثلاث فوق 2 GB لكل واحدة، مع أنها تشترك في طبقة أساس حجمها 231.9 MB، والتنزيل المضغوط أصغر بكثير (367 MB ل api و346 ل worker و338 ل ws و95 ل dashboard). فخصص للتثبيت نحو 8 GB على القرص قبل بيانات MongoDB، وضعف ذلك وقت الترقية لأن النسخة القديمة والجديدة تبقيان معاً حتى تحذف القديمة. وأما الذاكرة فنحو 1.1 GB دون عمل ترتفع إلى قرابة 2 GB عند الإقلاع، لذلك لا يناسب Novu سيرفراً صغيراً بذاكرة 1 GB، والحد الأدنى الواقعي سيرفر بذاكرة 4 GB. والتوثيق الرسمي يوصي لتثبيت على سيرفر واحد ب 4 vCPU و8 GB للخدمات الأربع، ومعها 2 GB ل MongoDB و2 GB ل Redis، وهذا للإنتاج بحجم معقول وليس للتجربة.
وأما زمن الإقلاع فبعد إعادة تشغيل كاملة أصبح api سليماً بعد 54.6 ثانية، وworker بعد 55.1 ثانية. وهذا يعني أن أي إعادة تشغيل للسيرفر أو ترقية توقف الإرسال قرابة دقيقة، تبقى خلالها الأحداث تنتظر إذا كان api يعمل، أو تفشل طلبات تطبيقك إذا كان api نفسه متوقفاً. لذلك اجعل تطبيقك يعيد المحاولة عند فشل الطلب إلى Novu، أو يكتب الحدث في جدول الصادر Outbox عنده ثم يرسله، بدل أن يضيع إشعار الطلب لأن Novu كان يعيد التشغيل.
قبل الإنتاج Production: النطاقات وTLS والنسخ الاحتياطي والترقية
ما شغلناه في التجربة كله على localhost، وعلى سيرفر حقيقي تحتاج الأمور التالية:
ثلاثة نطاقات خلف Reverse Proxy بشهادة TLS
المتصفح يكلم ثلاث خدمات: لوحة التحكم، وapi، وws لل Inbox، ولذلك تحتاج ثلاثة نطاقات فرعية Subdomains أو مسارات، كلها بشهادة TLS. ومثال بملف Caddyfile لأنه يصدر الشهادات بنفسه، والتفصيل في دليل Caddy:
notify.example.com {
reverse_proxy 127.0.0.1:4000
}
notify-api.example.com {
reverse_proxy 127.0.0.1:3000
}
notify-ws.example.com {
reverse_proxy 127.0.0.1:3002
}ثم تغير المتغيرات في .env لتطابق النطاقات، لأن الملف المجتمعي يبنيها من HOST_NAME مع المنافذ، وهذا لا يصلح خلف Reverse Proxy:
API_ROOT_URL=https://notify-api.example.com
FRONT_BASE_URL=https://notify.example.com
VITE_API_HOSTNAME=https://notify-api.example.com
VITE_WEBSOCKET_HOSTNAME=https://notify-ws.example.comوالمتغيران اللذان يبدآن ب VITE_ تقرؤهما dashboard، وهما ما يكتبه متصفح فريقك ليصل إلى api وws، فإذا تركتهما على localhost فتحت اللوحة من بعيد ولم يعمل فيها شيء. ولاحظ أن ws يحتاج تمرير ترقية الاتصال إلى WebSocket، وCaddy يفعل ذلك تلقائياً، أما مع nginx فتحتاج ترويستي Upgrade وConnection كما في مقال تطبيقك خلف Reverse Proxy. وفكر أيضاً في من يحتاج الوصول إلى كل نطاق: api وws يجب أن يصل إليهما مستخدمو تطبيقك لأن ال Inbox يكلمهما، أما لوحة التحكم فلفريقك فقط، فاجعلها خلف VPN أو قائمة عناوين مسموحة.
النسخ الاحتياطي Backup: MongoDB ومفتاح التشفير
كل ما يهم في Novu موجود في MongoDB: ال Workflows والقوالب والمشتركون والتفضيلات ومفاتيح المزودين المشفرة. وأبسط نسخة احتياطية متسقة هي mongodump من داخل ال Container إلى ملف مضغوط:
docker exec sc6-novu-mongodb mongodump \
--username root --password "$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase admin \
--db novu-db --archive --gzip > novu-db-$(date +%F).archive.gzومعها احفظ ملف .env في مكان آمن منفصل، لأن STORE_ENCRYPTION_KEY فيه هو الذي يفك مفاتيح المزودين، والنسخة الاحتياطية دونه تعيد إليك ال Workflows ولكن كل التكاملات تحتاج إعادة إدخال مفاتيحها. وطبق على النسخة ما ذكرناه في النسخ الاحتياطي بقاعدة 3-2-1 واختبار الاستعادة، فالنسخة التي لم تجرب استعادتها لا تعرف هل تعمل. وسجل النشاط يكبر بسرعة، فراقب حجم قاعدة البيانات وحجم النسخة مع الوقت.
الترقية Upgrade والإصدارات المثبتة
الملف المجتمعي يثبت الخدمات الأربع على رقم واحد، وهذا صحيح: التوثيق يطلب أن تكون كلها على الإصدار نفسه. فلا تغير رقم api وحده، ولا تستخدم latest. وطريقة الترقية الآمنة أن تقرأ ملاحظات الإصدار في صفحة الإصدارات، ثم تأخذ نسخة احتياطية من MongoDB، ثم تغير الأرقام الأربعة معاً وتشغل docker compose pull ثم docker compose up -d، ثم تتأكد من رقم الإصدار الذي يعمل من /v1/health-check على api. وتذكر أن هذا يعني توقفاً قرابة دقيقة كما رأينا، فاختر له وقتاً هادئاً.
المفاتيح وفصل البيئات
المفتاح السري لكل بيئة يرسل الإشعارات لكل المستخدمين ويقرأ بياناتهم، فعامله كمفتاح قاعدة بيانات: في متغيرات البيئة على السيرفر أو في مدير أسرار Secrets Manager، وليس في المستودع. واستخدم مفتاح Production في الإنتاج فقط، فإذا كان تطبيقك في بيئة الاختبار يرسل بمفتاح الإنتاج فإن عملاءك الحقيقيين سوف تصلهم رسائل الاختبار. وأضف تكاملات المزودين في Production بمفاتيحها الحقيقية، وأبق Development على Mailpit أو ما يشبهه، فلا يخرج بريد حقيقي من بيئة التطوير.
أخطاء شائعة Common Mistakes
- اعتبار رد processed دليلاً على الإرسال: رأينا الرد نفسه والبريد فاشل، ورأيناه والعامل متوقف. فالرد يعني أن الحدث دخل الطابور فقط، وحالة الإرسال في سجل النشاط.
- ترك التسجيل مفتوحاً: أي شخص يصل إلى لوحة التحكم ينشئ حساباً على سيرفرك، فأضف
DISABLE_USER_REGISTRATION=trueإلى خدمة api بعد حسابك الأول، وتذكر أن الملف المجتمعي لا يمرره. - إطفاء الحماية من SSRF بدل قائمة السماح: أضف أسماء سيرفراتك فقط إلى
NOVU_SAFE_OUTBOUND_ALLOW، ولا تضف الشبكة الخاصة كلها. - نشر المنافذ على كل الواجهات: الملف الأصلي يفتح 3000 و3002 و4000 للعالم، فاربطها ب
127.0.0.1وافتحها عبر Reverse Proxy بشهادة TLS. - Inbox دون HMAC: معرف التطبيق عام، ومعرف المشترك يمكن تخمينه، فدون
subscriberHashيقرأ أي شخص إشعارات غيره. - قالب بعد Digest يستخدم
payload: الحمولة هي الحدث الأول، وللأخير أو للكل استخدمsteps.digest.events. - الأرقام مع الجمع العربي دون شرط: «1 تعليقات» و«2 تعليقات» تظهر للمستخدم كخطأ واضح، فاكتب الشروط في القالب.
- الحكم على التفضيلات من رد الطلب: طلب تغيير تفضيل Workflow حرج يرد بنجاح ولا يغير شيئاً، فاختبر بالإرسال الفعلي.
- ال Workflows في Development فقط: تطبيقك في الإنتاج يرسل بمفتاح Production ولا يجد ال Workflow، فانشر التغييرات وأضف التكاملات في البيئتين.
- Redis دون حفظ على القرص: المهام التي تنتظر تضيع إذا أعيد تشغيل Redis، فأضف له Volume وفعل AOF.
- إرسال بيانات شخصية إلى Push Webhook عند طرف ثالث: الطلب يحمل سجل المشترك كاملاً، فاجعل نقطة الاستقبال عندك، ولا تحفظ جسم الطلب في السجلات.
- توقع أن الاستضافة الذاتية تلغي FCM وAPNs: Novu يدير قناة Push ولا يوصلها، والتوصيل إلى الهاتف ما زال عبر Google وApple.
متى تختار Novu؟ جدول القرار Decision Table
Novu ليس الأداة الوحيدة للإشعارات، وحجمه وتعقيده يناسبان حالة معينة. والجدول التالي يضعه بجانب البديلين الأقرب: سيرفر تنبيهات بسيط مثل ntfy الذي شرحناه في إشعارات فورية إلى هاتفك مع ntfy، وأن تبني النظام بنفسك:
| حالتك | الأنسب | السبب |
|---|---|---|
| تنبيهات لفريقك من السكربتات والمراقبة: قرص ممتلئ، نسخة فشلت | ntfy أو Gotify | Container واحد بذاكرة عشرات الميغابايت، والتنبيه يصل خلال أجزاء من الثانية، ولا تحتاج قوالب ولا تفضيلات |
| تطبيقك يرسل لمستخدميه في عدة قنوات، ويريد Inbox وتفضيلات وتجميعاً | Novu | كل هذا جاهز، وتغيير النصوص والقنوات من اللوحة دون نشر كود جديد |
| فريق كبير يحتاج حسابات متعددة وصلاحيات وMFA على لوحة الإشعارات | Novu Cloud، أو بناء خاص | النسخة المجتمعية حساب واحد دون RBAC ولا MFA |
| ملايين الإشعارات يومياً، أو منطق أولويات ومزودين احتياطيين خاص جداً بعملك | البناء الخاص | تحتاج تحكماً كاملاً في الطوابير والتوسع Scaling، كما في مقال نظام الإشعارات |
| تطبيق صغير يرسل بريد التسجيل واستعادة كلمة المرور فقط | مكتبة بريد في التطبيق نفسه | ستة Containers وذاكرة 1 GB على الأقل لقناة واحدة ثمن كبير |
| بيانات المستخدمين يجب أن تبقى عندك بحكم النظام أو العقد | Novu المستضاف | البيانات والسجلات في MongoDB على سيرفرك، والخارج فقط ما يرسله المزود |
ومقارنة تفصيلية بين ntfy وGotify وNovu بقياسات من التشغيل نفسه موجودة في مقال المقارنة ضمن البطاقات في آخر هذا المقال.
قائمة تحقق Checklist قبل أن ترسل لمستخدمين حقيقيين
- الأسرار الثلاثة وكلمة مرور MongoDB مولدة عشوائياً، و
.envمحفوظ في مكان آمن خارج السيرفر. - المنافذ مربوطة ب
127.0.0.1، وال Reverse Proxy يفتح ثلاثة نطاقات بشهادة TLS، ولوحة التحكم ليست مفتوحة للجميع. DISABLE_USER_REGISTRATION=trueممرر إلى api ومجرب بطلب تسجيل يرد 400.- متغيرات
API_ROOT_URLوVITE_API_HOSTNAMEوVITE_WEBSOCKET_HOSTNAMEتطابق النطاقات. NOVU_SAFE_OUTBOUND_ALLOWفيه أسماء سيرفراتك الداخلية فقط.- مخزن S3 حقيقي إذا كان أي بريد يحمل مرفقات.
- ال Workflows منشورة في Production، والتكاملات مضافة هناك بمفاتيح الإنتاج، وتطبيقك يستخدم مفتاح Production.
- HMAC مفعل لتكامل Inbox في Production، و
subscriberHashيحسب على السيرفر. - كل قالب بعد Digest مجرب بثلاثة أحداث، والأعداد العربية بشروط.
- الإشعارات الحرجة محصورة في الأمان والحساب والعمليات، وليس فيها تسويق.
- Redis له Volume وAOF، وworker مراقب بفحص الصحة وطول الطابور.
- نسخة mongodump يومية مع اختبار استعادة، ومراقبة حجم القاعدة.
- تطبيقك يحفظ
transactionIdمع رقم الطلب، ويعيد المحاولة إذا فشل طلبه إلى api.
الخلاصة
وصلنا لنهاية الموضوع، وأهم ما فيه:
- Novu خدمة إشعارات مستقلة: تطبيقك يرسل حدثاً واحداً، وهي تقرر القنوات والقوالب والمزودين والتجميع والتفضيلات، والنسخة المجتمعية بترخيص MIT تعمل على سيرفرك بستة Containers.
- الفصل بين api وworker عبر طوابير Redis يجعل الرد سريعاً (وسيط 28 ms)، ولكنه يجعل رد processed لا يعني الإرسال، فالحقيقة في سجل النشاط.
- التثبيت يحتاج تعديلات: الأسرار، وربط المنافذ محلياً، وإغلاق التسجيل المفتوح، وقائمة سماح لسيرفراتك الداخلية لأن الحماية من SSRF ترفض العناوين الخاصة.
- ال Digest جمع خمسة تعليقات في رسالة واحدة لكل قناة، مع خطأين يجب أن تنتبه لهما: الحمولة هي الحدث الأول، والجمع العربي يحتاج شروطاً.
- التفضيلات تعمل كما يجب في الإشعار العادي، والإشعار الحرج يتجاوزها، فاحصر الحرج فيما يستحقه.
- مكون Inbox يعمل مع سيرفرك ب
backendUrlوsocketUrl، ودون HMAC يقرأ أي شخص إشعارات غيره. - يحتاج نحو 8 GB على القرص وأكثر من 1 GB من الذاكرة دون عمل، ودقيقة ليقلع، وFCM وAPNs ما زالا طريق Push إلى الهاتف.
دليلكيف تبني نظام إشعارات يصل إلى ملايين المستخدمينكيف تصل الرسالة الصحيحة إلى المستخدم مرة واحدة وفي وقتها عبر الإشعار والرسائل والبريد، حتى عندما يتعطل المزود.
دليلإشعارات Push بدون Firebase: ما يستبدل وما يبقى عند Appleما الذي تستطيع أن تخرج منه Firebase في إشعارات الويب وAndroid وiPhone، مع مختبر يرسل Web Push بمفاتيحك وUnifiedPush عبر ntfy على سيرفرك.
دليلإشعارات فورية من سيرفرك إلى هاتفك مع ntfyكيف تشغل سيرفر ntfy خاصاً، وتصلك على هاتفك رسالة عندما يمتلئ القرص أو تفشل النسخة الاحتياطية أو ينتهي النشر.
دليلntfy أم Gotify أم Novu؟ مقارنة على تنبيه واحدأرسلنا تنبيه فشل النسخة الاحتياطية نفسه إلى ntfy وGotify وNovu، وقسنا زمن وصوله وذاكرة كل أداة وقرصها، لتعرف أيها لتنبيهات فريقك وأيها لإشعارات عملائك.
دليلGotify: سيرفر إشعارات بسيط لسكربتاتك وتطبيقاتككيف تشغل Gotify على سيرفرك فتصل تنبيهات سكربتاتك وأدواتك إلى هاتف Android بتوكن إرسال لا يقرأ، ومعه إضافة Go تنبهك عندما تسكت مهمة مجدولة.
دليلApprise: إرسال التنبيه إلى أي قناة من مكان واحدملف إعداد واحد بوسوم يوصل تنبيه أي سكربت إلى الهاتف وغرفة المحادثة والبريد وأي API داخلي، مع تجربة حقيقية لخمس قنوات وما يكشفه Apprise API بإعداداته الافتراضية.
دليلإشعارات المتصفح Web Push وVAPID دون خدمة خارجيةكيف تطلب إذن الإشعارات في اللحظة الصحيحة، وتشفر الرسالة وتوقعها بيدك بحسب RFC 8291 وRFC 8292، وتعرف متى يموت الاشتراك حتى حين ترد الخدمة بالقبول.
دليلUnifiedPush: إشعارات Android دون Googleكيف يصل إشعار تطبيقك إلى هاتف Android عبر موزع وسيرفر تختارهما أنت، بتجربة على هاتف حقيقي مع ntfy وما الذي يوقف الإشعارات في الخلفية.سجل التحديثات
- 20 نوفمبر 2026: كتابة المقال، وتشغيل النسخة المجتمعية من Novu (ملف Docker Compose من الوسم v3.20.0 بخدمات 3.19.0 وmongo 8.0.17 وredis 8.10.3-alpine) مع Mailpit v1.34.0 ونقطة استقبال Push Webhook، وتجربة ثلاثة Workflows والتجميع والتفضيلات ومكون Inbox من @novu/js 3.20.0 وتوقف worker.