Files
melesICUmover/README.md
T
domandClaude Opus 5 0f574cccde Make legacy poller resilient to S3/DB outages
The poller crashed on every S3 or DB error (1162 restarts during the
fsn1 object storage degradation on 2026-09-21). Now:

- main loop catches errors per cycle, classifies them (S3 5xx/throttling,
  connection/timeouts, psycopg.OperationalError = transient; everything
  else logged with traceback) and retries with exponential backoff
  (5 s .. 5 min, reset after success); db_init runs until it succeeds once
- explicit botocore config for the poller: connect/read timeouts, standard
  retries (total attempts), s3v4, path addressing; S3(cfg) without a
  config keeps the previous client for the Gundi path
- DB connect timeout + TCP keepalives
- one S3 client per cycle shared by all workers
- a batch stops after a transient S3/DB error (image stays ERROR as before)
- no busy loop when ready sets keep failing
- [HEARTBEAT] log line with counters, heartbeat file + Docker healthcheck
- tools/entrance_inventory.py: read-only listing of icu/entrance orphans
- unit tests with simulated S3/DB failures

Per-image transaction, status names/order, keys and paths are unchanged.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-21 16:56:55 +02:00

6.1 KiB

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 (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.

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.