From 0950dfe26e251e59cd05d004d465b760f94b1d75 Mon Sep 17 00:00:00 2001 From: D4rkst3r Date: Wed, 12 Aug 2026 00:04:37 +0200 Subject: [PATCH] =?UTF-8?q?Anleitung=20aus=20docs/=20=E2=80=94=202026-08-1?= =?UTF-8?q?2=2000:04?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- API.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 86 insertions(+), 1 deletion(-) diff --git a/API.md b/API.md index 38e84fe..1cc94fe 100644 --- a/API.md +++ b/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/`** — 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 }