Nasazení a HTTPS

2 min čtení

PgArachne je navržen tak, aby dělal jednu věc dobře: API Gateway. Pro SSL/TLS (HTTPS), bezpečnost hlaviček a veřejné směrování byste před něj měli umístit reverzní proxy.

Možnost A: Caddy Server

Nejlepší pro: Moderní produkční nasazení, snadné použití.

Caddy je jediný webový server, který ve výchozím nastavení automaticky získává a obnovuje SSL certifikáty (Let’s Encrypt). Vyžaduje téměř nulovou konfiguraci.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Možnost B: Nginx

Nejlepší pro: Enterprise prostředí, komplexní směrování.

Nginx je průmyslovým standardem pro vysoce výkonné vyvažování zátěže (load balancing). Použijte jej, pokud již máte infrastrukturu Nginx. Certbot budete muset spravovat ručně.

server {
    server_name example.com;
    location / {
        proxy_pass http://localhost:8080;
    }
}

Možnost C: Ngrok

Nejlepší pro: Lokální vývoj, dema, testování webhooků.

Ngrok vytváří bezpečný tunel z veřejného internetu přímo do vašeho notebooku bez konfigurace firewallu. Ideální pro okamžité ukázky kolegům.

./ngrok http 8080

Produkční checklist

Ukončete TLS na reverse proxy a přeposílejte X-Forwarded-Proto a X-Forwarded-For.
V PgArachne nastavte TRUSTED_PROXIES na IP/CIDR rozsahy vašich proxy.
Pro SSE cesty vypněte buffering a nastavte delší read timeouty pro stream.
Metriky publikujte jen interně (výchozí 127.0.0.1:9090) a scrape provádějte z monitorovací sítě.

Ukázka hardeningu Nginx (SSE, stahování souborů, forwarded hlavičky)

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

# SSE: /{API_PREFIX}/{database}/sse — long-lived stream, must not be buffered
location ~ ^/db/[^/]+/sse$ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_buffering off;
    proxy_read_timeout 1h;
}

# File downloads: /{API_PREFIX}/{database}/file — large files and ZIP archives
location ~ ^/db/[^/]+/file/?$ {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_buffering off;
    proxy_read_timeout 300s;
}

Pokud jste změnili API_PREFIX, nahraďte db svou hodnotou.

Velká stahování (`/file`) za reverzní proxy

Vypněte buffering odpovědí (proxy_buffering off v Nginxu). Jeden soubor se odesílá s hlavičkou Content-Length, ZIP archiv se streamuje bez ní. Se zapnutým bufferingem Nginx nejprve celou odpověď uloží do dočasného souboru, což zpozdí začátek stahování a spotřebovává místo na disku.
Zvyšte read timeout (proxy_read_timeout, výchozí 60 s), pokud databázová funkce, která soubory sestavuje, může běžet déle — PgArachne neodešle nic, dokud funkce nevrátí všechny řádky.
Nekomprimujte application/zip ani jiné již komprimované typy médií (gzip na ZIPu jen zbytečně zatěžuje CPU).
Limit paměti: PgArachne drží řádky jedné odpovědi v paměti (omezeno FILE_MAX_BYTES, výchozí 64 MiB, a FILE_MAX_ENTRIES); limity nastavte podle očekávaného počtu souběžných stahování. client_max_body_size se týká jen malého JSON požadavku, nikoli stahování.
Caddy odpovědi streamuje ve výchozím nastavení; žádná další konfigurace není potřeba.

← Bezpečnost a autentizace Chybové kódy →

Nasazení a HTTPS