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