Domen, HTTPS és reverse proxy

Antimatter telepítése doménnévre HTTPS-tel, a compose-fájl Caddy-profiljának vagy saját reverse proxy használatával, valamint a rendszer URL és a klienscímek helyes beállítása.

A rendszer URL

A rendszer URL (ServiceSettings.SiteURL) az az cím, amellyel a felhasználók eléri az Antimattert, például https://chat.example.com. A szerver ezt használja a levelekben és értesítésekben szereplő hivatkozásokban, a bejelentkezési átirányításoknál (OAuth, OpenID Connect, SAML), a mobil- és asztali alkalmazásokban, valamint a kérések forrásának ellenőrzéséhez. Állítsa be pontosan a böngésző címsorában szereplő címre: protokoll, domén és port (ha nem az alapértelmezett), utólagos perjel nélkül.

• A helyi compose-fájllal: SITE_URL a .env fájlban.
• Máshol: AM_SERVICESETTINGS_SITEURL, vagy Rendszerkonzol › Környezet › Webszerver › Rendszer URL.

Ha a rendszer URL hibás, a hitelesítő szolgáltatóval történő bejelentkezés sikertelen lesz, a levelekben szereplő hivatkozások rossz helyre mutatnak, és az alkalmazások nem tudnak csatlakozni. A domén megváltoztatása után frissítse itt és minden hitelesítő szolgáltató átirányítási URL-einél.

HTTPS a csomagolt Caddy-profil használatával

A helyi compose.yaml fájl tartalmaz egy Caddy szolgáltatást az https profilban. Ez Let's Encrypt-től szerez tanúsítványt, automatikusan megújítja, átirányítja az HTTP-t HTTPS-re, és továbbítja mindent, websockets-t is, az Antimatternek.

1. Mutassa a domén DNS-rekordját (A, és AAAA IPv6-hoz) a szerverre.
2. Nyissa meg a tűzfalban a 80/tcp, 443/tcp és 443/udp (HTTP/3) portokat. A Let's Encryptnek elérhetőnek kell lennie a 80-as vagy 443-as porton az internetről.
3. Adja hozzá a domént a .env fájlhoz, és állítsa be a rendszer URL-t:

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

4. Indítsa el a profillal:

   docker compose --profile https up -d

Adja hozzá a --profile https opciót minden későbbi docker compose up parancshoz, vagy tegye be a COMPOSE_PROFILES=https bejegyzést a .env fájlba, hogy a sima docker compose up -d is tartalmazza. A Caddy a https kötetben tárolja a tanúsítványokat.

Az Antimatter saját portja továbbra is közzé van téve a gazdagépen (HTTP_PORT, alapértelmezetten 8065). Caddy használata esetén ezt csak a szerver saját használatára tartsa meg:

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

A Caddy a belső edge hálózaton keresztül éri el az Antimattert, nem ezen a porton, így ez nem változtat semmit a felhasználók számára.

Saját reverse proxy (nginx) használatával

Ha a szerveren már fut nginx, vagy más proxy, ne engedélyezze az https profilt, és mutassa a proxyt az Antimatter 8065-ös portjára. A proxy-nak a következőket kell tennie:

• továbbítania a websocket-eszkálációkat (a webes és a mobil alkalmazások nyitva tartanak egy websocketet a /api/v4/websocket útvonalon, egyes alkalmazások pedig sajátot nyitnak);
• elfogadnia olyan kéréseket, amelyek testje legalább olyan nagy, mint a legnagyobb feltöltés (Maximális fájl méret, alapértelmezés szerint 100 MB);
• nyitva tartania a hosszú ideig fennálló kapcsolatok (websockets, nagy méretű feltöltések és letöltések);
• továbbítania a Host fejlécet és a kliens címet.

Egy teljes szerverblokk, az antimatter-docker gyártási sablonjából átdolgozva. Cserélje ki a domainnevet és a tanúsítványok útvonalait:

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

Ellenőrizze a fájlt a nginx -t paranccsal, és alkalmazza a systemctl reload nginx paranccsal. A szerver maga küldi az X-Content-Type-Options, Referrer-Policy, Permissions-Policy és X-Frame-Options fejléceket; csak az HSTS van a proxy hatáskörében. Amint az HTTPS működik, emelje meg a max-age értékét, és csak akkor adja hozzá az includeSubDomains opciót, ha minden altartomány HTTPS-t használ.

Docker Compose és a hoston futó nginx esetén a fenti upstream a publikált 8065-ös portra mutat. Csak a 127.0.0.1 címen publikálja (HTTP_PORT=127.0.0.1:8065), hogy senki ne kerülhessen meg a proxyt.

Az antimatter-docker repository-ban található egy teljes beállítás nginx-sel konténerben, és Let's Encrypt-tel certboton keresztül, a deploy/compose mappában.

Egyéb proxyk

Bármely proxy megfelel, ha teljesíti a fenti négy pontot. A hangos és videóhívások sosem mennek át a proxyon: saját portot használnak, lásd Hívások és hang.

Klienscímek proxy mögött

Proxy mögött minden kérés úgy tűnik, mintha a proxytól származna. A valódi kliens cím rögzítéséhez, a kliensenkénti sebességkorlátozás alkalmazásához és az IP-szűréshez állítsa be, melyik fejléc hordozza a címet, és mely proxykban bízhat a szerver. Ezeknek a beállításoknak nincs mezője a Rendszerkonzolban: állítsa be őket a config.json fájlban, vagy változókkal.

Egy változóban több értéket szóközzel kell elválasztani: AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP". A szerver elutasítja a konfigurációt, ha a TrustedProxyIPs bejegyzése nem IP-cím, és nem CIDR-hálózat sem.

Hogyan határozza meg a szerver a kliens címét

Minden proxy a X-Forwarded-For mező jobb oldalára fűzi azt a címet, ahonnan a kérést kapta. A kliens által a fejlécben küldött érték a bal oldalon marad. Így a szerver jobbról balra olvassa a fejlécet, kihagyja a megbízható proxyk címét, és az első más címet tekinti a kliens címének. A kliens nem tudja saját címét megadni a fejléc küldésével.

• Egy proxy mögött a TrustedProxyIPHeader beállítás önmagában elegendő a helyes címhez: a szerver a fejléc legjobb oldalán lévő címét veszi. Indításkor figyelmeztetést ír a naplóba, amíg be nem állítja a TrustedProxyIPs bejegyzést is. Enélkül bárki, aki közvetlenül elérte a 8065-ös portot, beállíthatja a fejlécet, ezért a portot csak a 127.0.0.1 címen vagy egy privát hálózaton tegye közzé.
• Több proxy mögött, például CDN vagy terheléselosztó esetén, ha az ön proxyja előtt áll, mindent soroljon fel a TrustedProxyIPs bejegyzésben. Ellenkező esetben a szerver a külső proxy címét tekinti a kliens címének.
• A proxy lecserélheti a fejlécet a látott címre, ahogy a fenti nginx példa is teszi (X-Forwarded-For $remote_addr), vagy hozzáfűzheti a meglévőhöz (nginx $proxy_add_x_forwarded_for). Mindkettő működik.

Mely címeket kell felsorolni

Sorolja fel azt a címet, ahonnan a proxy kérései érkeznek, ahogy az Antimatter látja.

• A webhely compose fájljával és a Caddy-vel ez már megvan: a Caddy az edge hálózaton keresztül éri el az Antimattert, a compose fájl pedig a TrustedProxyIPHeader bejegyzést X-Forwarded-For-ra, a TrustedProxyIPs bejegyzést pedig a hálózat tartományára, az EDGE_SUBNET értékre állítja (172.29.71.0/28, hacsak nem módosítja a .env fájlban). Módosítsa az EDGE_SUBNET értékét, ha az átfed valamelyik hálózatával.
• Az antimatter-docker gyártási környezetbeállításai ugyanezt teszik az nginx konténerhez, a FRONTEND_SUBNET használatával.
• Ha az nginx a gazdagépen fut, az Antimatter pedig Dockerben, a kérések a publikált porton keresztül érik el az Antimattert, általában a compose projekt hálózatának átjáró-címéről (docker network inspect mutatja meg). Állítsa be az AM_SERVICESETTINGS_TRUSTEDPROXYIPS értékét erre a címre a compose.override.yaml fájlban.
• Docker nélkül, ha nginx ugyanazon a gazdagépen fut, akkor 127.0.0.1 (és ::1, ha nginx IPv6-n keresztül kapcsolódik).

TLS proxy nélkül

A szerver maga is kiszolgálhat HTTPS-t a Rendszerkonzol › Környezet › Webszerver menüben: a Kapcsolat biztonság legyen TLS-re (ServiceSettings.ConnectionSecurity) állítva, a TLS tanúsítvány fájl és a TLS kulcs fájl (ServiceSettings.TLSCertFile, ServiceSettings.TLSKeyFile) megadása mellett, vagy a Használjon Let's Encrypt-et (ServiceSettings.UseLetsEncrypt) bekapcsolásával. Ekkor a szervernek a 443-as porton kell hallgatnia (Hallgatási cím, ServiceSettings.ListenAddress, alapértelmezetten :8065), a ServiceSettings.Forward80To443 pedig átirányítja a 80-as portot. A reverse proxyt könnyebb üzemeltetni és megújítani, és ezt feltételezi a jelen útmutató is.

Szerveridőzítők és kérés mérete

A szerver saját webszerverének beállításai a Rendszerkonzol › Környezet › Webszerver menüben:

A proxy saját időtúllépéseit legalább ennyi ideig állítsa be a normál kérésekhez, a testméretét pedig legalább a Maximális fájl méret értékére.