Merge pull request 'Migration nach llmnode' (#60) from develop into main
Deploy Production llm-node / deploy (push) Successful in 1m22s
Deploy Production / deploy (push) Successful in 1m4s

Reviewed-on: #60
This commit was merged in pull request #60.
This commit is contained in:
Lars committed 2026-10-29 15:53:41 +01:00
commit de86ec0131
15 files changed
+1002 -39

No files matched your search

@@ -0,0 +1,86 @@
# Produktions-Deployments (Raspberry Pi + llm-node)
Stand: 2026-10-29
Zwei unabhängige Prod-Deployments laufen parallel. Beide starten bei jedem Push auf `main`, jeweils als eigener Workflow-Lauf auf eigenem Runner. Ein Fehler im einen blockiert das andere nicht.
Backup, Recovery und Erstbefüllung der llm-node-DB: `RECOVERY_CONTRACT.md`.
| | Raspberry Pi (alt) | llm-node (neu) |
|---|---|---|
| Workflow | `.gitea/workflows/deploy-prod.yml` | `.gitea/workflows/deploy-prod-llm-node.yml` |
| Workflow-Name | `Deploy Production` | `Deploy Production llm-node` |
| Host | 192.168.2.49, `raspberrypi5`, aarch64 | 192.168.2.144, `llm-node`, x86_64 |
| Runner | `Raspi5-Paperless`, Label `ubuntu-latest` (Host-Modus) | `llm-node-runner`, Label `linux_host` (Host-Modus) |
| Deploy-Verzeichnis | `/home/lars/docker/shinkan` | `/home/llmadmin/docker/shinkan-prod` |
| Compose | `docker-compose.yml`, Projekt `shinkan` (Verzeichnisname) | `docker-compose.yml` + `docker-compose.llm-node.yml`, Projekt `shinkan-prod` |
| Konfiguration | `/home/lars/docker/shinkan/.env` | `/etc/shinkan/prod.env` (Workflow-Variable `ENV_FILE`) |
| Datenbank | Volume `shinkan_shinkan-db-data` auf dem Pi | Volume `shinkan-prod_shinkan-db-data` auf llm-node |
| Medien (Host) | `SHINKAN_MEDIA_HOST` laut Pi-`.env` | `/srv/shinkan/prod/media` (NFSv4 von `192.168.2.63:/volume1/shinkan-media/prod`) |
| Medien (Container) | `/app/media` | `/app/media` |
| Medienbereinigung | `retention-cron` läuft immer mit | aus; nur mit `MEDIA_RETENTION: enabled` |
| Ports | 3003, 127.0.0.1:8003, 127.0.0.1:5434 | 3003, 127.0.0.1:8003, 127.0.0.1:5434 |
| Manuell auslösen | nur per Push auf `main` | Push auf `main` oder Gitea „Run workflow“ (`workflow_dispatch`) |
Die Runner-Labels sind am 2026-10-29 aus den `.runner`-Dateien beider Hosts abgelesen worden (act_runner v0.2.11). Jeder Workflow prüft im ersten Schritt Hostname und Architektur und bricht auf einem fremden Runner ab. Wer Labels an einem Runner ändert, muss beide Workflows mitprüfen; `ubuntu-latest` darf nicht auf llm-node, `linux_host` nicht auf dem Pi registriert werden.
Das llm-node-Deployment braucht vom Pi nichts: Code kommt aus dem Gitea auf llm-node selbst, DB und Konfiguration liegen lokal, Medien direkt auf dem NAS.
## Server-Voraussetzungen auf llm-node
Außerhalb des Repos eingerichtet und nicht Teil des Workflows:
- `/etc/shinkan/prod.env`, lesbar für `llmadmin` (Runner-User), Pflicht: `DB_PASSWORD`. `SHINKAN_MEDIA_HOST` und `MEDIA_ROOT` sind optional; wenn gesetzt, müssen sie `/srv/shinkan/prod/media` bzw. `/app/media` sein. `COMPOSE_PROFILES` darf dort nicht stehen.
- NFS-Mount `/srv/shinkan/prod/media`, dauerhaft und beim Boot abgesichert. Erreichbarkeit und Monitoring des NAS liegen beim Server, nicht im Deployment.
- `/home/llmadmin/docker/shinkan-prod`; das Git-Checkout legt der Workflow beim ersten Lauf selbst an.
## docker-compose.llm-node.yml
Override nur für llm-node; Pi und Dev nutzen ihn nicht. Alle Compose-Aufrufe im Workflow (build, up, rm, ps, logs) laufen als
```bash
docker compose -p shinkan-prod -f docker-compose.yml -f docker-compose.llm-node.yml --env-file /etc/shinkan/prod.env ...
```
- Ersetzt den Medien-Mount von `backend` und `retention-cron` durch einen Bind-Mount `/srv/shinkan/prod/media` → `/app/media` mit `create_host_path: false`. Ist der Mount nicht da, startet der Container nicht, statt Medien auf die lokale Platte zu schreiben.
- Hängt `retention-cron` an das Profil `media-retention`. Ohne Profil wird der Dienst weder gebaut noch gestartet.
## Ablauf je Lauf (llm-node)
1. Runner-Guard (`llm-node`/`x86_64`)
2. `ENV_FILE` prüfen: lesbar, `DB_PASSWORD` gesetzt, kein `COMPOSE_PROFILES`, Medienwerte passend. Es werden keine Werte ausgegeben.
3. `git fetch origin main` + `git reset --hard origin/main` im Deploy-Verzeichnis
4. `build --no-cache` und `up -d --remove-orphans`. Bei `MEDIA_RETENTION: disabled` wird ein noch vorhandener `retention-cron` entfernt.
5. Healthchecks mit Wiederholung (bis ca. 3 min je Prüfung):
- `127.0.0.1:8003/api/version`
- `127.0.0.1:8003/api/health/ready` mit `status=ready`, `database=true`, `schema_complete=true` (HTTP 200 allein reicht nicht)
- `127.0.0.1:3003/api/version` und `127.0.0.1:3003/api/health/ready` (gleiche Bedingung, über Frontend-Nginx)
- `127.0.0.1:3003/`
Bei Fehler: `compose ps` und Backend-Logs, Lauf rot.
## Medienbereinigung auf llm-node aktivieren
Pi und llm-node nutzen denselben Medienbestand, aber getrennte Datenbanken. Eine Bereinigung auf einer Seite kann Dateien löschen, die die andere Datenbank noch referenziert. Deshalb ist `retention-cron` auf llm-node aus.
Aktivieren erst, wenn nur noch eine Datenbank den Bestand führt (Pi-Bereinigung abgeschaltet bzw. Cutover erfolgt):
1. In `deploy-prod-llm-node.yml` `MEDIA_RETENTION: disabled` auf `enabled` setzen.
2. Über `develop` → `main` ausrollen. Der Lauf baut und startet `retention-cron` mit Profil `media-retention`.
Die Bereinigungslogik selbst (`backend/scripts/media_retention_scheduler.py`, täglich 03:00 Europe/Berlin, kein Löschen beim Start) ist dieselbe wie auf dem Pi.
## Altes Deployment (Pi) abschalten
Nur den Workflow abschalten, nicht den Pi-Runner: der Runner bedient auch `Deploy Development` und `Test Suite`.
Eine der beiden Varianten:
- **Gitea-UI (ohne Commit):** Repository → Actions → `Deploy Production` → „Disable workflow“. Rückgängig über „Enable workflow“.
- **Im Repo:** `.gitea/workflows/deploy-prod.yml` löschen oder den Trigger auf `on: workflow_dispatch` reduzieren und über `develop` → `main` ausrollen.
Folgen:
- `deploy-prod-llm-node.yml` ist davon unberührt.
- `test.yml` startet seine Prod-Prüfungen per `workflow_run` nach `Deploy Production`. Diese Prüfungen laufen gegen das Pi-Verzeichnis und entfallen mit dem Abschalten. Sie sind nicht auf llm-node umgestellt.
- Die Pi-Container laufen weiter, einschließlich der Pi-Medienbereinigung, bis sie dort mit `docker compose down` gestoppt werden.
+200
View File
@@ -0,0 +1,200 @@
# Shinkan Backup & Recovery – Schnittstelle zum Backup-Orchestrator
Stand: 2026-10-29 · Status: **Entwurf zur Abstimmung, nichts umgesetzt**
Dieses Dokument legt fest, wie der Backup-Orchestrator (`pi-backup-orchestrator`, eigenes Projekt) und Shinkan bei Backup, Wiederherstellung und Restore-Test zusammenarbeiten. Es richtet sich an den Orchestrator-Agenten und an die Umsetzung der Shinkan-Skripte.
Grundsatz: **Der Orchestrator weiß, wann und wohin gesichert wird. Shinkan weiß, wie die eigene Datenbank sicher eingespielt und geprüft wird.** Der Orchestrator ruft Shinkan-Skripte auf und wertet Exit-Code und JSON aus. Shinkan-Interna (Migrationen, Sessions, Medienpfade, Healthchecks) stehen nicht im Orchestrator.
Verwandt: `PROD_DEPLOYMENTS.md` (Deployments Pi + llm-node), `MEDIA_ASSETS_AND_ARCHIVE_SPEC.md` (Medien-Lifecycle).
---
## 1. Ist-Stand (geprüft am 2026-10-29, nur lesend)
| Punkt | Stand |
|---|---|
| Orchestrator | `pi-backup-orchestrator` v0.3 auf dem Pi, Timer `backup-orchestrator-daily` täglich 05:30, Job `shinkan-prod-db` (Phase 10, kritisch), danach `nas-data` (Phase 20) |
| Dump | `pg_dump` im Container `shinkan-db-prod`, **Plain SQL**, PostgreSQL 16.12, ca. 1,2 MB, 94 Tabellen |
| Ablage | `/media/lars/paperless/db-backup/shinkan-prod.sql` auf der **lokalen NVMe** des Pi, fester Dateiname (bis 2026-10-28 mit Zeitstempel); auf das NAS über `nas-data` |
| Migrationen | Tabelle `schema_migrations(id, migration, executed_at)`; `migration` = Dateiname ohne `.sql`, z. B. `096_login_lockout_and_totp`. Maßgeblich ist `backend/run_migrations.py` (läuft beim Backend-Start). Die Variante in `db_init.py` (Spalte `filename`) wird beim Start nicht genutzt. |
| Medien | Gemeinsamer Bestand auf dem NAS (`192.168.2.63:/volume1/shinkan-media/prod`), im Container `/app/media`. `media_assets.storage_key` relativ (`library/…`) mit `sha256` und `byte_size`; ältere `exercise_media.file_path` als `/media/<storage_key>` |
| Ziel-Prod | llm-node, Compose-Projekt `shinkan-prod`, `docker-compose.yml` + `docker-compose.llm-node.yml`, Konfiguration `/etc/shinkan/prod.env`, Container `shinkan-db-prod` (Postgres nur `127.0.0.1:5434`) |
## 2. Begriffe
- **Backup-Satz:** Dump + Prüfsumme + Backup-Manifest + Medien-Manifest, alle mit demselben Zeitstempel. Nur ein vollständiger Satz gilt als Backup.
- **Ziel (target):** benannte, fest im Skript hinterlegte Umgebung. Kein freies Zusammenbauen von Pfaden über Parameter.
| target | Host | Zweck | Schreibt in DB |
|---|---|---|---|
| `pi-prod` | raspberrypi5 | Manifest zum bestehenden Pi-Dump | nein (nur lesend) |
| `llm-prod` | llm-node | Manifest, Recovery, Erstbefüllung | ja, nur `restore` |
| `llm-restoretest` | llm-node | Restore-Test, wird danach entfernt | ja, nur eigene Wegwerf-DB |
Jedes Skript prüft wie die Workflows Hostname und Architektur und bricht auf einem fremden Host ab. Restore auf `pi-prod` gibt es nicht.
## 3. Schnittstelle
Alle Skripte liegen im Shinkan-Repo unter `scripts/ops/` und laufen auf dem Host der Zielumgebung, aus dem jeweiligen Deploy-Checkout. Die Code-Version, gegen die geprüft wird, ist damit immer die dort deployte.
Gemeinsam für alle Befehle:
- Ergebnis als JSON in die Datei `--result <pfad>` (Orchestrator legt den Pfad fest, z. B. im Run-Log-Verzeichnis). Auf stdout nur menschenlesbares Log.
- Keine Secrets, keine Dump-Inhalte, keine personenbezogenen Daten in Log oder JSON. Tabellennamen, Zeilenzahlen, Dateipfade im Medienbestand und Versionsangaben sind erlaubt.
- Exit-Codes:
| Code | Bedeutung |
|---|---|
| 0 | erfolgreich |
| 1 | Fehler während der Ausführung (Details im JSON) |
| 2 | Aufruf oder Vorbedingung falsch (falscher Host, fehlende Datei, fehlende Bestätigung) |
| 3 | Dump passt nicht zum Code (enthält Migrationen, die der Code nicht kennt) |
| 4 | Prüfsumme stimmt nicht |
| 5 | Wiederherstellung durchgeführt, Prüfung danach fehlgeschlagen (Rollback ausgeführt bzw. im JSON beschrieben) |
### 3.1 `shinkan-backup-manifest`
Aufruf direkt nach dem Dump, im selben Orchestrator-Job.
```
shinkan-backup-manifest --target pi-prod|llm-prod --dump <datei> --out-dir <verzeichnis> --result <json>
```
Schreibt neben den Dump:
- `<dump>.sha256`
- `<dump>.manifest.json`:
- `created_at`, `host`, `target`
- `app_version` (aus `/api/version`), `git_commit` (Deploy-Checkout)
- `migrations`: Liste aus `schema_migrations.migration`, `last_migration`
- `dump_format` (`plain` | `custom`), `dump_bytes`, `dump_sha256`
- `row_counts` je Tabelle, nur informativ (eigener Lesezugriff, nicht derselbe Snapshot wie der Dump)
- `media_manifest` (Dateiname + sha256)
- `<dump>.media.jsonl`, eine Zeile je Datei im Medienbestand: `path` (relativ zu `/app/media`), `size`, `mtime`. `sha256` nur für neue oder geänderte Dateien (Cache über `path`+`size`+`mtime`), damit der Lauf bei wachsendem Bestand kurz bleibt.
Der Manifest-Job liest nur; ein Fehler darin macht den Backup-Satz unvollständig, aber nicht den Dump ungültig. Empfehlung: Job unkritisch, Kuma-Meldung eigener Monitor.
### 3.2 `shinkan-restore`
```
shinkan-restore --target llm-prod|llm-restoretest --dump <datei> --result <json>
[--confirm <db>@<host>] [--allow-overwrite] [--sessions clear|keep]
```
- `--confirm shinkan@llm-node` ist bei `llm-prod` Pflicht.
- `--allow-overwrite` ist Pflicht, wenn die Ziel-DB echte Daten hat (mindestens ein Eintrag in `profiles`). Eine frisch migrierte DB ohne Profile gilt als leer.
- `--sessions`: Default `clear`. `keep` nur bei Recovery desselben Systems nach einem Crash, wenn angemeldete Nutzer angemeldet bleiben sollen.
Ablauf (verbindlich):
1. **Vorbedingungen:** Host-Guard, Dump lesbar, `<dump>.sha256` vorhanden und passend (sonst Exit 4), Zielkonfiguration vorhanden.
2. **In eine Staging-DB einspielen,** nicht direkt in die Live-DB: `shinkan_restore_<zeitstempel>` im laufenden Postgres-Container anlegen und den Dump in **einer Transaktion** einspielen, bei Fehler Abbruch ohne Teilstand.
- Plain SQL: `psql -v ON_ERROR_STOP=1 --single-transaction`
- Custom-Format (`PGDMP`-Kopf): `pg_restore --single-transaction --exit-on-error --no-owner --no-acl`
3. **Migrationsabgleich in der Staging-DB:** Jeder Eintrag in `schema_migrations.migration` muss als `backend/migrations/<eintrag>.sql` im deployten Code existieren. Sonst ist der Dump neuer als der Code → Staging-DB löschen, Exit 3. Fehlende Einträge (Dump älter als Code) sind normal; sie werden beim Backend-Start nachgezogen.
4. **Plausibilität in der Staging-DB:** Pflichttabellen wie im Ready-Check vorhanden; `profiles`, `skills` nicht leer. Abweichung der Zeilenzahlen zum Manifest nur als Hinweis im JSON.
5. **Sessions:** bei `clear` `TRUNCATE sessions` in der Staging-DB.
6. **Umschalten:**
- Backend, Frontend und `retention-cron` stoppen (Compose `stop`, Postgres läuft weiter).
- Live-DB umbenennen: `shinkan` → `shinkan_before_<zeitstempel>`.
- Staging-DB umbenennen: `shinkan_restore_<zeitstempel>` → `shinkan`.
- Backend und Frontend starten; `retention-cron` nur, wenn es im Deployment aktiviert ist (llm-node: `MEDIA_RETENTION`).
7. **Prüfen:** dieselben Healthchecks wie im Deploy-Workflow, insbesondere `/api/health/ready` mit `status=ready`, `database=true`, `schema_complete=true`.
8. **Bei Fehler in 6–7:** Dienste stoppen, Umbenennung rückgängig machen (`shinkan_before_<zeitstempel>` → `shinkan`), Dienste starten, erneut prüfen. Exit 5 mit beiden Ergebnissen im JSON.
9. **Aufräumen:** `shinkan_before_<zeitstempel>` bleibt stehen, bis jemand sie ausdrücklich löscht (eigener Befehl `--drop-previous <name>` oder manuell). Kein automatisches Löschen.
Ergebnis-JSON u. a.: `dump_sha256`, `dump_last_migration`, `code_last_migration`, `migrations_applied_on_start`, `sessions`, `previous_db`, `health`, `duration_seconds`.
### 3.3 `shinkan-restore-test`
```
shinkan-restore-test --dump <datei> --result <json> [--playwright] [--keep]
```
Baut eine Wegwerf-Umgebung auf llm-node, spielt den Dump mit `shinkan-restore --target llm-restoretest` ein, prüft und räumt auf.
- **Eigenes Compose-Projekt** `shinkan-restoretest` mit **eigener Compose-Datei ohne `container_name`**. Die Basisdatei setzt feste Namen (`shinkan-db-prod` …) und kollidiert sonst mit Prod auf demselben Host.
- **Ports:** Frontend und Backend nur auf `127.0.0.1`, Postgres ohne veröffentlichten Port. Konkrete Ports vor Umsetzung auf llm-node prüfen.
- **Medien nur lesend:** `/srv/shinkan/prod/media:/app/media:ro`. Der Medienbestand ist gemeinsam; ein Test darf dort nichts schreiben oder löschen.
- **Aus:** `retention-cron`, SMTP (Variablen leer), `AUTO_ADMIN_FIRST_USER`, `ADMIN_BOOTSTRAP_EMAILS`, OpenRouter.
- **Prüfungen:** Ready-Check, Plausibilität wie 3.2, Medien-Abgleich (3.4) gegen den aktuellen Bestand.
- **`--playwright`:** lesende Smoke-Tests gegen `PLAYWRIGHT_BASE_URL` der Testumgebung. Tests, die hochladen oder Medien ändern, müssen ausgeschlossen werden (schreibgeschützter Mount). Testzugang über einen eigens im Test angelegten Nutzer, nicht über echte Nutzerkonten.
- **Ende:** `docker compose -p shinkan-restoretest down -v`, außer bei `--keep` (zur Fehlersuche).
Empfohlener Takt: wöchentlich mit dem jüngsten Backup-Satz, zusätzlich nach Änderungen an Dump-Format oder Migrationsrunner.
### 3.4 `shinkan-media-diff`
```
shinkan-media-diff --target llm-prod|llm-restoretest --result <json> [--manifest <dump>.media.jsonl]
```
Vergleicht die Medienverweise der (wiederhergestellten) DB mit dem aktuellen Medienbestand. Löscht und ändert nichts.
Kategorien im Ergebnis:
| Kategorie | Bedeutung | Folge |
|---|---|---|
| `missing` | in `media_assets` / `exercise_media` referenziert, Datei fehlt | reparieren oder Eintrag bereinigen |
| `mismatch` | Datei vorhanden, `byte_size` oder `sha256` passt nicht | prüfen |
| `added_after_backup` | Datei vorhanden, nicht referenziert, nicht im Medien-Manifest des Backups | Upload nach dem Backup; DB-Eintrag ging mit dem Restore verloren → Kandidat für Nachpflege |
| `orphan` | Datei vorhanden, nicht referenziert, bereits im Manifest | Kandidat zum Aufräumen |
Solange Pi und llm-node denselben Bestand mit getrennten Datenbanken nutzen, gehören `orphan` und `added_after_backup` teilweise zur anderen Installation. **Keine automatische Bereinigung** auf Basis dieses Berichts.
Der Bericht enthält immer das Versions-Tripel: App-Version und Commit des Ziels, letzte Migration der DB, Medien-Manifest des Backups.
## 4. Zuständigkeiten
| Aufgabe | Orchestrator | Shinkan |
|---|---|---|
| Zeitplan (täglich, später 2-stündlich) | ✓ | |
| Dump erzeugen (`pg_dump` im Container) | ✓ | |
| Manifest erzeugen | ruft auf | `shinkan-backup-manifest` |
| Ablage, Generationen, Kopie auf NAS | ✓ | |
| Meldungen (Kuma, Webhooks) | ✓ | liefert Exit-Code + JSON |
| Restore-Test planen | ✓ | `shinkan-restore-test` |
| Recovery auslösen | manuell über Orchestrator-CLI | `shinkan-restore` |
| Medienabgleich | ruft nach Restore auf | `shinkan-media-diff` |
| Installation auf llm-node | ✓ | |
## 5. Anforderungen an den Orchestrator
1. **Generationen auf dem NAS.** Mit festem Dateinamen gibt es lokal nur einen Stand. Auf dem NAS müssen mehrere Backup-Sätze erhalten bleiben. Vorschlag: 2-stündliche Sätze 2 Tage, tägliche 30 Tage, monatliche 12 Monate. Ein Satz wird erst überschrieben bzw. rotiert, wenn der neue vollständig ist (Dump + `.sha256` + Manifest).
2. **Atomar schreiben:** Dump erst in eine temporäre Datei, nach Erfolg umbenennen. Ein abgebrochener Dump darf den letzten guten nicht ersetzen.
3. **Dump-Format:** Plain SQL funktioniert. Empfohlen für die Zukunft: `pg_dump -Fc` (kleiner, Inhaltsverzeichnis mit `pg_restore --list`, gezielte Teil-Restores). `shinkan-restore` erkennt beide Formate.
4. **llm-node:** Eigene Orchestrator-Instanz auf llm-node für `shinkan-prod` (`docker exec shinkan-db-prod pg_dump …`). Postgres ist dort nur lokal erreichbar; Fern-Dumps vom Pi sind nicht vorgesehen.
5. **Bis zum Cutover** laufen beide Sicherungen: Pi für das alte Prod, llm-node für das neue. Ablage getrennt (`shinkan-prod-pi/`, `shinkan-prod-llm/`), damit Sätze nicht verwechselt werden.
6. **Takt für externe Kunden:** Vollständige Dumps alle 2 Stunden sind bei der aktuellen Größe unproblematisch und jeder Satz ist eigenständig einspielbar. Ein „Diff zum ersten Dump des Tages“ ist mit `pg_dump` nicht möglich; ein Textvergleich von SQL-Dumps ist kein verlässliches Backup. Für Datenverlust im Minutenbereich ist der Weg WAL-Archivierung mit Basis-Backup (z. B. pgBackRest oder WAL-G, Point-in-Time-Recovery). Das ändert die Postgres-Konfiguration und ist ein eigenes Vorhaben.
## 6. Erstbefüllung llm-node (einmalig)
Nutzt bewusst denselben Weg wie die Recovery; die Erstbefüllung ist damit der erste echte Recovery-Test.
1. Deploy-Workflow `Deploy Production llm-node` ist mindestens einmal erfolgreich gelaufen (DB frisch migriert, keine Profile).
2. Jüngsten Pi-Backup-Satz (`shinkan-prod.sql` + `.sha256` + Manifest) nach llm-node kopieren, Ablage `/var/lib/shinkan/restore/` (Verzeichnis 700, Dateien 600, Eigentümer `llmadmin`).
3. Optional vorher `shinkan-restore-test` mit diesem Satz.
4. `shinkan-restore --target llm-prod --dump … --confirm shinkan@llm-node --sessions clear` (ohne `--allow-overwrite`, da die DB als leer gilt).
5. `shinkan-media-diff --target llm-prod` und Bericht ansehen.
6. Fachliche Stichprobe (Login, Übungen, Medien).
Vor Schritt 4 klären: SMTP in `/etc/shinkan/prod.env` für die Testphase aus oder bewusst an (echte Nutzerdaten → echte Mails möglich).
Für den Cutover wird Schritt 2–6 mit Schreibstopp auf dem Pi wiederholt (Pi-Backend stoppen, Dump, Restore mit `--allow-overwrite`).
## 7. Sicherheit und Datenschutz
- Dumps enthalten E-Mail-Adressen, Passwort-Hashes und TOTP-Geheimnisse. Ablage nur mit Rechten 600/640, Transport nur im LAN per SSH, nie ins Repo, nie in Webhooks, Logs oder Kuma-Nachrichten.
- Skripte geben keine Umgebungsvariablen aus und lesen Zugangsdaten nur aus der Zielkonfiguration bzw. dem Container.
- Auf dem Pi-Prod nur lesende Zugriffe (Manifest). Kein Restore auf dem Pi.
- Restore-Test nie mit beschreibbarem Medien-Mount, nie mit aktivem SMTP.
## 8. Offene Entscheidungen
1. Dump-Format künftig `-Fc` oder weiter Plain SQL?
2. Aufbewahrung der Generationen (Vorschlag in 5.1) und ob das NAS zusätzlich Snapshots führt.
3. Ports und Takt des Restore-Tests; welche Playwright-Tests als lesender Smoke-Satz gelten.
4. Default `--sessions` bei Crash-Recovery (`clear` sicherer, `keep` bequemer).
5. Zeitpunkt für WAL-Archivierung/PITR (spätestens mit dem ersten externen Kunden mit Zusage zur Verfügbarkeit).
6. Wiederherstellung einzelner Vereine bei mehreren Kunden: mit beiden Verfahren nicht direkt möglich; bei Bedarf eigenes Export/Import-Konzept je Mandant.
+166
View File
@@ -0,0 +1,166 @@
name: Deploy Production llm-node
# Zweites, unabhängiges Prod-Deployment auf llm-node (192.168.2.144, AMD64).
# Läuft parallel zu "Deploy Production" (Raspberry Pi). Den Namen nicht auf
# "Deploy Production" ändern: test.yml hört per workflow_run exakt auf diesen Namen.
# Runner: llm-node-runner mit einzigem Label linux_host (Host-Modus).
# Der Pi-Runner (Raspi5-Paperless) hat nur ubuntu-latest und nimmt diesen Job nie an.
# Compose: docker-compose.yml + docker-compose.llm-node.yml, Konfiguration aus ENV_FILE.
# Doku: .claude/docs/technical/PROD_DEPLOYMENTS.md
on:
push:
branches: [main]
workflow_dispatch:
jobs:
deploy:
runs-on: linux_host
env:
APP_DIR: /home/llmadmin/docker/shinkan-prod
ENV_FILE: /etc/shinkan/prod.env
COMPOSE_PROJECT: shinkan-prod
REPO_URL: http://192.168.2.144:3000/Lars/shinkan-jinkendo.git
MEDIA_HOST: /srv/shinkan/prod/media
# Medienbereinigung (retention-cron): disabled | enabled.
# Pi und llm-node teilen den Medienbestand bei getrennten Datenbanken.
# Nur nach Abschalten der Pi-Bereinigung bzw. dem Cutover auf enabled setzen.
MEDIA_RETENTION: disabled
steps:
- name: Runner prüfen (nur llm-node)
shell: bash
run: |
set -euo pipefail
if [ "$(hostname)" != "llm-node" ] || [ "$(uname -m)" != "x86_64" ]; then
echo "✗ Falscher Runner: $(hostname)/$(uname -m), erwartet llm-node/x86_64. Abbruch."
exit 1
fi
echo "✓ Runner $(hostname)/$(uname -m)"
- name: Konfiguration prüfen
shell: bash
run: |
set -euo pipefail
if [ ! -r "$ENV_FILE" ]; then
echo "✗ $ENV_FILE fehlt oder ist nicht lesbar."
exit 1
fi
env_value() {
grep -E "^$1=" "$ENV_FILE" | tail -1 | cut -d= -f2- | tr -d "\"'" || true
}
if [ -z "$(env_value DB_PASSWORD)" ]; then
echo "✗ DB_PASSWORD ist in $ENV_FILE nicht gesetzt."
exit 1
fi
# Profile steuert allein MEDIA_RETENTION in diesem Workflow.
if grep -Eq "^COMPOSE_PROFILES=" "$ENV_FILE"; then
echo "✗ COMPOSE_PROFILES in $ENV_FILE entfernen; die Bereinigung schaltet MEDIA_RETENTION im Workflow."
exit 1
fi
# Override mountet fest $MEDIA_HOST -> /app/media; abweichende Werte ergäben einen zweiten Mount.
media_host="$(env_value SHINKAN_MEDIA_HOST)"
media_root="$(env_value MEDIA_ROOT)"
if [ -n "$media_host" ] && [ "$media_host" != "$MEDIA_HOST" ]; then
echo "✗ SHINKAN_MEDIA_HOST=$media_host, erwartet $MEDIA_HOST."
exit 1
fi
if [ -n "$media_root" ] && [ "$media_root" != "/app/media" ]; then
echo "✗ MEDIA_ROOT=$media_root, erwartet /app/media."
exit 1
fi
case "$MEDIA_RETENTION" in
disabled|enabled) ;;
*) echo "✗ MEDIA_RETENTION=$MEDIA_RETENTION, erlaubt: disabled | enabled."; exit 1 ;;
esac
echo "✓ $ENV_FILE geprüft, Medien $MEDIA_HOST -> /app/media, Bereinigung $MEDIA_RETENTION"
- name: Code aktualisieren
shell: bash
run: |
set -euo pipefail
cd "$APP_DIR"
if [ ! -d .git ]; then
git init -q
git remote add origin "$REPO_URL"
fi
git fetch origin main
git reset --hard origin/main
git log -1 --oneline
- name: Build und Start
shell: bash
run: |
set -euo pipefail
echo "=== Deploying Shinkan to PRODUCTION (llm-node) ==="
cd "$APP_DIR"
dc() {
docker compose -p "$COMPOSE_PROJECT" -f docker-compose.yml -f docker-compose.llm-node.yml \
--env-file "$ENV_FILE" "$@"
}
if [ "$MEDIA_RETENTION" = enabled ]; then
dc --profile media-retention build --no-cache
dc --profile media-retention up -d --remove-orphans
else
dc build --no-cache
dc up -d --remove-orphans
# Ein früher gestarteter retention-cron läuft sonst weiter.
dc --profile media-retention rm -s -f retention-cron
fi
- name: Healthchecks
shell: bash
run: |
set -euo pipefail
cd "$APP_DIR"
dc() {
docker compose -p "$COMPOSE_PROJECT" -f docker-compose.yml -f docker-compose.llm-node.yml \
--env-file "$ENV_FILE" "$@"
}
wait_for() {
local url="$1" label="$2" i
for i in $(seq 1 60); do
if curl -sf -o /dev/null "$url"; then
echo "✓ $label healthy ($url)"
return 0
fi
sleep 3
done
echo "✗ $label nicht erreichbar ($url)"
return 1
}
# HTTP 200 reicht nicht: status=ready, database=true und schema_complete=true.
wait_ready() {
local url="$1" label="$2" i body=""
for i in $(seq 1 60); do
body="$(curl -sf "$url" || true)"
if [ -n "$body" ] && printf '%s' "$body" \
| jq -e '.status == "ready" and .database == true and .schema_complete == true' >/dev/null 2>&1; then
echo "✓ $label ready ($url)"
return 0
fi
sleep 3
done
echo "✗ $label nicht ready ($url):"
printf '%s' "$body" | jq -c '{status, database, schema_complete}' 2>/dev/null || echo " keine gültige Antwort"
return 1
}
ok=1
wait_for http://127.0.0.1:8003/api/version "PROD API (direkt)" || ok=0
if [ "$ok" = 1 ]; then
wait_ready http://127.0.0.1:8003/api/health/ready "PROD API (direkt)" || ok=0
fi
if [ "$ok" = 1 ]; then
wait_for http://127.0.0.1:3003/api/version "PROD API über Frontend-Nginx" || ok=0
fi
if [ "$ok" = 1 ]; then
wait_ready http://127.0.0.1:3003/api/health/ready "PROD API über Frontend-Nginx" || ok=0
fi
if [ "$ok" = 1 ]; then
wait_for http://127.0.0.1:3003/ "PROD Frontend" || ok=0
fi
if [ "$ok" != 1 ]; then
dc ps || true
dc logs backend --tail 120 || true
exit 1
fi
echo "=== Shinkan PROD Deploy (llm-node) complete ==="
+15
View File
@@ -1,5 +1,11 @@
name: Deploy Production
# Prod-Deployment auf dem Raspberry Pi. Parallel dazu: deploy-prod-llm-node.yml.
# Namen nicht ändern: test.yml hört per workflow_run exakt auf "Deploy Production".
# Runner: Raspi5-Paperless mit einzigem Label ubuntu-latest (Host-Modus); der
# llm-node-Runner trägt dieses Label nicht. Der Guard bricht auf jedem anderen Host ab.
# Abschalten: .claude/docs/technical/PROD_DEPLOYMENTS.md
on:
push:
branches: [main]
@@ -8,6 +14,15 @@ jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Runner prüfen (nur Raspberry Pi)
run: |
set -e
if [ "$(hostname)" != "raspberrypi5" ] || [ "$(uname -m)" != "aarch64" ]; then
echo "✗ Falscher Runner: $(hostname)/$(uname -m), erwartet raspberrypi5/aarch64. Abbruch."
exit 1
fi
echo "✓ Runner $(hostname)/$(uname -m)"
- name: Deploy to Production
run: |
set -e
+46 -17
View File
@@ -1,15 +1,16 @@
name: Test Suite
# develop: push/PR → Tests gegen Dev (parallel oder vor Deploy Development).
# main: kein push/PR-Trigger — vermeidet doppelten Dev-Lauf beim Merge develop→main;
# Prod-Tests nur via workflow_run nach erfolgreichem Deploy Production.
# Eigener Workflow, getrennt von Deploy Development.
# push/PR auf develop: diese Datei, Ziel ist das Testsystem.
# workflow_run nur nach Deploy Production. Nicht nach dem Dev-Deploy:
# der Listener auf main nutzt bei fehlendem Namen sonst das Prod-Verzeichnis.
on:
push:
branches: [develop]
pull_request:
branches: [develop]
workflow_run:
workflows: ["Deploy Development", "Deploy Production"]
workflows: ["Deploy Production"]
types: [completed]
jobs:
@@ -25,18 +26,24 @@ jobs:
REF_NAME="${{ github.ref_name }}"
BASE_REF="${{ github.base_ref }}"
RUN_WORKFLOW="${{ github.event.workflow_run.name }}"
APP_DIR="/home/lars/docker/shinkan"
COMPOSE_FILE="docker-compose.yml"
HEAD_BRANCH="${{ github.event.workflow_run.head_branch }}"
if [ "$EVENT_NAME" = "workflow_run" ]; then
if [ "$RUN_WORKFLOW" = "Deploy Development" ]; then
APP_DIR="/home/lars/docker/shinkan-dev"
COMPOSE_FILE="docker-compose.dev-env.yml"
if [ "$RUN_WORKFLOW" != "Deploy Production" ]; then
echo "workflow_run ist nicht Deploy Production (name=$RUN_WORKFLOW head=$HEAD_BRANCH ref=$REF_NAME)."
echo "Produktion wird nicht angefasst."
exit 1
fi
APP_DIR="/home/lars/docker/shinkan"
COMPOSE_FILE="docker-compose.yml"
elif [ "$REF_NAME" = "develop" ] || [ "$BASE_REF" = "develop" ]; then
APP_DIR="/home/lars/docker/shinkan-dev"
COMPOSE_FILE="docker-compose.dev-env.yml"
else
echo "Kein Dev-Ziel (event=$EVENT_NAME ref=$REF_NAME base=$BASE_REF). Abbruch."
exit 1
fi
echo "CI-Ziel: $APP_DIR ($COMPOSE_FILE)"
cd "$APP_DIR"
echo "Warte auf stabilen backend-Container …"
@@ -70,16 +77,24 @@ jobs:
run: |
EVENT_NAME="${{ github.event_name }}"
REF_NAME="${{ github.ref_name }}"
BASE_REF="${{ github.base_ref }}"
RUN_WORKFLOW="${{ github.event.workflow_run.name }}"
APP_DIR="/home/lars/docker/shinkan"
HEAD_BRANCH="${{ github.event.workflow_run.head_branch }}"
if [ "$EVENT_NAME" = "workflow_run" ]; then
if [ "$RUN_WORKFLOW" = "Deploy Development" ]; then
APP_DIR="/home/lars/docker/shinkan-dev"
if [ "$RUN_WORKFLOW" != "Deploy Production" ]; then
echo "workflow_run ist nicht Deploy Production (name=$RUN_WORKFLOW head=$HEAD_BRANCH ref=$REF_NAME)."
echo "Produktion wird nicht angefasst."
exit 1
fi
elif [ "$REF_NAME" = "develop" ]; then
APP_DIR="/home/lars/docker/shinkan"
elif [ "$REF_NAME" = "develop" ] || [ "$BASE_REF" = "develop" ]; then
APP_DIR="/home/lars/docker/shinkan-dev"
else
echo "Kein Dev-Ziel (event=$EVENT_NAME ref=$REF_NAME base=$BASE_REF). Abbruch."
exit 1
fi
echo "CI-Ziel: $APP_DIR"
python3 -m py_compile "$APP_DIR/backend/main.py"
echo "✓ Backend syntax OK"
@@ -92,16 +107,24 @@ jobs:
run: |
EVENT_NAME="${{ github.event_name }}"
REF_NAME="${{ github.ref_name }}"
BASE_REF="${{ github.base_ref }}"
RUN_WORKFLOW="${{ github.event.workflow_run.name }}"
APP_DIR="/home/lars/docker/shinkan"
HEAD_BRANCH="${{ github.event.workflow_run.head_branch }}"
if [ "$EVENT_NAME" = "workflow_run" ]; then
if [ "$RUN_WORKFLOW" = "Deploy Development" ]; then
APP_DIR="/home/lars/docker/shinkan-dev"
if [ "$RUN_WORKFLOW" != "Deploy Production" ]; then
echo "workflow_run ist nicht Deploy Production (name=$RUN_WORKFLOW head=$HEAD_BRANCH ref=$REF_NAME)."
echo "Produktion wird nicht angefasst."
exit 1
fi
elif [ "$REF_NAME" = "develop" ]; then
APP_DIR="/home/lars/docker/shinkan"
elif [ "$REF_NAME" = "develop" ] || [ "$BASE_REF" = "develop" ]; then
APP_DIR="/home/lars/docker/shinkan-dev"
else
echo "Kein Dev-Ziel (event=$EVENT_NAME ref=$REF_NAME base=$BASE_REF). Abbruch."
exit 1
fi
echo "CI-Ziel: $APP_DIR"
cd "$APP_DIR/frontend"
npm install
@@ -129,6 +152,9 @@ jobs:
echo "mode=prod" >> $GITHUB_OUTPUT
echo "base_url=https://shinkan.jinkendo.de" >> $GITHUB_OUTPUT
echo "→ k6 gegen Prod-Basis."
elif [ "$EVENT" = "workflow_run" ]; then
echo "workflow_run ist nicht Deploy Production (name=$WF_NAME). Abbruch."
exit 1
else
echo "mode=dev" >> $GITHUB_OUTPUT
echo "base_url=${DEV_BASE}" >> $GITHUB_OUTPUT
@@ -219,6 +245,9 @@ jobs:
echo "mode=prod" >> $GITHUB_OUTPUT
echo "base_url=https://shinkan.jinkendo.de" >> $GITHUB_OUTPUT
echo "→ Prod. Secrets: E2E_PROD_TEST_EMAIL / E2E_PROD_TEST_PASSWORD."
elif [ "$EVENT" = "workflow_run" ]; then
echo "workflow_run ist nicht Deploy Production (name=$WF_NAME). Abbruch."
exit 1
else
echo "mode=dev" >> $GITHUB_OUTPUT
echo "base_url=${DEV_BASE}" >> $GITHUB_OUTPUT
+7 -1
View File
@@ -139,8 +139,14 @@ Git Workflow:
develop → Auto-Deploy → dev.shinkan.jinkendo.de (shinkan-dev/, Port 3098/8098)
main → Auto-Deploy → shinkan.jinkendo.de (shinkan/, Port 3003/8003)
main → Auto-Deploy → llm-node (192.168.2.144, /home/llmadmin/docker/shinkan-prod)
parallel, eigener Workflow deploy-prod-llm-node.yml
Compose-Override docker-compose.llm-node.yml, Config /etc/shinkan/prod.env
Details + Abschalten des Pi-Prod: .claude/docs/technical/PROD_DEPLOYMENTS.md
Gitea: http://192.168.2.144:3000/Lars/shinkan-jinkendo
Runner: Raspberry Pi (/home/lars/gitea-runner/)
Runner: Raspberry Pi (/home/lars/gitea-runner/, Label ubuntu-latest)
llm-node (act_runner.service, Label linux_host)
Manuell:
cd /home/lars/docker/shinkan[-dev]
+1 -1
View File
@@ -456,12 +456,12 @@ def submit_content_report(
- Journaleintrag im Medien-Audit-Log (wenn target_type=media_asset)
- E-Mail-Bestaetigung an Melder + Benachrichtigung an Plattform-Admins (best-effort)
"""
limiter._check_request_limit(request, _content_report_rate_marker, False)
if not body.good_faith_confirmed:
raise HTTPException(
status_code=400,
detail="Die Gutglaubenserklärung (good_faith_confirmed) muss bestätigt werden.",
)
limiter._check_request_limit(request, _content_report_rate_marker, False)
priority = "high" if body.report_reason in HIGH_PRIORITY_REASONS else "normal"
+2 -2
View File
@@ -2,12 +2,12 @@
"""
Automatische Medien-Retention (Papierkorb Stufe 1→2, Purge wenn fällig).
Lauf z. B. täglich per Cron:
Einzellauf (der tägliche Planer ist media_retention_scheduler.py):
cd /path/to/backend && python scripts/media_retention_job.py
Umgebung wie Backend (DB_*), optional:
MEDIA_TRASH_SOFT_TO_HIDDEN_DAYS (Default 30)
MEDIA_TRASH_HIDDEN_TO_PURGE_DAYS (Default 90)
MEDIA_TRASH_HIDDEN_TO_PURGE_DAYS (Default 30)
"""
from __future__ import annotations
@@ -0,0 +1,121 @@
#!/usr/bin/env python3
"""Täglicher Start von media_retention_job.py um 03:00 Europe/Berlin.
Der Prozess löscht beim Start nichts. Ein Lauf sofort nach dem Start nur mit
RETENTION_RUN_ON_START=1. Ein fehlgeschlagener Lauf bleibt im Log
(RETENTION_FAIL); der Prozess bleibt aktiv, damit Docker ihn nicht sofort
erneut startet.
"""
from __future__ import annotations
import logging
import os
import subprocess
import sys
import time
from datetime import datetime, timedelta
from zoneinfo import ZoneInfo
LOG = logging.getLogger("retention.scheduler")
DEFAULT_TZ = "Europe/Berlin"
_RUN_ON_START = "RETENTION_RUN_ON_START"
_TZ_ENV = "RETENTION_TZ"
def retention_zone() -> ZoneInfo:
name = os.environ.get(_TZ_ENV, DEFAULT_TZ).strip() or DEFAULT_TZ
return ZoneInfo(name)
def next_run_at(now: datetime, *, hour: int = 3) -> datetime:
"""Nächste Uhrzeit `hour`:00 in der Zeitzone von `now`.
`now` muss zeitzonenbewusst sein. Die Zone von `now` ist die Planungszone.
"""
if now.tzinfo is None:
raise ValueError("now muss eine Zeitzone tragen")
zone = now.tzinfo
local = now.astimezone(zone)
day = local.date()
target = datetime(day.year, day.month, day.day, hour, 0, 0, tzinfo=zone)
if target.timestamp() <= local.timestamp():
day = day + timedelta(days=1)
target = datetime(day.year, day.month, day.day, hour, 0, 0, tzinfo=zone)
return target
def seconds_until_next_0300(now: datetime, *, hour: int = 3) -> float:
"""Sekunden bis zum nächsten Lauf, als absolute Dauer.
`target - now` zieht bei gleicher tzinfo die Wanduhr ab und liegt an
Umstellungstagen um eine Stunde daneben. `timestamp()` rechnet in UTC.
"""
target = next_run_at(now, hour=hour)
local = now.astimezone(target.tzinfo)
return target.timestamp() - local.timestamp()
def _job_path() -> str:
return os.path.join(os.path.dirname(os.path.abspath(__file__)), "media_retention_job.py")
def _run_on_start() -> bool:
return os.environ.get(_RUN_ON_START, "").strip() == "1"
def run_job() -> int:
"""Startet den Retention-Job. Führt keine Löschung in diesem Prozess aus."""
LOG.info("Retention-Lauf startet")
completed = subprocess.run([sys.executable, "-u", _job_path()], check=False)
if completed.returncode != 0:
LOG.error("RETENTION_FAIL exit=%s", completed.returncode)
else:
LOG.info("RETENTION_OK")
return int(completed.returncode)
def serve(
*,
iterations: int | None = None,
sleep=time.sleep,
clock=None,
run=None,
) -> None:
zone = retention_zone()
if clock is None:
def clock() -> datetime:
return datetime.now(zone)
execute = run if run is not None else run_job
if _run_on_start():
LOG.info("Sofortlauf wegen RETENTION_RUN_ON_START=1")
execute()
completed = 0
while iterations is None or completed < iterations:
target = next_run_at(clock())
LOG.info("Nächster Retention-Lauf %s", target.isoformat(timespec="seconds"))
while True:
remaining = target.timestamp() - clock().timestamp()
if remaining <= 1:
break
LOG.info("Warte %.0f Sekunden bis %s", remaining, target.isoformat(timespec="seconds"))
sleep(remaining)
execute()
completed += 1
def main() -> int:
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s %(levelname)s %(message)s",
stream=sys.stdout,
force=True,
)
serve()
return 0
if __name__ == "__main__":
raise SystemExit(main())
@@ -0,0 +1,167 @@
"""Scheduler für den Papierkorb-Job: 03:00 Europe/Berlin, ohne echten Löschlauf."""
from __future__ import annotations
import logging
from datetime import datetime, timedelta
from pathlib import Path
from zoneinfo import ZoneInfo
import pytest
from scripts.media_retention_scheduler import (
next_run_at,
run_job,
seconds_until_next_0300,
serve,
)
BERLIN = ZoneInfo("Europe/Berlin")
def _compose_file() -> Path | None:
"""Repo-Root lokal. Im Backend-Image liegt nur /app, ohne docker-compose.yml."""
for parent in Path(__file__).resolve().parents:
candidate = parent / "docker-compose.yml"
if candidate.is_file():
return candidate
return None
def test_winter_afternoon_waits_until_next_morning() -> None:
now = datetime(2026, 1, 15, 10, 0, tzinfo=BERLIN)
assert next_run_at(now).isoformat() == "2026-01-16T03:00:00+01:00"
assert seconds_until_next_0300(now) == 17 * 3600
def test_summer_before_three_is_same_morning() -> None:
now = datetime(2026, 7, 15, 2, 0, tzinfo=BERLIN)
assert next_run_at(now).isoformat() == "2026-07-15T03:00:00+02:00"
assert seconds_until_next_0300(now) == 3600
def test_exactly_0300_waits_until_next_day() -> None:
now = datetime(2026, 1, 15, 3, 0, tzinfo=BERLIN)
assert next_run_at(now).isoformat() == "2026-01-16T03:00:00+01:00"
assert seconds_until_next_0300(now) == 24 * 3600
def test_spring_forward_sleeps_absolute_22_hours() -> None:
now = datetime(2026, 3, 28, 4, 0, tzinfo=BERLIN)
target = next_run_at(now)
assert target.isoformat() == "2026-03-29T03:00:00+02:00"
assert seconds_until_next_0300(now) == 22 * 3600
assert (target - now).total_seconds() == 23 * 3600
def test_fall_back_sleeps_absolute_24_hours() -> None:
now = datetime(2026, 10, 24, 4, 0, tzinfo=BERLIN)
target = next_run_at(now)
assert target.isoformat() == "2026-10-25T03:00:00+01:00"
assert seconds_until_next_0300(now) == 24 * 3600
assert (target - now).total_seconds() == 23 * 3600
def test_naive_datetime_is_rejected() -> None:
with pytest.raises(ValueError):
next_run_at(datetime(2026, 1, 15, 10, 0))
def test_serve_sleeps_before_first_run(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.delenv("RETENTION_RUN_ON_START", raising=False)
state = {"now": datetime(2026, 1, 15, 10, 0, tzinfo=BERLIN)}
events: list[tuple] = []
def clock() -> datetime:
return state["now"]
def sleep(seconds: float) -> None:
events.append(("sleep", seconds))
state["now"] = state["now"] + timedelta(seconds=seconds)
def run() -> None:
events.append(("run",))
serve(iterations=1, sleep=sleep, clock=clock, run=run)
assert events == [("sleep", 17 * 3600), ("run",)]
def test_serve_can_run_once_on_start(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv("RETENTION_RUN_ON_START", "1")
state = {"now": datetime(2026, 7, 15, 2, 0, tzinfo=BERLIN)}
events: list[str] = []
def sleep(seconds: float) -> None:
events.append("sleep")
state["now"] = state["now"] + timedelta(seconds=seconds)
serve(
iterations=1,
sleep=sleep,
clock=lambda: state["now"],
run=lambda: events.append("run"),
)
assert events == ["run", "sleep", "run"]
def test_serve_continues_after_failed_run(monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.delenv("RETENTION_RUN_ON_START", raising=False)
state = {"now": datetime(2026, 1, 15, 10, 0, tzinfo=BERLIN)}
runs: list[int] = []
def sleep(seconds: float) -> None:
state["now"] = state["now"] + timedelta(seconds=seconds)
def run() -> int:
runs.append(1)
return 1
serve(iterations=2, sleep=sleep, clock=lambda: state["now"], run=run)
assert runs == [1, 1]
def test_run_job_logs_failure_without_starting_real_job(
monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
) -> None:
class Done:
returncode = 1
monkeypatch.setattr(
"scripts.media_retention_scheduler.subprocess.run",
lambda *args, **kwargs: Done(),
)
with caplog.at_level(logging.INFO, logger="retention.scheduler"):
assert run_job() == 1
assert "RETENTION_FAIL exit=1" in caplog.text
def test_run_job_logs_success(
monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
) -> None:
class Done:
returncode = 0
seen: list[list[str]] = []
def fake_run(cmd, check=False):
seen.append(list(cmd))
return Done()
monkeypatch.setattr("scripts.media_retention_scheduler.subprocess.run", fake_run)
with caplog.at_level(logging.INFO, logger="retention.scheduler"):
assert run_job() == 0
assert seen and seen[0][-1].endswith("media_retention_job.py")
assert "RETENTION_OK" in caplog.text
assert "RETENTION_FAIL" not in caplog.text
def test_compose_starts_scheduler_script() -> None:
compose = _compose_file()
if compose is None:
pytest.skip("docker-compose.yml liegt nicht im Backend-Image")
text = compose.read_text(encoding="utf-8")
start = text.index(" retention-cron:")
block = text[start : text.index("\nvolumes:", start)]
assert 'command: ["python", "-u", "scripts/media_retention_scheduler.py"]' in block
assert "python -c" not in block
assert 'PYTHONUNBUFFERED: "1"' in block
assert "RETENTION_RUN_ON_START" not in block
+17 -1
View File
@@ -73,8 +73,24 @@ def test_submit_requires_good_faith():
good_faith_confirmed=False,
)
from routers.content_reports import submit_content_report
from starlette.requests import Request
request = Request(
{
"type": "http",
"http_version": "1.1",
"method": "POST",
"scheme": "http",
"path": "/api/content-reports",
"raw_path": b"/api/content-reports",
"query_string": b"",
"headers": [],
"client": ("127.0.0.1", 50000),
"server": ("testserver", 80),
}
)
with pytest.raises(HTTPException) as exc:
submit_content_report(body)
submit_content_report(request, body)
assert exc.value.status_code == 400
assert "Gutglauben" in exc.value.detail
+24 -3
View File
@@ -1,7 +1,7 @@
# Shinkan Jinkendo Version Information
APP_VERSION = "0.8.243"
BUILD_DATE = "2026-10-13"
APP_VERSION = "0.8.246"
BUILD_DATE = "2026-10-29"
DB_SCHEMA_VERSION = "20261012096"
MODULE_VERSIONS = {
@@ -49,10 +49,31 @@ MODULE_VERSIONS = {
"membership": "1.0.0",
"catalogs": "1.5.0", # Updated: Trainer Contexts API (Migration 012)
"maturity_models": "1.4.0", # matrix_stack_bundle: vollständiger Katalog+Modelle+Bindings Export/Import
"content_reports": "1.5.2", # POST /content-reports: 10 Meldungen pro Stunde und IP
"content_reports": "1.5.3", # Gutglauben vor dem Stundenlimit; Direktaufruf im Test mit Request
}
CHANGELOG = [
{
"version": "0.8.246",
"date": "2026-10-29",
"changes": [
"Zweites Prod-Deployment auf llm-node: eigener Workflow, Konfiguration aus /etc/shinkan/prod.env, Medien über docker-compose.llm-node.yml ohne automatisch angelegte Host-Pfade. Die Medienbereinigung startet dort nur nach ausdrücklicher Freigabe. Der Deploy gilt erst als erfolgreich, wenn /api/health/ready Datenbank und Schema bestätigt.",
],
},
{
"version": "0.8.245",
"date": "2026-10-28",
"changes": [
"Papierkorb-Retention läuft täglich um 03:00 Uhr Europe/Berlin. Ein fehlgeschlagener Lauf bleibt im Container-Log sichtbar und löscht beim Containerstart nichts.",
],
},
{
"version": "0.8.244",
"date": "2026-10-13",
"changes": [
"Inhaltsmeldungen ohne Gutglaubenserklärung zählen nicht auf das Stundenlimit.",
],
},
{
"version": "0.8.243",
"date": "2026-10-13",
+32
View File
@@ -0,0 +1,32 @@
# Ergänzung zu docker-compose.yml für das Prod-Deployment auf llm-node.
# Nur zusammen mit der Basisdatei verwenden:
# docker compose -p shinkan-prod -f docker-compose.yml -f docker-compose.llm-node.yml \
# --env-file /etc/shinkan/prod.env ...
# Pi und Dev nutzen diese Datei nicht.
services:
backend:
environment:
MEDIA_ROOT: /app/media
# Ersetzt den Medien-Mount der Basisdatei (gleiches Ziel /app/media).
# Kein create_host_path: fehlt das NFS-Verzeichnis, startet der Container nicht,
# statt auf die lokale Platte zu schreiben.
volumes:
- type: bind
source: /srv/shinkan/prod/media
target: /app/media
bind:
create_host_path: false
# Pi und llm-node teilen den Medienbestand, haben aber getrennte Datenbanken.
# Die Bereinigung startet hier nur mit Profil media-retention (siehe PROD_DEPLOYMENTS.md).
retention-cron:
profiles: ["media-retention"]
environment:
MEDIA_ROOT: /app/media
volumes:
- type: bind
source: /srv/shinkan/prod/media
target: /app/media
bind:
create_host_path: false
+2 -14
View File
@@ -89,20 +89,7 @@ services:
context: ./backend
dockerfile: Dockerfile
container_name: shinkan-retention-cron
command: >
python -c "
import time, subprocess, sys, os, datetime
def next_3am():
now = datetime.datetime.now()
target = now.replace(hour=3, minute=0, second=0, microsecond=0)
if target <= now:
target += datetime.timedelta(days=1)
return (target - now).total_seconds()
subprocess.run([sys.executable, 'scripts/media_retention_job.py'], check=False)
while True:
time.sleep(next_3am())
subprocess.run([sys.executable, 'scripts/media_retention_job.py'], check=False)
"
command: ["python", "-u", "scripts/media_retention_scheduler.py"]
working_dir: /app
environment:
DB_HOST: postgres
@@ -110,6 +97,7 @@ services:
DB_NAME: shinkan
DB_USER: shinkan_user
DB_PASSWORD: ${DB_PASSWORD}
PYTHONUNBUFFERED: "1"
MEDIA_ROOT: "${MEDIA_ROOT:-/app/media}"
# Loeschkonzept (Audit P-03b): 30 Tage Soft-Trash, dann 30 Tage Hidden, dann Purge (gesamt 60 Tage).
MEDIA_TRASH_SOFT_TO_HIDDEN_DAYS: "${MEDIA_TRASH_SOFT_TO_HIDDEN_DAYS:-30}"
+116
View File
@@ -0,0 +1,116 @@
#!/bin/sh
# Prüfungen gegen den bereits deployten Stack. Ziel ist Pflicht: dev oder prod.
# Kein Default auf Produktion.
set -eu
TARGET="${1:-}"
CHECK="${2:-}"
case "$TARGET" in
dev)
APP_DIR="/home/lars/docker/shinkan-dev"
COMPOSE_FILE="docker-compose.dev-env.yml"
BASE_URL="https://dev.shinkan.jinkendo.de"
HEALTH_TRIES=90
HEALTH_SLEEP=2
;;
prod)
APP_DIR="/home/lars/docker/shinkan"
COMPOSE_FILE="docker-compose.yml"
BASE_URL="https://shinkan.jinkendo.de"
HEALTH_TRIES=60
HEALTH_SLEEP=5
;;
*)
echo "Ziel muss dev oder prod sein, war: '${TARGET}'." >&2
exit 1
;;
esac
echo "CI-Ziel: $TARGET ($APP_DIR, $BASE_URL), Prüfung: $CHECK"
wait_health() {
echo "Warte auf $BASE_URL/health …"
i=1
while [ "$i" -le "$HEALTH_TRIES" ]; do
if curl -sf "$BASE_URL/health" >/dev/null 2>&1; then
echo "Health OK (Versuch $i)"
return 0
fi
i=$((i + 1))
sleep "$HEALTH_SLEEP"
done
echo "Timeout: $BASE_URL/health nicht erreichbar"
curl -v "$BASE_URL/health" || true
return 1
}
run_pytest() {
cd "$APP_DIR"
echo "Warte auf stabilen backend-Container …"
i=1
while [ "$i" -le 60 ]; do
if docker compose -f "$COMPOSE_FILE" exec -T backend true 2>/dev/null; then
echo "Backend bereit (Versuch $i)"
break
fi
if [ "$i" -eq 60 ]; then
echo "Timeout: backend-Container nicht bereit"
docker compose -f "$COMPOSE_FILE" ps || true
docker compose -f "$COMPOSE_FILE" logs backend --tail 80 || true
exit 1
fi
i=$((i + 1))
sleep 5
done
docker compose -f "$COMPOSE_FILE" exec -T backend sh -lc "
pip install -r /app/requirements-dev.txt &&
cd /app &&
ACCESS_LAYER_STRICT=1 python scripts/check_access_layer_hints.py &&
python scripts/security_release_checks.py &&
ACCESS_LAYER_INTEGRATION=1 TRAINING_PLANNING_INTEGRATION=1 SKIP_DB_MIGRATE=1 python -m pytest tests -m 'not slow' -ra -vv --tb=short
"
}
run_lint() {
python3 -m py_compile "$APP_DIR/backend/main.py"
echo "Backend syntax OK"
}
run_frontend() {
cd "$APP_DIR/frontend"
npm install
npm run build
echo "Frontend build OK"
}
run_k6() {
wait_health
K6_VER="v0.55.0"
ARCH=$(uname -m)
case "$ARCH" in
x86_64) K6_ARCH=amd64 ;;
aarch64|arm64) K6_ARCH=arm64 ;;
*) echo "k6: unbekannte Architektur: $ARCH" >&2; exit 1 ;;
esac
echo "Installing k6 ${K6_VER} linux-${K6_ARCH}"
curl -sSL "https://github.com/grafana/k6/releases/download/${K6_VER}/k6-${K6_VER}-linux-${K6_ARCH}.tar.gz" -o /tmp/k6.tgz
tar -xzf /tmp/k6.tgz -C /tmp
sudo mv "/tmp/k6-${K6_VER}-linux-${K6_ARCH}/k6" /usr/local/bin/k6
k6 version
cd "$APP_DIR"
echo "k6 gegen BASE_URL=$BASE_URL"
BASE_URL="$BASE_URL" k6 run scripts/load/k6-health-baseline.js
echo "k6 Health-Baseline passed"
}
case "$CHECK" in
pytest) run_pytest ;;
lint) run_lint ;;
frontend) run_frontend ;;
k6) run_k6 ;;
*)
echo "Prüfung muss pytest, lint, frontend oder k6 sein, war: '${CHECK}'." >&2
exit 1
;;
esac