Anleitung aus docs/ — 2026-08-12 00:04

API.md

@@ -137,6 +137,69 @@ direkt hierher.
 
 ---
 
+## Für eine Statusseite
+
+Zwei Adressen, beide öffentlich, beide ohne Anmeldung — und sie beantworten
+**verschiedene** Fragen.
+
+```
+GET /health    ->  200  {"ok":true}
+GET /status    ->  200 | 503  mit Begründung
+```
+
+`/health` beweist genau eines: **der Prozess nimmt Anfragen an.** Daran hängt
+auch der `HEALTHCHECK` des Containers, und dort ist eine billige Prüfung
+richtig — eine schwere, die bei einer langsamen Platte einmal ausfällt, ließe
+Docker den Container neu starten, also genau dann, wenn er unter Last steht.
+
+`/status` sieht wirklich nach:
+
+| Prüfung | wie |
+|---|---|
+| `datenbank` | eine echte Abfrage gegen eine echte Tabelle |
+| `platte` | schreiben **und wieder löschen** — der einzige Beweis |
+| `ausliefern` | eine zufällige Datei aus der Datenbank auf der Platte nachmessen |
+| `bestand` | kein Eintrag, aber Dateien da? Dann stimmt etwas nicht |
+| `platz` | ab 95 % belegt |
+| `sicherung` | älter als 26 Stunden oder fehlgeschlagen |
+
+```json
+{ "dienst": "d4rk_media", "ok": true, "stand": "gesund", "seit": 4271,
+  "pruefungen": [ { "was": "datenbank", "ok": true }, … ] }
+```
+
+**Zwei Stufen, und der Unterschied ist der zwischen „tut es nicht" und „braucht
+Aufmerksamkeit".** Datenbank, Platte, Ausliefern und Bestand sind das Geschäft
+dieses Dienstes — fällt eines aus, ist er `gestoert` und die Antwort ist
+**503**. Eine alte Sicherung oder eine volle Platte machen ihn
+`beeintraechtigt`: er liefert weiter aus, die Antwort bleibt **200**.
+
+Wer auch das rot haben will, hängt `?streng=1` an — dann gibt alles außer
+`gesund` eine 503.
+
+### In Uptime Kuma
+
+```
+Dienst läuft      https://fivemanage.d4rkst3r.de/status
+Braucht Pflege    https://fivemanage.d4rkst3r.de/status?streng=1
+```
+
+> **Warum `bestand` dabei ist.** Nachgemessen an genau diesem Dienst: wird eine
+> Sicherung zurückgespielt, ohne `media.db-wal` daneben zu entfernen, spielt
+> SQLite das WAL der **alten** Datenbank über die neue. Ergebnis: 0 Einträge,
+> während 4452 Dateien danebenliegen. Der Dienst kommt hoch, `/health` ist
+> grün, die Mediathek ist leer.
+>
+> ```
+> /health sagt:  HTTP 200
+> /status sagt:  HTTP 503   kein Eintrag in der Datenbank, aber Dateien auf der Platte
+> ```
+
+Was **nicht** hinausgeht: Dateizahlen, Größen, Pfade, Tokennamen, Benutzer. Die
+einzige Zahl ist die Laufzeit in Sekunden.
+
+---
+
 ## Anmeldung: Token
 
 Alle Skript-Wege brauchen einen Token im Kopf:
@@ -235,11 +298,33 @@ heraus wäre entweder Mixed Content oder ginge ins Leere.
 
 ---
 
-## GET /api/exists/<pfad>
+## GET /api/exists?pfad=<pfad>
 
 Für „nur fehlende" in einem Serienlauf: eine winzige Antwort gegen 130 KB
 Upload.
 
+> **Diese Form und nicht mehr `/api/exists/<pfad>`** — der Grund ist
+> nachgemessen und unangenehm. Die alte Form endet auf `.webp`, und Nginx
+> Proxy Managers `assets.conf` greift auf **jede** URL mit Bildendung:
+>
+> ```nginx
+> location ~* ^.*\.(css|js|jpe?g|gif|png|webp|...)$ {
+>     proxy_cache public-cache;
+>     proxy_ignore_headers Set-Cookie Cache-Control Expires ...;
+>     proxy_cache_valid any 30m;
+> }
+> ```
+>
+> Der Proxy legt die berechtigte Antwort weg und liefert sie danach **an jeden
+> aus, auch ohne Token** — gemessen: 200 mit voller Auskunft, `Authorization`
+> gar nicht gesetzt. Unser eigenes `Cache-Control` hilft nicht,
+> `proxy_ignore_headers` wirft es weg. Und es geht auch andersherum: landet
+> zuerst ein `401` im Zwischenspeicher, bekommen ihn 30 Minuten lang alle.
+>
+> Die Abfrageform endet nie auf eine Bildendung und ist deshalb **von sich aus**
+> dicht — ohne von einer Zeile in einer fremden Oberfläche abzuhängen. Die alte
+> Form bleibt, weil Skripte sie benutzen; neu gebaut wird mit dieser.
+
 ```json
 { "exists": true, "path": "vehicles/adder.webp",
   "url": "…", "size": 132760, "sha256": "…", "updated_at": 1786466462488 }