Bereitstellung & HTTPS

2 Min. Lesezeit

Bereitstellung & HTTPS

PgArachne ist darauf ausgelegt, eine Aufgabe gut zu erfüllen: API Gateway. Für SSL/TLS (HTTPS), Header-Sicherheit und öffentliches Routing sollten Sie einen Reverse Proxy davor platzieren.

Option A: Caddy Server

Am besten für: Moderne Produktionsbereitstellungen, Benutzerfreundlichkeit.

Caddy ist der einzige Webserver, der standardmäßig automatisch SSL-Zertifikate (Let’s Encrypt) bezieht und erneuert. Er erfordert fast keine Konfiguration.

# Caddyfile
example.com {
    reverse_proxy localhost:8080
}

Option B: Nginx

Am besten für: Unternehmensumgebungen, komplexes Routing.

Nginx ist der Industriestandard für hochleistungsfähiges Load Balancing. Verwenden Sie dies, wenn Sie bereits eine Nginx-Infrastruktur haben. Sie müssen Certbot manuell verwalten.

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

Option C: Ngrok

Am besten für: Lokale Entwicklung, Demos, Webhook-Tests.

Ngrok erstellt einen sicheren Tunnel vom öffentlichen Internet direkt zu Ihrem Laptop, ohne Firewalls zu konfigurieren. Ideal, um Kollegen Ihre Arbeit sofort zu zeigen.

./ngrok http 8080

Produktions-Checkliste

TLS am Reverse Proxy terminieren und X-Forwarded-Proto sowie X-Forwarded-For weiterreichen.
In PgArachne TRUSTED_PROXIES auf die Proxy-IP/CIDR-Bereiche setzen.
Für SSE-Routen Buffering deaktivieren und ausreichend lange Read-Timeouts setzen.
Metriken nur intern exponieren (Standard 127.0.0.1:9090) und aus dem Monitoring-Netz scrapen.

Nginx-Hardening-Beispiel (SSE, Datei-Downloads, Forwarded Header)

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

Ersetzen Sie db durch Ihren API_PREFIX, falls Sie ihn geändert haben.

Große Downloads (`/file`) hinter einem Reverse Proxy

Response-Buffering deaktivieren (proxy_buffering off in Nginx). Eine einzelne Datei wird mit Content-Length gesendet, ein ZIP-Archiv ohne. Bei aktiviertem Buffering legt Nginx zuerst die gesamte Antwort in einer temporären Datei ab, was den Beginn des Downloads verzögert und Speicherplatz kostet.
Read-Timeout erhöhen (proxy_read_timeout, Standard 60 s), wenn die Datenbankfunktion, die die Dateien erzeugt, länger laufen kann — PgArachne sendet nichts, bis die Funktion alle Zeilen zurückgegeben hat.
Nicht komprimieren: application/zip und andere bereits komprimierte Medientypen (gzip auf einem ZIP verbraucht nur CPU).
Speicherlimit: PgArachne hält die Zeilen einer Antwort im Speicher (begrenzt durch FILE_MAX_BYTES, Standard 64 MiB, und FILE_MAX_ENTRIES); dimensionieren Sie die Limits passend zur erwarteten Zahl gleichzeitiger Downloads. client_max_body_size betrifft nur die kleine JSON-Anfrage, nicht den Download.
Caddy streamt Antworten standardmäßig; keine zusätzliche Konfiguration nötig.

← Sicherheit & Authentifizierung Fehlercodes →

Bereitstellung & HTTPS