michael/Unraid-Navigator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
11b76f4572312bf44b713f910a85ceec7f25e29e
Unraid-Navigator/docs/MACHBARKEITSSTUDIE.md
T

11 KiB
Raw Blame History

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

Reference in New Issue View Git Blame Copy Permalink