نشر Matrix Synapse باستخدام Docker Compose و PostgreSQL
قم بإعداد خادم Synapse منزلي دائم باستخدام Docker Compose و PostgreSQL وتكوين خاص وفحوصات قبل عرضه عبر HTTPS.
شغّل Synapse كمشروع Docker Compose مع دليل تكوين دائم وقاعدة بيانات PostgreSQL. يُنشئ الإعداد الموضح أدناه مفاتيح التوقيع الخاصة بـ Synapse homeserver.yaml، ويربطه بـ PostgreSQL، ويُبقي مُستمع HTTP على المضيف المحلي، مما يسمح لك بوضع HTTPS والاتحاد خلف وكيل عكسي قبل فتح الخادم للإنترنت.
يُعدّ Synapse خادم Matrix الرئيسي: فهو يخزّن الحسابات والغرف والفعاليات والوسائط الخاصة بالخادم. يُشغّل Docker Compose حاويات Synapse وPostgreSQL من ملف YAML واحد. هذه نقطة بداية لجهاز واحد، وليست نشرًا عامًا كاملًا لـ Matrix.
قم بتثبيت محرك Docker ومكوّن Docker Compose الإضافي، ثم تأكد من docker compose versionعمله. يتضمن Docker Desktop مكوّن Compose الإضافي على نظامي التشغيل Windows و macOS؛ ويمكن لمستخدمي Linux تثبيت مكوّن Compose الإضافي من مستودع حزم Docker. راجع تعليمات تثبيت Docker Compose .
اختر اسم خادم Matrix الدائم قبل إنشاء التكوين. يظهر هذا الاسم في معرّفات المستخدمين، مثل @alex:matrix.example.org، وتغييره لاحقًا ليس تعديلًا روتينيًا لاسم المضيف. في هذا المثال، matrix.example.orgيُمثّل اسم خادم Matrix واسم المضيف العام. بالنسبة للخادم العام، وجّه سجل DNS الخاص به إلى مضيفك، وخطط لإنشاء وكيل عكسي HTTPS. يُعدّ مستمع HTTP الذي أنشأه Synapse على المنفذ 8008 مناسبًا للاختبار المحلي؛ وتشير وثائق التثبيت إلى أن الاستخدام العملي يتطلب HTTPS.
على مضيف Docker، أنشئ مجلد عمل ومجلدات دائمة. synapseسيحتوي المجلد على التكوين المُنشأ ومفتاح التوقيع؛ data/postgresوسيحتوي المجلد على ملفات قاعدة البيانات.
mkdir -p ~/matrix-synapse/synapse ~/matrix-synapse/data/postgres
cd ~/matrix-synapse
umask 077
openssl rand -hex 32
انسخ مخرجات الأمر إلى .envملف جديد باسم DB_PASSWORD=.... احتفظ بهذا الملف خاصًا وقم بعمل نسخة احتياطية آمنة منه. يقرأ Compose .envالتغييرات في ملف Compose؛ لا يقوم Synapse بتوسيع هذه المتغيرات تلقائيًا داخل homeserver.yaml. ستُدخل كلمة المرور نفسها في هذا الملف في الخطوة 3.

أنشئ الملف docker-compose.ymlفي مجلد المشروع. يستخدم هذا المثال صورة Synapse الرسمية الصادرة عن Element HQ و PostgreSQL 16. تم ربط منفذ Synapse بواجهة الشبكة المحلية (loopback) بدلاً من ربطه بأي واجهة شبكة أخرى. يساعد فحص الحالة Compose على انتظار اكتمال PostgreSQL قبل بدء تشغيل Synapse.
services:
synapse:
image: ghcr.io/element-hq/synapse:latest
restart: unless-stopped
environment:
SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
volumes:
- ./synapse:/data
ports:
- "127.0.0.1:8008:8008"
depends_on:
db:
condition: service_healthy
db:
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_USER: synapse
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: synapse
POSTGRES_INITDB_ARGS: --encoding=UTF-8 --lc-collate=C --lc-ctype=C
volumes:
- ./data/postgres:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
interval: 10s
timeout: 5s
retries: 5
أدخل القيمة العشوائية من الخطوة 1. لا تُضِف هذا الملف إلى نظام التحكم في الإصدار. إذا قمت بتغيير الإصدار الرئيسي لـ PostgreSQL لاحقًا، فاتبع إجراءات الترقية الخاصة بـ PostgreSQL بدلاً من مجرد توجيه صورة أحدث إلى دليل بيانات موجود DB_PASSWORD=your-generated-value..env
قم بإنشاء التكوين الأولي ومفتاح التوقيع في synapseالدليل المُثبَّت. استخدم نفس اسم الخادم الذي اخترته أعلاه. حدد خيار الإحصائيات بشكل صريح؛ إليك هو no.
docker compose run --rm --no-deps \
-e SYNAPSE_SERVER_NAME=matrix.example.org \
-e SYNAPSE_REPORT_STATS=no \
synapse generate
generateيُنشئ وضع الحاوية الرسمي homeserver.yamlمفتاح التوقيع المطلوب. افتح synapse/homeserver.yamlقسم قاعدة بيانات SQLite الخاص به واستبدله بما يلي. استبدل PASTE_THE_SAME_DB_PASSWORD_HEREالقيمة بالقيمة المطابقة تمامًا للمخزنة في .env. هذا الحقل هو قيمة حرفية لتكوين Synapse، وليس استيفاءً من Compose.
database:
name: psycopg2
args:
user: synapse
password: PASTE_THE_SAME_DB_PASSWORD_HERE
dbname: synapse
host: db
port: 5432
cp_min: 5
cp_max: 10

احتفظ بالملف المُنشأ registration_shared_secretبشكل خاص. يستخدمه برنامج Synapse لأداة تسجيل المستخدمين عبر سطر الأوامر؛ أي شخص يحصل عليه يمكنه إنشاء حسابات، بما في ذلك المسؤولين. أبقِ التسجيل العام مُعطّلاً إلا إذا كنت تنوي تقديمه عمدًا وراجعت ضوابط إساءة الاستخدام المرتبطة به.
من الدليل الذي يحتوي على الملف docker-compose.yml، تحقق من صحة ملف Compose وابدأ الخدمات:
docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=100 synapse db
يتحقق الأمر الأول من قدرة Compose على تحليل الملف وحلّه DB_PASSWORD. ثم يبدأ الأمر التالي تشغيل قاعدة البيانات وخادم المنزل في الخلفية. راجع سجلات النظام بحثًا عن أخطاء في اتصال قاعدة البيانات أو ملف تهيئة مفقود. ولأن هذا الإعداد يربط المجلدات المحلية، فإن تهيئة قاعدة البيانات وSynapse تبقى محفوظة عند إعادة إنشاء الحاويات.

قم بتشغيل طلب إصدارات عميل Matrix من مضيف Docker. تعني استجابة JSON أن واجهة برمجة تطبيقات العميل تستجيب؛ أما الاستجابة الفارغة أو رفض الاتصال أو خطأ HTTP فتعني أنه يجب عليك فحص سجلات Synapse والتأكد من أن المنفذ 8008 يستمع.
curl -fsS http://127.0.0.1:8008/_matrix/client/versions
بمجرد الاستجابة، أنشئ مستخدمًا أوليًا بشكل تفاعلي. سيطلب منك هذا الأمر اسم المستخدم وكلمة المرور؛ اختر "لا" للمسؤول إلا إذا كنت بحاجة إلى حساب مسؤول تحديدًا.
docker compose exec synapse register_new_matrix_user \
-c /data/homeserver.yaml http://localhost:8008

يُعدّ ربط المنفذ بالمضيف المحلي فقط مقصودًا: فهو يمنع الوصول العام المباشر إلى مستمع HTTP غير المشفر. بالنسبة للعملاء البعيدين، قم بتهيئة وكيل عكسي بشهادة TLS صالحة، وقم بتوجيه مسارات Matrix إلى Synapse. يجب أن يمرر الوكيل رؤوس HTTP X-Forwarded-Forو X-Forwarded-ProtoHTTPS؛ وفي تهيئة المستمع المُنشأة، فعّل x_forwarded: trueالمنفذ 8008. لا تقم بتعيين مستمع Synapse المُحاوي للربط بالمنفذ 8008 فقط 127.0.0.1، لأن ذلك يمنع حاوية الوكيل من الوصول إليه. إذا كان الوكيل العكسي مُحاويًا أيضًا، فضعه هو وSynapse على شبكة Docker مشتركة، وقم بتوجيه الطلبات إلى اسم الخدمة synapse:8008.
الاتحاد منفصل عن بدء التشغيل المحلي. تحتاج خوادم Matrix الأخرى إلى اكتشاف خادمك والوصول إليه، عادةً عبر المنفذ 8448 أو من خلال اكتشاف HTTPS المُفوَّض. .well-knownيجب أن تتطابق سجلات نظام أسماء النطاقات (DNS) وتوجيه الوكيل العكسي وأي سجلات مطلوبة مع اسم الخادم المُختار. اتبع وثائق Synapse الخاصة بالوكيل العكسي وإرشادات التثبيت قبل الإعلان عن خادم منزلي عام. تتطلب المكالمات الصوتية والمرئية أيضًا خادم TURN لضمان اتصال وسائط موثوق.
إذا تعذر على Synapse الاتصال بـ PostgreSQL، فتحقق من أن اسم خدمة Compose hostهو dbنفسه اسم الخدمة، وأن كلمتي المرور متطابقتان تمامًا، وأن حاوية قاعدة البيانات سليمة. إذا تعذر الوصول إلى نقطة النهاية، فتحقق من docker compose psسجلات Synapse، وما إذا كانت خدمة أخرى تستخدم منفذ المضيف 8008. قم بعمل نسخة احتياطية من كلٍّ من دليل بيانات PostgreSQL وتكوين Synapse ومفتاح التوقيع؛ فمفتاح التوقيع ضروري لهوية الخادم.
للحصول على تفاصيل حول إعدادات PostgreSQL، راجع دليل PostgreSQL الخاص بـ Synapse . أما بالنسبة لخيارات الحاويات وإنشاء المستخدمين، فاستخدم وثائق Docker الرسمية الخاصة بـ Synapse .
قم بإعداد خادم Synapse منزلي دائم باستخدام Docker Compose و PostgreSQL وتكوين خاص وفحوصات قبل عرضه عبر HTTPS.
قم بتعيين اسم ذي علامة تجارية وألوان مخصصة وأصول تسجيل دخول لنشر Element Web الخاص بك مع فهم الأجزاء التي ستظل تحمل علامة Element التجارية.
قم بتشخيص ما إذا كان برنامج Synapse قد وصل إلى الحد الأقصى للملفات المفتوحة لكل عملية، وقم بتعيين ملف systemd drop-in للخدمة أو العامل المناسب، وتحقق من الحد الأقصى للتشغيل.
اكتشف ما إذا كان الخطأ يقتصر على متصفح واحد أو حدث واحد، ثم استخدم مفتاح استرداد Element أو جهازًا موثوقًا به دون المخاطرة بسجل التصفح المشفر المتبقي.
استخدم واجهات برمجة تطبيقات Synapse الخاصة بحذف السجلات والوسائط أو إعدادات الاحتفاظ لإزالة البيانات القديمة بأمان، ثم تحقق من اكتمال العملية واستعادة مساحة القرص.
قم بتثبيت المكتبة الحالية، وقم بتوصيل حساب Matrix مخصص، وقم بتشغيل روبوت !echo صغير مع معالجة بيانات اعتماد أكثر أمانًا واختبار واضح.
قم بإعداد ثلاثة جسور mautrix مع تسجيلات وتسجيلات دخول واختبارات منفصلة - وتجنب مفاجآت شبكات Docker وسياسة الحساب والمزامنة.
ابحث عن الأشياء التي تملأ مساحة تخزين Synapse، وقم بتعيين الاحتفاظ الآمن بالوسائط، وقم بمسح ذاكرة التخزين المؤقت عن بعد دون حذف الملفات مباشرة من القرص.
راجع نشاط الجهاز، وقم بتعطيل حسابات Synapse غير النشطة المؤكدة من خلال واجهة برمجة تطبيقات المسؤول، وتعرف على ما الذي تزيله علامة المسح الاختيارية فعليًا.
حدد ما إذا كانت ذاكرة PostgreSQL تأتي من عمليات الاستعلام، أو المخازن المؤقتة المشتركة، أو الاتصالات، أو الصيانة، ثم قم بإجراء تغييرات مستهدفة آمنة لـ Synapse.