VARIOS AI hinter einem Reverse Proxy betreiben

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.

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

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://<PROJECT_DOMAIN>/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)
HTTP auf Port 80

Der Proxy leitet an https://<VARIOS-AI-Server>:443 weiter. Traefik setzt X-Forwarded-Proto: https selbst, weil die Verbindung per HTTPS ankommt.

Let's Encrypt am Router abschalten

Entfernen Sie am php-Service das Label mit dem Certificate Resolver. Alle anderen Labels bleiben unverändert:

docker-compose.yml

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.

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:

docker-compose.yml

traefik:
  command:
    [...]
    - "--entrypoints.websecure.address=:443"
    - "--entrypoints.websecure.forwardedHeaders.trustedIPs=<IP-Adresse des Proxys>"

Mehrere Adressen oder Netze trennen Sie mit Komma, etwa 10.0.0.5,10.0.1.0/24.

Änderungen anwenden

docker compose up -d

Der Proxy leitet unverschlüsselt an http://<VARIOS-AI-Server>:80 weiter. Verwenden Sie diesen Weg nur, wenn die Strecke zwischen Proxy und VARIOS-AI-Server vertrauenswürdig ist.

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:

docker-compose.yml

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

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:

docker-compose.yml

traefik:
  command:
    [...]
    - "--entrypoints.web.address=:80"
    - "--entrypoints.web.forwardedHeaders.trustedIPs=<IP-Adresse des Proxys>"

Mehrere Adressen oder Netze trennen Sie mit Komma, etwa 10.0.0.5,10.0.1.0/24.

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.

Änderungen anwenden

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.

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.

/etc/nginx/conf.d/varios-ai.conf

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://<VARIOS-AI-Server>;
        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.
API-Zugriffe mit API-Schlüssel	`/api`	Externe Systeme wie der n8n-Node 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.
Office-Add-ins	`/office` und die übrigen Pfade	Outlook und Word laden die Add-ins in einer eigenen Browserkomponente. Ob diese das Clientzertifikat vorlegt, hängt von Office-Version und Betriebssystem ab.	Vor dem Rollout auf allen eingesetzten Plattformen testen.
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:

ssl_verify_client optional;

location /scim/ {
    # ohne Clientzertifikat, geschützt durch SCIM_TOKEN
    proxy_pass https://<VARIOS-AI-Server>;
    # [...] gleiche proxy_*-Einstellungen wie unter location /
}

location / {
    if ($ssl_client_verify != SUCCESS) {
        return 403;
    }
    proxy_pass https://<VARIOS-AI-Server>;
    # [...]
}

Prüfen

Aufruf über den Proxy

Öffnen Sie https://<PROJECT_DOMAIN> auf einem Gerät mit Clientzertifikat und melden Sie sich an.

Nach der Anmeldung landen Sie wieder unter https://<PROJECT_DOMAIN>, nicht unter http:// oder einer internen Adresse.

WebSocket

Stellen Sie im Chat eine Frage.

Die Antwort erscheint fortlaufend. In den Entwicklertools des Browsers zeigt der Tab Netzwerk für wss://<PROJECT_DOMAIN>/ws den Status 101.

Direkter Zugriff gesperrt

Rufen Sie von einem Arbeitsplatz https://<VARIOS-AI-Server> direkt auf.

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

Einführung

Nutzung

Administration

Installation

Betrieb

Sicherheit

Changelog

VARIOS AI hinter einem Reverse Proxy betreiben

Aufbau

Anforderungen an den Reverse Proxy

VARIOS-AI-Server anpassen

Beispielkonfiguration für nginx

Zugriffe ohne Clientzertifikat

Prüfen

Fehlerbehebung

​Aufbau

​Anforderungen an den Reverse Proxy

​VARIOS-AI-Server anpassen

​Beispielkonfiguration für nginx

​Zugriffe ohne Clientzertifikat

​Prüfen

​Fehlerbehebung

Aufbau

Anforderungen an den Reverse Proxy

VARIOS-AI-Server anpassen

Beispielkonfiguration für nginx

Zugriffe ohne Clientzertifikat

Prüfen

Fehlerbehebung