ماذا تفعل هذه الوحدة #

لدى النسخة الكثير لترويه: fail2ban حظر عنوان IP، وaide رصد تغيّر ملف نظام، ونسخة الليلة الاحتياطية فشلت، وقرص الجذر بلغ 95 %. وإذا نبّهت كل وحدة بطريقتها —بريد هنا، سطر سجل هناك— فلن يعلم أحد بشيء، ومع عشر نسخ تتضاعف المشكلة عشر مرات.

وحدة global-alerts هي ناقل التنبيهات المركزي في imaxe: أمر واحد تمرّ عبره كل تلك الإشعارات ووجهة واحدة تصل إليها، وهي موضوع Amazon SNS مشترك بين أسطولك كله. من هناك يوزّع SNS كما تشاء: بريد، رسائل SMS، دالة Lambda، طابور SQS، نظام المناوبات لديك. يَنشر بـدور IAM الخاص بالنسخة (صلاحية sns:Publish)، فلا توجد أي بيانات اعتماد تُحفظ. ويصفّي الضجيج قبل الإرسال: عتبة الخطورة تُسقط ما لا يبلغ المستوى الذي يهمّك، ونافذة إزالة التكرار تمنع التنبيه نفسه من إيقاظك أربعين مرة.

وإن لم يكن SNS متاحًا —الشبكة معطّلة، الدور بلا صلاحيات بعد، المنطقة غير قابلة للوصول— لا يضيع التنبيه: يُوضَع في طابور على القرص ويعيد مؤقّت systemd المحاولة كل 5 دقائق.

قبل أن تبدأ

تحتاج إلى معرّف ARN لموضوع SNS (arn:aws:sns:المنطقة:الحساب:الموضوع) وأن تتمكّن النسخة من النشر فيه. إن أطلقت صورة AMI من المشغّل، فقالب CloudFormation ينشئ الموضوع أصلًا، ويشترك ببريدك، وينشئ دور IAM بصلاحية sns:Publish، ويمرّر معرّف ARN إلى النسخة كوسم: تُضبط الوحدة تلقائيًا ولا شيء عليك فعله هنا.

بداية سريعةمهام خطوة بخطوة

مهام شائعة #

اختر ما تريد فعله. كل وصفة تأتي بالأمر مكتوبًا — بدّل معرّف ARN والنص بما يخصّك، ثم اضغط نسخ.

ضبط موضوع SNS إرسال تنبيه اختباري إرسال تنبيه من سكربت عرض حالة الناقل تقليل الضجيج عرض الطابور وإعادة المحاولة إسكات الوحدة

1

ضبط موضوع SNS

أخبر النسخة أين عليها نشر إشعاراتها.

اتصل بخادمك عبر SSH بالمستخدم ubuntu.

وجّه الوحدة إلى معرّف ARN الخاص بموضوعك. تُستنتج المنطقة من المعرّف نفسه، فلا حاجة عادةً لذكرها:

الطرفية

$ sudo imaxe global-alerts configure \
    --topic-arn arn:aws:sns:eu-west-1:123456789012:imaxe-alerts

عدة نسخ تنشر في الموضوع نفسه؟ أعطِ كل واحدة وسم مصدر يسهل تمييزه عبر --source (يُستخدم hostname افتراضيًا):

الطرفية

$ sudo imaxe global-alerts configure --source web-prod-1

يبقى الإعداد في /etc/imaxe/global-alerts.yml ويصبح الإرسال مُفعَّلًا. تابع مع وصفة إرسال تنبيه اختباري.

2

إرسال تنبيه اختباري

تأكّد أن دور IAM ينشر فعلًا قبل أن تثق بالقناة.

انشر تنبيهًا اختباريًا في الموضوع المضبوط:

الطرفية

$ sudo imaxe global-alerts test

يتخطّى الاختبار العتبة وإزالة التكرار —يخرج دائمًا— وإن فشل شيء، يعيد إليك خطأ AWS الحقيقي بدل الوضع الصامت في الطابور. راجع صندوق البريد المشترك في الموضوع (ومجلد البريد المزعج).

إن رأيت MessageId ووصلك الإشعار، فالقناة تعمل. وإن ظهر AuthorizationError، فالنسخة تفتقر إلى صلاحية sns:Publish على ذلك الموضوع.

3

إرسال تنبيه من سكربت

القناة نفسها التي تستخدمها الوحدات، متاحة لما يخصّك.

تنبيه بخطورته ومصدره:

الطرفية

$ sudo imaxe global-alerts send --severity critical \
    --source backup --subject "فشل النسخ الاحتياطي" \
    "انتهى النسخ الاحتياطي الليلي لقاعدة البيانات بخطأ"

إن كان النص يأتي من أمر آخر، مرّره عبر stdin مستخدمًا - بدل الرسالة:

الطرفية

$ df -h / | sudo imaxe global-alerts send --severity warning -

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

الطرفية

$ sudo imaxe global-alerts send --severity warning \
    --dedup-key root-disk-full "قرص الجذر عند 95%"

يسافر التنبيه إلى الموضوع بصيغة JSON، ومعه النسخة والمنطقة والطابع الزمني مُضمَّنة سلفًا. وبدون --dedup-key تشتقّ الوحدة مفتاحًا من المصدر + الخطورة + الموضوع.

4

عرض حالة الناقل

الموضوع والمنطقة وواجهة AWS والتنبيهات المعلّقة، بنظرة واحدة.

ملخّص الحالة الراهنة:

الطرفية

$ sudo imaxe global-alerts status

للتحقق من الإعداد الذي يسري فعلًا —بما في ذلك ما يصل عبر وسوم النسخة، وله أولوية على الملف—:

الطرفية

$ sudo imaxe global-alerts show
$ sudo imaxe global-alerts status --json

ستعرف إن كان ثمة موضوع مضبوط، وفي أي منطقة يجري النشر، وكم تنبيهًا ينتظر في الطابور. ومع --json يصبح جاهزًا للوحة معلومات أو لسكربت.

5

تقليل الضجيج

ارفع عتبة الخطورة ووسّع نافذة إزالة التكرار.

إن أردت أن تعلم بالمهم فقط، أسقط كل ما هو دون warning:

الطرفية

$ sudo imaxe global-alerts configure --min-severity warning

لا راية لنافذة إزالة التكرار: تُضبط في ملف الإعداد. ارفعها إن تكرّر التنبيه نفسه كثيرًا:

/etc/imaxe/global-alerts.yml

dedup_window: 1h   # 30s، 5m، 1h… (الافتراضي 5m)

تُسقَط التنبيهات دون العتبة قبل خروجها (ولا تدخل الطابور) وتُكبَت التكرارات داخل النافذة. ويظل test ينشر دائمًا، فلا تفقد وسيلة التحقق من القناة.

6

عرض الطابور وإعادة المحاولة

ما بقي معلّقًا حين لم يستجب SNS، وكيف تجبر الإرسال.

انظر ما هو معلّق وآخر المفاتيح المُرسَلة:

الطرفية

$ sudo imaxe global-alerts history

إعادة المحاولة يقوم بها مؤقّت systemd كل 5 دقائق أصلًا، لكن يمكنك إجبارها بعد إصلاح الصلاحية أو الشبكة:

الطرفية

$ sudo imaxe global-alerts flush
$ systemctl status imaxe-global-alerts-flush.timer

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

7

إسكات الوحدة

توقّف عن النشر دون فقدان الإعداد.

عطّل إرسال التنبيهات وأزل مؤقّت إعادة المحاولة:

الطرفية

$ sudo imaxe global-alerts remove

يبقى الموضوع والمنطقة وبقية الإعدادات في الملف: ولإعادة التفعيل يكفي configure، فهو يعيد تمكين الوحدة.

تتوقّف النسخة عن النشر. ولا تفشل أوامر send التالية: تنبّه عبر stderr إلى أن الوحدة معطّلة وتنتهي بالرمز 0.

بلا دور IAM لا تنبيهات

تنشر الوحدة ببيانات اعتماد دور النسخة، لا بمفاتيح محفوظة. وإن لم يسمح الدور بـsns:Publish على ذلك الموضوع، فستتراكم التنبيهات في الطابور واحدًا تلو الآخر دون أن تصل أبدًا. وimaxe global-alerts test يخبرك بذلك فورًا، بالخطأ كما تعيده AWS تمامًا.

مرجع CLIالأوامر والرايات والملفات

الملخّص #

الاستخدام

imaxe global-alerts <أمر-فرعي> [--topic-arn ARN] [--severity المستوى] [رايات]

تتطلّب كل الأوامر الفرعية صلاحيات root (استخدم sudo) لأنها تكتب في /etc/imaxe/، وتحتفظ بالحالة في /var/lib/imaxe/، وتدير وحدة systemd. ولا أسرار للتعامل معها: يمرّ النشر عبر دور IAM الخاص بالنسخة. أضف --json إلى status أو show أو history أو flush للحصول على مخرجات يقرأها الحاسوب.

الأوامر الفرعية #

الأمر الفرعي	ماذا يفعل	الرايات المهمّة
status	الحالة: الموضوع المضبوط، والمنطقة الفعلية، وتوافر واجهة AWS، والتنبيهات في الطابور.	--json
configure	يضبط موضوع SNS وخيارات الإرسال. ويعيد تمكين الوحدة إن كانت معطّلة.	--topic-arn, --region, --source, --min-severity
send	ينشر تنبيهًا. وهي القناة التي يستخدمها المشغّل وبقية الوحدات.	--severity, --source, --subject, --dedup-key
test	ينشر تنبيهًا اختباريًا متجاوزًا العتبة وإزالة التكرار، ويبلّغ بالخطأ الحقيقي إن فشل.	--severity
show	يعرض الإعداد الفعلي (الملف + وسوم النسخة المطبَّقة سلفًا).	--json
history	التنبيهات المعلّقة في الطابور ومفاتيح إزالة التكرار المُرسَلة حديثًا.	--json
flush	يعيد محاولة التنبيهات المصفوفة. ويشغّله مؤقّت systemd أيضًا.	--json
remove	يعطّل الإرسال ويزيل المؤقّت. ويحتفظ بالإعداد.	—

الوسائط والرايات #

الراية	النوع	الافتراضي	الوصف
--topic-arn مطلوب	string	—	معرّف ARN لموضوع SNS الهدف (`arn:aws:sns:المنطقة:الحساب:الموضوع`). وبدونه لا تستطيع الوحدة النشر.
--region	string	من ARN	منطقة AWS. إن أُغفلت، تُستنتج من معرّف ARN للموضوع؛ وإلا فمن IMDS أو من `AWS_REGION`.
--source	string	hostname	وسم المصدر. في `configure` وسم النسخة؛ وفي `send` وسم ذلك التنبيه بعينه (مثلًا الوحدة التي أطلقته).
--min-severity	string	info	العتبة: تُسقط التنبيهات دون هذا المستوى. القيم: `info`، `warning`، `critical`.
--severity	string	info	في `send`/`test`: مستوى هذا التنبيه. وتُقبل الصيغتان المختصرتان `warn` و`crit`.
--subject	string	من الرسالة	موضوع قصير. إن أُغفل، يُشتقّ من الرسالة نفسها.
--dedup-key	string	مُشتقّ	مفتاح إزالة التكرار: يكبت التكرارات داخل `dedup_window`. ويُحسَب افتراضيًا من المصدر + الخطورة + الموضوع.
<الرسالة> مطلوب	موضعي	—	في `send`: نص التنبيه، أو `-` لقراءته من `stdin`.
--json	bool	false	في `status` و`show` و`history` و`flush`، يُخرج النتيجة بصيغة JSON على `stdout`.

الإسقاط ليس فشلًا

حين يُسقَط تنبيه —الوحدة معطّلة، أو الخطورة دون العتبة، أو تكرار داخل النافذة— يشرح send ذلك عبر stderr وينتهي بـالرمز 0. وهكذا لا ينكسر السكربت الذي أطلقه بسبب مرشّح ضبطتَه أنت بنفسك.

الإعداد عبر وسوم النسخة #

كل عملية نشر تحتاج أن تشير إلى موضوعها، وإعادة بناء صورة AMI لأجل ذلك بلا معنى. لهذا تقرأ الوحدة، إضافة إلى الملف، وسوم النسخة ذات البادئة imaxe.global-alerts. عبر IMDSv2: فإن وُجدت غلبت على ملف YAML. وهذا ما يفعله قالب CloudFormation في المشغّل، وهو يشترط كذلك MetadataOptions.InstanceMetadataTags: enabled حتى يمكن قراءتها.

الوسم	يعادل	القيم
imaxe.global-alerts.topic_arn	topic_arn	معرّف ARN لموضوع SNS الهدف.
imaxe.global-alerts.region	region	منطقة AWS؛ فارغة = تُستنتج من ARN أو من IMDS.
imaxe.global-alerts.source	source	وسم المصدر؛ فارغ = hostname.
imaxe.global-alerts.min_severity	min_severity	`info` · `warning` · `critical`
imaxe.global-alerts.dedup_window	dedup_window	مدة: `30s`، `5m`، `1h`…
imaxe.global-alerts.enabled	enabled	`true`/`false` (وكذلك `1`/`0`، `yes`/`no`، `on`/`off`).

خارج AWS، أو مع حجب IMDS، تفشل القراءة خلال أجزاء من الثانية وتمضي الوحدة بما يقوله الملف. ولمعرفة ما صار فعّالًا حقًا: imaxe global-alerts show.

الملفات والمسارات #

المسار	المحتوى
/etc/imaxe/global-alerts.yml	إعداد الوحدة: الموضوع والمنطقة والمصدر والعتبة ونافذة إزالة التكرار.
/var/lib/imaxe/state/global-alerts/spool/	طابور التنبيهات المعلّقة، واحد لكل ملف `.json`، بترتيب زمني.
/var/lib/imaxe/state/global-alerts/sent.json	سجلّ مفاتيح إزالة التكرار مع وقت آخر إرسال.
/etc/systemd/system/imaxe-global-alerts-flush.timer	مؤقّت إعادة المحاولة: يبدأ بعد دقيقتين من الإقلاع ويتكرّر كل 5 دقائق.

مثال على global-alerts.yml:

/etc/imaxe/global-alerts.yml

enabled: true
topic_arn: arn:aws:sns:eu-west-1:123456789012:imaxe-alerts
region: ""            # فارغة = تُستنتج من ARN أو من IMDS
source: ""            # فارغ = hostname النسخة
min_severity: info
dedup_window: 5m

الحالة (الطابور وسجلّ إزالة التكرار) تسكن في /var/lib/imaxe/ لا في /etc/ عن قصد: فهي حالة لا إعداد. ويمكن نقل المسارين بمتغيّري البيئة IMAXE_CONFIG_DIR وIMAXE_STATE_DIR.

صيغة التنبيه #

جسم رسالة SNS هو JSON بإصدار مُرقَّم (schema: 1)، ليتمكّن المشترك من معالجته بدالة Lambda أو بطابور، لا مجرد قراءته بالبريد:

جسم الرسالة

{
  "schema": 1,
  "severity": "critical",
  "source": "backup",
  "subject": "فشل النسخ الاحتياطي",
  "message": "انتهى النسخ الاحتياطي الليلي لقاعدة البيانات بخطأ",
  "host": "web-prod-1",
  "instance_id": "i-0abc123def4567890",
  "region": "eu-west-1",
  "ts": "2026-07-25T03:14:07Z",
  "dedup_key": "9f2c1b7e44a0d513"
}

يُركَّب موضوع رسالة SNS على هيئة [imaxe][الخطورة] host: الموضوع، ويُنقّى إلى ASCII قابل للطباعة ويُقتطع عند 100 حرف، وهو الحد الذي يفرضه SNS.

رموز الخروج والسجلات #

كل تنفيذ يعيد رمزًا يمكنك فحصه بـecho $? — مفيد للتسلسل داخل السكربتات:

0OKاكتملت العملية. وكذلك حين يُسقَط التنبيه أو يُصفّ عن قصد.

1ERRخطأ عام: تعذّر نشر الاختبار، أو تعذّر نشره ولا صفّه.

2USAGEوسائط غير صالحة: راية مجهولة، أو رسالة ناقصة، أو خطورة غير صالحة.

64NO TOPICلا يوجد موضوع SNS مضبوط، لا بملف ولا بوسم.

تستجيب الوحدة أيضًا لفحص سلامة imaxe: فإن كانت مُفعَّلة بلا موضوع، يفشل health، بحيث يفضح ذلك أمرُ imaxe health قبل أن يلزم أول تنبيه.

الطرفية

$ sudo imaxe global-alerts test; echo "الخروج: $?"
$ journalctl -u imaxe-global-alerts-flush.service -n 50

حل المشكلات #

العَرَض	السبب المرجّح	الحل
يظهر NO TOPIC (الرمز 64)	لا الملف ولا الوسوم تحمل معرّف ARN لموضوع.	نفّذ `configure --topic-arn …`، أو تحقّق أن للنسخة الوسم `imaxe.global-alerts.topic_arn` وأن الوسوم مفعّلة في البيانات الوصفية.
«SNS غير متاح؛ التنبيه في الطابور» مرة تلو الأخرى	ينقص دورَ النسخة `sns:Publish` على ذلك الموضوع، أو أن ARN يخصّ حسابًا أو منطقة أخرى.	نفّذ `test` لرؤية خطأ AWS بدقة، وصحّح سياسة الدور ثم `flush`.
«واجهة aws متاحة: false» في status	واجهة AWS غير مثبّتة على النسخة؛ والوحدة تنشر عبرها.	ثبّت واجهة AWS. صور imaxe تأتي بها جاهزة؛ أما على مضيفك الخاص فيلزم إضافتها.
تضبط شيئًا ويظل show يعرض قيمة أخرى	وسم `imaxe.global-alerts.*` يطغى على الملف: له الأولوية بحكم التصميم.	غيّر وسم النسخة (أو مُعامل مكدّس CloudFormation) بدل ملف YAML.
لا يصل إلا الأول من عدة تنبيهات متطابقة	نافذة إزالة التكرار تكبتها.	هذا هو المتوقّع. أنقص `dedup_window`، أو استخدم `--dedup-key` مختلفة إن كانت أحداثًا مختلفة فعلًا.
لا يصل شيء ولا توجد أخطاء	الوحدة معطّلة، أو الخطورة دون `min_severity`.	`show` يعرض لك `enabled` والعتبة؛ و`configure` يعيد تمكين الإرسال.
تُنشَر التنبيهات لكنها لا تصلك بالبريد	اشتراك موضوع SNS غير مؤكَّد.	ابحث عن بريد التأكيد من AWS (راجع البريد المزعج) واقبل الاشتراك في وحدة تحكّم SNS.

هل واجهتك مشكلة مع وحدة التنبيهات؟

راسلنا مرفقًا مخرجات «imaxe <module> status --json» وسنرد عليك بسرعة.

التواصل مع الدعم

نقطة واحدة تسمع منها أسطولك كله

ماذا تفعل هذه الوحدة #

مهام شائعة #

ضبط موضوع SNS

إرسال تنبيه اختباري

إرسال تنبيه من سكربت

عرض حالة الناقل

تقليل الضجيج

عرض الطابور وإعادة المحاولة

إسكات الوحدة

الملخّص #

الأوامر الفرعية #

الوسائط والرايات #

الإعداد عبر وسوم النسخة #

الملفات والمسارات #

صيغة التنبيه #

رموز الخروج والسجلات #

حل المشكلات #

هل واجهتك مشكلة مع وحدة التنبيهات؟