ScarriffleandClaude Opus 5
91eb934048
Einrichtung, Anmeldung, Mediathek, Detailseite mit Abspielen und Herunterladen, Zuordnung korrigieren, Verwaltung. Die Oberfläche aus der Jellyfin-Zeit ist dabei vollständig ersetzt: `types.ts`, `prefs.ts`, `contrast.ts`, `views/cards.ts`, `views/player.ts` und `views/settings.ts` sprachen Jellyfins Schnittstelle und hatten hier nichts mehr zu suchen. Seitenleiste links, waagerechte Reihen auf der Startseite, Plakate im Verhältnis 2:3, unscharfer Hintergrund hinter dem Kopf der Detailseite — das ist der Zuschnitt von Plex, weil er gefällt. **Die Farbe bleibt Flaros Orchidee**, nicht Plex' Orange; der Aufbau ist das Vorbild, nicht das Aussehen. Welche Bibliothek gezeigt wird, entscheidet die Seitenleiste. Eine zweite Umschaltung innerhalb der Seite wäre dieselbe Entscheidung an zwei Orten. --- **Der Zugang liegt jetzt auch in einem Cookie.** Ein `<img>`, ein `<video>` und ein Download-Link senden keine eigenen Kopfzeilen — eine App kann ihr Token in jede Anfrage legen, ein Browser nicht. Das Token stattdessen in die Adresse zu schreiben wäre der naheliegende Ausweg und stünde danach in jedem Zugriffsprotokoll, in jedem Verlauf und in jedem weitergegebenen Link. `HttpOnly`, damit kein eingeschlichenes Skript herankommt. `SameSite=Strict` gegen Anfragen von fremden Seiten. `Secure` nur über https — sonst liesse sich die Oberfläche im Heimnetz über http gar nicht benutzen. Die Apps benutzen weiterhin die Kopfzeile: ein zweiter Weg zum selben Token, kein zweites Verfahren. --- **Der Fehler, den erst der echte Container zeigte:** eine weisse Seite, ohne Hinweis worauf. Die Rückfallregel verlangt für jede Anfrage ohne eigenen Endpunkt einen angemeldeten Benutzer, und `/assets/index.js` hat keinen. Die statischen Dateien standen unter `UseAuthorization` — ein neuer Besucher bekam 401 auf genau das Skript, das ihm die Anmeldemaske zeichnen sollte. `/` kam durch, weil der SPA-Rückfall `AllowAnonymous` trägt; alles mit Dateiendung nicht. Jetzt liegen sie davor. Mit Prüfung. Beim Bau desselben Images der zweite: seit der Kontext die Projektwurzel ist, überschrieb `COPY server/` die `obj/`-Verzeichnisse aus dem Container mit denen vom Arbeitsrechner — die zeigen auf osx-arm64, gebaut wird linux-arm64, `dotnet publish` brach mit NETSDK1047 ab. Dafür gibt es jetzt eine `.dockerignore` in der Wurzel; die unter `server/` sucht Docker seit dem Umzug nicht mehr. --- Vier Prüfungen schlugen danach fehl, und zwar zu Recht: sie hiessen „ohne Anmeldung gibt es nichts", benutzten aber den Client, der nach dem Anmelden ein Cookie hält. Sie prüften also den Angemeldeten. Jetzt sagen sie ausdrücklich, dass sie ohne Zugang fragen. 313 Tests grün. Im Container nachgewiesen: Anmelden, Plakate, Abspielen, Staffeln und Folgen, Verwaltung — und ein Neuladen auf `/verwaltung`, das nicht in einem 404 endet. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
296 lines
12 KiB
Markdown
296 lines
12 KiB
Markdown
# Flaro-Server
|
|
|
|
Ein Medienserver, der dieselben Dinge kann wie Jellyfin — und zwei, die dort
|
|
nicht gehen.
|
|
|
|
**Stand: Stufe 3 von 5.** Benutzer, Anmeldung, Einrichtung, Bestand einlesen,
|
|
Metadaten — und **Download mit allen Ton- und Textspuren**, der Grund für
|
|
dieses Projekt. Was noch fehlt: Streamen mit Umrechnen (HLS), Fortschritt und
|
|
Gesehen-Status, Live TV. Der Entwurf samt Begründungen steht
|
|
in [`docs/superpowers/specs/2026-10-03-flaro-server-design.md`](../docs/superpowers/specs/2026-10-03-flaro-server-design.md).
|
|
|
|
## Warum
|
|
|
|
**Download mit allen Tonspuren.** Jellyfins Transcode-Endpunkt bildet eine
|
|
Tonspur je Sitzung ab; was offline landet, ist einspurig, und welche Spur es
|
|
ist, entscheidet der Server. Einmal war es die Audiodeskription — drei Gigabyte
|
|
Mobilfunk für eine Datei, die niemand hören wollte.
|
|
|
|
**Fortschritt ohne Schwelle.** Jellyfin merkt sich unterhalb eines
|
|
Mindestanteils gar nichts. Wer zehn Minuten sieht und abbricht, findet beim
|
|
nächsten Mal keinen Anknüpfungspunkt.
|
|
|
|
## Betreiben
|
|
|
|
```bash
|
|
cp docker-compose.example.yml docker-compose.yml
|
|
# Pfade anpassen — jeder darin ist ein Beispiel, keiner stimmt bei dir.
|
|
docker compose up -d
|
|
```
|
|
|
|
Dann `http://localhost:8080` öffnen; der Einrichtungsassistent legt das erste
|
|
Administratorkonto an. Danach verschliesst sich dieser Weg von selbst.
|
|
|
|
### Einstellungen
|
|
|
|
| Variable | Bedeutung | Voreinstellung im Image |
|
|
|---|---|---|
|
|
| `FLARO_DATA` | Datenbank und Einstellungen. **Das Einzige, was gesichert werden muss.** | `/config` |
|
|
| `FLARO_CACHE` | Bilder und Zwischenstände. Darf verlorengehen. | `/cache` |
|
|
| `FLARO_TRANSCODE` | Kratzplatz fürs Umrechnen. Am besten auf eine SSD. | `/transcode` |
|
|
| `ASPNETCORE_URLS` | Worauf gelauscht wird | `http://+:8080` |
|
|
| `TZ` | Zeitzone | `UTC` |
|
|
| `FLARO_RATELIMIT_SIGNIN` | Anmeldeversuche je Minute und Adresse | `10` |
|
|
| `FLARO_RATELIMIT_POLLING` | Nachfragen je Minute und Adresse | `120` |
|
|
|
|
**Medienpfade stehen hier nicht.** Sie werden in der Oberfläche als
|
|
Bibliotheken angelegt und liegen in der Datenbank — sonst müsste der Container
|
|
neu starten, um eine Bibliothek hinzuzufügen.
|
|
|
|
### Rechte
|
|
|
|
Das Image läuft als `1000:1000`, **nicht als root**. Gehören die eingehängten
|
|
Verzeichnisse jemand anderem, trage in der Compose-Datei
|
|
`user: "<uid>:<gid>"` ein (`id -u` und `id -g` auf dem Wirt sagen, welche)
|
|
oder übereigne sie mit `chown`.
|
|
|
|
Stimmt etwas nicht, bricht der Server **beim Start** ab und nennt Variable,
|
|
Pfad, seine eigene Kennung und den nächsten Schritt. Das ist Absicht: ohne
|
|
diese Meldung stünde dort nur „unable to open database file".
|
|
|
|
### Hardware fürs Umrechnen
|
|
|
|
`/dev/dri` durchreichen — VAAPI deckt Intel wie AMD ab. Fehlt es, rechnet Flaro
|
|
in Software; das ist langsamer, aber es läuft. **Zum blossen Umpacken wird gar
|
|
keine Hardware gebraucht**, und das ist der Weg, der den meisten Beständen
|
|
hilft.
|
|
|
|
## Weboberfläche
|
|
|
|
Der Server liefert sie selbst aus, unter derselben Adresse wie die
|
|
Schnittstelle. Kein Proxy davor, kein CORS, kein Mischmasch aus http und
|
|
https. Gebaut wird sie im Image mit; wer nur an ihr arbeitet, nimmt Vite:
|
|
|
|
```bash
|
|
cd ../web/app
|
|
npm install
|
|
FLARO_SERVER=http://localhost:18080 npm run dev # auf http://localhost:5173
|
|
```
|
|
|
|
Vite reicht `/api` an den Server weiter, damit die Herkunft dieselbe bleibt
|
|
wie im Betrieb.
|
|
|
|
**Der Zugang liegt in einem Cookie, nicht nur in der Kopfzeile.** Ein
|
|
`<img>`, ein `<video>` und ein Download-Link senden keine eigenen
|
|
Kopfzeilen; das Token stattdessen in die Adresse zu schreiben hiesse, es in
|
|
jedes Zugriffsprotokoll und jeden weitergegebenen Link zu setzen. Das Cookie
|
|
ist `HttpOnly` und `SameSite=Strict`, `Secure` nur über https — sonst liesse
|
|
sich die Oberfläche im Heimnetz gar nicht benutzen. Die Apps benutzen
|
|
weiterhin die Kopfzeile: ein zweiter Weg zum selben Token, kein zweites
|
|
Verfahren.
|
|
|
|
## Entwickeln
|
|
|
|
```bash
|
|
dotnet test # 313 Tests
|
|
dotnet run --project src/Flaro.Api # auf http://localhost:5000
|
|
```
|
|
|
|
Ohne gesetzte Variablen legt der Server `data/`, `cache/` und `transcode/`
|
|
neben dem Programm an.
|
|
|
|
```bash
|
|
# Image bauen, beide Architekturen.
|
|
# **Aus der Wurzel des Projekts**, nicht aus server/: der Bau braucht
|
|
# web/app für die Oberfläche.
|
|
cd .. && docker buildx build --platform linux/amd64,linux/arm64 \
|
|
-f server/Dockerfile -t flaro:dev .
|
|
|
|
# Ein lokaler Server mit Beispielmedien zum Ausprobieren
|
|
Tools/demo-medien.sh && docker compose -f server/docker-compose.local.yml up -d --build
|
|
|
|
# Eine Migration nach einer Modelländerung
|
|
dotnet ef migrations add <Name> --project src/Flaro.Data --startup-project src/Flaro.Api --output-dir Migrations
|
|
```
|
|
|
|
Migrationen wandern **beim Start** des Servers, nicht über ein eigenes
|
|
Kommando.
|
|
|
|
### Aufbau
|
|
|
|
| Projekt | Aufgabe |
|
|
|---|---|
|
|
| `Flaro.Core` | Domäne: Benutzer, Anmeldung, Bibliotheken. Kennt kein HTTP und keine Datenbank |
|
|
| `Flaro.Data` | EF Core, SQLite, Migrationen |
|
|
| `Flaro.Media` | ffprobe und ffmpeg. Als eigene Prozesse, nicht eingebunden |
|
|
| `Flaro.Metadata` | TMDB und die Bildablage. Hinter einer Schnittstelle, damit alles andere ohne Netz prüfbar bleibt |
|
|
| `Flaro.Api` | Endpunkte, Authentifizierung, Auslieferung der Oberfläche |
|
|
|
|
Was sicherheitsrelevant ist, liegt in `Flaro.Core` — dort ist es ohne Server
|
|
prüfbar, und die Tests dazu sind die, die am meisten wert sind.
|
|
|
|
### Zwei Entscheidungen, die beim Lesen Fragen aufwerfen
|
|
|
|
**Zeitpunkte liegen als Unix-Millisekunden in der Datenbank, nicht als Text.**
|
|
SQLite hat keinen Zeittyp; ein `DateTimeOffset` landet sonst als Text mitsamt
|
|
Zonenversatz, und dann steht `…T12:00+02:00` neben `…T11:00Z` — derselbe
|
|
Augenblick, als Text aber falsch herum sortiert. EF weigert sich deshalb,
|
|
`ExpiresAt > jetzt` überhaupt zu übersetzen.
|
|
|
|
**Token sind keine JWT.** Der Server schlägt sie nach, statt sie zu prüfen.
|
|
Ein nachgeschlagenes Token lässt sich **sofort** widerrufen; ein signiertes
|
|
gilt bis zum Ablauf weiter, und für ein verlorenes Telefon ist das der falsche
|
|
Satz. In der Datenbank steht nur der Fingerabdruck.
|
|
|
|
## Bestand einlesen
|
|
|
|
```
|
|
POST /api/v1/libraries/{id}/scan stösst an, antwortet sofort mit 202
|
|
GET /api/v1/libraries/{id}/scan Stand: idle | running | enriching | finished | failed
|
|
GET /api/v1/movies?search=&skip=&take=
|
|
GET /api/v1/series
|
|
GET /api/v1/series/{id}/episodes?season=
|
|
GET /api/v1/images/{schlüssel}
|
|
```
|
|
|
|
**Der Scan läuft im Hintergrund**, nicht in der Anfrage: ein Bestand mit 40 000
|
|
Titeln braucht Minuten, und eine so lange offene Anfrage läuft hinter jedem
|
|
Reverse Proxy ins Zeitlimit. Einer je Bibliothek gleichzeitig.
|
|
|
|
Zweimal scannen ergibt dasselbe wie einmal. Zugeordnet wird über den Titel
|
|
**aus dem Dateinamen** — der angezeigte kommt nach dem ersten Lauf von TMDB
|
|
und ändert sich dabei.
|
|
|
|
### Metadaten
|
|
|
|
**Flaro bringt einen TMDB-Zugang mit** — es läuft ohne Einrichtung. Wer lieber
|
|
seinen eigenen benutzt, hinterlegt ihn unter `PUT /api/v1/settings/metadata`;
|
|
der sticht den mitgelieferten. Abgefragt werden kann nur, *ob* einer da ist und
|
|
ob es der mitgelieferte ist — der Zugang selbst kommt nie zurück.
|
|
|
|
Hinterlegt werden kann beides, was auf TMDBs Kontoseite steht: der **API Read
|
|
Access Token** (empfohlen — er geht als `Authorization`-Kopfzeile hinaus, nicht
|
|
in der Adresse, und kann nur lesen) oder der ältere **API Key**.
|
|
|
|
Die Sprache steht auf `en-US` und wird in denselben Einstellungen umgestellt.
|
|
|
|
Bilder werden einmal heruntergeladen und liegen unter `FLARO_CACHE`. Die App
|
|
holt sie bei Flaro, nicht bei TMDB: sonst bräuchte sie dafür Internet, und TMDB
|
|
erführe, wer wann was ansieht.
|
|
|
|
**Der Hinweis auf TMDB ist Pflicht, keine Höflichkeit.** Deren Bedingungen
|
|
verlangen Logo und einen festen Satz. Beides liefert
|
|
`GET /api/v1/system/info` unter `attributions` — ohne Anmeldung abrufbar,
|
|
damit ein Client es auch auf dem Anmeldebildschirm zeigen kann. Jeder Client
|
|
muss es anzeigen.
|
|
|
|
## Herunterladen — mit allen Spuren
|
|
|
|
```
|
|
GET /api/v1/files/{id}/delivery was passieren wird, bevor etwas passiert
|
|
GET /api/v1/files/{id}/download die Datei — oder 202, solange umgepackt wird
|
|
```
|
|
|
|
**`delivery` zuerst fragen.** Dort steht, ob die Datei unverändert hinausgeht
|
|
oder umgepackt wird, welche Tonspuren dabei neu gerechnet werden müssen und
|
|
welche Untertitel nicht mitkönnen. Drei Gigabyte zu laden und erst danach zu
|
|
merken, dass die Untertitel fehlen, war der Anlass für dieses Projekt.
|
|
|
|
**Alle Tonspuren kommen mit.** Der Plan hat kein Feld „welche Tonspur" — es
|
|
gibt nichts auszuwählen, weil alle mitgehen. Sprachkennungen und Spurnamen
|
|
überstehen das Umpacken; nachgewiesen an einer Datei mit „Deutsch" und
|
|
„Audiodeskription", die sich allein am Namen unterscheiden.
|
|
|
|
**Das Bild wird nie angefasst.** Es wandert Byte für Byte in die MP4. Nur
|
|
Tonspuren in Codecs, die das Gerät nicht kennt — DTS, TrueHD —, werden neu
|
|
gerechnet, und auch dann keine einzige Bildzeile.
|
|
|
|
**Bildbasierte Untertitel fallen weg.** PGS und VobSub passen in keine MP4.
|
|
Das steht in `delivery` unter `subtitlesDropped`, statt stillschweigend zu
|
|
geschehen.
|
|
|
|
**Umgepackt wird auf die Platte, nicht in die Antwort.** Der bequeme Weg wäre,
|
|
ffmpeg unmittelbar durchzureichen — dann kennt aber niemand die Länge im
|
|
Voraus: kein Fortschrittsbalken, kein Fortsetzen, kein Springen. Dafür gibt es
|
|
`FLARO_TRANSCODE`.
|
|
|
|
| Variable | Bedeutung | Voreinstellung |
|
|
|---|---|---|
|
|
| `FLARO_FFMPEG` | Pfad zu ffmpeg | `ffmpeg` |
|
|
| `FLARO_FFPROBE` | Pfad zu ffprobe | `ffprobe` |
|
|
|
|
## Zuordnung korrigieren
|
|
|
|
```
|
|
GET /api/v1/movies/{id}/matches?query=&year= Vorschläge
|
|
PUT /api/v1/movies/{id}/match { "tmdbId": 70523 }
|
|
GET /api/v1/series/{id}/matches?query=&year=
|
|
PUT /api/v1/series/{id}/match
|
|
```
|
|
|
|
**Weil Raten manchmal danebengeht.** Die Suche nach „Dark" lieferte „Dark
|
|
Shadows" von 1966 — ohne Jahresangabe gewinnt bei TMDB der beliebteste
|
|
Treffer. Dagegen hilft keine bessere Heuristik, sondern nur die Möglichkeit,
|
|
es richtigzustellen.
|
|
|
|
Eine Korrektur wird **festgeschrieben**: in der Datenbank, in der NFO-Datei
|
|
und als `lockdata`. Danach sucht kein Lauf mehr danach, und ein Neuaufbau der
|
|
Datenbank oder ein Umzug findet die Entscheidung wieder. Bei einer Serie
|
|
werden die Folgen gleich mit neu geholt — die alten gehörten zur falschen
|
|
Serie.
|
|
|
|
Nur Administratoren, denn es ändert die Mediathek für alle.
|
|
|
|
## Beiwerk im Medienordner
|
|
|
|
Mit `FLARO_WRITE_SIDECARS=true` legt Flaro Plakate, Hintergründe und
|
|
NFO-Dateien neben den Film:
|
|
|
|
```
|
|
Der Untergang (2004)/
|
|
├── Der Untergang (2004).mkv
|
|
├── poster.jpg
|
|
├── fanart.jpg
|
|
└── movie.nfo
|
|
```
|
|
|
|
Liegen mehrere Filme in einem Ordner, heisst das Beiwerk
|
|
`Der Untergang (2004)-poster.jpg` — sonst überschrieben sie sich gegenseitig.
|
|
Serien bekommen `tvshow.nfo` eine Ebene über dem Staffelordner, Folgen je eine
|
|
NFO und ein Standbild neben der Datei.
|
|
|
|
**Standardmässig aus**, und die Medieneinhängung muss dafür ohne `:ro`
|
|
auskommen. Was Flaro schreiben darf, steht als Erlaubnisliste im Code
|
|
(`SidecarNames`): alles andere wird abgelehnt, und Mediendateien werden nie
|
|
geändert, umbenannt oder gelöscht. Transcode-Zwischenstände kommen nie in
|
|
einen Medienordner — die liegen unter `FLARO_TRANSCODE`.
|
|
|
|
**Gelesen wird auch ohne Schreiberlaubnis.** Eine vorhandene NFO ist eine
|
|
Zuordnung, die jemand getroffen hat; Flaro nimmt sie und sucht gar nicht erst.
|
|
Dasselbe gilt für Ordnernamen der Form `Der Untergang (2004) [tmdbid-613]` —
|
|
Flaro liest sie, benennt aber **nichts** um. Umbenennen ist der einzige
|
|
Eingriff, der eine Bibliothek wirklich zerlegen kann.
|
|
|
|
| Variable | Bedeutung | Voreinstellung |
|
|
|---|---|---|
|
|
| `FLARO_WRITE_SIDECARS` | Beiwerk in den Medienordner schreiben | `false` |
|
|
|
|
## Anmeldung am Fernseher
|
|
|
|
Ein Passwort auf der Apple-TV-Fernbedienung zu tippen ist eine Zumutung.
|
|
Stattdessen:
|
|
|
|
1. Der Fernseher fordert an und bekommt einen **sechsstelligen Code** für den
|
|
Bildschirm und einen **Abholschein**, den nur er kennt.
|
|
2. Am Telefon, angemeldet, wird der Code bestätigt — dort steht, welches Gerät.
|
|
3. Der Fernseher holt mit seinem Abholschein das Token ab.
|
|
|
|
**Der Code allein holt nie ein Token ab.** Ohne den Abholschein wären
|
|
sechsstellige Codes ein Türschloss mit einer Million Schlüsseln.
|
|
|
|
## Lizenz
|
|
|
|
**GPL-2.0-only.** Abhängigkeiten müssen dazu passen: MIT, BSD oder GPL-2.0.
|
|
**Apache-2.0 ist ausgeschlossen** — Einzelheiten und der Grund stehen in
|
|
[`LICENSES.md`](../LICENSES.md).
|