Wdrożenie i HTTPS

2 min czytania

PgArachne jest zaprojektowany tak, aby dobrze wykonywać jedno zadanie: API Gateway. Dla SSL/TLS (HTTPS), bezpieczeństwa nagłówków i publicznego routingu, powinieneś umieścić przed nim Reverse Proxy.

Opcja A: Caddy Server

Najlepsze dla: Nowoczesnych wdrożeń produkcyjnych, łatwości użycia.

Caddy to jedyny serwer WWW, który domyślnie automatycznie uzyskuje i odnawia certyfikaty SSL (Let’s Encrypt). Wymaga prawie zerowej konfiguracji.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Opcja B: Nginx

Najlepsze dla: Środowisk enterprise, złożonego routingu.

Nginx jest branżowym standardem dla wysokowydajnego load balancingu. Użyj go, jeśli już masz infrastrukturę Nginx. Certbota będziesz musiał zarządzać ręcznie.

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

Opcja C: Ngrok

Najlepsze dla: Lokalnego developmentu, demonstracji, testowania webhooków.

Ngrok tworzy bezpieczny tunel z publicznego internetu bezpośrednio do twojego laptopa, bez konfigurowania zapór sieciowych. Idealne do natychmiastowego pokazania swojej pracy współpracownikom.

./ngrok http 8080

Lista kontrolna produkcyjna

Terminuj TLS na reverse proxy i przekazuj dalej X-Forwarded-Proto oraz X-Forwarded-For.
Ustaw TRUSTED_PROXIES w PgArachne na zakresy IP/CIDR twojego proxy.
Wyłącz buforowanie dla tras SSE i ustaw wystarczająco długie limity czasu odczytu dla streamingu.
Udostępniaj metryki tylko wewnętrznie (domyślnie 127.0.0.1:9090) i pobieraj je z sieci monitoringu.

Przykład hardeningu Nginx (SSE, pobieranie plików, przekazywane nagłówki)

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

Zastąp db swoją wartością API_PREFIX, jeśli ją zmieniłeś.

Duże pliki do pobrania (`/file`) za reverse proxy

Wyłącz buforowanie odpowiedzi (proxy_buffering off w Nginx). Pojedynczy plik jest wysyłany z nagłówkiem Content-Length, archiwum ZIP jest strumieniowane bez niego. Przy włączonym buforowaniu Nginx najpierw zapisuje całą odpowiedź do pliku tymczasowego, co opóźnia start pobierania i zajmuje miejsce na dysku.
Zwiększ timeout odczytu (proxy_read_timeout, domyślnie 60 s), jeśli funkcja bazy danych budująca pliki może działać dłużej — PgArachne nie wysyła nic, dopóki funkcja nie zwróci wszystkich wierszy.
Nie kompresuj application/zip ani już skompresowanych typów mediów (gzip na ZIP-ie tylko marnuje CPU).
Limit pamięci: PgArachne buforuje wiersze jednej odpowiedzi w pamięci (ograniczone przez FILE_MAX_BYTES, domyślnie 64 MiB, oraz FILE_MAX_ENTRIES); dobierz limity do spodziewanej liczby równoczesnych pobrań. client_max_body_size dotyczy tylko małego żądania JSON, nie pobierania.
Caddy domyślnie strumieniuje odpowiedzi; nie jest potrzebna dodatkowa konfiguracja.

← Bezpieczeństwo i uwierzytelnianie Kody błędów →

Wdrożenie i HTTPS