Domini, HTTPS i proxys inversos

Posa Antimatter en un nom de domini amb HTTPS, utilitzant el perfil de Caddy del fitxer compose o un proxy invers propi, i configura correctament l'URL del lloc web i les adreces del client.

L'URL del lloc web

L'URL del lloc web (ServiceSettings.SiteURL) és l'adreça que les persones utilitzen per accedir a Antimatter, com ara https://chat.example.com. El servidor l'utilitza en els enllaços dels correus electrònics i les notificacions, en les redireccions d'inici de sessió (OAuth, OpenID Connect, SAML), per a les aplicacions mòbil i d'escriptori, i per comprovar d'on provenen les sol·licituds. Configura-la exactament com l'adreça que apareix a la barra d'adreces del navegador: esquema, domini i port (si no és el predeterminat), sense barra inclinada final.

• Amb el fitxer compose del lloc: SITE_URL a .env.
• En qualsevol altre lloc: AM_SERVICESETTINGS_SITEURL, o Consola del sistema › Entorn › Servidor web › URL del lloc web.

Si l'URL del lloc web és incorrecta, l'inici de sessió amb un proveïdor d'identitat fallarà, els enllaços dels correus apuntaran a un lloc incorrecte i les aplicacions poden no connectar-se. Després de canviar el domini, actualitza-la aquí i a les URL de redirecció de cada proveïdor d'identitat.

HTTPS amb el perfil de Caddy inclòs

El compose.yaml del lloc inclou un servei de Caddy al perfil https. Obté un certificat de Let's Encrypt, el renova automàticament, redirigeix HTTP a HTTPS i transfereix tot, inclosos els websockets, a Antimatter.

1. Apunta un registre DNS (A, i AAAA per a IPv6) del teu domini al servidor.
2. Obre els ports 80/tcp, 443/tcp i 443/udp (HTTP/3) al tallafoc. Let's Encrypt ha de poder accedir al port 80 o 443 des d'Internet.
3. Afegeix el domini a .env i configura l'URL del lloc web:

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

4. Inicia amb el perfil:

   docker compose --profile https up -d

Afegeix --profile https a cada docker compose up posterior, o posa COMPOSE_PROFILES=https a .env perquè un simple docker compose up -d l'inclougi. Caddy guarda els seus certificats al volum https.

El port propi d'Antimatter continua publicat a l'amfitrió (HTTP_PORT, 8065 per defecte). Amb Caddy davant, mantén-lo només per al propi servidor:

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

Caddy accedeix a Antimatter a través de la xarxa interna edge, no a través d'aquest port, així que això no canvia res per als teus usuaris.

Amb el teu propi proxy invers (nginx)

Si el servidor ja executa nginx o un altre proxy, desactiva el perfil https i apunta el proxy al port 8065 d'Antimatter. El proxy ha de:

• transmetre les actualitzacions de websocket (l'aplicació web i les aplicacions mòbil mantenen un websocket obert a /api/v4/websocket, i algunes aplicacions n'obren un de propi);
• acceptar cossos de sol·licitud d'almenys la mida de la càrrega més gran (Mida màxima del fitxer, 100 MB per defecte);
• mantir obertes les connexions de llarga durada (websockets, càrregues i descàrregues grans);
• transmetre la capçalera Host i l'adreça del client.

Un bloc de servidor complet, adaptat de la plantilla de producció d'antimatter-docker. Substitueix el domini i les rutes dels certificats:

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;
    }
}

Comprova el fitxer amb nginx -t i aplica'l amb systemctl reload nginx. El servidor envia per si mateix X-Content-Type-Options, Referrer-Policy, Permissions-Policy i X-Frame-Options; només l'HSTS depèn del proxy. Augmenta el seu max-age quan l'HTTPS funcioni, i afegeix includeSubDomains només si tots els subdominis utilitzen HTTPS.

Amb Docker Compose i nginx a l'amfitrió, l'upstream anterior apunta al port 8065 publicat. Publica'l només a 127.0.0.1 (HTTP_PORT=127.0.0.1:8065), perquè ningú no es salti el proxy.

El repositori antimatter-docker té una configuració completa amb nginx en un contenedor i Let's Encrypt mitjançant certbot, a deploy/compose.

Altres proxys

Qualsevol proxy funciona si compleix els quatre punts anteriors. Les trucades d'àudio i vídeo mai no passen pel proxy: utilitzen el seu propi port, consulta Trucades i veu.

Adreces de clients darrere d'un proxy

Darrere d'un proxy, totes les sol·licituds semblen provenir del proxy. Per registrar l'adreça real del client, aplicar límits de freqüència per client i utilitzar filtratge per IP, indica al servidor quina capçalera porta l'adreça i quins proxys pot confiar. Cap d'aquestes configuracions té un camp a la Consola del sistema: estableix-les a config.json o amb variables.

En una variable, separa diversos valors amb espais: AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP". El servidor rebutja una configuració amb una entrada a TrustedProxyIPs que no sigui ni una adreça IP ni un rang CIDR.

Com el servidor troba l'adreça del client

Cada proxy afegeix l'adreça des de la qual ha rebut la sol·licitud a la dreta de X-Forwarded-For. El que el client hagi enviat al capçalera original queda a l'esquerra. Per tant, el servidor llegeix el capçalera des de la dreta, salta les adreces dels teus proxys de confiança i pren la primera altra adreça com a la del client. Un client no pot triar la seva adreça enviant el seu propi capçalera.

• Darrere d'un sol proxy, TrustedProxyIPHeader per si sol dona l'adreça correcta: el servidor pren l'adreça més a la dreta del capçalera. Registra un avís en arrencar fins que també configuris TrustedProxyIPs. Sense això, qualsevol qui arribi directament al port 8065 pot establir el capçalera, així que publica aquest port només a 127.0.0.1 o en una xarxa privada.
• Darrere de diversos proxys, per exemple un CDN o un equilibrador de càrrega davant del teu propi proxy, llista'ls tots a TrustedProxyIPs. En cas contrari, el servidor pren l'adreça del proxy extern com a la del client.
• El proxy pot substituir el capçalera per l'adreça que veu, com fa l'exemple d'nginx anterior (X-Forwarded-For $remote_addr), o afegir-hi (el $proxy_add_x_forwarded_for d'nginx). Ambdues opcions funcionen.

Quines adreces llistar

Llista l'adreça des de la qual arriben les sol·licituds del proxy, tal com la veu Antimatter.

• Amb el fitxer compose del lloc i Caddy, això ja està fet: Caddy arriba a Antimatter a través de la xarxa edge, i el fitxer compose estableix TrustedProxyIPHeader a X-Forwarded-For i TrustedProxyIPs al rang d'aquesta xarxa, EDGE_SUBNET (172.29.71.0/28 si no el canvies a .env). Canvia EDGE_SUBNET si se superposa amb una de les teves xarxes.
• La configuració de producció d'antimatter-docker fa el mateix per al seu contenidor nginx, amb FRONTEND_SUBNET.
• Amb nginx a l'amfitrió i Antimatter a Docker, les sol·licituds arriben a Antimatter a través del port publicat, normalment des de l'adreça de la passarel·la de la xarxa del projecte compose (docker network inspect la mostra). Estableix AM_SERVICESETTINGS_TRUSTEDPROXYIPS a aquesta adreça a compose.override.yaml.
• Sense Docker, amb nginx al mateix host, és 127.0.0.1 (i ::1 si nginx es connecta per IPv6).

TLS sense proxy

El servidor també pot servir HTTPS directament, a Consola del sistema › Entorn › Servidor web: Seguretat de la connexió establert a TLS (ServiceSettings.ConnectionSecurity), amb Fitxer del certificat TLS i Fitxer de la clau privada TLS (ServiceSettings.TLSCertFile, ServiceSettings.TLSKeyFile), o bé Utilitza Let’s Encrypt (ServiceSettings.UseLetsEncrypt). El servidor ha d'escoltar aleshores al port 443 (Adreça d'escolta, ServiceSettings.ListenAddress, :8065 per defecte), i ServiceSettings.Forward80To443 redirigeix el port 80. Un proxy invers és més fàcil de gestionar i renovar, i és el que suposa aquesta guia.

Temps d'espera del servidor i mida de les sol·licituds

Configuració del propi servidor web del servidor, a Consola del sistema › Entorn › Servidor web:

Mantén els propis temps d'espera del proxy com a mínim tan llargs com aquests per a les sol·licituds normals, i la mida del cos com a mínim Mida màxima del fitxer.