Quack mit einem Reverse-Proxy absichern

Der Quack-Server spricht nur einfaches HTTP und bindet standardmäßig an Localhost. Die Begründung für diese Konfigurationen finden Sie unter Sicherheit. Für jedes Deployment jenseits von rein lokal gilt dasselbe Muster wie für jeden anderen HTTP-basierten Datenbank- / Anwendungsserver: Stellen Sie einen bewährten HTTP-Reverse-Proxy davor und lassen Sie den Proxy TLS terminieren.

Der Quack-Client spielt dabei mit: Für nicht-lokale URIs geht er standardmäßig von HTTPS aus, sodass ein korrekt vorgeschalteter Server auch von der Clientseite „einfach funktioniert“.

Diese Anleitung führt durch drei Setups, in der Reihenfolge ihrer wahrscheinlichen Nützlichkeit:

Ein lokales TLS-Testsetup mit Caddy, damit Sie den vollständigen HTTPS-Pfad auf Ihrer Maschine durchspielen können.
nginx + Let’s Encrypt in der Produktion.
Caddy + Let’s Encrypt in der Produktion.

Die beiden Produktionssetups sind austauschbar. Wählen Sie, was zu Ihrem Betriebsstack passt.

Lokales Testsetup mit Caddy

Sie können den vollständigen HTTPS-Pfad auf Ihrer eigenen Maschine mit Caddy durchspielen. Caddy stellt sich selbst ein Zertifikat für localhost von einer lokalen CA aus und installiert das CA-Root ins System-Trust-Store, sodass DuckDBs HTTPS-Client dem Zertifikat ohne Extra-Konfiguration vertraut.

1. Caddy ausführen

Speichern Sie diese Caddyfile:

localhost:8443 {
    reverse_proxy 127.0.0.1:9494 {
        flush_interval -1
    }

    request_body {
        max_size 256MB
    }
}

Starten Sie anschließend Caddy:

brew install caddy # macOS, for other platforms see https://caddyserver.com/docs/install
caddy run --config Caddyfile

Beim ersten Lauf werden Sie nach erhöhten Rechten gefragt, um Caddys lokale CA ins System-Trust-Store zu installieren. Danach werden von Caddy für localhost ausgestellte Zertifikate systemweit vertraut.

2. Quack starten und über den Proxy verbinden

In einer DuckDB-Sitzung starten Sie den Server (das gibt ein Authentifizierungstoken aus):

{:.codebox-server}

CALL quack_serve('quack:localhost');

In der Client-Sitzung verbinden Sie sich über Caddy auf :8443. Lokale URIs nutzen standardmäßig einfaches HTTP, daher müssen Sie SSL explizit erzwingen:

{:.codebox-server}

ATTACH 'quack:localhost:8443' AS quack (
    TOKEN '⟨authentication_token-from-quack_serve⟩',
    DISABLE_SSL false
);

FROM quack.query('SELECT 42');

Wenn der Roundtrip gelingt, ist Ihr Verkehr als TLS zu Caddy gegangen, wurde terminiert und als einfaches HTTP an Quack auf :9494 weitergeleitet.

Nginx + Let’s Encrypt

Das dürfte die häufigste Wahl sein. Eine minimale Site für einen Quack-Server, der auf der Loopback-Schnittstelle lauscht, sieht wie folgt aus:

server {
    listen 443 ssl http2;
    server_name quack.example.com;

    ssl_certificate     /etc/letsencrypt/live/quack.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/quack.example.com/privkey.pem;

    # Quack RPC bodies can be large: PREPARE carries SQL, APPEND carries
    # inserted DataChunks. The 1 MiB nginx default will fail mid-INSERT.
    client_max_body_size 256M;

    # Long-running queries can sit on the wire between FETCHes for
    # minutes. Raise the timeouts above nginx's default 60s.
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;

    location / {
        proxy_pass http://127.0.0.1:9494;

        # Keep-alive against upstream. Quack relies on persistent
        # connections to keep server-side `quack_connection_id` state alive.
        proxy_http_version 1.1;
        proxy_set_header Connection "";

        # Quack streams results via repeated FETCH responses; buffering
        # through nginx defeats the streaming and inflates memory.
        proxy_buffering off;
    }
}

Auf der Quack-Seite starten Sie den Server an Localhost gebunden (der Standard):

{:.codebox-server}

CALL quack_serve('quack:localhost');

Stellen Sie das Zertifikat mit certbot --nginx -d quack.example.com aus. Clients verbinden sich automatisch über HTTPS:

{:.codebox-client}

ATTACH 'quack:quack.example.com' AS quack;   -- HTTPS auto-selected

Caddy + Let’s Encrypt

Caddy bezieht Zertifikate automatisch von Let’s Encrypt und braucht fast keine Konfiguration. Ein vollständiger öffentlich erreichbarer Quack-Proxy:

quack.example.com {
    reverse_proxy 127.0.0.1:9494 {
        # Equivalent of nginx `proxy_buffering off`. Required so Quack's
        # streamed FETCH responses pass through immediately instead of
        # being buffered in Caddy.
        flush_interval -1
    }

    # Equivalent of nginx `client_max_body_size`. PREPARE / APPEND bodies
    # can be much larger than the default request body cap.
    request_body {
        max_size 256MB
    }
}

Caddy übernimmt Ausstellung und Erneuerung der Zertifikate automatisch. Ein certbot-Schritt ist nicht nötig.

Auf der Quack-Seite starten Sie den Server an Localhost gebunden (der Standard):

{:.codebox-server}

CALL quack_serve('quack:localhost');

Clients verbinden sich automatisch über HTTPS:

{:.codebox-client}

ATTACH 'quack:quack.example.com' AS quack;   -- HTTPS auto-selected