Zum Inhalt springen

Reverse Proxy für SQL2REST

HTTPS-Termination für externe Zugriffe einrichten. Zwei dokumentierte Pfade: Cloudflare Tunnel als Default-Empfehlung und Caddy als DIY-Alternative.

Brauchst du diesen Guide überhaupt?

In drei Szenarien brauchst du diese Anleitung nicht. Wenn eines davon zutrifft, kannst du den Rest der Seite überspringen.

  • Dein Server läuft schon hinter HTTPS bei einem JTL-Hoster (z.B. CMO, ecomDATA, vergleichbare). Der Hoster terminiert TLS am Edge und routet intern auf den SQL2REST-Port. Du musst nichts tun.
  • Du hast einen eigenen Webserver (IIS, nginx, Apache) mit gültigem Cert und kannst reverse_proxy / URL Rewrite auf SQL2REST's Port konfigurieren. Dann brauchst du diesen Guide nicht, nur einen zusätzlichen Vhost- oder Location-Block.
  • Du nutzt schon einen Cloudflare Tunnel für andere Services (z.B. JTL-Wawi-Remote-Access). Dann ergänzt du nur eine ingress-Zeile in deiner bestehenden config.yml, der Rest dieses Guides ist Setup-Wiederholung.

Wenn keines davon zutrifft, einfach weiterlesen.

Wofür brauchst du HTTPS?

Zwei Use-Cases treiben die HTTPS-Anforderung. Beide laufen über denselben Reverse-Proxy, ohne dass du etwas trennen musst.

(a) MCP für mehrere Workstations

Claude Desktop, Claude Code, Cursor und Windsurf greifen auf eine zentrale SQL2REST-Installation zu. Jede Arbeitsplatz-IDE spricht den HTTP-MCP-Endpoint /mcp an. Ohne HTTPS würde der API-Key bei jedem Aufruf im Klartext durch das öffentliche Netz wandern. Verfügbar ab v1.1.96 (Team-Tarif für Remote-MCP zwischen Workstations).

(b) Externer API-Zugriff

Eigene Integrationen, Dashboards, CRM-Sync oder Webhook-Empfänger sprechen die REST-Endpunkte unter /api/*. Der gleiche Reverse-Proxy bedient beide Pfade in einem Mount.

Claude Desktop: ein Auth-Sonderfall

Claude Desktop pusht in der UI zu OAuth. Für die hier beschriebene X-API-Key-Auth braucht jede Workstation einen lokalen mcp-remote-Proxy in der claude_desktop_config.json. Native MCP-Clients (Claude Code, Cursor, Windsurf) sprechen HTTP-MCP direkt mit Custom-Headern und brauchen den Proxy nicht. Eine vollständige Anleitung findest du auf JTL-Wawi mit Claude Desktop verbinden.

Warum überhaupt Reverse-Proxy?

SQL2REST authentifiziert per X-API-Key-Header. Über plain HTTP im öffentlichen Netz wandert dieser Header im Klartext. Jeder Knoten dazwischen kann ihn mitlesen und sofort wiederverwenden. Im LAN ist das tolerierbar, im Internet nicht.

Reverse-Proxy ist die Industrie-Standard-Lösung: Ein vorgelagerter Dienst terminiert TLS (HTTPS), kümmert sich um Cert-Renewal und reicht intern via plain HTTP an SQL2REST weiter. Vorteile gegenüber HTTPS-im-Anwendung: kein Cert-Management im Build, keine Race-Conditions beim Renewal, kein Mehrwert durch eigene TLS-Implementierung.

Cloudflare Tunnel vs. Caddy

Beide Pfade liefern HTTPS-Termination. Die Wahl hängt davon ab, ob du eine eigene Domain mit DNS-Zugriff hast und ob du Ports am Router aufmachen kannst.

Pfad Cert-Management Setup-Zeit Domain nötig Wann passend
Cloudflare Tunnel CF macht HTTPS ~15 Min Subdomain einer CF-verwalteten Domain reicht Default-Empfehlung, keine Port-Freigabe nötig
Caddy Auto Let's Encrypt ~30 Min Eigene Domain mit DNS-Zugriff DIY-Sysadmin, klassischer VPS oder eigener Server mit Port 80/443

Cloudflare Tunnel (Default-Empfehlung)

Kein Port-Forwarding am Router, kein Cert-Management, kein eigener öffentlicher Webserver. Eine Subdomain auf einer in Cloudflare verwalteten Domain reicht. Der Free-Tier deckt den SQL2REST-Bedarf bequem ab.

Schritt für Schritt

  1. Cloudflare-Account anlegen (kostenlos).
  2. Domain (oder eine Subdomain einer eigenen Domain) auf Cloudflare-Nameserver legen. Cloudflare zeigt die Nameserver beim Anlegen der Zone an.
  3. cloudflared für Windows herunterladen und als Service installieren.
  4. Browser-Login einmalig durchführen:
cmd
cloudflared tunnel login
  1. Named Tunnel erstellen:
cmd
cloudflared tunnel create sql2rest
  1. config.yml anlegen unter %USERPROFILE%\.cloudflared\config.yml:
config.yml
tunnel: <TUNNEL-ID>
credentials-file: C:\Users\<USER>\.cloudflared\<TUNNEL-ID>.json

ingress:
  # Service-Mount deckt sowohl /api/* (REST) als auch /mcp (MCP) ab,
  # kein Extra-Routing noetig.
  - hostname: sql2rest.kunde.de
    service: http://localhost:8000
  - service: http_status:404
  1. DNS-Eintrag erzeugen (CNAME auf den Tunnel):
cmd
cloudflared tunnel route dns sql2rest sql2rest.kunde.de
  1. Als Windows-Service installieren, damit der Tunnel Reboots überlebt:
cmd
cloudflared service install
  1. Verifizieren: Im Browser https://sql2rest.kunde.de/health öffnen. Erwartet wird ein 200-Response mit JSON-Body. Für authentifizierte Endpunkte den API-Key im Header mitsenden:
cmd
curl -H "X-API-Key: YOUR_KEY" https://sql2rest.kunde.de/customers

Typische Pannen

  • Service nicht gestartet: sc query cloudflared zeigt RUNNING? Falls nicht: cloudflared service install erneut, dann net start cloudflared.
  • DNS nicht propagiert: 1 bis 2 Minuten warten oder mit nslookup sql2rest.kunde.de prüfen. Im CF-Dashboard kontrollieren, dass der CNAME auf <TUNNEL-ID>.cfargotunnel.com zeigt.
  • Falscher localhost-Port: Der Port in config.yml muss dem [API] Port aus deiner config.ini entsprechen (Standard 8000).

Caddy (DIY-Alternative)

Minimaler Caddyfile, automatisches Let's-Encrypt-Cert, läuft als Windows-Service. Passt zur DIY-Sysadmin-Welt: eigene Domain, eigener Server, Port 80 und 443 erreichbar.

Voraussetzungen

  • Eigene Domain mit DNS-A-Record auf die öffentliche IP des Servers.
  • Port 80 und 443 müssen vom Internet aus erreichbar sein (für die Let's-Encrypt-Validation).
  • SQL2REST läuft lokal auf dem gleichen Server, Standard-Port 8000.

Schritt für Schritt

  1. Caddy für Windows herunterladen (Standard-Build reicht, keine Module nötig).
  2. Caddyfile im Caddy-Verzeichnis anlegen:
Caddyfile
sql2rest.kunde.de {
    # reverse_proxy deckt sowohl /api/* (REST) als auch /mcp (MCP) ab,
    # kein Extra-Routing noetig.
    reverse_proxy localhost:8000
}
  1. Caddy als Windows-Service einrichten (zum Beispiel über NSSM), oder zum Testen im Vordergrund laufen lassen:
cmd
caddy run --config Caddyfile
  1. Erst-Run holt automatisch ein Let's-Encrypt-Cert. Im Log sollte eine "certificate obtained"-Zeile erscheinen. Renewal läuft danach im Hintergrund.
  2. Verifizieren: https://sql2rest.kunde.de/health öffnen. Anschließend mit API-Key:
cmd
curl -H "X-API-Key: YOUR_KEY" https://sql2rest.kunde.de/customers

Typische Pannen

  • Cert-Provisioning schlägt fehl: Port 80 ist nicht von außen erreichbar. Router-Forwarding und Windows-Firewall prüfen. Let's Encrypt validiert per HTTP-01-Challenge auf Port 80.
  • DNS falsch: A-Record muss auf die öffentliche IP zeigen, nicht auf eine LAN-IP. Mit nslookup sql2rest.kunde.de prüfen.
  • 502 Bad Gateway: Caddy läuft, aber SQL2REST nicht. sc query sql2rest oder die Setup-Wizard-Service-Anzeige checken.

Was als Nächstes