> ## Content Index
> Fetch the complete content index at: https://arabroot.io/llms.txt
> Use this file to discover other available public pages before exploring further.

# بروتوكول MQTT مع Mosquitto: كيف تتكلم الأجهزة
- URL: https://arabroot.io/articles/بروتوكول-mqtt-مع-mosquitto-كيف-تتكلم-الاجهزة/
- Published: 2026-11-06T01:44:31.000Z
- Updated: 2026-11-06T02:56:03.000Z
- Description: نفهم الوسيط من الداخل برسائل حقيقية: مستويات التسليم والرسائل المحفوظة والوصية والجلسات الدائمة، ثم نغلقه بالتشفير وكلمات المرور والصلاحيات.
- Author: فريق عرب رووت
- Tags: الأدلة التقنية, الإلكترونيات والطائرات المسيرة والطباعة ثلاثية الأبعاد, الاستضافة الذاتية, Mosquitto

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

وكل هذه الأسئلة إجاباتها في مكان واحد، هو الوسيط Broker الذي تمر به كل الرسائل، وفي البروتوكول الذي يتكلمه، وهو MQTT. وفي مقال [إنترنت الأشياء من الحساس إلى لوحة المتابعة](https://arabroot.io/articles/%D8%A7%D9%86%D8%AA%D8%B1%D9%86%D8%AA-%D8%A7%D9%84%D8%A7%D8%B4%D9%8A%D8%A7%D8%A1-iot-%D9%85%D9%86-%D8%A7%D9%84%D8%AD%D8%B3%D8%A7%D8%B3-%D8%A7%D9%84%D9%89-%D9%84%D9%88%D8%AD%D8%A9-%D8%A7%D9%84%D9%85%D8%AA%D8%A7%D8%A8%D8%B9%D8%A9/)، أول مقال في هذه السلسلة، بنينا المسار كاملاً ورأينا أن إعدادين في المستقبل حولا 137 قراءة مفقودة إلى صفر، وفي هذا المقال سوف نأخذ الوسيط وحده ونفهمه من الداخل مع Mosquitto، فنرى كل ميزة في البروتوكول بمخرج حقيقي من الأدوات `mosquitto_pub` و`mosquitto_sub`، ثم نغلق الوسيط بالتشفير وكلمات المرور والصلاحيات. والمواضيع في السلسلة:

- [إنترنت الأشياء IoT من الحساس إلى لوحة المتابعة](https://arabroot.io/articles/%D8%A7%D9%86%D8%AA%D8%B1%D9%86%D8%AA-%D8%A7%D9%84%D8%A7%D8%B4%D9%8A%D8%A7%D8%A1-iot-%D9%85%D9%86-%D8%A7%D9%84%D8%AD%D8%B3%D8%A7%D8%B3-%D8%A7%D9%84%D9%89-%D9%84%D9%88%D8%AD%D8%A9-%D8%A7%D9%84%D9%85%D8%AA%D8%A7%D8%A8%D8%B9%D8%A9/).
- بروتوكول MQTT مع Mosquitto (الموضوع الحالي).
- [Home Assistant مع ESPHome: أجهزة وأتمتة على سيرفرك](https://arabroot.io/articles/home-assistant-%D9%85%D8%B9-esphome-%D8%A7%D8%AA%D9%85%D8%AA%D8%A9-%D8%A7%D9%84%D9%85%D8%B3%D8%AA%D9%88%D8%AF%D8%B9-%D8%B9%D9%84%D9%89-%D8%B3%D9%8A%D8%B1%D9%81%D8%B1%D9%83/).
- [لوحات المتابعة لإنترنت الأشياء مع Node-RED وGrafana](https://arabroot.io/articles/%D9%84%D9%88%D8%AD%D8%A7%D8%AA-%D8%A7%D9%84%D9%85%D8%AA%D8%A7%D8%A8%D8%B9%D8%A9-%D9%84%D8%A7%D9%86%D8%AA%D8%B1%D9%86%D8%AA-%D8%A7%D9%84%D8%A7%D8%B4%D9%8A%D8%A7%D8%A1-node-red-%D9%85%D8%B9-grafana/).
- [تحديث الأجهزة عن بعد OTA دون أن تتعطل](https://arabroot.io/articles/%D8%AA%D8%AD%D8%AF%D9%8A%D8%AB-%D8%A7%D9%84%D8%A7%D8%AC%D9%87%D8%B2%D8%A9-%D8%B9%D9%86-%D8%A8%D8%B9%D8%AF-ota-%D8%AF%D9%88%D9%86-%D8%A7%D9%86-%D8%AA%D8%AA%D8%B9%D8%B7%D9%84/).
- [أمن إنترنت الأشياء: الأجهزة التي ينساها الجميع](https://arabroot.io/articles/%D8%A7%D9%85%D9%86-%D8%A7%D9%86%D8%AA%D8%B1%D9%86%D8%AA-%D8%A7%D9%84%D8%A7%D8%B4%D9%8A%D8%A7%D8%A1-iot-%D8%A7%D9%84%D8%A7%D8%AC%D9%87%D8%B2%D8%A9-%D8%A7%D9%84%D8%AA%D9%8A-%D9%8A%D9%86%D8%B3%D8%A7%D9%87%D8%A7-%D8%A7%D9%84%D8%AC%D9%85%D9%8A%D8%B9/).

وسوف نناقش في هذا المقال ما يلي:

- لماذا Mosquitto، وما الذي تغير في الإصدار 2.1 الذي صدر هذا العام.
- ما يحدث في الاتصال نفسه: اسم الكلاينت والجلسة ومدة keepalive، وكيف تقرؤها من سجل الوسيط.
- المواضيع Topics والمرشحات Wildcards، ومواضيع `$SYS` التي يراقب بها الوسيط نفسه.
- مستويات التسليم QoS الثلاثة برسائلها الحقيقية، ولماذا وصلت رسالة QoS 2 على أنها QoS 0.
- الرسالة المحفوظة Retained والوصية Last Will، وثلاث طرق لاختفاء الجهاز وأيها يرسل الوصية.
- الجلسة الدائمة Persistent Session، وتجربة «ماذا يحدث إذا أعيد تشغيل الوسيط؟» مع الحفظ وبدونه.
- ميزات MQTT 5: الاشتراك المشترك Shared Subscription وانتهاء صلاحية الرسالة ورموز السبب Reason Codes، ومشكلة جهازين باسم واحد.
- الأمان: TLS بشهادة من سلطة خاصة بك، وكلمات المرور والصلاحيات بإضافات Mosquitto 2.1، ومشكلتان واجهتانا في التشغيل.
- Mosquitto في الإنتاج، والأخطاء الشائعة، وقائمة تحقق.

## لماذا Mosquitto؟ وما الجديد في 2.1؟

Mosquitto وسيط MQTT مفتوح المصدر من مؤسسة Eclipse، مكتوب بلغة C، ويأتي معه الكلاينتان `mosquitto_pub` و`mosquitto_sub` ومكتبة `libmosquitto`، ويقول ملف [الرخصة](https://github.com/eclipse-mosquitto/mosquitto/blob/master/LICENSE.txt?ref=arabroot.io) في مستودعه إنه مرخص برخصة مزدوجة EPL-2.0 أو EDL-1.0، والأخيرة هي نفسها BSD-3-Clause، أي أنك تستطيع أن تستخدمه في منتج تجاري دون أن تنشر كودك. والسبب في شهرته أنه صغير جداً، فالـ Docker Image الرسمي `eclipse-mosquitto:2.1.2-alpine` حجمه قرابة 13 ميجابايت، ويعمل على Raspberry Pi وعلى سيرفر كبير بالإعداد نفسه، ويكفي لمئات أو آلاف الأجهزة في شركة صغيرة أو متوسطة. وهناك وسطاء آخرون مفتوحو المصدر مثل [EMQX](https://github.com/emqx/emqx?ref=arabroot.io) و[VerneMQ](https://github.com/vernemq/vernemq?ref=arabroot.io) و[NanoMQ](https://github.com/nanomq/nanomq?ref=arabroot.io)، وكلها تتكلم MQTT نفسه، فالأجهزة لا تعرف ولا تهتم أي وسيط على الطرف الآخر، وما تتعلمه هنا عن البروتوكول ينتقل معك إلى أي منها.

وفي 29 يناير 2026 صدر الإصدار 2.1.0، ثم 2.1.1 و2.1.2 في فبراير، وفي [سجل التغييرات](https://github.com/eclipse-mosquitto/mosquitto/blob/v2.1.2/ChangeLog.txt?ref=arabroot.io) عدة أشياء تهمك إذا كنت تنقل إعداداً قديماً:

- الخياران `password_file` و`acl_file` أصبحا قديمين Deprecated لصالح إضافتين Plugins بالكود نفسه، وسوف يحذفان في الإصدار 3.0، وكذلك `per_listener_settings` لصالح خيارات خاصة بكل منفذ مثل `listener_allow_anonymous`، وهذا ما سوف نستخدمه في قسم الأمان.
- الحد الافتراضي لحجم الرسالة `max_packet_size` أصبح 2,000,000 بايت بعد أن كان حد البروتوكول 256 ميجابايت، فإذا كانت أجهزتك ترسل ملفات أو صوراً فعليك أن ترفعه بنفسك.
- أضيف الخيار `--test-config` الذي يفحص ملف الإعداد قبل التشغيل، وأصبح الوسيط يكتب في السجل إصدار البروتوكول والتشفير الذي اتفق عليه كل كلاينت، وأضيف إرسال DISCONNECT بالسبب «session taken over» لكلاينت MQTT 5 الذي يدخل غيره باسمه، وسوف نرى الثلاثة في المختبر.

## المختبر Lab: الوسيط وأدوات الكلاينت

سوف نبدأ بوسيط دون أي حماية حتى نرى البروتوكول نفسه، ثم نغلقه في آخر المقال. وكل شيء يعمل على شبكة Docker خاصة اسمها `iot-mq-net`، دون أي منفذ منشور على جهازك، والكلاينت نفسه Container مؤقت من الـ Image نفسه. والإعداد الأول `mosquitto-open.conf`:

```ini
# Step 1: the broker with no security, to see the protocol itself. Reachable only inside iot-mq-net.
listener 1883
allow_anonymous true
persistence true
persistence_location /mosquitto/data/
log_dest stdout
log_type all
connection_messages true
```

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

```bash
docker network create iot-mq-net
docker run -d --name iot-mq --network iot-mq-net \
  -v "$PWD/mosquitto-open.conf:/mosquitto/config/mosquitto.conf:ro" \
  -v iot-mq-data:/mosquitto/data eclipse-mosquitto:2.1.2-alpine
docker run --rm eclipse-mosquitto:2.1.2-alpine mosquitto --test-config -c /mosquitto/config/mosquitto.conf

# a shortcut for the client commands in the rest of the article
cli() { docker run --rm --network iot-mq-net eclipse-mosquitto:2.1.2-alpine "$@"; }
```

والمخرج:

```text
1793923471: Configuration file is OK.
1793923471: mosquitto version 2.1.2 terminating
```

ولاحظ أن الفحص بدأ الوسيط وأنهاه مباشرة دون أن يفتح أي منفذ، فهو آمن على سيرفر يعمل فيه وسيط آخر. والدالة `cli` اختصار فقط، حتى يكون كل أمر في المقال Container كلاينت مستقلاً على الشبكة نفسها، كما يكون الجهاز الحقيقي على الشبكة.

## الاتصال CONNECT: اسم الكلاينت والجلسة ومدة keepalive

كل شيء في MQTT يبدأ برسالة CONNECT يرسلها الكلاينت بعد أن يفتح اتصال TCP، وفيها أهم القرارات التي تحدد سلوكه كله: اسم الكلاينت Client ID الذي يعرفه به الوسيط، وعلامة الجلسة النظيفة Clean Session التي تقول هل ينسى الوسيط كل شيء عنه عند انقطاعه، ومدة keepalive التي يعد بأن يرسل خلالها شيئاً ولو إشارة حياة، والوصية Last Will إن وجدت، واسم المستخدم وكلمة المرور. ويرد الوسيط بـ CONNACK فيه رمز النتيجة. والوسيط يكتب هذه القرارات في سجله مع كل اتصال، كما في هذا السطر من المختبر:

```text
1793924024: New client connected from 172.18.0.3:44438 as auto-2C8D383F-C056-E392-9854-392830458DB9 (p5, c1, k60, u'room1-temp').
```

والقوسان فيهما أربع معلومات: `p5` إصدار البروتوكول، وهنا 5 أي MQTT 5.0، و4 تعني 3.1.1 بحسب رقم الإصدار داخل البروتوكول نفسه، و`c1` جلسة نظيفة و`c0` جلسة دائمة، و`k60` مدة keepalive بالثواني وهي القيمة الافتراضية في أدوات Mosquitto، و`u'room1-temp'` اسم المستخدم. ولاحظ اسم الكلاينت نفسه: لم نعطه اسماً، فأعطاه الوسيط اسماً عشوائياً يبدأ بـ `auto-`، وهذا مقبول لأداة تجرب أمراً واحداً، ولكنه خطأ في جهاز حقيقي أو خدمة، لأن الاسم هو الذي يربط الكلاينت بجلسته، والاسم العشوائي يعني جلسة جديدة مع كل اتصال.

أما keepalive فتحدد متى يعرف الوسيط أن الكلاينت اختفى، وتقول [مواصفة MQTT 5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html?ref=arabroot.io) إن الوسيط يجب أن يغلق الاتصال إذا لم يصله أي شيء من الكلاينت خلال مرة ونصف مدة keepalive. وهذا يعني أن جهازاً بـ keepalive قيمتها 60 ثانية قد يبقى «متصلاً» في نظر الوسيط دقيقة ونصفاً بعد أن انقطعت عنه الكهرباء، والقيمة القصيرة تكشف الانقطاع بسرعة ولكنها تكلف إشارات حياة أكثر، وهذا قرار يعتمد على البطارية والشبكة، وسوف نرى أثره بالثواني في تجربة الوصية.

## المواضيع Topics مع المرشحات Wildcards

اسم الموضوع نص مقسم بالشرطة المائلة `/` إلى مستويات، والوسيط لا يحتاج أن تنشئه مسبقاً، فأول رسالة عليه تكفي. والمشترك يكتب مرشحاً Topic Filter قد يحتوي رمزين: `+` بدل مستوى واحد، و`#` بدل هذا المستوى وكل ما بعده، ولا يأتي إلا في آخر المرشح. والصورة التالية تبين ثلاثة مشتركين بمرشحات مختلفة وما يصل لكل منهم:

![على اليمين ثلاثة ناشرين room1-temp وroom2-temp وgw-store1 كل منهم ينشر على موضوعه، وفي الوسط الوسيط Mosquitto يطابق الموضوع مع كل مرشح، وعلى اليسار ثلاثة مشتركين: ingest-1 بالمرشح coldstore/# يصله كل شيء، وdashboard بالمرشح coldstore/store1/+/telemetry تصله القراءات دون الحالة، وdoor-siren بالمرشح coldstore/+/room1-door/# يصله الباب فقط، وفي الأسفل أن المرشح coldstore/#/telemetry مرفوض](https://arabroot.io/content/images/2026/11/mqtt-mosquitto-01-pubsub.webp)

الناشر لا يعرف المشتركين، والوسيط يطابق كل رسالة مع كل مرشح

والوسيط يرفض المرشح غير الصحيح من البداية، كما حدث عندما جربنا وضع `#` في وسط المرشح:

```text
-- coldstore/#/telemetry
Error: Invalid subscription topic 'coldstore/#/telemetry', are all '+' and '#' wildcards correct?
```

وهناك فرع خاص من المواضيع يبدأ بـ `$SYS`، ينشر فيه Mosquitto معلومات عن نفسه كل فترة، مثل عدد الكلاينتات المتصلة وعدد الرسائل المحفوظة وإصداره، ولا يصل إلى المرشح `#` العادي حتى لا يختلط بمواضيع التطبيق، وإنما تشترك فيه باسمه:

```bash
cli mosquitto_sub -h iot-mq -v -t '$SYS/broker/retained messages/count' \
  -t '$SYS/broker/clients/connected' -t '$SYS/broker/version' -C 3
```

```text
$SYS/broker/retained messages/count 57
$SYS/broker/clients/connected 1
$SYS/broker/version mosquitto version 2.1.2
```

والرقم 57 للرسائل المحفوظة قد يبدو كبيراً ونحن لم نحفظ إلا ثلاثاً، والسبب أن مواضيع `$SYS` نفسها محفوظة، فكل مشترك جديد يجد آخر قيمة لها فوراً. وهذه المواضيع هي أسهل طريقة لمراقبة الوسيط من Prometheus أو أي أداة أخرى، وقد شرحنا المراقبة بالمقاييس في [مقال Prometheus مع Grafana](https://arabroot.io/articles/%D9%85%D9%82%D8%A7%D9%8A%D9%8A%D8%B3-%D8%A7%D9%84%D8%B3%D9%8A%D8%B1%D9%81%D8%B1%D8%A7%D8%AA-metrics-prometheus-%D9%85%D8%B9-%D9%84%D9%88%D8%AD%D8%A7%D8%AA-grafana/).

## مستويات التسليم QoS: ثلاثة وعود مختلفة

مستوى التسليم Quality of Service، واختصاراً QoS، هو الوعد الذي يتفق عليه طرفان حول رسالة واحدة: هل يكفي أن ترسلها، أم يجب أن يتأكد المرسل أنها وصلت، أم يجب أن تصل مرة واحدة بالضبط؟ ولكل مستوى رسائل إضافية يتبادلها الطرفان، والأفضل أن تراها بعينك. لذلك شغلنا مشتركاً بمستوى 2 مع الخيار `-d` الذي يطبع كل رسالة بروتوكول، ثم نشرنا القراءة نفسها ثلاث مرات بالمستويات الثلاثة:

```bash
docker run -d --name iot-mq-sub --network iot-mq-net eclipse-mosquitto:2.1.2-alpine \
  mosquitto_sub -h iot-mq -d -v -q 2 -i sub-dashboard -t 'coldstore/#'
for q in 0 1 2; do
  cli mosquitto_pub -h iot-mq -d -i room1-temp -q $q -t coldstore/store1/room1-temp/telemetry -m "{\"seq\":$((10+q)),\"temp_c\":4.1}"
done
```

والمخرج من جهة الناشر:

```text
== QoS 0
Client room1-temp sending CONNECT
Client room1-temp received CONNACK (0)
Client room1-temp sending PUBLISH (d0, q0, r0, m1, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
Client room1-temp sending DISCONNECT
== QoS 1
Client room1-temp sending CONNECT
Client room1-temp received CONNACK (0)
Client room1-temp sending PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
Client room1-temp received PUBACK (Mid: 1, RC:0)
Client room1-temp sending DISCONNECT
== QoS 2
Client room1-temp sending CONNECT
Client room1-temp received CONNACK (0)
Client room1-temp sending PUBLISH (d0, q2, r0, m1, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
Client room1-temp received PUBREC (Mid: 1)
Client room1-temp sending PUBREL (m1)
Client room1-temp received PUBCOMP (Mid: 1, RC:0)
Client room1-temp sending DISCONNECT
```

ومن جهة المشترك:

```text
Client sub-dashboard sending SUBSCRIBE (Mid: 1, Topic: coldstore/#, QoS: 2, Options: 0x00)
Client sub-dashboard received SUBACK
Subscribed (mid: 1): 2
Client sub-dashboard received PUBLISH (d0, q0, r0, m0, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
coldstore/store1/room1-temp/telemetry {"seq":10,"temp_c":4.1}
Client sub-dashboard received PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
Client sub-dashboard sending PUBACK (m1, rc0)
coldstore/store1/room1-temp/telemetry {"seq":11,"temp_c":4.1}
Client sub-dashboard received PUBLISH (d0, q2, r0, m2, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
Client sub-dashboard sending PUBREC (m2, rc0)
Client sub-dashboard received PUBREL (Mid: 2)
Client sub-dashboard sending PUBCOMP (m2)
coldstore/store1/room1-temp/telemetry {"seq":12,"temp_c":4.1}
```

وفي المخرج أعلاه لاحظ التالي:

- الأقواس بعد PUBLISH فيها أعلام الرسالة: `d0` أنها ليست إعادة إرسال Duplicate، و`q` مستواها، و`r0` أنها ليست محفوظة، و`m` رقم الرسالة Message ID الذي تربط به الردود، ثم الموضوع وحجم المحتوى.
- في QoS 0 لا يوجد أي رد، والناشر يرسل ثم ينسى، وإذا ضاعت الرسالة في الشبكة فلا أحد يعرف. ولاحظ أن رقم الرسالة عند المشترك `m0`، لأن المستوى 0 لا يحتاج رقماً.
- في QoS 1 يرد المستقبل بـ PUBACK، والمرسل يحتفظ بالرسالة ويعيد إرسالها بعلامة `d1` حتى يصله الرد، فالرسالة تصل مرة على الأقل، وقد تصل مرتين إذا ضاع الرد نفسه.
- في QoS 2 أربع رسائل بدل واحدة: PUBLISH ثم PUBREC «استلمت» ثم PUBREL «احذفها من عندك» ثم PUBCOMP «انتهينا»، وهذه المصافحة هي التي تضمن أن الرسالة تسلم للتطبيق مرة واحدة بالضبط.
- والأهم أن الوعد بين طرفين فقط: من الناشر إلى الوسيط، ثم من الوسيط إلى كل مشترك على حدة، ولكل منهما رقم رسالة مختلف، فالقراءة 12 كانت `m1` عند الناشر و`m2` عند المشترك.

والصورة التالية تلخص المستويات الثلاثة:

![ثلاثة أعمدة: QoS 0 مرة واحدة على الأكثر برسالة PUBLISH q0 فقط ولا رد ولا إعادة، وQoS 1 مرة واحدة على الأقل برسالة PUBLISH q1 m1 ثم PUBACK Mid 1 وقد تصل مرتين، وQoS 2 مرة واحدة بالضبط بأربع رسائل PUBLISH ثم PUBREC ثم PUBREL ثم PUBCOMP، وتحتها ملاحظة أن رسالة QoS 2 وصلت لمشترك QoS 0 على أنها q0](https://arabroot.io/content/images/2026/11/mqtt-mosquitto-02-qos.webp)

المستويات الثلاثة برسائلها كما طبعها mosquitto\_pub -d في المختبر

ولنرى النقطة الأخيرة بوضوح، اشترك كلاينت آخر بمستوى 0، ثم نشرنا رسالة بمستوى 2:

```text
Subscribed (mid: 1): 0
Client sub-q0 received PUBLISH (d0, q0, r0, m0, 'coldstore/store1/room1-temp/telemetry', ... (23 bytes))
coldstore/store1/room1-temp/telemetry {"seq":13,"temp_c":4.0}
```

فالرسالة نشرت بـ QoS 2، ووصلت إلى هذا المشترك بـ `q0`، لأن الوسيط يسلم لكل مشترك بالأقل بين مستوى النشر ومستوى الاشتراك. وهذا يعني أن جهازاً ينشر أمراً مهماً بـ QoS 2 لا يضمن شيئاً إذا كان البرنامج الذي يستقبله اشترك بـ QoS 0، وأن المستوى قرار على الطرفين وليس على الناشر وحده.

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

## الرسالة المحفوظة Retained: آخر قيمة لكل مشترك جديد

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

```bash
cli mosquitto_pub -h iot-mq -r -q 1 -t coldstore/store1/room1-temp/status -m online
cli mosquitto_pub -h iot-mq -r -q 1 -t coldstore/store1/room1-temp/config -m '{"period_s":30,"max_c":8}'
cli mosquitto_sub -h iot-mq -d -v -t 'coldstore/store1/room1-temp/#' -W 2
```

```text
Client (null) received CONNACK (0)
Subscribed (mid: 1): 0
Client null received PUBLISH (d0, q0, r1, m0, 'coldstore/store1/room1-temp/status', ... (6 bytes))
coldstore/store1/room1-temp/status online
Client null received PUBLISH (d0, q0, r1, m0, 'coldstore/store1/room1-temp/config', ... (25 bytes))
coldstore/store1/room1-temp/config {"period_s":30,"max_c":8}
Timed out
```

ولاحظ العلامة `r1` على الرسالتين، فهي تقول للمشترك إن هذه رسالة محفوظة من الماضي وليست حدثاً جديداً، والتطبيق الجيد يفرق بين الاثنين، فلا يطلق تنبيهاً على حالة قديمة كأنها حدثت الآن. و`-W 2` يجعل الأداة تخرج بعد ثانيتين، ولهذا ظهرت `Timed out`. ولحذف رسالة محفوظة تنشر رسالة محفوظة فارغة على الموضوع نفسه بالخيار `-n`:

```bash
cli mosquitto_pub -h iot-mq -r -n -t coldstore/store1/room1-temp/config
cli mosquitto_sub -h iot-mq -v -t 'coldstore/store1/room1-temp/#' -W 2
```

```text
coldstore/store1/room1-temp/status online
Timed out
```

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

## الوصية Last Will: كيف يعرف الوسيط أن الجهاز اختفى؟

الوصية Last Will رسالة يسلمها الكلاينت للوسيط في رسالة CONNECT نفسها، ويقول له: إذا اختفيت دون أن أودعك، فانشر هذه الرسالة نيابة عني. والاستخدام الأشهر أن يكون موضوع الوصية هو موضوع الحالة، بالمحتوى `offline` وعلامة الحفظ، والجهاز نفسه ينشر `online` محفوظة فور اتصاله، وبهذا الشكل يجد أي مشترك في أي وقت حالة كل جهاز دون أن يسأله. ولكن السؤال المهم هو متى بالضبط يعتبر الوسيط أن الجهاز اختفى؟ وهناك ثلاث طرق لاختفاء الجهاز، وجربناها كلها.

الطريقة الأولى هي انقطاع الكهرباء أو الشبكة، حيث يتوقف الجهاز فجأة دون أن يرسل شيئاً، ولا يصل إلى الوسيط حتى إغلاق TCP. وأقرب محاكاة لذلك أن نجمد Container الجهاز بالأمر `docker pause`، فيبقى الاتصال مفتوحاً في نظر الوسيط ولكن لا يصل منه أي شيء. شغلنا الجهاز بـ keepalive قيمتها 10 ثوان ووصية، ومراقباً يطبع الوقت مع كل رسالة حالة:

```bash
docker run -d --name iot-mq-watch --network iot-mq-net eclipse-mosquitto:2.1.2-alpine \
  mosquitto_sub -h iot-mq -F '%I %t %p' -t 'coldstore/+/+/status'
docker run -d --name iot-mq-dev --network iot-mq-net eclipse-mosquitto:2.1.2-alpine \
  mosquitto_sub -h iot-mq -i room2-temp -k 10 --will-topic coldstore/store1/room2-temp/status \
  --will-payload offline --will-qos 1 --will-retain -t coldstore/store1/room2-temp/cmd
cli mosquitto_pub -h iot-mq -r -q 1 -t coldstore/store1/room2-temp/status -m online
docker pause iot-mq-dev
```

والمخرج من المراقب ومن سجل الوسيط:

```text
2026-11-06T00:06:45+0000 coldstore/store1/room2-temp/status online
2026-11-06T00:06:57+0000 coldstore/store1/room2-temp/status offline

1793923617: Client room2-temp [172.18.0.5:55120] disconnected: exceeded timeout.
```

جمدنا الجهاز في 00:06:47، ووصلت الوصية في 00:06:57، أي بعد 10 ثوان من الانقطاع، وسبب الانقطاع في سجل الوسيط `exceeded timeout`، أي أن المدة مرت دون أي رسالة. والمدة الفعلية تحسب من آخر رسالة وصلت من الجهاز وليس من لحظة الانقطاع، ولهذا قد تكون أقل من 15 ثانية التي تعطيها قاعدة المرة ونصف المرة لـ keepalive قيمتها 10\. وبالقيمة الافتراضية 60 ثانية كان الانتظار سيصل إلى دقيقة ونصف.

والطريقتان الأخريان هما توقف البرنامج نفسه، وجربناهما بإرسال إشارتين مختلفتين للبرنامج:

```text
INT at 00:07:20
KILL at 00:07:28
2026-11-06T00:07:28+0000 coldstore/store1/room3-temp/status offline-KILL

1793923641: Client room3-temp [172.18.0.5:49738] disconnected.
1793923648: Client room3-temp [172.18.0.5:41202] disconnected: connection closed by client.
```

مع الإشارة SIGINT، وهي ما يحدث عندما تضغط Ctrl+C، أغلق البرنامج الاتصال بشكل طبيعي وأرسل رسالة DISCONNECT، فكتب الوسيط `disconnected.` فقط ولم يرسل أي وصية، لأن الكلاينت ودع فعلاً. ومع SIGKILL مات البرنامج فوراً وأغلق نظام التشغيل الاتصال دون DISCONNECT، فكتب الوسيط `connection closed by client` وأرسل الوصية `offline-KILL` في الثانية نفسها. والصورة التالية تجمع التجارب:

![في الأعلى الرسالة المحفوظة: الجهاز ينشر online بعلامة r=1 مرة واحدة إلى الوسيط، والوسيط يحتفظ بها على موضوع status، وبعد ساعة يشترك أحدهم فتصله فوراً بعلامة r1، وفي الأسفل خط زمني للوصية: 00:06:45 online محفوظة، ثم 00:06:47 انقطاع الجهاز بالأمر docker pause، ثم فترة لا يصل فيها شيء، ثم 00:06:57 exceeded timeout والوسيط ينشر offline، وتحتها بطاقتان: إيقاف البرنامج بـ SIGKILL يرسل الوصية فوراً، وإيقافه بـ SIGINT يرسل DISCONNECT فلا وصية](https://arabroot.io/content/images/2026/11/mqtt-mosquitto-03-retained-will.webp)

الحالة المحفوظة مع الوصية كما حدثت في المختبر

والدرس العملي من هذا: إذا أردت أن يعرف النظام بإعادة التشغيل المقصودة أيضاً، فاجعل الجهاز ينشر `offline` محفوظة بنفسه قبل أن يغلق الاتصال، لأن الإغلاق الطبيعي لا يطلق الوصية. وفي MQTT 5 هناك أيضاً تأخير الوصية Will Delay Interval، الذي يجعل الوسيط ينتظر قليلاً قبل نشرها، فإذا عاد الجهاز خلال المدة لا تنشر، وهذا مفيد للأجهزة على شبكة جوال تنقطع ثوان وتعود.

## الجلسة الدائمة Persistent Session: رسائل المشترك الغائب

في المقال السابق رأينا أن الرسائل التي نشرت وخدمة الاستقبال غائبة ضاعت كلها، لأن جلستها كانت نظيفة. والحل هو الجلسة الدائمة: يتصل الكلاينت باسم ثابت وعلامة Clean Session مطفأة، فيحتفظ الوسيط باشتراكاته بعد انقطاعه، ويجمع له في طابور كل رسالة QoS 1 أو 2 تطابق اشتراكاته. وفي أدوات Mosquitto الخيار `-c` هو الذي يطفئ الجلسة النظيفة. أنشأنا الجلسة ثم خرجنا، ونشرنا ثلاث قراءات بـ QoS 1 وقراءتين بـ QoS 0، ثم عدنا بالاسم نفسه:

```bash
cli mosquitto_sub -h iot-mq -c -i ingest-1 -q 1 -t 'coldstore/+/+/telemetry' -W 1
for i in 1 2 3; do cli mosquitto_pub -h iot-mq -q 1 -t coldstore/store1/room1-temp/telemetry -m "{\"seq\":$((100+i)),\"q\":1}"; done
for i in 4 5; do cli mosquitto_pub -h iot-mq -q 0 -t coldstore/store1/room1-temp/telemetry -m "{\"seq\":$((100+i)),\"q\":0}"; done
cli mosquitto_sub -h iot-mq -c -i ingest-1 -q 1 -t 'coldstore/+/+/telemetry' -W 2 -v -d
```

```text
Client ingest-1 received CONNACK (0)
Client ingest-1 received PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room1-temp/telemetry', ... (17 bytes))
coldstore/store1/room1-temp/telemetry {"seq":101,"q":1}
Client ingest-1 received PUBLISH (d0, q1, r0, m2, 'coldstore/store1/room1-temp/telemetry', ... (17 bytes))
coldstore/store1/room1-temp/telemetry {"seq":102,"q":1}
Client ingest-1 received PUBLISH (d0, q1, r0, m3, 'coldstore/store1/room1-temp/telemetry', ... (17 bytes))
coldstore/store1/room1-temp/telemetry {"seq":103,"q":1}
Subscribed (mid: 1): 1
Timed out
```

وفي المخرج لاحظ التالي:

- وصلت القراءات 101 و102 و103 قبل أن يصل رد الاشتراك `Subscribed`، لأن الوسيط كان يعرف الاشتراك من الجلسة القديمة، فأرسل الطابور فور الاتصال.
- القراءتان 104 و105 بـ QoS 0 لم تصلا، وهذا ما يقوله البروتوكول نفسه، وفي Mosquitto خيار غير معياري `queue_qos0_messages` يغير ذلك، وقيمته الافتراضية false بحسب [صفحة الإعداد](https://mosquitto.org/man/mosquitto-conf-5.html?ref=arabroot.io).
- الطابور له حد، فالخيار `max_queued_messages` قيمته الافتراضية 1000 رسالة لكل كلاينت، وما زاد يرمى. فإذا كان لديك 50 جهازاً ترسل كل ثانيتين، فهذا الحد يمتلئ في 40 ثانية فقط من غياب خدمة الاستقبال، وعليك أن تحسبه وترفعه أو تجعله بالحجم `max_queued_bytes`.
- والجلسة الدائمة لكلاينت لا يعود أبداً تبقى في ذاكرة الوسيط إلى الأبد، ولذلك هناك الخيار `persistent_client_expiration` الذي يحذف الجلسات الغائبة بعد مدة تحددها مثل `14d`.

## ماذا يحدث إذا أعيد تشغيل الوسيط Broker Restart؟

الجلسة الدائمة تحمي من غياب المشترك، ولكن ماذا لو كان الوسيط نفسه هو الذي أعيد تشغيله لتحديث أو عطل؟ هنا يأتي دور الخيار `persistence`. ففي الإعداد الأول كان مفعلاً، فنشرنا ثلاث قراءات أخرى بـ QoS 1 والخدمة غائبة، ثم أعدنا تشغيل الوسيط:

```text
1793923694: Saving in-memory database to /mosquitto/data//mosquitto.db.
1793923696: Restored 6 base messages
1793923696: Restored 3 retained messages
1793923696: Restored 1 clients
1793923696: Restored 1 subscriptions
1793923696: Restored 3 client messages
coldstore/store1/room1-temp/telemetry {"seq":201}
coldstore/store1/room1-temp/telemetry {"seq":202}
coldstore/store1/room1-temp/telemetry {"seq":203}
```

عند التوقف حفظ الوسيط كل ما في ذاكرته في الملف `mosquitto.db` داخل الـ Volume، وعند العودة استعاد جلسة واحدة دائمة هي `ingest-1` مع اشتراكها والرسائل الثلاث في طابورها، فوصلت كلها عند عودة الخدمة. ولاحظ «Restored 3 retained messages»: حالات الأجهزة المحفوظة عادت أيضاً.

ثم كررنا الشيء نفسه بالإعداد ذاته مع تغيير سطر واحد إلى `persistence false`:

```text
1793923727: mosquitto version 2.1.2 starting
== ingest-1 after restart
Timed out
== retained after restart
Timed out
```

لا توجد أي أسطر Restored، والخدمة عادت فلم تجد شيئاً، والقراءات الثلاث ضاعت، والحالة المحفوظة `online` ضاعت أيضاً، فأي لوحة جديدة لن تعرف حالة أي جهاز حتى يعيد نشرها. والصورة التالية تلخص الجلسة الدائمة والتجربتين:

![في الأعلى الجهاز يرسل أثناء غياب ingest-1 ثلاث قراءات seq 101 و102 و103 بـ q1 وقراءتين بـ q0، والوسيط يحفظ في طابور ingest-1 الثلاث فقط، ثم يعود ingest-1 بالاسم نفسه والخيار -c فتصله قبل SUBACK، وفي الأسفل بطاقتان: إعادة تشغيل الوسيط مع persistence true وسطور Restored 1 clients وRestored 3 client messages ونتيجة 3 / 3، ومع persistence false دون أي Restored ونتيجة 0 / 3 وضياع الحالة المحفوظة](https://arabroot.io/content/images/2026/11/mqtt-mosquitto-04-session.webp)

الجلسة الدائمة تحمي من غياب المشترك، والحفظ على القرص يحميها من إعادة تشغيل الوسيط

ولاحظ هنا أمرين: الأول أن الحفظ يحدث عند التوقف الطبيعي وكل فترة يحددها `autosave_interval`، وقيمتها الافتراضية 1800 ثانية بحسب صفحة الإعداد، فإذا انقطعت الكهرباء عن السيرفر فجأة فقد تضيع الرسائل التي وصلت بعد آخر حفظ، وفي Mosquitto 2.1 إضافة `persist-sqlite` بديلة تكتب باستمرار في قاعدة SQLite لمن يحتاج ذلك. والثاني أن الحفظ يحتاج Volume دائماً، فـ Container الوسيط دون Volume على `/mosquitto/data` يفقد كل شيء عند إعادة إنشائه حتى مع `persistence true`.

## ميزات MQTT 5: الاشتراك المشترك Shared Subscription، وانتهاء الصلاحية Message Expiry

الإصدار 5.0 من البروتوكول أضاف ميزات كثيرة، وثلاث منها تهمك مباشرة في إنترنت الأشياء. الأولى الاشتراك المشترك Shared Subscription: عندما تكبر الأجهزة لا تكفي نسخة واحدة من خدمة الاستقبال، ولو شغلت نسختين باشتراك عادي لوصلت كل رسالة للاثنتين وحفظت مرتين. والحل أن تشترك النسختان في مجموعة باسم يبدأ بـ `$share/`، فيوزع الوسيط الرسائل بينهما ويرسل كل رسالة لواحدة فقط:

```bash
for w in a b; do
  docker run -d --name iot-mq-w$w --network iot-mq-net eclipse-mosquitto:2.1.2-alpine \
    mosquitto_sub -h iot-mq -V mqttv5 -i ingest-$w -q 1 -t '$share/ingest/coldstore/+/+/telemetry' -F "ingest-$w got %p"
done
for i in 1 2 3 4 5 6; do cli mosquitto_pub -h iot-mq -V mqttv5 -q 1 -t coldstore/store1/room1-temp/telemetry -m "{\"seq\":$((400+i))}"; done
```

```text
ingest-a got {"seq":401}
ingest-a got {"seq":403}
ingest-a got {"seq":405}
ingest-b got {"seq":402}
ingest-b got {"seq":404}
ingest-b got {"seq":406}
```

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

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

```bash
cli mosquitto_pub -h iot-mq -V mqttv5 -r -q 1 -t coldstore/store1/room1-temp/alarm -m 'door open' \
  -D publish message-expiry-interval 5
cli mosquitto_sub -h iot-mq -V mqttv5 -t coldstore/store1/room1-temp/alarm -W 1 -F '%t %p (expiry left: %E s)'
sleep 6
cli mosquitto_sub -h iot-mq -V mqttv5 -t coldstore/store1/room1-temp/alarm -v -W 1
```

```text
coldstore/store1/room1-temp/alarm door open (expiry left: 4 s)
Timed out
Timed out
```

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

والثالثة رموز السبب Reason Codes: في MQTT 3.1.1 كانت الردود تقول نجح أو فشل فقط، وفي أحيان كثيرة لا تقول شيئاً، أما في الإصدار 5 فكل رد فيه رمز يقول لماذا، وتعرضها [المواصفة](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html?ref=arabroot.io) في جدول واحد، مثل 16 «لا يوجد مشتركون» و135 «غير مصرح» و142 «أخذت الجلسة». وسوف نرى الثلاثة في المختبر، وسوف نرى لماذا هذا الفرق مهم جداً في قسم الصلاحيات.

## ماذا يفعل الجهاز عند العودة؟ عاصفة إعادة الاتصال Reconnect Storm

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

والحل على جهة الجهاز في ثلاث نقاط. الأولى الانتظار المتزايد Exponential Backoff مع حد أعلى معقول، كما رأينا في المقال السابق حيث كان الحد الافتراضي 120 ثانية في مكتبة paho طويلاً جداً. والثانية العشوائية Jitter: أن يضيف كل جهاز إلى مدة الانتظار جزءاً عشوائياً من الثانية أو الثانيتين، فتتوزع العودة على فترة بدل أن تأتي في لحظة واحدة، وهذه إضافة صغيرة في الكود ولكنها تغير شكل الضغط على الوسيط تماماً. والثالثة ألا يرسل الجهاز طابوره كله دفعة واحدة، وإنما على دفعات صغيرة، وهنا يساعد البروتوكول نفسه: في MQTT 5 يعلن كل طرف في CONNECT حداً اسمه Receive Maximum، وهو أكبر عدد من رسائل QoS 1 و2 التي تقبل أن تكون في الطريق دون تأكيد، وتقول ملاحظات الإصدار 2.1.1 في سجل التغييرات إن Mosquitto أصبح يكتب تحذيراً بدل أن يقطع الكلاينت الذي يتجاوز هذا الحد، حتى تتمكن من إصلاح الكلاينت المخالف بدل أن يختفي.

وعلى جهة الوسيط تستطيع أن تحمي نفسك بحدود واضحة: `max_connections` لكل منفذ، والخيار الجديد في 2.1 `global_max_connections` للوسيط كله، و`max_inflight_messages` لعدد الرسائل في الطريق لكل كلاينت. وقد يتساءل البعض: أليس الأفضل ألا يرفض الوسيط أي اتصال؟ والإجابة أن الوسيط الذي يقبل كل شيء حتى تنفد ذاكرته يتوقف عن خدمة الجميع، أما الوسيط الذي يرفض بعض الاتصالات مؤقتاً فيبقى يعمل، والأجهزة المرفوضة تعود بعد ثوان بفضل الانتظار المتزايد، وهذا بالضبط سبب وجود الانتظار في الجهاز.

## اسم الكلاينت Client ID: جهازان باسم واحد

نعود إلى الموظف الذي نسخ برنامج الجهاز الأول إلى الجهاز الثاني كما هو، فأصبح للجهازين الاسم نفسه `room1-temp`. والمواصفة تقول إن الوسيط إذا اتصل به كلاينت باسم موجود فعليه أن يقطع الاتصال القديم، وهذا منطقي لجهاز أعيد تشغيله قبل أن يعرف الوسيط أن اتصاله القديم مات. ولكن عندما يكون هناك جهازان فعلاً، وكل منهما يعيد الاتصال آلياً عند الانقطاع، فماذا يحدث؟ شغلنا كلاينتين بالاسم نفسه بفارق ثلاث ثوان:

```text
== A
Client room1-temp sending SUBSCRIBE (Mid: 4, Topic: coldstore/store1/room1-temp/cmd, QoS: 0, Options: 0x00)
Client room1-temp received SUBACK
Subscribed (mid: 4): 0
Received DISCONNECT (142)

1793924085: Client room1-temp [172.18.0.4:57246] disconnected: session taken over.
1793924085: New client connected from 172.18.0.3:42330 as room1-temp (p5, c1, k60, u'room1-temp').
1793924086: Client room1-temp [172.18.0.3:42330] disconnected: session taken over.
1793924086: New client connected from 172.18.0.4:57250 as room1-temp (p5, c1, k60, u'room1-temp').
```

الكلاينت A استقبل DISCONNECT برمز السبب 142، وهو «session taken over»، ثم أعاد الاتصال فطرد B، ثم أعاد B الاتصال فطرد A، وعددنا في سجل الوسيط 9 مرات من هذا الطرد المتبادل خلال قرابة 8 ثوان، وكل رسالة في الطريق أثناء ذلك معرضة للضياع، واللوحة ترى الجهاز يختفي ويظهر. وهذه بالضبط مشكلة الجهازين اللذين «يختفيان ويظهران كل ثانية» في قصتنا، وحلها أن يكون اسم الكلاينت فريداً لكل جهاز، ويأتي من شيء لا يتكرر مثل عنوان MAC أو رقم تسلسلي يكتب عند التصنيع، وليس من ملف إعداد ينسخ بين الأجهزة.

![على اليمين جهازان A وB بالاسم room1-temp يتصلان بالوسيط ويطرد كل منهما الآخر بالرسالة DISCONNECT (142) session taken over، وتحتهما 9 مرات في 8 ثوان، وعلى اليسار اشتراك مشترك Shared Subscription بالمرشح $share/ingest/coldstore/+/+/telemetry يوزع فيه الوسيط القراءات بين ingest-a الذي وصله 401 و403 و405 وingest-b الذي وصله 402 و404 و406](https://arabroot.io/content/images/2026/11/mqtt-mosquitto-06-clientid.webp)

اسم واحد لجهازين يعني طرداً متبادلاً، أما توزيع الرسائل بين خدمتين فمكانه الاشتراك المشترك بأسماء مختلفة

## الأمان Security: TLS ثم كلمات المرور ثم الصلاحيات

كل ما سبق كان على وسيط يقبل أي أحد، ويقرأ أي أحد فيه أي شيء، ويكتب أي أحد على أي موضوع، بما في ذلك موضوع الأوامر. والآن نغلقه بثلاث طبقات، كل واحدة تجيب على سؤال مختلف: TLS يجيب «هل يقرأ أحد الرسائل في الطريق، وهل هذا هو الوسيط الحقيقي؟»، وكلمة المرور تجيب «من أنت؟»، والصلاحيات ACL تجيب «ماذا يحق لك؟». وسوف نهاجم هذا الوسيط نفسه في [مقال أمن إنترنت الأشياء](https://arabroot.io/articles/%D8%A7%D9%85%D9%86-%D8%A7%D9%86%D8%AA%D8%B1%D9%86%D8%AA-%D8%A7%D9%84%D8%A7%D8%B4%D9%8A%D8%A7%D8%A1-iot-%D8%A7%D9%84%D8%A7%D8%AC%D9%87%D8%B2%D8%A9-%D8%A7%D9%84%D8%AA%D9%8A-%D9%8A%D9%86%D8%B3%D8%A7%D9%87%D8%A7-%D8%A7%D9%84%D8%AC%D9%85%D9%8A%D8%B9/) من السلسلة، أما هنا فنبني الإعداد ونفهمه.

### شهادة الوسيط Certificate من سلطة خاصة CA

الأجهزة داخل شركتك لا تحتاج شهادة من سلطة عامة، لأنها لا تتصل باسم نطاق على الإنترنت، والأسهل والأكثر تحكماً أن تنشئ سلطة شهادات خاصة CA وتضع شهادتها في كل جهاز. وقد شرحنا الشهادات وصيغها في [مقال الشهادات الرقمية](https://arabroot.io/articles/%D8%A7%D9%84%D8%B4%D9%87%D8%A7%D8%AF%D8%A7%D8%AA-%D8%A7%D9%84%D8%B1%D9%82%D9%85%D9%8A%D8%A9-tls-%D9%88-x509-%D9%88%D8%B5%D9%8A%D8%BA-pem-%D9%88-der/)، والسكربت التالي ينشئ السلطة ثم شهادة الوسيط:

```bash
#!/bin/sh
# Own CA for the lab, then a server certificate for the broker name iot-mq (CN and SAN must match what clients connect to).
set -e
cd /w/certs
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes -days 3650 \
  -keyout ca.key -out ca.crt -subj "/CN=coldstore lab CA"
openssl req -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes \
  -keyout server.key -out server.csr -subj "/CN=iot-mq"
printf "subjectAltName=DNS:iot-mq,DNS:localhost\nextendedKeyUsage=serverAuth\n" > server.ext
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -days 825 -out server.crt -extfile server.ext
chmod 644 server.key ca.crt server.crt
openssl x509 -in server.crt -noout -subject -issuer -ext subjectAltName -dates
```

```text
subject=CN=iot-mq
issuer=CN=coldstore lab CA
X509v3 Subject Alternative Name:
    DNS:iot-mq, DNS:localhost
notBefore=Nov  6 00:09:55 2026 GMT
notAfter=Feb  8 00:09:55 2029 GMT
```

شغلناه في Container من `python:3.13.18-slim` لأن فيه OpenSSL 3.5.7\. ولاحظ أن الاسم في الحقل `subjectAltName` هو `iot-mq`، وهو الاسم الذي سوف تتصل به الأجهزة، فالكلاينت يقارن الاسم الذي طلبه بالاسم في الشهادة، وإذا اختلفا رفض الاتصال حتى لو كانت الشهادة موقعة من سلطتك. ومفتاح السلطة `ca.key` هو أهم ملف في النظام كله، فمن يملكه يستطيع أن يصنع وسيطاً مزيفاً تثق به كل الأجهزة، ولذلك مكانه خارج السيرفر وخارج المستودع.

### كلمات المرور Passwords، ثم الصلاحيات ACL

لكل جهاز وخدمة اسم وكلمة مرور خاصة، والأداة `mosquitto_passwd` تحفظها كهاش في ملف:

```bash
for u in room1-temp:Room1-Lab-Pass gw-store1:Gw-Lab-Pass ingest-1:Ingest-Lab-Pass dashboard:Dash-Lab-Pass; do
  mosquitto_passwd -b /w/passwd ${u%%:*} ${u#*:}
done
```

```text
room1-temp:$7$1000$F4a1ybSXPasSJ3oQ84LCecVuEErfDa2UfxoS+lgD+ebEidbdmo1RedEFzxXpV...
gw-store1:$7$1000$Rdz/77XjbK2RjfgBinKZNk8iowoCl+mX9wSg/cAcRx1MKjBXpi1Wsl5imNR9Mt...
```

وهنا ملاحظة وجدناها في المختبر: تقول [صفحة الأداة](https://mosquitto.org/man/mosquitto%5Fpasswd-1.html?ref=arabroot.io) ورسالة المساعدة فيها إن الخوارزمية الافتراضية argon2id، ولكن كل سطر في الملف بدأ بـ `$7$1000$`، وهي صيغة sha512-pbkdf2 بألف تكرار، ولما طلبنا argon2id صراحة بالخيار `-H argon2id` ردت الأداة في هذا الـ Image بالخطأ `Error: Unable to hash password.`. أي أن الـ Image المبني على Alpine يعمل بـ PBKDF2، وهي خوارزمية مقبولة، ولكن إذا كانت سياستك تشترط argon2id فتحقق من الملف نفسه ولا تعتمد على ما تقوله صفحة المساعدة.

ثم ملف الصلاحيات `acl`، وفيه تعطي لكل مستخدم ما يحتاجه فقط:

```text
# Anyone authenticated: nothing unless granted below. Read top to bottom, user blocks then patterns.
# Each device writes only its own topics and reads only its own commands (%u = its username).
pattern write coldstore/store1/%u/telemetry
pattern write coldstore/store1/%u/status
pattern read  coldstore/store1/%u/cmd

# The ingest service reads everything of the application, writes nothing.
user ingest-1
topic read coldstore/#

# The dashboard reads, and may send commands to devices.
user dashboard
topic read coldstore/#
topic write coldstore/+/+/cmd
```

وفي الملف أعلاه لاحظ التالي:

- الأسطر `pattern` تطبق على كل مستخدم، و`%u` يستبدل باسم المستخدم، فسطر واحد يكفي لكل الأجهزة: كل جهاز يكتب قراءاته وحالته فقط، ويقرأ أوامره فقط. وبهذا الشكل اسم المستخدم هو اسم الجهاز في المواضيع، وهذا تصميم يجعل الصلاحيات تتبع الأسماء تلقائياً.
- خدمة الاستقبال تقرأ كل شيء ولا تكتب شيئاً، فإذا سرقت كلمة مرورها لا يستطيع المخترق أن يرسل أمراً.
- اللوحة وحدها تكتب الأوامر، وهي المكان الذي يجب أن يكون فيه دخول المستخدمين وسجل من أرسل ماذا.
- ما لم يذكر في الملف ممنوع، فلا يوجد سطر «امنع»، وإنما كل شيء ممنوع إلا ما أعطيته.

### إعداد الوسيط الآمن Secure Config

```ini
# Step 2: every client logs in, every topic is checked, and traffic outside the lab network is encrypted.
persistence true
persistence_location /mosquitto/data/
log_dest stdout
log_type error
log_type warning
log_type notice
log_type information
connection_messages true

# plain listener kept only for clients on the same host network namespace (health checks); no anonymous login
listener 1883
listener_allow_anonymous false

# TLS listener for devices and services
listener 8883
listener_allow_anonymous false
certfile /mosquitto/config/certs/server.crt
keyfile /mosquitto/config/certs/server.key
cafile /mosquitto/config/certs/ca.crt
tls_version tlsv1.2

# Mosquitto 2.1: password and ACL checks as plugins (the old password_file / acl_file options are deprecated)
global_plugin /usr/lib/mosquitto_password_file.so
plugin_opt_password_file /mosquitto/config/passwd
global_plugin /usr/lib/mosquitto_acl_file.so
plugin_opt_acl_file /mosquitto/config/acl
```

ولاحظ أن `tls_version tlsv1.2` في Mosquitto 2 يعني الحد الأدنى وليس الإصدار الوحيد، كما تقول صفحة الإعداد، ولهذا سوف ترى في السجل أن الاتصالات اتفقت على TLS 1.3\. وأن الإضافتين بـ `global_plugin` تطبقان على كل المنافذ، فلا يوجد منفذ يتجاوز كلمات المرور أو الصلاحيات.

### مشكلتان واجهتانا: صلاحيات الملفات File Permissions ومجلد الشهادات

في المحاولة الأولى ربطنا مجلد المختبر بالـ Container مباشرة، فعمل الوسيط ولكن ملأ السجل بتحذيرات لكل ملف سري:

```text
Warning: File /mosquitto/config/passwd has world readable permissions. Future versions will refuse to load this file.
To fix this, use `chmod 0700 /mosquitto/config/passwd`.
Warning: File /mosquitto/config/passwd owner is not mosquitto. Future versions will refuse to load this file.To fix this, use `chown mosquitto /mosquitto/config/passwd`.
```

والسبب أن الملفات المربوطة من Windows عبر Docker Desktop، أو من مجلد مشترك، تظهر داخل الـ Container مملوكة للمستخدم root ويقرؤها الجميع، ولا ينفع `chmod` عليها. والتحذير يقول بوضوح إن الإصدارات القادمة سوف ترفض تحميل الملف، أي أن الوسيط الذي يعمل اليوم قد لا يعمل بعد ترقية. والحل الأنظف أن نبني Image صغيراً ينسخ الملفات بالمالك والصلاحية الصحيحة، فكتبنا Dockerfile بالخيار `COPY --chmod=0600`، فاختفت التحذيرات، ولكن الوسيط توقف فوراً بخطأ جديد:

```text
Error: Unable to load CA certificates. Check cafile "/mosquitto/config/certs/ca.crt".
OpenSSL Error [0]: error:8000000D:system library::Permission denied
mosquitto version 2.1.2 terminating
```

والملف `ca.crt` نفسه كانت صلاحيته 644 ويقرؤه الجميع، فلماذا «Permission denied»؟ وعند فحص المجلد وجدنا السبب:

```text
drw-------    1 mosquitto mosquitto      4096 Nov  6 00:10 certs
```

فالخيار `--chmod` في `COPY` يطبق الصلاحية على المجلد الذي ينشئه أيضاً، والمجلد بصلاحية 0600 ليس فيه حرف `x`، فلا يستطيع أحد أن يدخله ليقرأ أي ملف فيه مهما كانت صلاحية الملف نفسه. والحل أن ننشئ المجلد أولاً بصلاحية صحيحة، ثم ننسخ إليه:

```dockerfile
# The secure broker: secrets copied in with the owner and mode Mosquitto 2.1 expects
# (a bind mount from Windows or a shared folder shows them world readable and owned by root).
FROM eclipse-mosquitto:2.1.2-alpine
# create the folder first: COPY --chmod applies the mode to folders it creates too, and 0600 without x cannot be entered
RUN install -d -o mosquitto -g mosquitto -m 0750 /mosquitto/config/certs
COPY --chown=mosquitto:mosquitto --chmod=0600 passwd acl /mosquitto/config/
COPY --chown=mosquitto:mosquitto --chmod=0600 certs/server.key /mosquitto/config/certs/
COPY --chmod=0644 certs/server.crt certs/ca.crt /mosquitto/config/certs/
COPY --chmod=0644 mosquitto-secure.conf /mosquitto/config/mosquitto.conf
```

```bash
docker build -t iot-mq-secure:1 .
docker run -d --name iot-mq --network iot-mq-net -v iot-mq-data:/mosquitto/data iot-mq-secure:1
```

```text
1793923989: Opening ipv4 listen socket on port 8883.
1793923989: Opening ipv6 listen socket on port 8883.
1793923989: mosquitto version 2.1.2 running
```

ولاحظ أن هذا الـ Image فيه مفتاح الوسيط وملف كلمات المرور، فلا ترفعه إلى أي Registry عام، وفي الإنتاج الأفضل أن تأتي هذه الملفات من مدير أسرار، وقد شرحنا الخيارات في [مقال إدارة الأسرار](https://arabroot.io/articles/%D8%A7%D8%AF%D8%A7%D8%B1%D8%A9-%D8%A7%D9%84%D8%A7%D8%B3%D8%B1%D8%A7%D8%B1-secrets-manager-openbao-%D8%A7%D9%85-infisical/).

### اختبار البوابات Security Tests: ماذا يرفض الوسيط ولماذا؟

الآن نجرب الأخطاء الشائعة واحداً واحداً، والكلاينت يأخذ شهادة السلطة `ca.crt` فقط، فهي عامة ولا سر فيها:

```bash
cli() { docker run --rm --network iot-mq-net -v "$PWD/certs/ca.crt:/ca.crt:ro" eclipse-mosquitto:2.1.2-alpine "$@"; }
cli mosquitto_pub -h iot-mq -t coldstore/store1/room1-temp/telemetry -m x                              # 1 anonymous
cli mosquitto_pub -h iot-mq -u room1-temp -P wrong -t coldstore/store1/room1-temp/telemetry -m x       # 2 wrong password
cli mosquitto_pub -d -h iot-mq -p 8883 -u room1-temp -P Room1-Lab-Pass -t t -m x                        # 3 TLS, no CA
cli mosquitto_pub -d -h 172.18.0.2 -p 8883 --cafile /ca.crt -u room1-temp -P Room1-Lab-Pass -t t -m x   # 4 TLS by IP
```

```text
Connection error: Connection Refused: not authorised
Error: The connection was refused
Connection error: Connection Refused: not authorised
Error: The connection was refused
Client null sending CONNECT
Error: Protocol error
OpenSSL Error while trying to get the error[0]: error:0A000086:SSL routines::certificate verify failed
Client null sending CONNECT
Error: Protocol error
OpenSSL Error while trying to get the error[0]: error:0A000086:SSL routines::certificate verify failed
```

وسجل الوسيط للمحاولتين الأخيرتين:

```text
1793924050: OpenSSL Error while trying to get the error[0]: error:0A000418:SSL routines::tlsv1 alert unknown ca
1793924052: OpenSSL Error while trying to get the error[0]: error:0A000412:SSL routines::ssl/tls alert bad certificate
```

وفي المخرج أعلاه لاحظ التالي:

- الدخول دون اسم والدخول بكلمة مرور خاطئة أعطيا الرد نفسه `not authorised`، وهذا مقصود، حتى لا يعرف المخترق هل الاسم موجود أم لا.
- في المحاولة الثالثة لم يعط الكلاينت شهادة السلطة، فلم يثق بشهادة الوسيط، وفي الرابعة أعطاها ولكنه اتصل بعنوان IP بدل الاسم `iot-mq` الموجود في الشهادة. والكلاينت يقول في الحالتين `Protocol error` فقط، وهي رسالة لا تفيد، ومع `-d` ظهر السبب الحقيقي `certificate verify failed`، وفي سجل الوسيط فرق واضح: `unknown ca` للأولى و`bad certificate` للثانية. فإذا اشتكى أحد من «Protocol error» فأول سؤال: بأي اسم يتصل، ومعه أي شهادة سلطة؟

ثم نجرب الصلاحيات بكلمات مرور صحيحة، أولاً بـ MQTT 5:

```bash
cli mosquitto_pub -h iot-mq -p 8883 --cafile /ca.crt -V mqttv5 -d -q 1 -u room1-temp -P Room1-Lab-Pass -t coldstore/store1/room1-temp/telemetry -m '{"seq":1}'
cli mosquitto_pub -h iot-mq -p 8883 --cafile /ca.crt -V mqttv5 -d -q 1 -u room1-temp -P Room1-Lab-Pass -t coldstore/store1/room2-temp/telemetry -m '{"seq":1}'
cli mosquitto_pub -h iot-mq -p 8883 --cafile /ca.crt -V mqttv5 -d -q 1 -u ingest-1 -P Ingest-Lab-Pass -t coldstore/store1/room1-temp/cmd -m 'compressor off'
```

```text
Client auto-2C8D383F-... sending PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room1-temp/telemetry', ... (9 bytes))
Client auto-2C8D383F-... received PUBACK (Mid: 1, RC:16)
Warning: Publish 1 failed: Not authorized.
Client auto-7AD168A5-... sending PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room2-temp/telemetry', ... (9 bytes))
Client auto-7AD168A5-... received PUBACK (Mid: 1, RC:135)
Warning: Publish 1 failed: Not authorized.
Client auto-1EEE3DBD-... sending PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room1-temp/cmd', ... (14 bytes))
Client auto-1EEE3DBD-... received PUBACK (Mid: 1, RC:135)
```

الجهاز نشر على موضوعه فوصله PUBACK برمز 16، وهو في المواصفة «No matching subscribers»، أي أن الرسالة قبلت ولكن لا يوجد مشترك الآن، وهذا نجاح مع معلومة وليس خطأ. ولما حاول أن ينشر على موضوع الغرفة الثانية جاءه الرمز 135 «Not authorized»، وكذلك خدمة الاستقبال لما حاولت أن ترسل أمر «compressor off». وسجل الاتصال في الوسيط يقول الآن مع كل اتصال اسم المستخدم والتشفير:

```text
New client connected from 172.18.0.3:51730 as auto-7AD168A5-... (p5, c1, k60, u'room1-temp').
Client auto-7AD168A5-... negotiated TLSv1.3 cipher TLS_AES_256_GCM_SHA384
```

ثم كررنا محاولة النشر على موضوع الغرفة الثانية نفسها، ولكن بـ MQTT 3.1.1، وهو الإصدار الافتراضي في كثير من المكتبات والأجهزة:

```text
Client null sending PUBLISH (d0, q1, r0, m1, 'coldstore/store1/room2-temp/telemetry', ... (9 bytes))
Client null received PUBACK (Mid: 1, RC:0)
```

الرد `RC:0`، أي نجاح! والحقيقة أن الوسيط رمى الرسالة، ولكن MQTT 3.1.1 لا يملك طريقة يقول بها «رفضت»، فيرد بالتأكيد العادي. وهذا يعني أن جهازاً بصلاحيات خاطئة بعد تعديل في ملف ACL سوف يرسل قراءاته أياماً وهو يظن أنها تصل، ولا يظهر أي خطأ في سجله، والطريقة الوحيدة لاكتشافه هي غياب القراءات عند المستقبل. وهذا سبب قوي لاستخدام MQTT 5 في الأجهزة الجديدة إذا كانت مكتبتها تدعمه.

وأخيراً جربنا القراءة: اشترك الجهاز `room1-temp` في كل شيء `coldstore/#`، ثم أرسلت اللوحة أمرين، واحداً له وواحداً للغرفة الثانية:

```text
Subscribed (mid: 1): 0
== what room1 received with # subscription:
coldstore/store1/room1-temp/cmd period 30
```

قبل الوسيط الاشتراك نفسه، ولكنه يفحص صلاحية القراءة مع كل رسالة، فوصل للجهاز أمره فقط، ولم يصله أمر الغرفة الثانية. والصورة التالية تلخص البوابات الثلاث وما رفضته كل منها:

![ثلاث بطاقات من اليمين: 1. التشفير TLS 8883 بقفل، يسأل هل يثق الكلاينت بشهادة الوسيط وهل الاسم iot-mq فيها، ورفض دون cafile بخطأ unknown ca وبالعنوان IP بخطأ bad certificate، والاتصال الناجح TLSv1.3 TLS_AES_256_GCM_SHA384، ثم 2. الدخول password-file بدرع، اسم وكلمة مرور لكل جهاز بهاش PBKDF2، والرفض not authorised للحالتين، ثم 3. الصلاحيات acl-file، كل جهاز يكتب في مواضيعه ويقرأ أوامره، وفي MQTT 5 الرد PUBACK RC:135 وفي MQTT 3.1.1 الرد RC:0 والرسالة ترمى بصمت](https://arabroot.io/content/images/2026/11/mqtt-mosquitto-05-security.webp)

البوابات الثلاث في الوسيط الآمن، وما رفضته كل منها في المختبر

## Mosquitto في الإنتاج Production

- **لا تنشر المنفذ 1883 إلى الإنترنت إطلاقاً:** الأجهزة خارج الشبكة تتصل على 8883 فقط، والأفضل عبر شبكة خاصة VPN، وقد شرحنا الفكرة في [مقال VPN](https://arabroot.io/articles/%D9%85%D8%A7-%D9%87%D9%88-vpn-%D8%B4%D8%B1%D8%AD-%D9%84%D9%84%D9%85%D8%A8%D8%AA%D8%AF%D8%A6%D9%8A%D9%86/).
- **الحفظ والـ Volume:** `persistence true` مع Volume دائم، وراجع `autosave_interval` بحسب ما تحتمل أن تفقد عند انقطاع الكهرباء المفاجئ.
- **حدود الطوابير:** احسب `max_queued_messages` من عدد الأجهزة وسرعتها وأطول غياب تتوقعه للمستقبل، وأضف `persistent_client_expiration`.
- **المراقبة:** اشترك في مواضيع `$SYS` لعدد الكلاينتات والرسائل المحفوظة والمستقبلة، ونبه على النقص المفاجئ في عدد المتصلين.
- **إدارة المستخدمين:** ملف كلمات المرور يكفي لعشرات الأجهزة، ومع العدد الأكبر هناك إضافة `dynamic-security` التي تدير المستخدمين والأدوار عبر الأداة `mosquitto_ctrl` دون إعادة تشغيل، أو شهادة لكل جهاز بدل كلمة المرور.
- **الجسر Bridge:** إذا كان لديك عدة مستودعات، فوسيط صغير في كل مستودع يربط بجسر بالوسيط المركزي، فيستمر العمل المحلي والتنبيه المحلي إذا انقطع الإنترنت، وتصل القراءات للمركز عند العودة.
- **فحص الإعداد قبل كل تعديل:** `mosquitto --test-config` قبل إعادة التشغيل، لأن الإصدار 2.1 يجعل الخطأ في ملف كلمات المرور أو الصلاحيات عند إعادة التحميل يوقف الوسيط كله، بحسب سجل التغييرات.

## أخطاء شائعة Common Mistakes

- **اسم كلاينت واحد لعدة أجهزة:** رأينا الطرد المتبادل 9 مرات في 8 ثوان.
- **اسم كلاينت عشوائي مع جلسة دائمة:** كل اتصال ينشئ جلسة جديدة تبقى في ذاكرة الوسيط ولا يعود إليها أحد.
- **الاعتماد على QoS الناشر وحده:** المشترك بـ QoS 0 يستقبل كل شيء بـ QoS 0.
- **حفظ القراءات أو الأوامر كرسائل محفوظة دون صلاحية:** القراءة القديمة تظهر كأنها الآن، والأمر القديم ينفذ عند كل إعادة تشغيل.
- **الوثوق بالوصية في الإغلاق الطبيعي:** DISCONNECT العادي لا يطلقها، فانشر `offline` بنفسك.
- **keepalive طويلة لجهاز مهم:** بالقيمة 60 قد تمر دقيقة ونصف قبل أن يعرف أحد.
- **persistence دون Volume:** الإعداد صحيح والنتيجة كأنه غير موجود.
- **الاكتفاء بـ MQTT 3.1.1 مع ACL:** الرفض صامت، والجهاز يظن أن رسائله تصل.
- **التشخيص من «Protocol error»:** استخدم `-d` واقرأ سجل الوسيط لترى السبب الحقيقي.

## قائمة تحقق Checklist قبل أن تربط أول جهاز

| البند            | القيمة المناسبة                                                     |
| ---------------- | ------------------------------------------------------------------- |
| اسم الكلاينت     | فريد لكل جهاز، من رقم تسلسلي أو عنوان MAC                           |
| الجلسة           | نظيفة للأجهزة التي ترسل فقط، ودائمة للخدمات التي تستقبل             |
| QoS              | 0 للقراءات المتكررة، و1 للسجل والحالة، و2 للأوامر الحرجة فقط        |
| keepalive        | بالثواني التي تحتمل أن يغيب فيها الجهاز دون أن تعرف، مقسومة على 1.5 |
| الحالة           | online محفوظة عند الاتصال، ووصية offline محفوظة                     |
| الحفظ            | persistence true مع Volume، وautosave\_interval مناسب               |
| الطوابير         | max\_queued\_messages محسوب، وpersistent\_client\_expiration        |
| المنافذ          | 8883 مع TLS فقط خارج السيرفر، ولا دخول دون اسم                      |
| الصلاحيات        | كل جهاز على مواضيعه، والأوامر من اللوحة وحدها                       |
| إصدار البروتوكول | MQTT 5 إذا كانت المكتبة تدعمه، لرموز السبب                          |

## تدريب عملي Practice

1. غير keepalive في تجربة الوصية إلى 4 ثوان ثم 30 ثانية، وقس الوقت بين `docker pause` ووصول `offline` في كل مرة.
2. أضف إلى ملف الصلاحيات مستخدماً للبوابة `gw-store1` يكتب قراءات كل الأجهزة التي خلفها فقط، ثم جرب أن ينشر باسم جهاز ليس خلفه.
3. اجعل `max_queued_messages 5`، ثم انشر 10 رسائل QoS 1 لجلسة `ingest-1` الغائبة، وانظر كم وصل منها، وما الذي يكتبه الوسيط في سجله.

## حذف المختبر Cleanup

```bash
docker rm -f iot-mq iot-mq-sub iot-mq-watch
docker network rm iot-mq-net
docker volume rm iot-mq-data
docker image rm iot-mq-secure:1
```

ويبقى Image الوسيط `eclipse-mosquitto:2.1.2-alpine` لأننا سوف نستخدمه في بقية السلسلة، أما مجلد `certs` ففيه مفتاح السلطة، فاحذفه أو انقله إلى مكان آمن إذا كنت سوف تستخدم هذه السلطة لأجهزة حقيقية.

## الخلاصة Summary

- رسالة CONNECT تحدد سلوك الكلاينت كله: اسمه وجلسته وkeepalive ووصيته، والوسيط يكتبها في سجله بالشكل `(p5, c1, k60, u'...')`.
- QoS وعد بين طرفين، والوسيط يسلم بالأقل بين مستوى النشر ومستوى الاشتراك.
- الرسالة المحفوظة مع الوصية تعطيان حالة كل جهاز دون سؤاله، والوصية تأتي بعد keepalive عند الانقطاع، وفوراً عند موت البرنامج، ولا تأتي عند الإغلاق الطبيعي.
- الجلسة الدائمة تحمي من غياب المشترك لرسائل QoS 1 و2، والحفظ على Volume يحميها من إعادة تشغيل الوسيط، ودون الحفظ ضاعت القراءات الثلاث والحالة المحفوظة.
- الأمان ثلاث بوابات: TLS بسلطة خاصة، ثم كلمة مرور لكل جهاز، ثم صلاحيات على المواضيع، وفي MQTT 3.1.1 يكون رفض الصلاحيات صامتاً.

[![](https://arabroot.io/content/images/2026/11/home-assistant-esphome-cover-cover.webp)دليلHome Assistant مع ESPHome: أتمتة المستودع على سيرفركنترجم برنامجاً حقيقياً للوحة ESP32، ونشغل الجهاز نفسه على السيرفر مع Home Assistant، ونكتب أتمتة تشغل الضاغط الاحتياطي، ثم نفصل الجهاز لنرى ما يحدث.](https://arabroot.io/articles/home-assistant-%D9%85%D8%B9-esphome-%D8%A7%D8%AA%D9%85%D8%AA%D8%A9-%D8%A7%D9%84%D9%85%D8%B3%D8%AA%D9%88%D8%AF%D8%B9-%D8%B9%D9%84%D9%89-%D8%B3%D9%8A%D8%B1%D9%81%D8%B1%D9%83/)[![](https://arabroot.io/content/images/2026/10/certificates-cover-cover.webp)دليلالشهادات الرقمية TLS للمبتدئين وصيغ ملفاتهاكيف يعرف المتصفح أنه يتحدث مع الموقع الحقيقي، وماذا يوجد داخل الشهادة، ولماذا تأتي ملفاتها بأكثر من صيغة.](https://arabroot.io/articles/%D8%A7%D9%84%D8%B4%D9%87%D8%A7%D8%AF%D8%A7%D8%AA-%D8%A7%D9%84%D8%B1%D9%82%D9%85%D9%8A%D8%A9-tls-%D9%88-x509-%D9%88%D8%B5%D9%8A%D8%BA-pem-%D9%88-der/)[![](https://arabroot.io/content/images/2026/11/prometheus-grafana-cover-cover.webp)دليلمقاييس السيرفرات Metrics: Prometheus مع لوحات Grafanaنجمع مقاييس المعالج والذاكرة والقرص والـ Containers مع Prometheus، ونتنبأ بموعد امتلاء القرص قبل أن يحدث، ونبني لوحة Grafana محفوظة ككود في Git.](https://arabroot.io/articles/%D9%85%D9%82%D8%A7%D9%8A%D9%8A%D8%B3-%D8%A7%D9%84%D8%B3%D9%8A%D8%B1%D9%81%D8%B1%D8%A7%D8%AA-metrics-prometheus-%D9%85%D8%B9-%D9%84%D9%88%D8%AD%D8%A7%D8%AA-grafana/)[![](https://arabroot.io/content/images/2026/10/network-segmentation-cover-cover.webp)دليلتقسيم الشبكة Network Segmentation بال VLAN وال VPCلماذا تصل كاميرا مخترقة إلى قاعدة بياناتك، وكيف تمنع ذلك بتقسيم الشبكة إلى مناطق لا يمر بينها إلا ما تسمح به.](https://arabroot.io/articles/%D8%AA%D9%82%D8%B3%D9%8A%D9%85-%D8%A7%D9%84%D8%B4%D8%A8%D9%83%D8%A9-network-segmentation-vlan-%D9%88-vpc/)

وفي [المقال القادم](https://arabroot.io/articles/home-assistant-%D9%85%D8%B9-esphome-%D8%A7%D8%AA%D9%85%D8%AA%D8%A9-%D8%A7%D9%84%D9%85%D8%B3%D8%AA%D9%88%D8%AF%D8%B9-%D8%B9%D9%84%D9%89-%D8%B3%D9%8A%D8%B1%D9%81%D8%B1%D9%83/) من السلسلة بإذن الله سوف نضع فوق هذا الوسيط Home Assistant وأجهزة ESPHome، ونكتب أول أتمتة.

## سجل التحديثات Changelog

- نوفمبر 2026: كتابة المقال، والتجربة على Mosquitto 2.1.2 (eclipse-mosquitto:2.1.2-alpine) مع أدوات mosquitto\_pub وmosquitto\_sub من الـ Image نفسه، وشهادات من OpenSSL 3.5.7 في python:3.13.18-slim، على Docker Engine 29.8.0، والمعلومات من توثيق Mosquitto وسجل تغييراته ومواصفة MQTT 5.0 كما قرأناها في 6 نوفمبر 2026.