Alan adı, HTTPS ve geri yönlendirmeli proxy'ler

Antimatter'i, compose dosyasındaki Caddy profili veya kendi geri yönlendirmeli proxy'niz aracılığıyla HTTPS destekli bir alan adında barındırın ve site URL'si ile istemci adreslerini doğru şekilde yapılandırın.

Site URL'si

Site URL'si (ServiceSettings.SiteURL), kullanıcıların Antimatter'e erişmek için kullandığı adresdir; örneğin https://chat.example.com. Sunucu, bu adresi e-posta ve bildirimlerdeki bağlantılarda, oturum açma yönlendirmelerinde (OAuth, OpenID Connect, SAML), mobil ve masaüstü uygulamalarda ve isteklerin nereden geldiğini denetlemek için kullanır. Tarayıcının adres çubuğundaki adresle birebir aynı olacak şekilde ayarlayın: şema, alan adı ve varsayılan olmayan bir port varsa port; sonda eğik çizgi olmadan.

• Site'nin compose dosyası ile: .env içindeki SITE_URL.
• Başka yerlerde: AM_SERVICESETTINGS_SITEURL veya Sistem Konsolu › Ortam › Site sunucusu › Site adresi.

Site URL'si yanlışsa, kimlik sağlayıcıyla oturum açma başarısız olur, e-postalardaki bağlantılar yanlış yere gider ve uygulamalar bağlantı kuramayabilir. Alan adını değiştirdikten sonra, bu adresi burada ve tüm kimlik sağlayıcılarının yönlendirme URL'lerinde güncelleyin.

Pakete ekli Caddy profili ile HTTPS

Site'nin compose.yaml dosyası, https profili içinde bir Caddy hizmeti içerir. Bu hizmet, Let's Encrypt'ten sertifika alır, sertifikayı kendisi yeniler, HTTP trafiğini HTTPS'e yönlendirir ve her şeyi (WebSocket'ler dahil) Antimatter'e iletir.

1. Alan adınızın DNS kaydını (A ve IPv6 için AAAA) sunucuya yönlendirin.
2. Firewall'da 80/tcp, 443/tcp ve 443/udp (HTTP/3) portlarını açın. Let's Encrypt'in 80 veya 443 portuna İnternet üzerinden erişebilmesi gerekir.
3. Alan adını .env dosyasına ekleyin ve site URL'sini ayarlayın:

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

4. Profil ile başlatın:

   docker compose --profile https up -d

Daha sonraki her docker compose up komutuna --profile https parametresini ekleyin veya düz docker compose up -d komutunun bu profili içermesi için .env dosyasına COMPOSE_PROFILES=https ekleyin. Caddy, sertifikalarını https hacminde saklar.

Antimatter'in kendi portu, ana makinede yayımlanmaya devam eder (HTTP_PORT, varsayılan olarak 8065). Caddy ön plandayken, bu portu yalnızca sunucu kendisi için kullanın:

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

Caddy, Antimatter'e o port üzerinden değil, dahili edge ağı üzerinden erişir; bu nedenle kullanıcılarınız için hiçbir şey değişmez.

Kendi geri yönlendirmeli proxy'nizle (nginx)

Sunucu zaten nginx veya başka bir vekil çalıştırıyorsa, https profilini devre dışı bırakın ve vekili Antimatter'ın 8065 portuna yönlendirin. Vekil şunları yapmalıdır:

• websocket yükseltmelerini iletmelidir (web uygulaması ve mobil uygulamalar /api/v4/websocket üzerinde bir websocket açık tutar, bazı uygulamalar kendi websocket'lerini açar);
• en büyük yükleme boyutuna (En büyük dosya boyutu, varsayılan olarak 100 MB) en az eşit olan istek gövdelerini kabul edin;
• uzun ömürlü bağlantıları açık tutmalıdır (websocket'ler, büyük yükleme ve indirmeler);
• Host başlığını ve istemcinin adresini iletmelidir.

antimatter-docker'daki üretim şablonundan uyarlanmış tam bir sunucu bloğu. Alan adını ve sertifika yollarını değiştirin:

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

Dosyayı nginx -t ile kontrol edin ve systemctl reload nginx ile uygulayın. Sunucu X-Content-Type-Options, Referrer-Policy, Permissions-Policy ve X-Frame-Options başlıklarını kendisi gönderir; yalnızca HSTS vekile aittir. HTTPS çalışmaya başladığında max-age değerini artırın ve yalnızca tüm alt alan adları HTTPS kullanıyorsa includeSubDomains ekleyin.

Docker Compose ve ana makinede nginx kullanıldığında, yukarıdaki upstream yayınlanan 8065 portuna işaret eder. Bunu yalnızca 127.0.0.1 üzerinde yayınlayın (HTTP_PORT=127.0.0.1:8065), böylece kimse vekili atlayamaz.

antimatter-docker deposu, nginx'in bir konteynerde ve Let's Encrypt'in certbot üzerinden kullanıldığı tam bir kurulum içerir; deploy/compose dizininde bulunur.

Diğer vekiller

Yukarıdaki dört maddeyi karşılayan herhangi bir vekil çalışır. Sesli ve görüntülü aramalar asla vekil üzerinden geçmez: kendi portlarını kullanırlar, bkz. Aramalar ve ses.

Vekil arkasındaki istemci adresleri

Vekil arkasında her istek vekilden geliyormuş gibi görünür. Gerçek istemci adresini günlüğe kaydetmek, istemci başına hız sınırlamaları uygulamak ve IP filtreleme kullanmak için sunucuya adresi hangi başlığın taşıdığını ve hangi vekillere güvenebileceğini bildirin. Bu ayarların hiçbirinin Sistem Konsolu alanında karşılığı yoktur: bunları config.json içinde veya değişkenlerle ayarlayın.

Bir değişkende birden fazla değeri boşluklarla ayırın: AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP". Sunucu, TrustedProxyIPs içindeki bir girdinin ne bir IP adresi ne de bir CIDR aralığı olduğu bir yapılandırmayı reddeder.

Sunucunun istemcinin adresini nasıl bulduğu

Her vekil, isteği hangi adresten aldığını X-Forwarded-For başlığının sağına ekler. İstemcinin başlığın kendisinde gönderdiği her şey solda kalır. Böylece sunucu başlığı sağdan okur, güvenilir vekillerinizin adreslerini atlar ve istemcinin adresi olarak ilk diğer adresi alır. Bir istemci, kendi başlığını göndererek adresini seçemez.

• Tek bir vekilin arkasında, TrustedProxyIPHeader tek başına doğru adresi verir: sunucu başlığın en sağdaki adresini alır. TrustedProxyIPs değerini de ayarlayana kadar başlangıçta bir uyarı kaydeder. Bu yapılandırma yapılmazsa, 8065 portuna doğrudan ulaşabilen herkes başlığı ayarlayabilir; bu yüzden bu portu yalnızca 127.0.0.1 üzerinde veya özel bir ağda yayınlayın.
• Birden fazla vekilin arkasında, örneğin kendi vekilinizin önünde bir CDN veya yük dengeleyici varsa, hepsini TrustedProxyIPs içinde listeleyin. Aksi halde sunucu, dış vekilin adresini istemcinin adresi olarak alır.
• Vekil, yukarıdaki nginx örneğinde yaptığı gibi başlığı gördüğü adresle değiştirebilir (X-Forwarded-For $remote_addr) veya başlığa ekleyebilir (nginx'in $proxy_add_x_forwarded_for değeri). İkisi de çalışır.

Hangi adreslerin listeleneceği

Vekilin isteklerinin geldiği adresi, Antimatter'in gördüğü şekilde listeleyin.

• Sitein compose dosyası ve Caddy kullanıldığında bu zaten yapılmıştır: Caddy, Antimatter'e edge ağı üzerinden ulaşır ve compose dosyası TrustedProxyIPHeader değerini X-Forwarded-For olarak, TrustedProxyIPs değerini ise bu ağın aralığı olan EDGE_SUBNET olarak (.env dosyasında değiştirmediyseniz 172.29.71.0/28) ayarlar. EDGE_SUBNET değeri, ağlarınızdan biriyle örtüşüyorsa değiştirin.
• antimatter-docker'daki üretim kurulumu, nginx konteyneri için FRONTEND_SUBNET değeriyle aynı işlemi yapar.
• nginx ana makinede ve Antimatter Docker'da olduğunda, istekler Antimatter'e yayınlanan port üzerinden ulaşır, genellikle compose projesinin ağının geçiş adresinden (docker network inspect komutu bunu gösterir). compose.override.yaml dosyasında AM_SERVICESETTINGS_TRUSTEDPROXYIPS değerini bu adrese ayarlayın.
• Docker olmadan, aynı ana makinede nginx kullanıldığında adres 127.0.0.1 (nginx IPv6 üzerinden bağlanıyorsa ::1).

Aracı olmadan TLS

Sunucu, Sistem Konsolu › Ortam › Site sunucusu bölümünde HTTPS trafiğini kendisi de sunabilir: Bağlantı güvenliği TLS olarak ayarlanır (ServiceSettings.ConnectionSecurity), TLS sertifika dosyası ve TLS anahtar dosyası (ServiceSettings.TLSCertFile, ServiceSettings.TLSKeyFile) tanımlanır veya Let's Encrypt kullanılsın seçilir (ServiceSettings.UseLetsEncrypt). Bu durumda sunucunun 443 portunu dinlemesi gerekir (Dinlenecek adres, ServiceSettings.ListenAddress, varsayılan olarak :8065) ve ServiceSettings.Forward80To443 80 portunu yönlendirir. Geri proxy (reverse proxy) çalıştırmak ve yenilemek daha kolaydır ve bu kılavuz bu yapıyı varsayar.

Sunucu zaman aşımıları ve istek boyutu

Sunucunun kendi web sunucusuna ait ayarları, Sistem Konsolu › Ortam › Site sunucusu bölümünde bulunur:

Proxy'nin kendi zaman aşım sürelerini normal istekler için bu değerlerden en az uzun tutun ve gövde boyutunu en az En büyük dosya boyutu kadar ayarlayın.