Unraid-Navigator/docs/MACHBARKEITSSTUDIE.md

U-Navigator - Machbarkeitsstudie

Stand: 2026-06-22

Kurzfazit

U-Navigator ist machbar.

Ein Unraid-Plugin kann eine optische Dateiverwaltung direkt im Unraid-WebGUI bereitstellen. Der sinnvollste Ansatz ist aber nicht, die komplette Synology File Station als reines PHP-Plugin nachzubauen. Besser ist eine kleine Unraid-Integration, die eine moderne Web-App einbettet und einen klar begrenzten lokalen Backend-Dienst für Dateioperationen nutzt.

Empfohlene Zielarchitektur:

• Unraid-Plugin fuer Installation, WebGUI-Menueintrag, Konfiguration und Rechte-/Pfadgrenzen.
• Lokaler Backend-Dienst fuer Dateioperationen, Suche, Upload/Download, Vorschau und lange Jobs.
• Frontend als moderne Single Page App im Unraid-WebGUI.
• Zugriff standardmaessig nur auf erlaubte Unraid-Pfade wie /mnt/user, optional /mnt/disk*, /mnt/cache, /mnt/poolname.

Was Unraid dafuer hergibt

Unraid laesst sich durch Plugins erweitern. Existierende reale Plugins zeigen das Muster:

• Plugin-Definition als .plg-Datei.
• Plugin-Dateien werden unter /usr/local/emhttp/plugins/<plugin> installiert.
• Persistente Plugin-Konfiguration liegt typischerweise unter /boot/config/plugins/<plugin>.
• WebGUI-Erweiterungen bestehen in der Praxis aus PHP, JavaScript, CSS, Shell-Skripten und paketierten Archivdateien.

Beispiele aus bestehenden Projekten:

• community.applications enthaelt ein Plugin-Verzeichnis unter source/.../usr/local/emhttp/plugins/community.applications und ist ueberwiegend PHP/JavaScript/HTML.
• unassigned.devices installiert Dateien nach /usr/local/emhttp/plugins, nutzt Shell-Skripte, Mountpoints und WebGUI-Seiten und zeigt, dass komplexere Storage-nahe Unraid-Plugins realistisch sind.
• dynamix ist bzw. war die WebGUI-Basisfamilie von Unraid; das alte Repository verweist auf die heutige Codebasis unter github.com/unraid/dynamix.

Funktionsumfang nach Risikostufen

MVP - realistisch

Ziel: Sicherer Dateibrowser fuer Unraid-Shares.

• Baumansicht fuer Shares und Ordner.
• Tabellen-/Listenansicht mit Name, Typ, Groesse, Datum, Besitzer/Rechten.
• Navigation in /mnt/user.
• Suchen nach Dateiname.
• Download einzelner Dateien.
• Upload in aktuellem Ordner.
• Ordner anlegen.
• Umbenennen.
• Kopieren/Verschieben innerhalb erlaubter Pfade.
• Loeschen mit Sicherheitsabfrage.
• Text-/Bildvorschau fuer einfache Dateitypen.
• Konfigurierbare erlaubte Root-Pfade.

Das ist technisch gut machbar.

Erweiterter Umfang - machbar, aber mehr Aufwand

• Mehrfachauswahl mit Batch-Aktionen.
• Fortschrittsanzeige fuer lange Kopier-/Verschiebe-Jobs.
• Hintergrundjobs mit Queue.
• Archiv erstellen/entpacken.
• Medienvorschau fuer Video/Audio.
• Dateirechte bearbeiten.
• Owner/Group anzeigen oder aendern.
• Share-uebergreifende Suche mit Index.
• Papierkorb oder Undo-Logik.
• Drag and Drop Upload.
• Kontextmenues wie in Synology File Station.

Das ist machbar, braucht aber einen sauberen Job-Runner und robuste Fehlerbehandlung.

Kritischer Umfang - nur mit klaren Grenzen

• Root-Dateisystem durchsuchen.
• Systemdateien bearbeiten.
• Dateien als root beliebig schreiben/loeschen.
• Direkte Bearbeitung von Docker-/VM-Images.
• Rekursive Massenoperationen ohne Quota, Dry-Run oder Abbruchmechanik.
• Oeffentliche Webfreigaben oder externe Links.

Diese Funktionen sind gefaehrlich und sollten nicht in den ersten Versionen enthalten sein.

Architekturvorschlag

Variante A: Reines Unraid-PHP-Plugin

Beschreibung: Die Dateioperationen laufen direkt ueber PHP-Seiten und Shell-Kommandos im Unraid-WebGUI.

Vorteile:

• Nahe am klassischen Unraid-Plugin-Modell.
• Wenig Runtime-Abhaengigkeiten.
• Einfaches Installationspaket.

Nachteile:

• Moderne UI und lange Jobs werden schnell unhandlich.
• Shell-Aufrufe muessen extrem sauber abgesichert werden.
• Uploads, Streaming, Suche und Fortschritt sind schwieriger wartbar.
• PHP-Versionen und Unraid-WebGUI-Aenderungen koennen brechen.

Bewertung: Machbar fuer einen einfachen Dateibrowser. Nicht ideal fuer eine File-Station-artige Anwendung.

Variante B: Plugin + lokaler Backend-Dienst

Beschreibung: Das Plugin installiert die WebGUI-Integration und startet einen lokalen Dienst. Das Frontend spricht diesen Dienst ueber HTTP oder Unix-Socket an.

Backend-Optionen:

• Go: sehr gut fuer statische Binary, Dateisystemoperationen, Performance.
• Rust: sehr robust, aber mehr Entwicklungsaufwand.
• Node.js: gute Web-Entwicklung, aber Runtime-Abhaengigkeit auf Unraid unschoener.
• Python: schnell fuer Prototyp, fuer Distribution auf Unraid weniger ideal.

Vorteile:

• Saubere API-Grenze.
• Bessere Kontrolle ueber Jobs, Streaming, Uploads und Suche.
• Moderne SPA moeglich.
• Backend kann strikt erlaubte Pfade erzwingen.
• Tests sind einfacher als bei reinem PHP/Shell.

Nachteile:

• Dienst-Lifecycle muss geloest werden.
• Binary-Builds fuer Unraid x86_64 noetig.
• Mehr Paketierungsaufwand.

Bewertung: Beste technische Variante fuer U-Navigator.

Variante C: Docker-App statt Plugin

Beschreibung: U-Navigator laeuft als Docker-Container und wird ueber Community Applications installiert.

Vorteile:

• Saubere Isolation.
• Einfache Runtime-Abhaengigkeiten.
• Updates leichter.
• Weniger Risiko fuer das Unraid-WebGUI.

Nachteile:

• Fuehlt sich weniger nativ an.
• Integration ins Unraid-WebGUI nur indirekt.
• Rechte und Pfad-Mappings muessen sauber dokumentiert werden.

Bewertung: Gut als Alternative oder spaeterer Parallelweg. Wenn das Ziel aber ein echtes Unraid-Plugin im WebGUI ist, ist Variante B passender.

Sicherheitsmodell

Ein Dateimanager auf einem NAS ist sicherheitskritisch. Das Sicherheitsmodell sollte von Anfang an feststehen.

Mindestregeln:

• Keine frei uebergebenen Shell-Kommandos.
• Alle Pfade canonicalisieren und gegen erlaubte Root-Pfade pruefen.
• Symlinks bewusst behandeln, standardmaessig nicht aus erlaubten Roots ausbrechen lassen.
• Kein Zugriff auf /boot, /etc, /usr, /var, /root im MVP.
• Aktionen mit Schreibzugriff getrennt absichern.
• CSRF-Schutz fuer mutierende Requests.
• Upload-Limits.
• Maximalgroessen und Timeouts fuer Vorschauen.
• Lange Operationen als Jobs mit Abbruchmoeglichkeit.
• Audit-Log fuer Schreib-/Loeschoperationen.
• Optionaler Read-only-Modus.

Wichtig: Unraid-WebGUI-Authentifizierung darf nicht blind als vollstaendige Autorisierung fuer alle Dateioperationen reichen. U-Navigator braucht zusaetzliche eigene Pfad- und Aktionsregeln.

Technische Hauptfragen

1. WebGUI-Integration

Machbar. Bestehende Plugins installieren Seiten und Assets unter /usr/local/emhttp/plugins/<plugin>. U-Navigator kann dort eine Page registrieren und die SPA laden.

Offen zu pruefen auf echter Unraid-Instanz:

• Aktuelle Page-Konventionen unter Unraid 7.x.
• Theme-Kompatibilitaet.
• Auth-/CSRF-Mechanismen.
• Reverse-Proxy-Verhalten des WebGUI.

2. Dateioperationen

Machbar. Linux/Unraid stellt alle noetigen Dateisystemoperationen bereit.

Risiken:

• User Shares unter /mnt/user koennen ueber mehrere Disks/Pools verteilt sein.
• Move-Operationen koennen je nach Quelle/Ziel echte Kopien plus Delete sein.
• Sparse Files, Hardlinks, Symlinks und Dateirechte muessen korrekt behandelt werden.
• Sehr grosse Ordner duerfen das WebGUI nicht blockieren.

3. Suche

Zwei Stufen sind sinnvoll:

• MVP: nicht-indexierte Namenssuche unter dem aktuellen Root mit Limits.
• Spaeter: Indexdienst mit SQLite, inotify/periodischem Scan und Ausschlussregeln.

Volltextsuche in Dokumenten sollte nicht Teil des MVP sein.

4. Vorschau

Einfach machbar:

• Textdateien mit Groessenlimit.
• Bilder ueber Browser oder Backend-Thumbnails.
• PDF optional spaeter.

Aufwendig:

• Office-Dokumente.
• Video-Transcoding.
• Exif/Metadatenindex.

5. Paketierung

Machbar als .plg plus Paketarchiv.

Wichtige Bestandteile:

• u-navigator.plg
• Paket mit usr/local/emhttp/plugins/u-navigator/...
• Frontend-Build
• Backend-Binary
• Start-/Stop-Skripte
• Konfiguration unter /boot/config/plugins/u-navigator/
• Logs unter /var/log oder Plugin-spezifisch mit Rotation

Empfohlener MVP-Schnitt

Version 0.1 sollte klein bleiben:

• Nur /mnt/user als Standardroot.
• Read-only-Modus als globale Option.
• Browse, Suche nach Name, Download.
• Schreibaktionen optional aktivierbar: Upload, Rename, Mkdir, Delete.
• Keine Rechte-/Owner-Aenderungen.
• Keine Archivfunktionen.
• Keine Volltextsuche.
• Keine externen Freigabelinks.

Damit laesst sich die technische Basis pruefen, ohne das NAS unnoetig zu gefaehrden.

Prototyp-Plan

Phase 1: Technischer Spike

Dauer: 1-2 Tage.

• Minimalen Unraid-Plugin-Skeleton bauen.
• Page im Unraid-WebGUI anzeigen.
• Statische SPA ausliefern.
• API-Endpunkt GET /api/list?path=... anbinden.
• Nur read-only Zugriff auf /mnt/user.

Erfolgskriterium: U-Navigator erscheint im WebGUI und listet Share-Inhalte.

Phase 2: Sicherer Dateibrowser

Dauer: 3-5 Tage.

• Pfad-Sandbox implementieren.
• Datei-/Ordnerdetails anzeigen.
• Download.
• Upload mit Limit.
• Rename/Mkdir/Delete hinter Feature-Flag.
• Fehlerfaelle sauber anzeigen.

Erfolgskriterium: Alltaegliche Dateioperationen funktionieren in erlaubten Shares ohne Shell-Injection- oder Path-Traversal-Risiko.

Phase 3: UX Richtung File Station

Dauer: 1-2 Wochen.

• Zwei-Pane-Layout oder Baum + Liste.
• Kontextmenues.
• Mehrfachauswahl.
• Drag and Drop.
• Fortschrittsdialoge.
• Bild-/Textvorschau.
• Suchpanel.

Erfolgskriterium: Die Anwendung fuehlt sich wie ein nativer NAS-Dateimanager an.

Risiken

Hoch

• Sicherheit bei Schreib-/Loeschoperationen.
• Unraid-WebGUI-API und Plugin-Konventionen sind weniger stabil dokumentiert als bei grossen Frameworks.
• Operationen auf /mnt/user koennen unerwartete Disk-/Pool-Grenzen beruehren.

Mittel

• Paketierung und Updates.
• Kompatibilitaet mit Unraid 6.12 vs. 7.x.
• Rechte/Owner/ACL-Verhalten.
• Performance bei sehr grossen Ordnern.

Niedrig

• Reine UI-Anzeige.
• Namenssuche.
• Download einzelner Dateien.
• Text-/Bildvorschau mit Limits.

Entscheidung

U-Navigator ist als Unraid-Plugin technisch machbar.

Die beste Umsetzung ist ein hybrides Plugin:

• Unraid-Plugin fuer Installation und Einbettung.
• Go-Backend als lokale Binary.
• SPA-Frontend fuer die File-Station-artige Bedienung.
• Striktes Sicherheitsmodell mit erlaubten Roots und Feature-Flags.

Nicht empfohlen ist ein grosses reines PHP/Shell-Plugin, weil Wartbarkeit, Sicherheit und moderne Bedienung dabei zu schnell gegenlaeufig werden.

Quellen und Referenzen

• Unraid Dokumentation: https://docs.unraid.net/
• Unraid Dynamix Repository: https://github.com/unraid/dynamix
• Altes Dynamix Repository mit Verweis auf heutige Codebasis: https://github.com/bergware/dynamix
• Community Applications Plugin: https://github.com/Squidly271/community.applications
• Unassigned Devices Plugin: https://github.com/dlandon/unassigned.devices
• Beispiel .plg Unassigned Devices: https://raw.githubusercontent.com/dlandon/unassigned.devices/master/unassigned.devices.plg
• Beispiel .plg Community Applications: https://raw.githubusercontent.com/Squidly271/community.applications/master/plugins/community.applications.plg