D4rkst3randClaude Opus 5
3f706b27e1
/health gab es und bleibt, wie es ist: app.get('/health', c => c.json({ok:true})).
Diese Zeile beweist genau eines -- der Prozess nimmt Anfragen an. Daran haengt
der HEALTHCHECK des Containers, und DORT ist billig richtig: eine schwere
Pruefung, die bei einer langsamen Platte einmal ausfaellt, liesse Docker den
Container neu starten, also genau dann, wenn er unter Last steht.
Fuer eine Statusseite ist das zu duenn -- sie stuende auf Gruen, waehrend die
Platte voll ist und kein Upload mehr angenommen wird.
/status sieht deshalb wirklich nach: Datenbank (eine echte Abfrage, nicht "die
Datei ist da"), Platte (schreiben UND wieder loeschen, der einzige Beweis),
Ausliefern (eine zufaellige Datei aus der Datenbank auf der Platte nachmessen),
Bestand, Platz und Sicherung. 200 wenn der Dienst sein Geschaeft tut, 503 wenn
nicht; ?streng=1 laesst auch eine Beeintraechtigung rot werden -- WELCHES von
beiden richtig ist, weiss nur, wer die Statusseite betreibt.
Oeffentlich, aber wortkarg: keine Dateizahlen, Groessen, Pfade, Tokennamen,
Benutzer. Und mit einer Zehn-Sekunden-Bremse -- ein oeffentlicher Endpunkt, der
auf die Platte schreibt, waere sonst ein Verstaerker.
UND DABEI FIEL EIN FEHLER IN MEINEM EIGENEN ZURUECKSPIEL-SKRIPT AUF.
Der harte Weg sollte an einem Wegwerf-Container geprueft werden. Der traf
zufaellig auf ein GEBRAUCHTES Volume, und die Zahlen waren eindeutig:
media.db aus dem Archiv, mit altem WAL daneben : 0 Zeilen
dieselbe Datei ohne die beiden Begleiter : 4452 Zeilen
Dateien auf der Platte : 4452
zurueckspielen.ps1 entfernte media.db, aber NICHT media.db-wal und
media.db-shm. Die liegen bei einem echten Zurueckspielen immer da -- der
laufende Dienst arbeitet im WAL-Modus. SQLite spielt das WAL der ALTEN
Datenbank ueber die NEUE, und heraus kommt der schlimmste denkbare Zustand: der
Dienst kommt hoch, /health ist gruen, die Mediathek ist leer, waehrend alle
Dateien danebenliegen.
Drei Konsequenzen:
1. Die Aufraeumzeile steht jetzt an EINER Stelle und nimmt media.db-wal,
media.db-shm und *.tmp mit. Uebung und Ernstfall fahren denselben Befehl --
zwei Fassungen waeren zwei, von denen die geuebte die harmlosere ist.
2. Die Uebung TAEUSCHT JETZT EINE BESTEHENDE INSTALLATION VOR, bevor sie
zurueckspielt: Container starten, warten bis media.db-wal daliegt, stoppen,
und erst dann einspielen. In ein leeres Volume zu spielen probt den Fall,
der nie eintritt.
3. /status erkennt den Zustand selbst -- "kein Eintrag in der Datenbank, aber
Dateien auf der Platte". Am kaputten Container gemessen:
/health sagt: HTTP 200
/status sagt: HTTP 503
Der geuebte Lauf danach, ueber eine vorgetaeuschte Installation:
im Volume liegt jetzt: files media.db media.db-shm media.db-wal
4452 Medieneintraege, 4452 Dateien -- gleich viele
ok items/shushi.png · items/weedbud_1.png · items/cc-castella.png
Die Uebung ist bestanden.
Gefunden beim Ueben und nicht im Ernstfall. Genau dafuer gibt es sie.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
d4rk_media
Eigener Medien-Dienst für alle FiveM-Ressourcen: Dateien annehmen, ablegen, ausliefern, in einem Dashboard verwalten. Ein Container, SQLite, Dateien auf einer Platte.
Läuft unter https://fivemanage.d4rkst3r.de — Dashboard und API an der
Wurzel, Dateien unter /f/.
vehicles/adder.webp → https://fivemanage.d4rkst3r.de/f/vehicles/adder.webp
Der Pfad ist der Schlüssel. vehicles/adder.webp bleibt
vehicles/adder.webp, damit die Vorlage in einem Skript schlicht
{model}.webp lauten kann. Die Adressen stehen nirgends in der Datenbank — sie
werden bei jeder Antwort aus PUBLIC_URL gebaut. Ein Umzug auf einen anderen
Namen ist eine geänderte Variable, kein Datenbankeingriff.
| Anleitung für Skripte | Wiki — Quelle ist docs/ |
| Stand und Reihenfolge | ROADMAP.md |
| Arbeitsweise | CLAUDE.md — prüfen statt raten |
Starten
cp .env.example .env # PUBLIC_URL und ADMIN_PASSWORD ausfüllen
docker compose up -d --build
Das war es. Ein Container, ein Volume, kein zweiter Dienst.
In Portainer: Stacks → Add stack → Repository, Compose path: docker-compose.yml. Die Werte kommen als Stack-Variablen.
Compose pathnimmt genau EINE Datei. Ergänzungen werden stillschweigend übergangen — alle Container gesund, alles 502. Das hat beim Vorgänger einen Nachmittag gekostet.
An der Oberfläche arbeiten
npm --prefix server/ui install
npm --prefix server/ui run dev
Läuft auf localhost:5173 und leitet /api und /f an den Container weiter.
Dass das Sitzungs-Cookie dabei ankommt, liegt an einer Ausnahme: es trägt
Secure, und ein Browser nimmt so eines über http nur auf localhost an.
Was der Dienst kann
Hochladen — über die Skript-API mit Token (drei Rumpfformen: multipart, Base64, rohe Bytes) oder aus dem Dashboard per Ziehen und Ablegen. Bilder, Videos, Ton, PDF. Ein ZIP wird ausgepackt statt abgelegt, und die Ordner darin bleiben erhalten — 3670 Bilder einzeln ins Fenster zu ziehen ist keine Bedienung.
Ausliefern — mit ETag, 304, Bereichsanfragen und nosniff. Vorschaubilder
werden beim Upload erzeugt (320 px WebP): aus 7,5 MB je Galerieseite werden
766 KB. Bei Video ist es ein Standbild aus dem Clip (ein Zehntel hinein, weil
viele mit Schwarz beginnen), bei Ton das eingebettete Titelbild; die Kachel
trägt zusätzlich die Laufzeit.
Sparen, ohne Adressen zu ändern — neben jedem PNG und JPEG liegt eine
WebP-Fassung, ausgeliefert unter derselben Adresse je nach Accept des
Aufrufers. Nachgemessen über den ganzen Bestand: 199 MB → 33 MB, das sind
83 %. Für Lua ändert sich nichts — es schickt kein Accept: image/webp und
bekommt weiterhin das Original.
Zurückholen — Gelöschtes liegt 30 Tage im Papierkorb, danach räumt der Dienst selbst auf. Die Datei ist dann nur nicht mehr öffentlich, nicht weg.
Zählen — wie oft eine Datei geholt wurde und wann zuletzt. Beantwortet die Frage, die ein Aufbewahrungsbericht sonst nicht beantworten kann: braucht das noch jemand?
Verwalten — Galerie mit Ordnerbaum, Suche, Filter nach Medienart, Sortierung, Mehrfachauswahl, Verschieben, Löschen.
Ansehen ohne neuen Tab — Bild, Video, Ton, PDF und alles Lesbare:
Markdown wird gesetzt, .lua und .json eingefärbt, CSV als Tabelle,
alles andere mit Zeilennummern. Video und Ton mit gemerkter Lautstärke und
„weiter zum nächsten Stück"; Leertaste hält an, die Pfeile springen fünf
Sekunden, mit Umschalt wechseln sie die Datei.
Markdown wird ohne Bibliothek dargestellt, und das ist kein Geiz: der
übliche Weg endet bei dangerouslySetInnerHTML, und die Sicherheit hängt dann
an einer Filterliste. Hier entsteht nie eine HTML-Zeichenkette — der Text wird
zu React-Knoten, ein <script> in einer hochgeladenen .md erscheint als die
acht Zeichen, die es ist.
Umbenennen — Datei und Ordner, mit der Warnung, die dazugehört: die Adresse ändert sich, und der Dialog sagt vorher, wie oft die Datei geholt wurde bzw. wie viele Dateien im Ordner betroffen sind.
Nachvollziehen — ein Verlauf: wer hat wann was abgelegt, ersetzt, verschoben oder gelöscht. Dazu: nach Abrufen sortieren, und je Token sehen, was damit abgelegt wurde.
Umziehen von Fivemanage — der Dienst spricht deren Sprache
(/api/image, /api/video, /api/audio, /api/v3/file, Schlüssel nackt im
Authorization-Kopf). Fremde Skripte ziehen um, indem eine Zeile getauscht
wird. Siehe docs/API.md.
Freigeben — /s/<schlüssel> zeigt einen Ordner ohne Anmeldung, etwa einen
Fahrzeugkatalog. Freigegeben wird die Liste, nicht der Inhalt: die Dateien
sind ohnehin öffentlich, ein zurückgezogener Link nimmt nur die Übersicht weg.
Anmelden — über Discord (eine Rolle auf dem Server genügt) oder mit Passwort. Das Passwort bleibt als Notausgang.
Sichern — täglich, geprüft, in die Nextcloud. Und der Dienst meldet nach
Discord, wenn die Sicherung ausbleibt. Zurückspielen lässt sich das Ganze mit
tools\zurueckspielen.ps1 — und üben lässt es sich auch, in einem
Wegwerf-Volume neben dem laufenden Dienst.
Beobachten — /health für den Container-Healthcheck (billig, beweist nur,
dass der Prozess antwortet) und /status für eine Statusseite: das prüft
Datenbank, Platte, Ausliefern, Bestand, Platz und Sicherung und antwortet mit
503, wenn der Dienst sein Geschäft nicht mehr tun kann.
Die eine Regel
Jeder Knopf gibt Rückmeldung, auch der erfolgreiche.
Das ist der Fehler, an dem der Fivemanage-Anlauf gescheitert ist: dessen
http-util.ts warf jeden Fehlschlag als new Error(…), die Hooks prüften auf
instanceof ApiError — und damit verschwand jeder Fehler lautlos. Create organization gab weder Erfolg noch Misserfolg zurück; das Ergebnis waren
neunzehn gleichnamige Organisationen.
Deshalb hier:
- In
server/ui/src/api.tssteht der einzigefetchund genau eine Fehlerklasse. - In
store.tsstehtrun(): Aktion rein, Erfolgstext rein — es meldet bei Erfolg diesen und bei Fehlschlag den Text des Dienstes. Wer darüber geht, kann keinen stillen Knopf bauen. - Jeder wartende Knopf ist gesperrt und zeigt einen Kreisel.
- Fehlermeldungen bleiben stehen, bis jemand sie wegklickt.
- Der Dienst hat eine Auffanglinie (
app.onError): auch ein unerwarteter Fehler bekommt einen Satz statt eines nacktenInternal Server Error.
Betrieb
Sicherung
tools/sichern.ps1, täglich 04:30 als geplante Aufgabe.
Die Datenbank wird nicht kopiert, sondern über SQLites eigene
Sicherungsschnittstelle herausgeholt — im WAL-Modus liegt das Zuletzte noch
nicht in media.db. Die Bilder kommen aus einem nur lesend eingehängten
Volume dazu, alles in ein tar.gz.
Und sie prüft sich selbst: auspacken, Datenbank öffnen, Medien, Token und
Benutzer zählen, mit dem laufenden Dienst vergleichen. Danach geht sie per
WebDAV in die Nextcloud und wird von dort zurückgeholt und die Prüfsumme
verglichen — ein PUT, der 201 sagt, hat nichts bewiesen.
Zugangsdaten und Aufbewahrung stehen im Panel unter Einstellungen.
Wiki
pwsh -File tools\wiki.ps1
Trägt docs/*.md ins Gitea-Wiki. Einseitig — docs/ ist die Quelle, das
Wiki die Kopie. Wer dort tippt, verliert es beim nächsten Lauf.
Zurückspielen
pwsh -File tools\zurueckspielen.ps1 # ÜBUNG (Standard)
pwsh -File tools\zurueckspielen.ps1 -Echt # der Ernstfall
Die Übung ist der eigentliche Gewinn. Sie legt ein Wegwerf-Volume an, spielt das Archiv hinein, startet einen zweiten Dienst davor, lässt ihn drei zufällige Dateien ausliefern und vergleicht deren SHA-256 mit dem, was in der Datenbank steht — dann räumt sie alles wieder ab. Der laufende Dienst wird nicht angefasst.
Das beantwortet die Frage, die sichern.ps1 nicht beantwortet: nicht „ist
das Archiv heil", sondern „wird daraus wieder ein laufender Dienst". Ein
Backup, das man nie zurückgespielt hat, ist kein Backup, sondern eine Datei.
Zuletzt gelaufen und bestanden:
4452 Medieneinträge, 316,3 MB, 2 Token, 2 Benutzer, 0 im Papierkorb
4452 Dateien -- gleich viele wie Einträge
ok items/velum2.png 113567 B
ok items/flesh-dolphin-2star.png 3623 B
ok items/burgermeat.png 4269 B
Von Hand ginge es auch:
tar xzf d4rk_media-JJJJ-MM-TT-HHMM.tar.gz
Ergibt media.db, files/ und papierkorb/. Alles drei ins Volume legen,
während der Container steht. Vorschaubilder und WebP-Fassungen sind nicht im
Archiv — beides ist abgeleitet und wird mit zwei Knöpfen unter
Speicher → Wartung neu gerechnet.
Der Papierkorb war anfangs nicht dabei, und das war ein Fehler: seine Einträge stehen in
media.dbund waren damit gesichert, die Dateien lagen daneben und waren es nicht. Nach einem Zurückspielen hätte der Papierkorb Zeilen gezeigt, deren „zurückholen" ins Leere greift. Er kostet fast nichts — was darin liegt, ist höchstens 30 Tage alt.
Was hier bewusst fehlt
Logging. Genau dafür schleppt Fivemanage ClickHouse mit, und genau da ist der Wartungsaufwand echt. Der Verlauf im Dashboard beantwortet „wer war das" — mehr braucht es hier nicht.
Mandanten, Rollen, Teams. Ein Dienst, den eine Person betreibt.
Automatisches Löschen. Vorbereitet ist der Bericht davor: wie viel ist älter als 7/30/90/365 Tage, was liegt doppelt. Eine Regel zu bauen, bevor man weiß, was da liegt, ist der Weg, wie man Daten verliert.
Spielerportal. Setzt voraus, dass Spieler hochladen. Der richtige Weg wäre
dann presigned URLs — kurzlebige signierte Adressen, mit denen ein Client
hochlädt, ohne je einen Token zu sehen.
Zwei Dinge, die Zeit gekostet haben
Der Proxy hielt Bilder fest. NPMs assets.conf greift über eine Regex auf
jede URL, die auf .webp, .png, .js, .css endet, legt die Antwort 30
Minuten weg und ignoriert dabei unsere Kopfzeilen. Ein überschriebenes Bild
blieb damit eine halbe Stunde alt — und /api/exists/…webp wurde
zwischengespeichert und danach auch ohne Token ausgeliefert.
Behoben mit drei Blöcken in der Custom Nginx Configuration des Proxy-Hosts:
location ^~ /api/ { proxy_cache off; include conf.d/include/proxy.conf; }
location ^~ /f/ { proxy_cache off; include conf.d/include/proxy.conf; }
location ^~ /t/ { proxy_cache off; include conf.d/include/proxy.conf; }
Das ^~ ist der ganze Trick: eine gewöhnliche Präfix-Regel verliert gegen
die Regex. In einem Wegwerf-Nginx nachgemessen.
Node 22 ist festgenagelt. better-sqlite3 11.10.0 liefert fertige
Binärdateien für ABI 115 (Node 20) und 127 (Node 22) — Node 24 hat ABI 137
und fehlt. Der Griff zur neuesten Version fällt auf node-gyp zurück und
braucht python3, make und g++ im Abbild.
Herkunft
Der Vorgänger war Fivemanage Lite mit PostgreSQL, MinIO und ClickHouse. Der
Stack lief; woran er gescheitert ist, steht oben unter Die eine Regel und
ausführlich in ROADMAP.md. Von dem, was er über eine Dateiablage hinaus kann,
haben wir nichts gebraucht und alles mitgeschleppt.
Seine Compose-Dateien liegen in legacy/, als Beleg und wegen der Kommentare —
nichts davon wird noch gestartet.