feat: add universal-db-restore, app migration contract, targets for kairo/tandoor/bookstack, and uptime kuma guide
This commit is contained in:
1 parent
a17afb4b13
commit
feb469d47b
10 files changed
+1079
-12
No files matched your search
@@ -0,0 +1,107 @@
|
||||
# Uptime Kuma Monitoring & Alerting Guide
|
||||
|
||||
Der `backup-orchestrator` verfügt über eine native, out-of-the-box Integration mit **Uptime Kuma**.
|
||||
Dieses Dokument beschreibt das Monitoring-Konzept, die Schritt-für-Schritt-Einrichtung und die Konfiguration.
|
||||
|
||||
---
|
||||
|
||||
## 1. Duales Überwachungskonzept
|
||||
|
||||
Das Gesamtsystem wird auf zwei komplementären Ebenen überwacht:
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
subgraph "1. Passive Push-Überwachung (Backup-Läufe & Restores)"
|
||||
BO["backup-orchestrator<br/>(systemd daily 05:30)"]
|
||||
BO -->|"HTTP Push: JOB_SUCCESS (up) / JOB_FAILED (down)"| K1["Uptime Kuma<br/>Push Monitor: Einzeljobs"]
|
||||
BO -->|"HTTP Push: RUN_FINISHED (overall ok/failed)"| K2["Uptime Kuma<br/>Push Monitor: Täglicher Gesamtlauf"]
|
||||
end
|
||||
|
||||
subgraph "2. Aktive Pull-Überwachung (Live-Dienste auf llm-node)"
|
||||
K3["Uptime Kuma<br/>HTTP(s) Monitor: 60s Intervall"]
|
||||
K3 -->|"GET /api/health/ready (Port 8003, 8001...)"| APP1["Shinkan / Kairo Backend"]
|
||||
K3 -->|"GET / (Port 3003, 8080...)"| APP2["Frontend & Web-UIs"]
|
||||
end
|
||||
```
|
||||
|
||||
### A. Passive Push-Überwachung (Heartbeat / Dead Man's Snitch)
|
||||
- **Problem bei Crons/Timern**: Wenn ein Cronjob gar nicht erst startet (Server abgestürzt, Timer deaktiviert, NAS-Mount fehlt), gibt es keine Fehlermeldung.
|
||||
- **Lösung via Kuma Push**: Der Orchestrator sendet am Ende eines Laufs aktiv ein Signal (`/api/push/<token>?status=up&msg=OK`). Bleibt dieses Signal nach 24 Stunden aus, schlägt Uptime Kuma automatisch Alarm ("Monitor DOWN").
|
||||
- Einzelne kritische Jobs (z. B. `paperless-db`, `shinkan-prod-db`, `nas-data`) können zudem dedizierte Push-Monitore bedienen.
|
||||
|
||||
### B. Aktive Pull-Überwachung (Service Health)
|
||||
- Uptime Kuma pollt im Regelbetrieb alle 60 Sekunden die Health-Endpoints (`ready_url`) der Container.
|
||||
- Nach einem Staging-Restore durch den Orchestrator wird so sofort verifiziert, ob die Anwendung auch von außen im Netzwerk wieder uneingeschränkt antwortet.
|
||||
|
||||
---
|
||||
|
||||
## 2. Einrichtung in Uptime Kuma (Schritt für Schritt)
|
||||
|
||||
### Schritt 1: Push-Monitor für den täglichen Backup-Lauf anlegen
|
||||
1. In Uptime Kuma auf **"Neuen Monitor hinzufügen"** klicken.
|
||||
2. Folgende Werte eintragen:
|
||||
- **Monitortyp**: `Push`
|
||||
- **Name**: `Backup: Täglicher Gesamtlauf (Pi 5)` (oder `Backup: Gesamtlauf llm-node`)
|
||||
- **Intervall (Heartbeat)**: `86400` Sekunden (24 Stunden)
|
||||
- **Wiederholungsintervall**: `300` Sekunden (5 Minuten)
|
||||
- **Max. Wiederholungen**: `2`
|
||||
3. Speichern. Uptime Kuma zeigt nun eine Push-URL an:
|
||||
```text
|
||||
http://<uptime-kuma-host>:3001/api/push/abc123token?status=up&msg=OK&ping=
|
||||
```
|
||||
4. Den Basis-Teil der URL kopieren: `http://<uptime-kuma-host>:3001/api/push/abc123token`.
|
||||
|
||||
### Schritt 2 (Optional): Push-Monitore für Einzeljobs anlegen
|
||||
Wiederhole den Vorgang für kritische Einzel-Jobs:
|
||||
- `Backup: Shinkan DB (Phase 10)`
|
||||
- `Backup: Paperless DB (Phase 10)`
|
||||
- `Backup: NAS Data Sync (Phase 20)`
|
||||
|
||||
---
|
||||
|
||||
## 3. Konfiguration im Backup-Orchestrator
|
||||
|
||||
Auf dem jeweiligen Server (`raspberrypi5` oder `llm-node`) wird die Datei `/etc/backup-orchestrator/notifications.json` gepflegt:
|
||||
|
||||
```json
|
||||
{
|
||||
"timeout_seconds": 3,
|
||||
"webhooks": [],
|
||||
"kuma": {
|
||||
"overall_push_url": "http://192.168.2.xxx:3001/api/push/YOUR_OVERALL_TOKEN",
|
||||
"job_push_urls": {
|
||||
"shinkan-prod-db": "http://192.168.2.xxx:3001/api/push/YOUR_SHINKAN_TOKEN",
|
||||
"paperless-db": "http://192.168.2.xxx:3001/api/push/YOUR_PAPERLESS_TOKEN",
|
||||
"nas-data": "http://192.168.2.xxx:3001/api/push/YOUR_NAS_DATA_TOKEN"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> [!IMPORTANT]
|
||||
> - Dateirechte: Die Datei muss mit `chmod 0600 /etc/backup-orchestrator/notifications.json` geschützt werden.
|
||||
> - Der Orchestrator akzeptiert sowohl die reine Basis-URL (`.../api/push/<token>`) als auch die von Kuma kopierte Beispiel-URL (`.../api/push/<token>?status=up&msg=OK`); Abfrageparameter werden automatisch bereinigt.
|
||||
|
||||
---
|
||||
|
||||
## 4. Testen der Uptime Kuma Push-Benachrichtigung
|
||||
|
||||
Um die Benachrichtigung zu testen, ohne ein vollständiges Backup auszulösen:
|
||||
|
||||
```bash
|
||||
# Trockenlauf / Status-Check (zeigt an, wie viele Kuma-URLs konfiguriert sind):
|
||||
backup-orchestrator --check
|
||||
|
||||
# Testlauf für einen einzelnen Job:
|
||||
BACKUP_ORCHESTRATOR_CUTOVER_APPROVED=YES backup-orchestrator --run --job shinkan-prod-db
|
||||
```
|
||||
|
||||
In Uptime Kuma wechselt der Monitor sofort auf **"UP"** (grün) und zeigt im Ereignisprotokoll die Job-ID, den Laufzeit-Timestamp und die Run-ID an.
|
||||
|
||||
---
|
||||
|
||||
## 5. Fehlertoleranz & Logging
|
||||
|
||||
- **Entkopplung**: Push-Benachrichtigungen werden asynchron über einen Thread-Pool versendet.
|
||||
- **Sicherheitsgarantie**: Netzwerk-Timeouts oder Fehler von Uptime Kuma verändern **niemals** den Exit-Code des Backup-Laufs. Ein erfolgreiches Backup bleibt immer `Exit 0`.
|
||||
- Fehlerhafte Push-Versuche werden in `/var/log/backup-orchestrator/<run_id>/notifications.log` protokolliert.
|
||||
Reference in new issue
Block a user