Initial U-Navigator prototype

2026-06-22 22:11:54 +02:00
commit 37ddea08f4
11 changed files with 1841 additions and 0 deletions
@@ -0,0 +1,338 @@
+# 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