النطاق، وHTTPS، والوكلاء العكسيون

ضع Antimatter على اسم نطاق مع HTTPS، باستخدام ملف Caddy في ملف compose أو وكيل عكسي خاص بك، و اضبط عنوان الموقع وعناوين العملاء بشكل صحيح.

عنوان الموقع

عنوان الموقع (ServiceSettings.SiteURL) هو العنوان الذي يستخدمه الأشخاص للوصول إلى Antimatter، مثل https://chat.example.com. يستخدمه الخادم في الروابط داخل رسائل البريد الإلكتروني والإشعارات، وفي إعادة التوجيهات عند تسجيل الدخول (OAuth، OpenID Connect، SAML)، ولتطبيقات الجوال وسطح المكتب، وللتحقق من مصدر الطلبات. اضبطه على العنوان الموجود في شريط عنوان المتصفح بالضبط: المخطط، والنطاق، والمنفذ إن لم يكن الافتراضي، دون شرطة مائلة في النهاية.

• عبر ملف compose الخاص بالموقع: SITE_URL في .env.
• في أي مكان آخر: AM_SERVICESETTINGS_SITEURL، أو وحدة التحكم بالنظام › البيئة › خادم الويب › عنوان URL للموقع.

إذا كان عنوان الموقع خاطئاً، سيفشل تسجيل الدخول عبر مزوّد الهوية، وستشير الروابط في رسائل البريد الإلكتروني إلى المكان الخاطئ، وقد لا تتمكن التطبيقات من الاتصال. بعد تغيير النطاق، حدّثه هنا وفي عناوين إعادة التوجيه لكل مزوّد هوية.

HTTPS باستخدام ملف Caddy المرفق

يتضمن ملف compose.yaml الخاص بالموقع خدمة Caddy في ملف https. تحصل على شهادة من Let's Encrypt، وتجدها تلقائياً، وتعيد توجيه HTTP إلى HTTPS، وتحوّل كل شيء، بما في ذلك websockets، إلى Antimatter.

1. وجّه سجل DNS (A، وAAAA لـ IPv6) لنطاقك إلى الخادم.
2. افتح المنافذ 80/tcp، 443/tcp و443/udp (HTTP/3) في جدار الحماية. يجب أن يتمكن Let's Encrypt من الوصول إلى المنفذ 80 أو 443 من الإنترنت.
3. أضف النطاق إلى .env واضبط عنوان الموقع:

   echo "DOMAIN=chat.example.com" >> .env
   sed -i 's|^SITE_URL=.*|SITE_URL=https://chat.example.com|' .env

4. ابدأ باستخدام الملف:

   docker compose --profile https up -d

أضف --profile https إلى كل أمر docker compose up لاحقاً، أو ضع COMPOSE_PROFILES=https في .env حتى يتضمن الأمر العادي docker compose up -d الملف. يحتفظ Caddy بشهاداته في مجلد https.

يبقى منفذ Antimatter الخاص به منشوراً على المضيف (HTTP_PORT، 8065 افتراضياً). مع وجود Caddy في المقدمة، احتفظ به للخادم نفسه فقط:

echo "HTTP_PORT=127.0.0.1:8065" >> .env
docker compose --profile https up -d

يصل Caddy إلى Antimatter عبر الشبكة الداخلية edge، وليس عبر ذلك المنفذ، لذا لا يغيّر هذا شيئاً لمستخدميك.

باستخدام وكيل عكسي خاص بك (nginx)

إذا كان الخادم يعمل بالفعل بـ nginx أو وكيل آخر، فبقي ملف تعريف https معطّلًا وجعل الوكيل يشير إلى منفذ Antimatter 8065. يجب أن يقوم الوكيل بما يلي:

• تمرير ترقية websocket (تُبقي تطبيق الويب وتطبيقات الجوال اتصال websocket مفتوحًا على /api/v4/websocket، وتفتح بعض التطبيقات اتصالاتها الخاصة)؛
• قبول أجسام الطلبات بحجم لا يقل عن أكبر عملية رفع (الحد الأقصى لحجم الملف، 100 ميغابايت افتراضيًا)؛
• إبقاء الاتصالات طويلة العمر مفتوحة (اتصالات websocket، عمليات الرفع والتنزيل الكبيرة)؛
• تمرير ترويسة Host وعنوان العميل.

كتلة خادم كاملة، مُعدّلة من قالب الإنتاج في antimatter-docker. استبدل النطاق ومسارات الشهادة:

upstream antimatter {
    server 127.0.0.1:8065;
    keepalive 64;
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      '';
}

proxy_cache_path /var/cache/nginx/antimatter levels=1:2 keys_zone=antimatter_cache:10m
                 max_size=3g inactive=120m use_temp_path=off;

server {
    listen 80;
    listen [::]:80;
    server_name chat.example.com;
    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    server_name chat.example.com;

    ssl_certificate     /etc/ssl/chat.example.com/fullchain.pem;
    ssl_certificate_key /etc/ssl/chat.example.com/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_session_timeout 1d;
    ssl_session_cache shared:AntimatterSSL:10m;
    ssl_session_tickets off;

    add_header Strict-Transport-Security "max-age=31536000" always;

    # At least FileSettings.MaxFileSize (100 MB by default).
    client_max_body_size 100M;

    proxy_http_version 1.1;
    proxy_set_header Host              $host;
    proxy_set_header X-Real-IP         $remote_addr;
    proxy_set_header X-Forwarded-For   $remote_addr;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Upgrade           $http_upgrade;
    proxy_set_header Connection        $connection_upgrade;
    proxy_buffers 256 16k;
    proxy_buffer_size 16k;

    location ~ ^/api/v[0-9]+/(users/)?websocket$ {
        client_body_timeout 60s;
        send_timeout 300s;
        lingering_timeout 5s;
        proxy_connect_timeout 90s;
        proxy_send_timeout 300s;
        proxy_read_timeout 90s;
        proxy_pass http://antimatter;
    }

    location / {
        proxy_read_timeout 600s;
        proxy_cache antimatter_cache;
        proxy_cache_revalidate on;
        proxy_cache_min_uses 2;
        proxy_cache_use_stale timeout;
        proxy_cache_lock on;
        proxy_pass http://antimatter;
    }
}

تحقق من الملف باستخدام nginx -t وطبّقه باستخدام systemctl reload nginx. يرسل الخادم X-Content-Type-Options وReferrer-Policy وPermissions-Policy وX-Frame-Options بنفسه؛ HSTS فقط هو ما يتولاه الوكيل. ارفع قيمة max-age بمجرد بدء عمل HTTPS، وأضف includeSubDomains فقط إذا كانت جميع النطاقات الفرعية تستخدم HTTPS.

عند استخدام Docker Compose وnginx على المضيف، يشير upstream المذكور أعلاه إلى المنفذ المنشور 8065. انشره على 127.0.0.1 فقط (HTTP_PORT=127.0.0.1:8065)، حتى لا يتجاوز أحد الوكيل.

يحتوي مستودع antimatter-docker على إعداد كامل مع nginx في حاوية وLet's Encrypt عبر certbot، في deploy/compose.

وكلاء آخرون

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

عناوين العملاء خلف وكيل

خلف وكيل، يبدو أن كل طلب يأتي من الوكيل. لتسجيل عنوان العميل الفعلي، طبّق حدود المعدل لكل عميل واستخدم تصفية عناوين IP، وأخبر الخادم بأي ترويسة تحمل العنوان، وبأي وكلاء يمكنه الوثوق. لا يوجد حقل في وحدة التحكم بالنظام لأي من هذين الإعدادين: اضبطهما في config.json أو باستخدام متغيرات.

في المتغيّر، افصل بين عدة قيم بمسافات: AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP". يرفض الخادم أي تكوين يحتوي على إدراج في TrustedProxyIPs لا يكون عنوان IP ولا نطاق CIDR.

كيف يجد الخادم عنوان العميل

يضيف كل وكيل (proxy) العنوان الذي استلم منه الطلب إلى يمين X-Forwarded-For. يبقى ما أرسله العميل في الترويسة نفسه على اليسار. لذلك يقرأ الخادم الترويسة من اليمين، ويتخطى عناوين وكلاءك الموثوقين، ويتخذ أول عنوان آخر كعنوان العميل. لا يستطيع العميل اختيار عنوانه بإرسال ترويسته الخاصة.

• خلف وكيل واحد، يمنح TrustedProxyIPHeader وحده العنوان الصحيح: يتخذ الخادم العنوان الأيمن في الترويسة. يسجّل تحذيرًا عند الإقلاع حتى تضبط أيضًا TrustedProxyIPs. بدونه، يستطيع أي شخص يصل إلى المنفذ 8065 مباشرةً ضبط الترويسة، لذا انشر هذا المنفذ على 127.0.0.1 أو على شبكة خاصة فقط.
• خلف عدة وكلاء، على سبيل المثال CDN أو موازن أحمال أمام وكيلك الخاص، اذكرهم جميعًا في TrustedProxyIPs. وإلا سيتخذ الخادم عنوان الوكيل الخارجي كعنوان العميل.
• يستطيع الوكيل استبدال الترويسة بالعنوان الذي يراه، كما يفعل مثال nginx أعلاه (X-Forwarded-For $remote_addr)، أو الإضافة إليها (nginx's $proxy_add_x_forwarded_for). كلاهما يعمل.

العناوين التي يجب ذكرها

اذكر العنوان الذي تأتي منه طلبات الوكيل، كما يراه Antimatter.

• مع ملف compose الخاص بالموقع وCaddy، تم ذلك بالفعل: يصل Caddy إلى Antimatter عبر شبكة edge، ويضبط ملف compose TrustedProxyIPHeader على X-Forwarded-For وTrustedProxyIPs على نطاق تلك الشبكة، EDGE_SUBNET (172.29.71.0/28 ما لم تغيّره في .env). غيّر EDGE_SUBNET إذا كان يتداخل مع إحدى شبكاتك.
• التكوين الإنتاجي في antimatter-docker يفعل الشيء نفسه لوعاء nginx الخاص به، باستخدام FRONTEND_SUBNET.
• مع nginx على المضيف وAntimatter في Docker، تصل الطلبات إلى Antimatter عبر المنفذ المنشور، عادةً من عنوان البوابة لشبكة مشروع compose (docker network inspect يعرضه). اضبط AM_SERVICESETTINGS_TRUSTEDPROXYIPS على ذلك العنوان في compose.override.yaml.
• بدون Docker، ومع nginx على نفس المضيف، يكون العنوان 127.0.0.1 (و::1 إذا كان nginx يتصل عبر IPv6).

TLS دون وكيل

يمكن للخادم أيضًا تقديم HTTPS بنفسه، في وحدة التحكم بالنظام › البيئة › خادم الويب: ضبط أمان الاتصال على TLS (ServiceSettings.ConnectionSecurity)، مع ملف شهادة TLS وملف مفتاح TLS (ServiceSettings.TLSCertFile، ServiceSettings.TLSKeyFile)، أو استخدام Let’s Encrypt (ServiceSettings.UseLetsEncrypt). يجب أن يستمع الخادم بعد ذلك إلى المنفذ 443 (عنوان الاستماع، ServiceSettings.ListenAddress، :8065 افتراضيًا)، ويعيد ServiceSettings.Forward80To443 توجيه المنفذ 80. من الأسهل تشغيل وكيل عكسي وتجديده، وهو ما يفترضه هذا الدليل.

مهلات الخادم وحجم الطلب

إعدادات خادم الويب الخاص بالخادم نفسه، في وحدة التحكم بالنظام › البيئة › خادم الويب:

حافظ على مهلات الوكيل نفسه على الأقل بنفس طول هذه المهلات للطلبات العادية، وعلى حجم الجسم على الأقل الحد الأقصى لحجم الملف.