> ## Documentation Index > Fetch the complete documentation index at: https://docs.varios-ai.com/llms.txt > Use this file to discover all available pages before exploring further. # VARIOS AI hinter einem Reverse Proxy betreiben > VARIOS AI über einen vorhandenen Reverse Proxy Ihres Unternehmens erreichbar machen, etwa mit Clientzertifikats-Authentifizierung Viele Unternehmen veröffentlichen interne Anwendungen über einen zentralen Reverse Proxy, der HTTPS terminiert und zusätzliche Zugriffskontrollen wie Clientzertifikate übernimmt. VARIOS AI lässt sich hinter einen solchen Proxy stellen. Diese Seite beschreibt, was VARIOS AI vom Proxy erwartet und welche Änderungen an der `docker-compose.yml` nötig sind. > [!NOTE] > > Jede Proxy-Umgebung ist anders aufgebaut. Die Konfigurationsbeispiele auf dieser Seite verwenden nginx und zeigen die Anforderungen von VARIOS AI. Übertragen Sie sie sinngemäß auf Ihr Produkt, etwa Apache, HAProxy, F5 oder einen Webserver mit eigenem Proxy-Modul. ## Aufbau ```text theme={null} Browser ──HTTPS──▶ Reverse Proxy ──HTTPS oder HTTP──▶ Traefik (VARIOS-AI-Server) ──▶ VARIOS AI ``` * Die Domain aus `PROJECT_DOMAIN` zeigt im DNS auf den **Reverse Proxy**, nicht auf den VARIOS-AI-Server. * Der Reverse Proxy stellt das Zertifikat aus, das die Nutzer sehen, und prüft bei Bedarf die Clientzertifikate. * Traefik bleibt auf dem VARIOS-AI-Server unverändert im Einsatz und nimmt die Anfragen des Proxys entgegen. * Auf dem VARIOS-AI-Server wird kein öffentlich gültiges Zertifikat benötigt. Let's Encrypt wird abgeschaltet. ## Anforderungen an den Reverse Proxy | Anforderung | Hintergrund | | - | - | | **Domain identisch mit `PROJECT_DOMAIN`** | VARIOS AI erzeugt Links, die WebSocket-Adresse `wss:///ws` und die Anmelde-Weiterleitung aus diesem Wert. Der Proxy muss VARIOS AI unter genau dieser Domain per HTTPS ausliefern. | | **`Host`-Header unverändert weitergeben** | Traefik ordnet Anfragen über die Regel ``Host(`${PROJECT_DOMAIN}`)`` zu. Kommt ein anderer Host an, antwortet Traefik mit `404`. | | **WebSocket für `/ws` erlauben** | Chat-Antworten werden per WebSocket übertragen. Der Proxy muss den Verbindungsaufbau per HTTP-Upgrade durchreichen (`Upgrade`- und `Connection`-Header, HTTP/1.1). | | **Lange Timeouts** | Antworten von Sprachmodellen können mehrere Minuten dauern. VARIOS AI selbst wartet bis zu 3600 Sekunden. Setzen Sie die Lese- und Sende-Timeouts des Proxys auf denselben Wert. | | **Upload-Größe** | VARIOS AI nimmt Anfragen bis 512 MB an, etwa für Dokumente in Wissensdatenbanken. Ein kleineres Limit am Proxy führt bei großen Uploads zum Fehler `413`. | | **Keine Pufferung der Antworten** | Gestreamte Antworten sollen ohne Verzögerung beim Browser ankommen. Schalten Sie die Antwortpufferung des Proxys für VARIOS AI ab. | `X-Forwarded-*`-Header werden von VARIOS AI ausgewertet; in der `docker-compose.yml` ist dafür `FLOW_HTTP_TRUSTED_PROXIES: "*"` bereits gesetzt. Wie diese Header durch Traefik gelangen, hängt von der gewählten Verbindung ab, siehe unten. ## VARIOS-AI-Server anpassen Wählen Sie, wie der Reverse Proxy Traefik erreicht. Wir empfehlen **HTTPS auf Port 443**: Die Strecke im Netz bleibt verschlüsselt, und es sind die wenigsten Änderungen nötig. **HTTPS auf Port 443 (empfohlen)** Der Proxy leitet an `https://:443` weiter. Traefik setzt `X-Forwarded-Proto: https` selbst, weil die Verbindung per HTTPS ankommt. **1. Let's Encrypt am Router abschalten** Entfernen Sie am `php`-Service das Label mit dem Certificate Resolver. Alle anderen Labels bleiben unverändert: ```yaml docker-compose.yml theme={null} php: [...] labels: - "traefik.enable=true" # entfernt: traefik.http.routers.variosai.tls.certresolver=le - "traefik.http.routers.variosai.tls=true" - "traefik.http.routers.variosai.rule=Host(`${PROJECT_DOMAIN}`)" - "traefik.http.routers.variosai.entrypoints=websecure" - "traefik.http.services.variosai.loadbalancer.server.port=80" - "traefik.http.routers.http-variosai.middlewares=redirect-https" - "traefik.http.routers.http-variosai.rule=Host(`${PROJECT_DOMAIN}`)" - "traefik.http.routers.http-variosai.entrypoints=web" - "traefik.http.middlewares.redirect-https.redirectscheme.scheme=https" - "traefik.http.middlewares.redirect-https.redirectscheme.permanent=true" ``` Ohne eigenes Zertifikat liefert Traefik sein selbstsigniertes Standardzertifikat (`TRAEFIK DEFAULT CERT`) aus. Der Proxy muss dieses Zertifikat entweder ohne Prüfung akzeptieren oder Sie hinterlegen ein Zertifikat Ihrer internen CA, dem der Proxy vertraut, siehe [Eigenes HTTPS-Zertifikat konfigurieren](https://docs.varios-ai.com/de/extended-support/security/traefik-certificates.md). **2. Optional: Client-IP-Adressen übernehmen** Traefik verwirft `X-Forwarded-For` von unbekannten Absendern. Ohne weitere Einstellung erscheint deshalb in Protokollen die IP-Adresse des Proxys statt der des Nutzers. Damit Traefik die Header des Proxys übernimmt, ergänzen Sie im `command`-Block des `traefik`-Service die IP-Adresse des Proxys: ```yaml docker-compose.yml theme={null} traefik: command: [...] - "--entrypoints.websecure.address=:443" - "--entrypoints.websecure.forwardedHeaders.trustedIPs=" ``` Mehrere Adressen oder Netze trennen Sie mit Komma, etwa `10.0.0.5,10.0.1.0/24`. **3. Änderungen anwenden** ```bash theme={null} docker compose up -d ``` **HTTP auf Port 80** Der Proxy leitet unverschlüsselt an `http://:80` weiter. Verwenden Sie diesen Weg nur, wenn die Strecke zwischen Proxy und VARIOS-AI-Server vertrauenswürdig ist. **1. Weiterleitung auf HTTPS entfernen** Der Router `http-variosai` leitet in der Standardkonfiguration jede Anfrage auf HTTPS um. Hinter einem Proxy, der per HTTP weiterleitet, entsteht dadurch eine Endlosschleife. Entfernen Sie am `php`-Service die Weiterleitung und den Certificate Resolver: ```yaml docker-compose.yml theme={null} php: [...] labels: - "traefik.enable=true" # entfernt: traefik.http.routers.variosai.tls.certresolver=le - "traefik.http.routers.variosai.tls=true" - "traefik.http.routers.variosai.rule=Host(`${PROJECT_DOMAIN}`)" - "traefik.http.routers.variosai.entrypoints=websecure" - "traefik.http.services.variosai.loadbalancer.server.port=80" # entfernt: traefik.http.routers.http-variosai.middlewares=redirect-https - "traefik.http.routers.http-variosai.rule=Host(`${PROJECT_DOMAIN}`)" - "traefik.http.routers.http-variosai.entrypoints=web" # entfernt: traefik.http.middlewares.redirect-https.redirectscheme.scheme=https # entfernt: traefik.http.middlewares.redirect-https.redirectscheme.permanent=true ``` **2. Weitergeleitete Header des Proxys übernehmen** Traefik ersetzt `X-Forwarded-Proto` von unbekannten Absendern durch das eigene Protokoll, hier `http`. VARIOS AI würde dann annehmen, es werde per HTTP aufgerufen. Ergänzen Sie im `command`-Block des `traefik`-Service die IP-Adresse des Proxys, damit Traefik dessen Header übernimmt: ```yaml docker-compose.yml theme={null} traefik: command: [...] - "--entrypoints.web.address=:80" - "--entrypoints.web.forwardedHeaders.trustedIPs=" ``` Mehrere Adressen oder Netze trennen Sie mit Komma, etwa `10.0.0.5,10.0.1.0/24`. > [!WARNING] > > Ohne diesen Schritt muss der Proxy trotzdem `X-Forwarded-Proto: https` senden, Traefik überschreibt den Wert aber. Fehlerhafte Anmelde-Weiterleitungen auf `http://` sind die Folge. **3. Änderungen anwenden** ```bash theme={null} docker compose up -d ``` Wird Let's Encrypt gar nicht mehr genutzt, können Sie zusätzlich die Optionen `--certificatesresolvers.le.*` aus dem `command`-Block des `traefik`-Service entfernen. > [!WARNING] > > Beschränken Sie den Zugriff auf die Ports 80 und 443 des VARIOS-AI-Servers per Firewall auf den Reverse Proxy. Andernfalls können Nutzer den Proxy und damit die Clientzertifikats-Prüfung umgehen, indem sie den Server direkt ansprechen. ## Beispielkonfiguration für nginx Das Beispiel zeigt einen nginx als Reverse Proxy mit Clientzertifikats-Prüfung und Weiterleitung per HTTPS. Ersetzen Sie Domain, Zertifikatspfade und Serveradresse durch Ihre Werte. ```nginx /etc/nginx/conf.d/varios-ai.conf theme={null} map $http_upgrade $connection_upgrade { default upgrade; '' close; } server { listen 443 ssl; server_name varios.example.com; ssl_certificate /etc/nginx/certs/varios.example.com.crt; ssl_certificate_key /etc/nginx/certs/varios.example.com.key; # Clientzertifikate prüfen ssl_client_certificate /etc/nginx/certs/client-ca.pem; ssl_verify_client on; client_max_body_size 512M; location / { proxy_pass https://; proxy_ssl_server_name on; proxy_ssl_name varios.example.com; proxy_ssl_verify off; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto https; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; proxy_buffering off; proxy_read_timeout 3600s; proxy_send_timeout 3600s; } } ``` `proxy_ssl_verify off` ist nur nötig, solange Traefik sein Standardzertifikat ausliefert. Haben Sie in Traefik ein Zertifikat Ihrer internen CA hinterlegt, setzen Sie stattdessen `proxy_ssl_verify on` und `proxy_ssl_trusted_certificate` auf diese CA. ## Zugriffe ohne Clientzertifikat Mit Clientzertifikats-Authentifizierung erreichen nur Geräte mit ausgerolltem Zertifikat VARIOS AI. Einige Zugriffe kommen jedoch nicht aus dem Browser eines Nutzers. Prüfen Sie, welche davon in Ihrer Installation genutzt werden: | Zugriff | Pfad | Betroffen, wenn | Lösung | | - | - | - | - | | **Anmeldung über Entra ID oder Keycloak** | `/login`, `/oauth2` | Nicht betroffen: Der Browser kehrt nach der Anmeldung mit seinem Zertifikat zu VARIOS AI zurück. | – | | **Benutzersynchronisation von Entra ID** | `/scim` | `SCIM_DIRECTION=push`: Entra ID sendet aus der Microsoft-Cloud und kann kein Clientzertifikat vorlegen. | Pfad `/scim` von der Zertifikatspflicht ausnehmen oder auf `SCIM_DIRECTION=pull` umstellen, siehe [Microsoft Entra ID](https://docs.varios-ai.com/de/extended-support/installation/microsoft-entra-id.md). | | **API-Zugriffe mit API-Schlüssel** | `/api` | Externe Systeme wie der [n8n-Node](https://docs.varios-ai.com/de/extended-support/installation/n8n-node.md) oder eigene Skripte rufen die API auf. | Den Systemen ein Clientzertifikat ausstellen. Eine Ausnahme für `/api` öffnet die gesamte API, die auch die Oberfläche verwendet. | | **Keycloak hinter demselben Proxy** | Keycloak-Domain | VARIOS AI ruft Keycloak serverseitig über `OIDC_CONFIGURATION_URL` auf und legt dabei kein Clientzertifikat vor. | Die Keycloak-Domain ohne Zertifikatspflicht veröffentlichen oder VARIOS AI eine interne Route zu Keycloak geben. | Eine Ausnahme für einen einzelnen Pfad lässt sich in nginx mit `ssl_verify_client optional` umsetzen. Die Prüfung erfolgt dann je `location`: ```nginx theme={null} ssl_verify_client optional; location /scim/ { # ohne Clientzertifikat, geschützt durch SCIM_TOKEN proxy_pass https://; # [...] gleiche proxy_*-Einstellungen wie unter location / } location / { if ($ssl_client_verify != SUCCESS) { return 403; } proxy_pass https://; # [...] } ``` ## Prüfen **1. Aufruf über den Proxy** Öffnen Sie `https://` auf einem Gerät mit Clientzertifikat und melden Sie sich an. > [!TIP] > > Nach der Anmeldung landen Sie wieder unter `https://`, nicht unter `http://` oder einer internen Adresse. **2. WebSocket** Stellen Sie im Chat eine Frage. > [!TIP] > > Die Antwort erscheint fortlaufend. In den Entwicklertools des Browsers zeigt der Tab **Netzwerk** für `wss:///ws` den Status `101`. **3. Direkter Zugriff gesperrt** Rufen Sie von einem Arbeitsplatz `https://` direkt auf. > [!TIP] > > Die Verbindung wird von der Firewall abgewiesen. ## Fehlerbehebung | Symptom | Ursache | Lösung | | - | - | - | | `404 page not found` von Traefik | Proxy gibt einen anderen `Host`-Header weiter | `Host`-Header unverändert weiterreichen, in nginx `proxy_set_header Host $host` | | Browser bricht mit „zu viele Weiterleitungen“ ab | Proxy leitet per HTTP weiter, Traefik leitet zurück auf HTTPS | Weiterleitung `redirect-https` entfernen, siehe Tab **HTTP auf Port 80** | | Nach der Anmeldung Weiterleitung auf `http://` | `X-Forwarded-Proto` kommt nicht als `https` bei VARIOS AI an | Bei HTTP-Weiterleitung `forwardedHeaders.trustedIPs` am Entrypoint `web` setzen | | Chat-Antworten erscheinen nicht oder erst am Ende | WebSocket-Upgrade wird blockiert oder Antworten werden gepuffert | `Upgrade`/`Connection`-Header und HTTP/1.1 setzen, Pufferung abschalten | | Lange Antworten brechen nach etwa 60 Sekunden ab | Standard-Timeout des Proxys | Lese- und Sende-Timeout auf 3600 Sekunden erhöhen | | Upload großer Dateien schlägt mit `413` fehl | Upload-Limit des Proxys zu klein | Limit auf 512 MB erhöhen, in nginx `client_max_body_size` | | `unable to generate TLS certificate` im Traefik-Log | Let's-Encrypt-Resolver noch aktiv | Label `tls.certresolver=le` am `php`-Service entfernen | | Proxy meldet Fehler beim TLS-Handshake mit Traefik | Proxy prüft das Standardzertifikat von Traefik oder sendet kein SNI bei aktivem `sniStrict` | Prüfung abschalten oder internes Zertifikat hinterlegen; SNI aktivieren, in nginx `proxy_ssl_server_name on` | | Benutzersynchronisation von Entra ID schlägt fehl | Proxy verlangt für `/scim` ein Clientzertifikat | Ausnahme für `/scim` einrichten oder `SCIM_DIRECTION=pull` verwenden | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.