domandClaude Opus 5.5 6d518b4542 Make the Gundi receiver robust against S3/DB outages
- Upload request path uses its own S3 client with short timeouts (5s/30s,
  2 attempts) and no longer holds a DB row lock during the S3 call; S3/DB
  failures answer 503 + Retry-After instead of 500 after minutes of waiting.
- Transient S3/DB errors in ingest/OCR no longer count against max_attempts
  (previously ~15 min of outage turned images into FAILED); the sweep retries.
- The sweep no longer queues the same id twice (no pile-up during long outages).
- Backlog check logs [GUNDI][ALARM] for stuck/failed entries.
- tools/gundi_requeue.py resets FAILED/FAIL entries; unit tests for all of it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-05 16:40:48 +02:00
2026-02-06 15:31:21 +00:00
2026-02-06 11:44:32 +01:00
2026-02-06 14:05:27 +00:00

melesICUmover

Dauer-Poller, der Wildkamera-Bilder aus einem Hetzner-S3-Bucket verarbeitet: liest neue Bilder + metadata.json (+ optional _categories.json), extrahiert per OCR (Tesseract) den Overlay-Zeitstempel, schreibt EXIF-Daten (exiftool), legt verarbeitetes Bild + Thumbnail zurueck nach S3, persistiert alles nach PostgreSQL (remote_cam.*), pusht optional an die DeerMapper-API und raeumt den Entrance-Ordner auf. Zustand pro Bild in remote_cam.import_job.status.

Konfiguration

Zweigeteilt - bewusst:

Datei Inhalt Im Git?
config.yaml Nicht-geheime App-Tunables + oeffentliche Endpunkte ja (Template)
.env Secrets: S3-Keys, PG_DSN, API-Key nein (.gitignore)

Secrets werden ausschliesslich ueber Umgebungsvariablen geladen; die Werte in .env ueberschreiben bzw. ergaenzen config.yaml. Beim Start prueft die App die Vollstaendigkeit und bricht mit klarer Meldung ab, falls ein Secret fehlt.

Unterstuetzte Umgebungsvariablen: S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY, PG_DSN, DEERMAPPER_API_URL, DEERMAPPER_API_KEY, GUNDI_API_KEY, CONFIG_YAML, DEBUG.

Betrieb (Docker)

cp .env.example .env      # danach echte, rotierte Werte eintragen
chmod 600 .env
docker compose up -d --build
docker compose logs -f

Stoerungen und Lebenszeichen (Poller)

Fehler eines Zyklus (S3 5xx/Throttling, Netz, DB weg) beenden den Poller nicht: er loggt eine Zeile [CYCLE_FAIL] kind=transient ... und versucht es mit exponentiellem Backoff erneut (backoff_initial_seconds bis backoff_max_seconds, Reset nach Erfolg, dann [RECOVERED]). Unerwartete Fehler (kind=unexpected, z. B. AccessDenied oder Programmierfehler) werden zusaetzlich mit Traceback geloggt. Ein Bild, bei dem S3/DB wegbricht, bleibt wie bisher auf ERROR; der Rest des Batches wartet auf den naechsten Zyklus.

Alle heartbeat_seconds erscheint [HEARTBEAT] mit Zaehlern (Zyklen, Bilder, Fehler, letzter Erfolg). Der Docker-Healthcheck prueft, ob die Hauptschleife vorankommt (/tmp/melesicumover.heartbeat juenger als 15 min):

docker inspect -f '{{.State.Health.Status}} restarts={{.RestartCount}}' melesicumover
docker exec melesicumover cat /tmp/melesicumover.heartbeat

S3-Timeouts/-Retries stehen unter app.s3_* in config.yaml.

Eingang pruefen (verwaiste Objekte)

docker compose run --rm --no-deps melesicumover python -m tools.entrance_inventory --db

Listet icu/entrance/ nach Typ (vollstaendig, JPG ohne JSON, JSON ohne JPG, nur Kategorien, fremd) und Alter, optional mit import_job-Status. Nur lesend.

Tests

pip install -r requirements.txt
python -m unittest discover -s tests -v     # oder: python -m pytest tests

Simulierte S3-/DB-Stoerungen fuer Backoff und Fehlerbehandlung; weder Netz noch DB noetig.

Gundi-Push-Pfad (gundi-receiver)

ICU pusht Events ueber eine Gundi-v2-kompatible API. Der Service gundi-receiver (gleiches Image, gundi_receiver.py) nimmt sie entgegen:

Route Zweck
POST /v2/events/ camera_status_report oder cameratrap_rep / icu_cameratrap_rep (JSON, Objekt oder Liste)
POST /v2/events/<object_id>/attachments/ JPEG zum cameratrap_rep (multipart/form-data)
GET /healthz Healthcheck

Auth ueber den Header apikey = GUNDI_API_KEY aus der .env.

Ablauf: Event und JPEG werden durable abgelegt und sofort quittiert. Stufe 1 (Sekunden) schreibt processed-JPEG + Thumbnail und image + detection. Stufe 2 liest danach asynchron per OCR den Kamera-Zeitstempel, setzt image.ocr_ts und DateTimeOriginal. Ein Sweep holt haengengebliebene Schritte nach und markiert Events ohne Bild nach abandon_after_hours als ABANDONED.

Verhalten bei S3-/DB-Ausfall

Teil Verhalten
Status-Events, Event anlegen brauchen kein S3; bei DB-Ausfall 503 + Retry-After: 30
Bild-Upload (.../attachments/) S3-Zugriff mit kurzen Zeitlimits (gundi.upload_*: 5 s Connect, 30 s Read, 2 Versuche), ohne offene DB-Sperre. Bei S3-Stoerung 503 + Retry-After: 30; das Event bleibt bis abandon_after_hours auf AWAITING_ATTACHMENT, der Client kann wiederholen
Ingest/OCR im Hintergrund S3-/DB-Stoerungen (main.is_transient_error) zaehlen nicht gegen max_attempts; der Sweep wiederholt alle stale_after_seconds. Nur echte Datenfehler fuehren zu FAILED/FAIL
Sweep reiht dieselbe ID nicht doppelt ein (kein Stau bei langem Ausfall)
Alarm [GUNDI][ALARM] backlog ... im Log (hoechstens alle 5 min), wenn Eintraege laenger als gundi.alarm_after_seconds in RECEIVED/AWAITING_ATTACHMENT/OCR-PENDING haengen oder FAILED/FAIL existieren

Gescheiterte Eintraege zuruecksetzen (Trockenlauf ohne --apply):

docker exec -w /app melesicumover-gundi python -m tools.gundi_requeue --apply

Wichtig: Der Client (ICU) muss nach 5xx/Timeout den Upload wiederholen; ohne Wiederholung geht das Bild verloren, wenn S3 laenger ausfaellt.

Datenmodell (schema/001_domain_model.sql)

Tabelle Inhalt
remote_cam.camera_status Statusupdates / Kameraeigenschaften (Zeitreihe je IMEI)
remote_cam.image Bildeigenschaften inkl. servertime, ocr_ts, ocr_state
remote_cam.detection Objektklassifikationen, confidence 0..1
remote_cam.image_with_status View: Bild + zum servertime gueltiger Status
remote_cam.gundi_inbox Transportschicht: Rohevents + Zustand des Push-Pfads

Das Schema legt der Receiver beim Start an. Die Legacy-Tabellen metadata / category werden vom alten Poller weiter befuellt, bis das Portal umgestellt ist.

Bestandsdaten migrieren

Split metadata -> image + camera_status, category -> detection. Wiederholbar, batchweise, liest die Alttabellen nur:

docker compose run --rm --no-deps gundi-receiver python -m tools.migrate_legacy

Vor dem Portal-Cutover erneut ausfuehren, um zwischenzeitlich neue Bilder nachzuziehen. --verify-only prueft nur die Zaehlungen.

Test

docker compose up -d --build gundi-receiver
docker compose run --rm --no-deps gundi-receiver \
  python -m tools.gundi_smoke_test --url http://127.0.0.1:8090 --jpeg /pfad/zu/bild.jpg

Standardmaessig schreibt der Pfad unter icu/gundi-test/ (siehe gundi: in config.yaml); fuer den Produktivbetrieb processed_prefix / thumb_prefix auf icu/processed/ / icu/thumbnails/ umstellen.

nginx (icu.meles.eu)

vhost liegt unter deploy/nginx/icu.meles.eu:

sudo cp deploy/nginx/icu.meles.eu /etc/nginx/sites-available/
sudo ln -s /etc/nginx/sites-available/icu.meles.eu /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d icu.meles.eu --redirect

ICU-Endpunkt: https://icu.meles.eu/v2/events/ (immer https — der 80->443-Redirect ist ein 301 und wuerde POST in GET verwandeln).

Sicherheitshinweise

  • Niemals Secrets in config.yaml oder ins Git schreiben - nur in .env.
  • PG_DSN mit ?sslmode=require; die Datenbank sollte nicht oeffentlich erreichbar sein (privates Netz / Firewall / SSH-Tunnel).
  • Debug-Port (5678) ist standardmaessig aus; bei Bedarf nur an 127.0.0.1 binden.
  • Nach Kompromittierung (z.B. Secrets waren im Git): rotieren, nicht nur entfernen.

Siehe MIGRATION.md fuer Secret-Rotation, Umzug auf einen neuen Server und Stilllegung des Altservers.

S
Description
ICU images are beeing processed and stored in the meles universe with this
Readme
194 KiB
Languages
Python 98.3%
Dockerfile 1.7%