Δομή, HTTPS και reverse proxies

Τοποθετήστε το Antimatter σε ένα όνομα δομής με HTTPS, χρησιμοποιώντας το προφίλ Caddy του αρχείου compose ή δικό σας reverse proxy, και ρυθμίστε σωστά τη διεύθυνση του χώρου και τις διευθύνσεις των πελατών.

Η διεύθυνση του χώρου

Η διεύθυνση του χώρου (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) στο firewall. Το 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 παραμένει εκτεθειμένη στον host (HTTP_PORT, 8065 ως προεπιλογή). Με το Caddy μπροστά, κρατήστε τη μόνο για τον ίδιο τον διακομιστή:

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

Το Caddy φτάνει το Antimatter μέσω του εσωτερικού δικτύου edge, όχι μέσω αυτής της θύρας, οπότε αυτό δεν αλλάζει τίποτα για τους χρήστες σας.

Με δικό σας reverse proxy (nginx)

Αν ο διακομιστής εκτελεί ήδη nginx ή κάποιο άλλο proxy, απενεργοποιήστε το προφίλ https και κατευθύνετε το proxy στην θύρα 8065 του Antimatter. Το proxy πρέπει:

• να επιτρέπει αναβαθμίσεις websocket (η web εφαρμογή και οι κινητές εφαρμογές διατηρούν ανοιχτό ένα websocket στο /api/v4/websocket, ενώ ορισμένες εφαρμογές ανοίγουν τα δικά τους);
• δεχτείτε σώματα αιτήσεων τουλάχιστον τόσο μεγάλα όσο το μεγαλύτερο ανέβασμα (Μέγιστο μέγεθος αρχείου, 100 MB από προεπιλογή);
• να διατηρεί ανοιχτές τις μακροχρόνιες συνδέσεις (websockets, μεγάλα ανέβασματα και λήψεις);
• να μεταδίδει την κεφαλίδα Host και τη διεύθυνση του πελάτη.

Ένας πλήρης μπλοκ διακομιστή, προσαρμοσμένος από το πρότυπο παραγωγής στο antimatter-docker. Αντικαταστήστε το domain και τις διαδρομές των πιστοποιητικών:

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 είναι αρμοδιότητα του proxy. Αυξήστε το max-age μόλις λειτουργήσει το HTTPS και προσθέστε includeSubDomains μόνο αν όλα τα υποdomain χρησιμοποιούν HTTPS.

Με Docker Compose και nginx στον host, το upstream παραπάνω δείχνει στην δημοσιευμένη θύρα 8065. Δημοσιεύστε την μόνο στο 127.0.0.1 (HTTP_PORT=127.0.0.1:8065), ώστε κανείς να μην παρακάμπτει το proxy.

Το αποθετήριο antimatter-docker περιλαμβάνει μια πλήρη ρύθμιση με nginx σε container και Let's Encrypt μέσω certbot, στο deploy/compose.

Άλλα proxy

Κάθε proxy λειτουργεί αρκεί να ικανοποιεί τα τέσσερα σημεία παραπάνω. Η ήχος και το βίντεο σε κλήσεις δεν περνούν ποτέ από το proxy: χρησιμοποιούν τη δική τους θύρα, δείτε Κλήσεις και φωνή.

Διευθύνσεις πελατών πίσω από proxy

Πίσω από ένα proxy, κάθε αίτημα φαίνεται να προέρχεται από το proxy. Για να καταγράφετε την πραγματική διεύθυνση του πελάτη, να εφαρμόζετε περιορισμούς ρυθμού ανά πελάτη και να χρησιμοποιείτε φιλτράρισμα IP, πείτε στον διακομιστή ποια κεφαλίδα μεταφέρει τη διεύθυνση και ποια proxy μπορεί να εμπιστευτεί. Καμία από αυτές τις ρυθμίσεις δεν έχει πεδίο στην Κονσόλα συστήματος: ρυθμίστε τις στο config.json ή με μεταβλητές.

Σε μια μεταβλητή, διαχωρίστε πολλαπλές τιμές με κενά: AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP". Ο διακομιστής απορρίπτει μια ρύθμιση που περιέχει στο TrustedProxyIPs μια τιμή που δεν είναι ούτε διεύθυνση IP ούτε εύρος CIDR.

Πώς ο διακομιστής εντοπίζει τη διεύθυνση του πελάτη

Κάθε proxy προσθέτει τη διεύθυνση από την οποία έλαβε το αίτημα στο δεξί μέρος του X-Forwarded-For. Ό,τι έστειλε ο πελάτης στο ίδιο το header παραμένει στο αριστερό μέρος. Επομένως, ο διακομιστής διαβάζει το header από δεξιά προς τα αριστερά, παραλείπει τις διευθύνσεις των αξιόπιστων proxy και λαμβάνει την πρώτη διαφορετική διεύθυνση ως τη διεύθυνση του πελάτη. Ένας πελάτης δεν μπορεί να επιλέξει τη διεύθυνσή του στέλνοντας το δικό του header.

• Πίσω από ένα proxy, μόνο το TrustedProxyIPHeader δίνει τη σωστή διεύθυνση: ο διακομιστής λαμβάνει τη δεξιότερη διεύθυνση του header. Καταγράφει μια προειδοποίηση κατά την εκκίνηση μέχρι να ορίσετε και το TrustedProxyIPs. Χωρίς αυτό, οποιονδήποτε μπορεί να φτάσει απευθείας στην θύρα 8065 και να ορίσει το header, οπότε δημοσιεύστε αυτή τη θύρα μόνο στο 127.0.0.1 ή σε ένα ιδιωτικό δίκτυο.
• Πίσω από πολλά proxy, για παράδειγμα ένα CDN ή έναν load balancer μπροστά από το δικό σας proxy, καταγράψτε τα όλα στο TrustedProxyIPs. Αλλιώς, ο διακομιστής θα λάβει τη διεύθυνση του εξωτερικού proxy ως τη διεύθυνση του πελάτη.
• Το proxy μπορεί να αντικαταστήσει το header με τη διεύθυνση που βλέπει, όπως κάνει το παράδειγμα nginx παραπάνω (X-Forwarded-For $remote_addr), ή να προσθέσει σε αυτό (το $proxy_add_x_forwarded_for του nginx). Και οι δύο μέθοδοι λειτουργούν.

Ποιες διευθύνσεις να καταγράψετε

Καταγράψτε τη διεύθυνση από την οποία προέρχονται τα αιτήματα του proxy, όπως τη βλέπει το Antimatter.

• Με το αρχείο compose του site και το Caddy, αυτό έχει ήδη γίνει: το Caddy φτάνει στο Antimatter μέσω του δικτύου edge, και το αρχείο compose ορίζει το TrustedProxyIPHeader στο X-Forwarded-For και το TrustedProxyIPs στο εύρος αυτού του δικτύου, EDGE_SUBNET (172.29.71.0/28, εκτός αν το αλλάξετε στο .env). Αλλάξτε το EDGE_SUBNET αν επικαλύπτεται με ένα από τα δίκτυά σας.
• Η παραγωγική ρύθμιση στο antimatter-docker κάνει το ίδιο για το container nginx, χρησιμοποιώντας το FRONTEND_SUBNET.
• Με nginx στον host και Antimatter σε Docker, τα αιτήματα φτάνουν στο Antimatter μέσω της δημοσιευμένης θύρας, συνήθως από τη διεύθυνση gateway του δικτύου του έργου compose (το docker network inspect τη δείχνει). Ορίστε το AM_SERVICESETTINGS_TRUSTEDPROXYIPS σε αυτή τη διεύθυνση στο compose.override.yaml.
• Χωρίς Docker, με nginx στον ίδιο υπολογιστή, είναι 127.0.0.1 (και ::1 αν ο nginx συνδέεται μέσω IPv6).

TLS χωρίς proxy

Ο διακομιστής μπορεί επίσης να παρέχει HTTPS μόνος του, στη Κονσόλα συστήματος › Περιβάλλον › Διακομιστής Ιστού: Ασφάλεια σύνδεσης ρυθμισμένη σε TLS (ServiceSettings.ConnectionSecurity), με Αρχείο πιστοποιητικού TLS και Αρχείο ιδιωτικού κλειδιού TLS (ServiceSettings.TLSCertFile, ServiceSettings.TLSKeyFile), ή Χρήση Let's Encrypt (ServiceSettings.UseLetsEncrypt). Τότε ο διακομιστής πρέπει να ακούει στην θύρα 443 (Διεύθυνση ακρόασης, ServiceSettings.ListenAddress, :8065 από προεπιλογή) και το ServiceSettings.Forward80To443 να ανακατευθύνει την θύρα 80. Ένας reverse proxy είναι ευκολότερος στη λειτουργία και την ανανέωση, και είναι αυτό που υποθέτει ο παρών οδηγός.

Χρονόρια διακομιστή και μέγεθος αιτήματος

Ρυθμίσεις του δικού του διακομιστή Ιστού, στο Κονσόλα συστήματος › Περιβάλλον › Διακομιστής Ιστού:

Κρατήστε τα χρονόρια του ίδιου του proxy τουλάχιστον τόσο μεγάλα όσο αυτά για τα κανονικά αιτήματα, και το μέγεθος σώματος τουλάχιστον Μέγιστο μέγεθος αρχείου.