Kann Jellyfin hinter einem Reverse-Proxy unter einem Unterpfad betrieben werden?

Eva Wong ist die technische Redakteurin und begeisterte Tüftlerin bei ZimaSpace. Als lebenslanger Geek mit einer Leidenschaft für Homelabs und Open-Source-Softwarehat sie sich darauf spezialisiert, komplexe technische Konzepte in verständliche, praxisnahe Anleitungenzu übersetzen. Eva ist überzeugt, dass Self-Hosting Spaß machen sollte und nicht einschüchternd sein darf. Mit ihren Tutorials hilft sie der Community dabei, Hardware-Setups zu durchschauen, vom Bau des ersten NAS bis zum sicheren Umgang mit Docker-Containern.

Ja. Jellyfin kann hinter einem Reverse-Proxy unter einem Subpfad wie https://example.com/jellyfin funktionieren, aber Jellyfin und der Proxy müssen denselben Basispfad verwenden.

Bei einem Subpfad-Fehler funktioniert die Website oft nur teilweise: Die Anmeldeseite wird möglicherweise geladen, während JavaScript, Bilder, WebSockets, Weiterleitungen oder native Clients fehlschlagen. Prüfe den Pfad schrittweise – zuerst die Basis-URL, dann die Proxy-Route, zuletzt die weitergeleiteten Header und die Client-Adresse –, damit du einen Pfadkonflikt von einem TLS- oder Proxy-Identitätsproblem unterscheiden kannst.

Jellyfins Basis-URL muss dem öffentlichen Subpfad entsprechen

Setze Jellyfins Basis-URL auf genau das öffentliche Präfix, das du verwenden möchtest, zum Beispiel /jellyfin. Füge kein anderes internes Präfix hinzu, nur weil der Proxy einen benannten Location-Block verwendet. Der im Browser sichtbare Pfad und die Jellyfin-Basis-URL müssen denselben Anwendungsstamm beschreiben.

Jellyfins Dokumentation zum Apache-Reverse-Proxy enthält ausdrücklich ein Subpfad-Beispiel und weist Administratoren an, die Basis-URL auf /jellyfin zu setzen, bevor sie Clients mit dieser vollständigen Adresse verbinden. offizielles Subpfad-Beispiel

Starte Jellyfin nach der Änderung der Basis-URL neu und öffne den öffentlichen Subpfad anschließend in einem neuen privaten Browserfenster. Wenn bei der ersten Weiterleitung sofort /jellyfin entfernt oder doppelt eingefügt wird, korrigiere die Basis-URL, bevor du WebSocket- oder Authentifizierungseinstellungen änderst.

Dasselbe Präfix durch den Reverse-Proxy leiten

Konfiguriere den Reverse-Proxy so, dass Anfragen, die mit dem öffentlichen Präfix beginnen, an Jellyfin weitergeleitet werden, ohne den Pfad zusätzlich zu verändern. Am einfachsten ist eine Konfiguration mit einem öffentlichen Präfix, einer passenden Jellyfin-Basis-URL und einem Upstream-Dienst.

Der Jellyfin-Leitfaden für Caddy zeigt dasselbe Muster: Jellyfin-Basispfad konfigurieren, das Präfix ohne abschließenden Schrägstrich auf die Variante mit abschließendem Schrägstrich umleiten und Anfragen unter diesem Präfix an das Jellyfin-Backend weiterleiten. übereinstimmender Basispfad und Proxy-Route

Wenn der Browser vom Proxy einen 404-Fehler erhält, bevor Jellyfin die Anfrage protokolliert, ist die Route auf der Proxy-Ebene falsch. Wenn Jellyfin die Anfrage erhält, aber Links ohne das Präfix generiert, ist die Basis-URL auf Anwendungsebene falsch. Halte diese beiden Fehlersignaturen auseinander.

Statische Ressourcen und WebSockets prüfen, nicht nur die Anmeldeseite

Eine erfolgreiche HTML-Antwort allein reicht nicht aus, um die Subpfad-Konfiguration als fehlerfrei einzustufen. Öffne die Entwicklertools oder das Proxy-Protokoll und prüfe, ob JavaScript-, CSS-, Bild-, API- und WebSocket-Anfragen alle unter demselben öffentlichen Präfix bleiben.

Die Reverse-Proxy-Beispiele von Jellyfin berücksichtigen WebSocket-Verbindungen, da interaktive Clients zusätzlich zu gewöhnlichen HTTP-Anfragen eine Socket-Verbindung aufrechterhalten. Eine Proxy-Regel, die nur Seitenanfragen verarbeitet, kann daher zunächst korrekt erscheinen, bis der Wiedergabestatus, Sitzungsaktualisierungen oder das Live-Verhalten der Benutzeroberfläche gestört sind. Anforderungen an den Reverse-Proxy

Das Erfolgskriterium ist einfach: keine wiederholten 404-/502-Fehler bei Assets mit Präfix, das WebSocket-Upgrade funktioniert und die Navigation springt nicht zum Website-Stammverzeichnis. Wenn nur eine Anfrageart fehlschlägt, korrigieren Sie die entsprechende Proxy-Regel, statt die Bibliotheks- oder Authentifizierungseinstellungen von Jellyfin zu ändern.

Die Client-Identität über den Proxy hinweg erhalten

Nachdem der Pfad funktioniert, überprüfen Sie die weitergeleiteten Client-Informationen. Jellyfin verwendet die Proxy-Vertrauenseinstellungen, um festzulegen, ob weitergeleitete Adressen und Protokolle akzeptiert werden sollen. Das wirkt sich auf das Verhalten bei lokalen und externen Verbindungen sowie auf Regeln für den externen Zugriff aus.

Der Jellyfin-Netzwerkleitfaden warnt davor, dass weitergeleitete Header von einem nicht vertrauenswürdigen Proxy verworfen werden, und empfiehlt, die Proxy-Adresse unter „Bekannte Proxys“ zu konfigurieren. Einstellung „Bekannte Proxys“ Eine separate Prüfung der Client-IP ist hilfreich, wenn die Website funktioniert, aber bei jeder Anfrage der Proxy als Absender erscheint.

Lösen Sie kein Identitätsproblem, indem Sie jedem privaten Subnetz oder jedem weitergeleiteten Header vertrauen. Fügen Sie nur den tatsächlichen Proxy-Hop oder das kontrollierte Proxy-Netzwerk hinzu und vergleichen Sie dann eine LAN-Anfrage mit einer Remote-Anfrage in den Jellyfin-Protokollen, um zu bestätigen, dass sie wie erwartet eingestuft werden.

Browser- und native Client-Adressen getrennt testen

Geben Sie die vollständige Serveradresse einschließlich des Unterpfads ein, wenn ein Jellyfin-Client nach der Server-URL fragt. Ein Client mit der gespeicherten Adresse https://example.com kann nicht selbst erkennen, dass Jellyfin unter /jellyfin erreichbar ist.

Testen Sie einen Browser und einen nativen Client im LAN und wiederholen Sie den Test anschließend über den öffentlichen Hostnamen. Wenn der Hostname funktioniert, der direkte Zugriff über die lokale IP-Adresse jedoch nicht, kann das erwartungsgemäß sein, wenn die Proxy-Route und das Zertifikat vom Hostnamen abhängen. Mit Tests mit Hostname und IP-Adresse lässt sich dieser Fall eingrenzen, ohne den Proxy weniger sicher zu konfigurieren.

Fahren Sie erst fort, wenn die URL mit vorangestelltem Präfix bei den von Ihnen tatsächlich unterstützten Clients nach der Anmeldung, beim Navigieren, bei der WebSocket-Nutzung und bei der Wiedergabe funktioniert. Wenn nur ein Client ausfällt, während Browser und andere Clients funktionieren, behandeln Sie das als Problem mit der Client-Adresse oder der Client-Kompatibilität, statt eine funktionierende Proxy-Konfiguration umzuschreiben.

Support und Tipps

Mehr zum Lesen

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.