كيفية إعداد خادم مصفوفة على Raspberry Pi 4 باستخدام Conduit

يمكن لجهاز Raspberry Pi 4 أن يُشكّل خادمًا منزليًا صغيرًا وعمليًا لشبكة Matrix، مناسبًا للاستخدام المنزلي أو لمجموعة خاصة أو مختبر، وقد صُمّم Conduit مع مراعاة خفة وزن الأجهزة. Matrix هو بروتوكول مفتوح للاتصال اللامركزي: يتصل المستخدمون بخادم منزلي ، يقوم بتخزين حساباتهم وبيانات غرفهم، بينما يسمح نظام الاتحاد لهذا الخادم بتبادل الأحداث مع خوادم Matrix الأخرى.

يستخدم هذا الدليل Conduit في Docker، مع NGINX كخادم وسيط لبروتوكول HTTPS. هذا يحافظ على عزل خدمة Matrix على Raspberry Pi مع إتاحة منافذ الويب العامة فقط. تمت مراجعة التعليمات بالرجوع إلى وثائق Conduit وMatrix وRaspberry Pi وDocker وNGINX المتوفرة في أكتوبر 2026. تجدر الإشارة إلى قيد هام: لا يزال Conduit يُصنّف نفسه كإصدار تجريبي (بيتا) ، لذا فهو الأنسب للمستخدمين الذين يتقبلون احتمال عدم عمل بعض ميزات Matrix والإصدارات القديمة من الغرف بنفس كفاءة عملها في بيئة Synapse ناضجة. يُرجى مراجعة مشروع Conduit الرسمي قبل استخدامه لخدمة بالغة الأهمية.

1. افهم عملية الإعداد قبل تثبيت أي شيء

المسار النهائي واضح ومباشر: يتصل عميل Matrix مثل Element بـ https://matrix.example.comNGINX؛ ثم يُنهي NGINX اتصال TLS ويُعيد توجيه الطلب إلى Conduit على Raspberry Pi؛ حيث يخزن Conduit قاعدة بياناته في وحدة تخزين Docker دائمة. في حال تفعيل خاصية الاتحاد، تصل الخوادم المنزلية الأخرى إلى نفس نقطة نهاية HTTPS العامة.

ستحتاج إلى جهاز Raspberry Pi 4، ومصدر طاقة موثوق، وبطاقة microSD أو قرص SSD، ونظام تشغيل 64 بت. يُفضل استخدام قرص SSD للخادم الذي تنوي الاحتفاظ به لفترة طويلة، لأن برنامج Matrix يكتب بيانات قاعدة البيانات والوسائط باستمرار. ستحتاج أيضًا إلى اسم نطاق إذا كان يجب أن يكون الخادم متاحًا عبر الإنترنت العام.

اعتبارًا من 15 سبتمبر 2026، يعتمد الإصدار الحالي من نظام التشغيل Raspberry Pi OS 64 بت على Debian 13 "Trixie"، ويتوفر نظام Raspberry Pi OS Lite لجهاز Pi 4. راجع صفحة تنزيل نظام Raspberry Pi OS الرسمية . يُعدّ نظام Lite مناسبًا لهذا الخادم لأنه يتجنب بيئة سطح المكتب غير الضرورية.

اختر اسم خادم المصفوفة بعناية

في هذا الدليل، اسم الخادم هو matrix.example.com. يبدو مُعرّف مستخدم Matrix الناتج كالتالي @alice:matrix.example.com. تعامل مع هذا الاسم كخيار هوية طويل الأمد. تتضمن مُعرّفات Matrix ومراجع الاتحاد اسم الخادم، لذا فإن تغييره لاحقًا لا يُعادل مجرد إعادة تسمية مُضيف ويب.

2. قم بتثبيت نظام التشغيل Raspberry Pi OS وتحديث جهاز Raspberry Pi

قم بتثبيت نظام التشغيل Raspberry Pi OS Lite 64-bit على البطاقة أو القرص الصلب SSD باستخدام برنامج Raspberry Pi Imager، وقم بتفعيل SSH أثناء عملية التثبيت إذا كنت ترغب في تثبيت النظام بدون شاشة، ثم قم بتشغيل جهاز Raspberry Pi. تأكد من أنك تستخدم نظام ARM 64-bit.

uname -m
cat /etc/os-release

uname -mينبغي أن يتم الإبلاغ عادةً aarch64. ثم قم بتثبيت التحديثات الحالية:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

3. قم بتثبيت Docker Engine و Compose

تنص وثائق Docker على أنه ينبغي لمستخدمي نظام التشغيل Raspberry Pi 64 بت استخدام حزم Debian ARM64 المدعومة بدلاً من مسار Raspberry Pi 32 بت الأقدم. تجدون الإجراء المعتمد على صفحة Docker Engine لنظام Debian . يتبع إعداد المستودع التالي هذا النهج:

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg   -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io   docker-buildx-plugin docker-compose-plugin

sudo docker run --rm hello-world

إذا طبع الأمر الأخير رسالة تأكيد "Hello World" من Docker، فهذا يعني أن بيئة تشغيل الحاوية تعمل بشكل صحيح. يمكنك متابعة sudo dockerبقية الدليل. إضافة حسابك إلى dockerالمجموعة اختيارية، ولكن تذكر أن عضوية مجموعة Docker تمنحك فعليًا صلاحيات المستخدم الجذر على المضيف.

4. إنشاء تكوين قناة

يمكن تهيئة Conduit باستخدام ملف TOML أو متغيرات البيئة. يذكر مرجع تهيئة Conduit الرسمي الحقول المطلوبة، ويوصي باستخدام server_nameRocksDB database_backend.database_path

أنشئ مجلد عمل:

sudo mkdir -p /opt/conduit
sudo chown "$USER":"$USER" /opt/conduit
cd /opt/conduit
nano conduit.toml

استخدم هذا التكوين المبدئي واستبدل اسم المضيف ورمز التسجيل:

[global]
server_name = "matrix.example.com"
database_backend = "rocksdb"
database_path = "/var/lib/matrix-conduit/"
address = "0.0.0.0"
port = 6167

allow_registration = true
registration_token = "replace-with-a-long-random-secret"
allow_federation = true
trusted_servers = ["matrix.org"]

لماذا 0.0.0.0هنا؟ داخل الحاوية، يجب أن يستمع Conduit على واجهة الحاوية حتى يتمكن Docker من الوصول إليها. سيظل منفذ جانب المضيف مرتبطًا فقط بـ 127.0.0.1، لذا فإن المنفذ 6167 غير مكشوف مباشرةً للإنترنت.

5. تشغيل Conduit باستخدام Docker Compose

يخلق /opt/conduit/docker-compose.yml:

services:
  conduit:
    image: registry.gitlab.com/famedly/conduit/matrix-conduit:latest
    container_name: matrix-conduit
    restart: unless-stopped
    ports:
      - "127.0.0.1:6167:6167"
    volumes:
      - ./conduit.toml:/etc/conduit.toml:ro
      - conduit-data:/var/lib/matrix-conduit/
    environment:
      CONDUIT_CONFIG: /etc/conduit.toml

volumes:
  conduit-data:

صورة GitLab Registry المستقرة هي الصورة الموصى بها في وثائق Conduit Docker الرسمية . تجنب نسخ وسم صورة قديم من أي دليل تعليمي عشوائي؛ استخدم السجل الرسمي واطلع على ملاحظات الإصدار قبل الترقية.

ابدأ الخدمة وافحصها:

cd /opt/conduit
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=100 conduit

تريد أن يبقى الحاوية في Upحالة تشغيل دون حلقات إعادة تشغيل متكررة. قبل تهيئة NGINX، تحقق من واجهة برمجة التطبيقات المحلية (API).

curl http://127.0.0.1:6167/_matrix/client/versions

6. قم بتوجيه نظام أسماء النطاقات (DNS) إلى جهاز Raspberry Pi وضع خادم NGINX أمام Conduit

أنشئ Aسجلاً matrix.example.comيشير إلى عنوان IPv4 العام الخاص بك. إذا قمت بنشر AAAAسجل، فتأكد من وصول IPv6 إلى جهاز Raspberry Pi؛ فقد يتسبب سجل IPv6 معطوب في فشل العملاء حتى عندما يعمل IPv4 بشكل صحيح.

في جهاز التوجيه المنزلي العادي، قم بتوجيه منفذي TCP 80 و443 إلى جهاز Raspberry Pi. إذا كان مزود خدمة الإنترنت الخاص بك يستخدم تقنية NAT من فئة مزودي الخدمة (CGNAT)، فقد لا يعمل توجيه المنافذ الواردة العادي؛ في هذه الحالة، ستحتاج إلى عنوان IP عام، أو خادم افتراضي خاص (VPS) أو تصميم نفق عكسي، أو ترتيب استضافة آخر.

قم بتثبيت NGINX:

sudo apt install -y nginx

يخلق /etc/nginx/sites-available/matrix:

server {
    listen 80;
    server_name matrix.example.com;

    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:6167;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

وثائق دليل NGINX الرسمي للوكيل العكسي والعناوينproxy_pass المُعاد توجيهها المستخدمة هنا.

sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/matrix
sudo nginx -t
sudo systemctl reload nginx

7. تفعيل بروتوكول HTTPS واكتشاف المصفوفة

يتطلب برنامج Matrix بروتوكول HTTPS صالحًا للنشر العام العادي. احصل على الشهادة فقط بعد أن يتم حل اسم النطاق (DNS) إلى جهاز Raspberry Pi والتأكد من إمكانية الوصول إلى المنفذ 80. يوفر نظام Debian Trixie حزم Certbot، كما ينشر مشروع Certbot أيضًا تعليمات خاصة بكل منصة على الموقع certbot.eff.org .

أحد المسارات الشائعة في Debian/NGINX هو:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d matrix.example.com

بعد أن يقوم Certbot بتحديث المضيف الظاهري لـ NGINX، اختبر التكوين مرة أخرى:

sudo nginx -t
sudo systemctl reload nginx

نظرًا لأن هذا الدليل يستخدم نفس اسم المضيف لاسم خادم Matrix ونقطة النهاية العامة، يمكن لـ Conduit الاستجابة /.well-knownلمسارات اكتشاف Matrix عبر الوكيل العكسي. تحدد مواصفات Matrix نقاط النهاية هذه حتى يتمكن العملاء والخوادم الأخرى من اكتشاف عنوان URL الصحيح للخادم الرئيسي. راجع مواصفات عميل-خادم Matrix .

8. أنشئ الحساب الأول، ثم تحقق من الخادم

توضح وثائق Docker الخاصة بـ Conduit أن أول حساب يتم إنشاؤه على خادم منزلي جديد يصبح حساب المدير. افتح عميل Matrix الذي يدعم رموز التسجيل، واختر خادمًا منزليًا مخصصًا، ثم أدخل الأمر التالي:

https://matrix.example.com

سجّل الحساب الأول باستخدام الرمز المميز من [المصدر] conduit.toml. افعل ذلك فور تشغيل الخدمة. إذا كنت لا ترغب في تسجيلات إضافية، فعدّل الإعدادات لضبط [القيمة] allow_registration = falseوأعد تشغيل الحاوية.

cd /opt/conduit
sudo docker compose restart conduit

قم الآن بإجراء ثلاثة فحوصات من أي جهاز يمكنه الوصول إلى النطاق:

curl https://matrix.example.com/_matrix/client/versions

curl https://matrix.example.com/.well-known/matrix/client

curl https://matrix.example.com/.well-known/matrix/server

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

أخطاء شائعة تمنع خادم Raspberry Pi Matrix من العمل

• استخدام نظام تشغيل 32 بت دون داع: بالنسبة لجهاز Pi 4، استخدم نظام التشغيل Raspberry Pi OS 64 بت وحزم Debian ARM64 المدعومة من Docker.
• عرض Conduit مباشرة: احتفظ بالمنفذ 6167 مرتبطًا 127.0.0.1بالمضيف وقم بعرض HTTPS من خلال NGINX.
• ترك التسجيل مفتوحًا بدون حماية: استخدم رمز تسجيل قوي أثناء الإعداد الأولي، ثم قم بتعطيل التسجيل إذا لم تكن بحاجة إليه.
• نشر نظام أسماء النطاقات غير الصحيح: يجب أن تؤدي سجلات IPv4 و IPv6 إلى نقطة نهاية تعمل إذا قمت بنشر كليهما.
• نسيان قواعد جهاز التوجيه أو جدار الحماية: لا يمكن للحاوية الصحيحة أن تعوض عن حظر TCP الوارد 80/443.
• بافتراض أن الرسائل النصية والمكالمات الصوتية متماثلة: يمكن لرسائل ماتريكس أن تعمل بينما تفشل المكالمات. تشير وثائق كوندويت إلى أن الاتصال الصوتي يتطلب خادم TURN مثل كوتورن.
• تجنب النسخ الاحتياطي: توصي الأسئلة الشائعة في Conduit بإيقاف تشغيل Conduit قبل إنشاء نسخة عادية من قاعدة بياناته على نظام الملفات، إلا إذا كنت تستخدم لقطة مناسبة لنظام الملفات. قم بعمل نسخة احتياطية من وحدة تخزين Docker وإعداداتك قبل التحديثات.

كيف يبدو التثبيت الناجح

تنتهي العملية عندما تتحقق كل هذه الشروط: يبقى حاوية Conduit قيد التشغيل بعد إعادة التشغيل؛ https://matrix.example.com/_matrix/client/versionsويعيد JSON؛ ويمكن لعميل Matrix التسجيل أو تسجيل الدخول إلى خادمك المنزلي المخصص؛ ويمكن للحساب إنشاء غرفة وإرسال رسالة؛ وإذا تم تمكين الاتحاد، فيمكن لمختبر الاتحاد الوصول إلى الخادم ويمكن للمستخدم التواصل مع الحسابات الموجودة على خادم منزلي آخر.

بالنسبة لتطبيقات Raspberry Pi الصغيرة، يُعد هذا أساسًا نظيفًا وليس نهايةً للإدارة. راقب مساحة التخزين المتاحة، وحافظ على تحديث نظام التشغيل Raspberry Pi وDocker، وقم بعمل نسخة احتياطية من قاعدة البيانات، واقرأ وثائق Conduit الرسمية قبل تفعيل أي ميزات إضافية. لا يزال Conduit خيارًا خفيفًا وجذابًا لأجهزة Raspberry Pi، ولكن كونه في مرحلة تجريبية (بيتا) يُعد أمرًا بالغ الأهمية من الناحية التشغيلية وليس مجرد إضافة ثانوية.