Technische Übersicht der Medienplattform

1. Systemzweck

Die Plattform ist ein privates, dauerhaft laufendes Mediensystem mit drei Inhaltswegen:

1. Lokale Medien auf einer Maschine zu Hause, die über einen privaten Tunnel und ein schreibgeschütztes Netzwerkdateisystem auf dem VPS eingebunden werden.
2. Automatisierte, Real-Debrid-gestützte Medien, die Riven verwaltet und Jellyfin über ein kuratiertes virtuelles Dateisystem bereitstellt.
3. Manuelle Real-Debrid-Links, die über ein kleines Webportal eingereicht und in kuratierte .strm-Einträge umgewandelt werden.

Der sichtbare Ablauf lautet:

Jellyfin
  -> lokale Bibliotheken, wenn die Medienquelle zu Hause online ist
  -> automatisierte Real-Debrid-/Riven-Bibliotheken vom VPS
  -> manuelle Real-Debrid-Filme und -Serien aus kuratierten Links

Jellyseerr
  -> normaler Anfrageablauf
  -> Riven-Automatisierung

Portal für manuelle Aufnahme
  -> unterstützte Real-Debrid-Links einfügen
  -> kuratierte .strm-Dateien erzeugen
  -> Jellyfin aktualisieren
  -> störende Extras filtern

Der rohe Real-Debrid-/Zurg-Mount bleibt ausschliesslich im Backend. Er wird bewusst nicht in Jellyfin eingebunden.

2. Öffentliche Dienste

Nur die für Nutzende bestimmten Webanwendungen sind öffentlich über HTTPS erreichbar:

media.example.com     -> Reverse Proxy -> Jellyfin
request.example.com   -> Reverse Proxy -> Jellyseerr
manual.example.com    -> Reverse Proxy -> Portal für manuelle Aufnahme

Nicht öffentlich:

• Riven API
• Zurg
• Postgres
• roher Real-Debrid-WebDAV-/FUSE-Mount
• Docker-Daemon
• lokale Dienst-Ports
• administratives SSH

3. Topologie im Überblick

Client-Gerät
  |
  | HTTPS
  v
Reverse Proxy auf dem VPS
  |
  +-- Jellyfin
  |     +-- lokaler Medien-Mount von der Maschine zu Hause
  |     +-- kuratierte Riven-Bibliothek
  |     +-- kuratierte manuelle Real-Debrid-Bibliothek
  |
  +-- Jellyseerr
  |     -> Riven fragt Anfragen ab
  |
  +-- Portal für manuelle Aufnahme
        -> Real-Debrid API
        -> kuratierte .strm-Dateien
        -> Jellyfin-Aktualisierung
        -> manueller Filter

Der VPS ist der öffentliche Edge-Knoten. Die Maschine zu Hause ist nur eine lokale Medienquelle und wird für die Real-Debrid-/Riven-Wiedergabe nicht benötigt.

4. Kern-Stack

Der Stack verwendet:

• Caddy als HTTPS-Reverse-Proxy.
• Docker Compose zur Orchestrierung der Dienste.
• Jellyfin für Wiedergabe und Durchsuchen der Bibliothek.
• Jellyseerr für Anfragen.
• Riven für automatisierte Real-Debrid-Beschaffung und die Bereitstellung eines kuratierten VFS.
• Postgres für den persistenten Zustand von Riven.
• Zurg und rclone für den Real-Debrid-/WebDAV-Zugriff im Backend.
• Systemd-Units und -Timer für Lebenszyklus, Mounts, Bereinigung und Wartung des Stacks.

Kern-Container:

jellyfin
jellyseerr
riven
riven-db
zurg

Anwendungs-Ports werden nur lokal gebunden. Öffentlicher Datenverkehr erreicht die Anwendungen ausschliesslich über den Reverse Proxy.

5. Jellyfin-Bibliotheksmodell

Jellyfin soll ausschliesslich kuratierte Pfade verwenden:

lokaler Medien-Mount
kuratierte Riven-Bibliothek
kuratierte manuelle Real-Debrid-Bibliothek

Vorgesehene Bibliotheken:

Local Movies       -> lokaler Filmordner
Local Shows        -> lokale Serien-/Anime-Ordner
Real-Debrid        -> kuratierte Riven-Filme/-Serien
Manual RD Movies   -> kuratierte manuelle Film-.strm-Dateien
Manual RD Shows    -> kuratierte manuelle Serien-.strm-Dateien

Den rohen Real-Debrid-/Zurg-Mount nicht zu Jellyfin hinzufügen. Dieser Pfad ist ausschliesslich Backend- und Debug-Speicher.

6. Weshalb rohes Real-Debrid vor Jellyfin verborgen bleibt

Rohes Real-Debrid/Zurg ist für direkte Jellyfin-Scans zu breit und zu stark von entferntem Speicher abhängig.

Beobachtete Probleme:

• Jellyfin versuchte, viele rohe entfernte Dateien zu prüfen.
• Trickplay- und Kapitelbild-Extraktion erzeugten unnötige entfernte I/O.
• Einige ffmpeg-/Probe-Aufträge wurden langsam oder blieben hängen.
• Bibliotheks-Scans wurden weniger stabil.

Lösung:

• Den rohen Real-Debrid-Mount ausschliesslich im Backend halten.
• Riven eine kuratierte Bibliothek bereitstellen lassen.
• Den manuellen Aufnahmeablauf kuratierte .strm-Dateien erzeugen lassen.
• Jellyfin so konfigurieren, dass Metadaten, Bilder, Untertitel und generierte Artefakte in Jellyfins Konfiguration/Cache gespeichert und nicht in eingebundene Medienpfade geschrieben werden.

7. Manuelle Real-Debrid-Aufnahme

Das manuelle Portal akzeptiert nur unterstützte direkte Real-Debrid-Links und wandelt sie in kuratierte Jellyfin-Einträge um.

Sein Umfang ist bewusst eng:

• Es validiert eingereichte Links.
• Es ruft die Real-Debrid API auf.
• Es schreibt kuratierte .strm-Dateien.
• Es schreibt begleitende Metadaten.
• Es führt den manuellen Filter aus.
• Es löst einen Jellyfin-Scan aus.

Es ist kein Shell-Runner und darf keine allgemeine Befehlsausführung bereitstellen.

Vor dem Portal soll eine Authentifizierung liegen, beispielsweise Basic Authentication am Reverse Proxy oder eine andere Zugriffskontrolle. Passwörter, Benutzernamen, API-Tokens und geheime Dateipfade dürfen nie in öffentliche Dokumentation übernommen werden.

8. Manuelle Filterung

Massenimporte von Real-Debrid-Ordnern können störende Extras wie Vor- und Abspänne ohne Credits, Trailer, Samples, Interviews und andere nicht primäre Videos enthalten. Diese erscheinen in Jellyfin häufig als defekte oder unerwünschte Einträge.

Der manuelle Filter verschiebt wahrscheinliche Extras aus dem für Jellyfin sichtbaren Speicher und bewahrt dabei genug Metadaten, um sie später wiederherzustellen oder zu prüfen:

• Informationen zur .strm-Datei
• begleitende Metadaten
• ursprünglicher Real-Debrid-Quelllink
• Dateinamen- und Grössenmetadaten
• Real-Debrid-Auflösungsmetadaten

Der Filter kann Einträge in Quarantäne regelmässig erneut prüfen. Wenn ein Link später auf einen normal verwendbaren Film- oder Episodennamen statt auf den Namen eines Extras auflöst, kann er in die sichtbare manuelle Bibliothek zurückkehren.

9. Riven und 451-Dämpfung

Beobachtetes Problem:

Riven kann wiederholt Real-Debrid-Antworten vom Typ 451 Infringing Torrent erhalten. Das kann Cooldown- und Circuit-Breaker-Kaskaden auslösen und das Backend blockiert wirken lassen, obwohl der Stack sonst gesund ist.

Der 451-Cleaner:

• durchsucht aktuelle Riven-Logs
• zeichnet wiederholt blockierte Hashes auf
• meldet betroffene Cooldown-Titel
• startet Riven nur neu, wenn Schwellenwerte überschritten werden
• begrenzt die Neustartrate, um Neustartschleifen zu verhindern

Er tut Folgendes nicht:

• Medien löschen
• Riven öffentlich bereitstellen
• rohes Real-Debrid in Jellyfin einbinden
• garantieren, dass blockierte Quellen abspielbar werden

Bedeutung von HTTP 451 in diesem Zusammenhang:

Real-Debrid hat einen bestimmten Kandidaten-Hash abgelehnt. Dies ist kein Routing-Fehler von Jellyfin, Reverse Proxy, Docker oder VPS.

10. Härtung des Medien-Mounts von zu Hause

Die lokale Medienbibliothek wird von einer Maschine zu Hause über einen privaten Tunnel und ein schreibgeschütztes Netzwerkdateisystem eingebunden.

Gelöstes Problem:

Der Mount konnte stark blockieren, wenn die Maschine zu Hause, der private Tunnel oder der NFS-Pfad langsam oder veraltet war. Dies verursachte Jellyfin-Quellfehler und liess Gesundheitsskripte hängen.

Design:

• bei Bedarf mounten
• den Mount schreibgeschützt halten
• den VPS-Start nicht blockieren, wenn die Maschine zu Hause offline ist
• Lesevorgänge schneller fehlschlagen lassen, statt unbegrenzt zu blockieren
• Real-Debrid-/Riven-Wiedergabe unabhängig von der Maschine zu Hause halten

Betriebliche Bedeutung:

• Wenn die Maschine zu Hause ausgeschaltet ist, können lokale Medien nicht verfügbar erscheinen.
• Jellyfin soll trotzdem weiterlaufen.
• Riven-/Real-Debrid-Medien sollen vom VPS verfügbar bleiben.

11. Anfrageablauf

Normaler Anfrageweg:

Nutzende Person öffnet das Anfrageportal
  -> fragt einen Film oder eine Serie an
  -> Riven fragt den Anfragedienst ab
  -> Riven durchsucht Release-Kandidaten
  -> Riven prüft die Real-Debrid-Verfügbarkeit
  -> akzeptierte Medien erscheinen in der kuratierten Riven-Bibliothek
  -> Jellyfin wird aktualisiert
  -> die nutzende Person schaut in Jellyfin

Bedeutung der Riven-Zustände:

• Scraped: Kandidaten wurden gefunden, aber die Medien sind nicht zwingend eingetroffen.
• Indexed: Metadaten-/Indexzustand existiert; bei Serien kann dieser auf Elternebene liegen und beweist nicht, dass jede Episode eingetroffen ist.
• Completed: Die Medien sollen eingetroffen und sichtbar sein.
• PartiallyCompleted: Einige Dateien sind eingetroffen.
• Ongoing: Die Verarbeitung läuft oder wartet noch.

Bedeutung des manuellen Real-Debrid-Ablaufs:

• Ein Link erscheint erst in Jellyfin, nachdem eine .strm-Datei in der kuratierten manuellen Bibliothek vorhanden ist und Jellyfin sie gescannt hat.
• Extras in Quarantäne sind bewusst nicht in Jellyfin sichtbar.
• Abgelaufene Direktlinks müssen möglicherweise über den privaten Wartungs-Workflow aktualisiert werden.

12. Jellyfin-Sicherheitseinstellungen

Bibliotheken auf entferntem Speicher sowie schreibgeschützte Bibliotheken sollen unnötige Schreibvorgänge und aufwendige Extraktionsaufträge vermeiden.

Empfohlene Bibliothekseinstellungen:

Disable realtime monitoring on remote/virtual paths.
Disable chapter image extraction.
Disable trickplay image extraction unless explicitly needed.
Do not save local metadata into mounted media paths.
Do not save subtitles into mounted media paths.

Begründung:

• Der lokale Medien-Mount ist schreibgeschützt.
• Riven- und Real-Debrid-Pfade sind virtuell oder basieren auf entferntem Speicher.
• Metadaten sollen in Jellyfins Konfiguration/Cache liegen, nicht in eingebundenen Medienordnern.

13. Erwarteter Dienstzustand

Gesunde Grundlage:

• Reverse Proxy ist aktiv
• Docker ist aktiv
• der Media-Stack-Dienst ist aktiv
• der Dienst für den Real-Debrid-Backend-Mount ist aktiv
• Jellyfin ist gesund
• Jellyseerr läuft
• Riven läuft
• die Riven-Datenbank ist gesund
• Zurg ist gesund

Während eines Scans können Poster und Vorschaubilder uneinheitlich erscheinen, bis Jellyfin die Metadatenarbeit abgeschlossen hat und sich Oberfläche sowie Cache beruhigt haben.

14. Bekannte kosmetische Probleme

Flackern von Postern oder Vorschaubildern

Beobachtetes Verhalten:

• Nach dem Öffnen einer Bibliothek und der Rückkehr zur Startseite können Vorschaubilder kurz verschwinden.
• Ein Neuladen der Seite stellt sie wieder her.

Wahrscheinliche Ursachen:

• Lazy-Loading-/Cache-Verhalten der Jellyfin-Weboberfläche.
• Aktiver Bibliotheks-Scan.
• Metadaten/Bilder werden noch in Jellyfins internen Cache geschrieben.

Empfohlene Massnahme:

In Ruhe lassen, solange das Problem nach Abschluss aller Scans nicht bestehen bleibt.

Merkwürdige Metadaten während eines Scans

Während aktiver Scans können Serien vorübergehend unvollständig oder schlecht gruppiert aussehen.

Richtlinie:

Die Korrektheit der Bibliothek erst beurteilen, wenn der Scan inaktiv ist.

15. Übliche private Betriebsvorgänge

Das private Runbook enthält Befehle für:

• Prüfung des Dienstzustands
• Neustart des gesamten Stacks
• Neustart nur von Riven
• Neustart nur von Jellyfin
• Aktualisierung der Jellyfin-Bibliotheken
• Beobachtung der Riven-Logs
• Prüfung, ob auf dem Host sichtbare Dateien auch im Jellyfin-Container sichtbar sind
• Aktualisierung lokaler Medien-Mounts
• Aktualisierung abgelaufener Real-Debrid-Links

Diese Befehle werden in der öffentlichen Version bewusst weggelassen, weil sie Hostnamen, Benutzende, Pfade, IP-Adressen, Dienstnamen und administrative Gewohnheiten offenlegen. Sie gehören stattdessen in ein privates Betriebsdokument.

16. Modell zur Fehlerbehebung

Eine Anfrage erscheint nicht in Riven

Prüfen, ob im Anfragedienst ausstehende Einträge vorhanden sind und Riven erfolgreich abfragt.

Interpretation:

• Keine abgerufenen Einträge: Der Anfragedienst hat nichts ausstehend, das Riven sieht.
• Ein oder mehrere abgerufene Einträge: Riven hat die Anfrage gesehen.
• Streams gefunden: Das Scraping hat funktioniert.
• Über Real-Debrid heruntergeladen: Die Beschaffung hat funktioniert.
• 451 Infringing Torrent: Real-Debrid hat diesen Kandidaten-Hash abgelehnt.

Ein Eintrag erscheint in Riven, aber nicht in Jellyfin

Die kuratierte Riven-Bibliothek aus Sicht des Hosts mit ihrer Sichtbarkeit im Jellyfin-Container vergleichen.

Wenn der Host Dateien sieht, Jellyfin aber nicht, muss Jellyfin möglicherweise neu gestartet oder erstellt werden, damit der aktuelle FUSE-Mount wieder in den Container eingebunden wird.

Ein Jellyfin-Scan scheint festzuhängen

Zustand und Logs der geplanten Aufgabe prüfen.

Nach dem Hinzufügen von Inhalten wird Folgendes erwartet:

Scan Media Library Running

Vollständige Scans nicht wiederholt auslösen, während bereits einer läuft.

Wenn rohe Real-Debrid-Pfade in ffmpeg- oder Probe-Befehlen erscheinen, ist dies eine Regression. Jellyfin darf den rohen Real-Debrid-Mount nicht sehen.

Lokale Medien werden entfernt nicht geladen

Prüfen:

• die Maschine zu Hause ist eingeschaltet
• der private Tunnel ist aktiv
• der Netzwerkdateisystem-Export ist aktiv
• der VPS kann den lokalen Medien-Mount lesen
• Jellyfin-Bibliothekspfade zeigen nur auf die vorgesehenen lokalen Ordner

Wichtig:

Die entfernte Wiedergabe lokaler Medien hängt vom Upload zu Hause und der Stabilität des privaten Tunnels ab. Die Riven-/Real-Debrid-Wiedergabe hängt nicht von der Maschine zu Hause ab.

17. Designgrenzen

• Riven nicht öffentlich bereitstellen.
• Zurg nicht öffentlich bereitstellen.
• Postgres nicht öffentlich bereitstellen.
• Docker nicht öffentlich bereitstellen.
• Rohen Real-Debrid-/Zurg-Speicher nicht in Jellyfin einbinden.
• Geheimnisse von Real-Debrid, Jellyfin, Datenbank oder Reverse Proxy weder ausgeben noch committen.
• Den manuellen Aufnahmeumfang eng halten.
• Jellyfin ausschliesslich auf kuratierten Pfaden halten.
• Aufwendige Jellyfin-Extraktionsfunktionen für entfernt gestützte Bibliotheken nur mit klarem Grund aktivieren.
• Verhindern, dass Jellyfin Metadaten in eingebundene Medienpfade schreibt.
• Nicht viele zusätzliche Jellyfin-Bibliotheken ohne klaren Vorteil beim Durchsuchen anlegen.

18. Weshalb das Design so aussieht

Weshalb ein VPS verwendet wird

Der VPS stellt Folgendes bereit:

• dauerhaft erreichbarer öffentlicher Endpunkt
• stabile Domain und TLS
• Reverse Proxy
• Anfrage- und Automatisierungsdienste, auch wenn die Maschine zu Hause ausgeschaltet ist
• von lokalem Speicher unabhängige Verfügbarkeit von Real-Debrid-/Riven-Medien
• aufgeräumterer mobiler und entfernter Zugriff

Die Maschine zu Hause ist nicht mehr der Host der öffentlichen Dienste. Sie ist nur eine lokale Medienquelle.

Weshalb eine einzige kuratierte Real-Debrid-Bibliothek verwendet wird

Eine kleinere Jellyfin-Bibliotheksoberfläche ist einfacher zu durchsuchen und zu warten.

Das bevorzugte Modell lautet:

Local Movies
Local Shows
Real-Debrid
Manual RD Movies
Manual RD Shows

So bleibt roher Backend-Speicher verborgen, während Inhalte weiterhin auffindbar sind.

Weshalb lokaler Anime unter Local Shows liegen kann

Anime ist episodischer Inhalt im Stil von TV-Serien. Ihn als Teil der lokalen Serienbibliothek zu behandeln verhindert zu viele getrennte Jellyfin-Bibliotheken und erlaubt weiterhin normales Durchsuchen und Filtern.

19. Funktionsdefinition

Die Plattform gilt als funktionsfähig, wenn:

1. das öffentliche Jellyfin über HTTPS lädt.
2. die öffentliche Anfrageoberfläche über HTTPS lädt.
3. das Portal für manuelle Aufnahme über HTTPS lädt und Authentifizierung verlangt.
4. Jellyfin die kuratierten lokalen, Riven- und manuellen Bibliotheken sieht.
5. Jellyfin den rohen Real-Debrid-/Zurg-Speicher nicht sieht.
6. Riven den Anfragedienst abfragt.
7. Riven mindestens eine Anfrage über Real-Debrid abschliessen kann.
8. abgeschlossene Riven-Einträge in der kuratierten Riven-Bibliothek erscheinen.
9. manuelle Real-Debrid-Links über kuratierte .strm-Dateien sichtbar werden können.
10. lokale Medien sichtbar sind, solange die Maschine zu Hause online ist.
11. die Dienste beim Start des VPS anlaufen.

20. Künftige Arbeit

• Scans abschliessen lassen und die Stabilität der Poster prüfen
• Regeln zur Rangfolge von Anfragen bei Bedarf verbessern
• Untertitelverwaltung später ergänzen
• eine erweiterte Auswahl exakter Releases ergänzen
• einen eigenen, dauerhaft laufenden Heimserver oder ein NAS erwägen, falls lokale Medien rund um die Uhr ohne Desktop verfügbar sein sollen