domandClaude Opus 5.5 39b22f0124 Keep top human/machine legacy categories below 0.5 for privacy blocking
The portal blocks images whose top ICU category is human or machine for non-admins. With the 0.5 threshold, 103 such images would have lost their detection and become visible. Those categories are now migrated when they were the image's top category, regardless of score.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-16 22:15:12 +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 in den letzten 24 h neue FAILED/FAIL entstanden sind (aeltere loesen keinen Dauer-Alarm aus)

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, Rohbezeichnung der Quelle
remote_cam.category_label / View detection_labeled einheitliches Label je Rohbezeichnung (Deer-Like -> deer)
remote_cam.image_superseded entfernte Gundi-Zwillinge aus dem Parallelbetrieb (mit Originalzeile)
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 (nur Klassen ab Score 0.5, ohne ''/none). Wiederholbar, batchweise, liest die Alttabellen nur:

docker compose run --rm --no-deps gundi-receiver python -m tools.migrate_legacy --plan   # nur lesen
docker compose run --rm --no-deps gundi-receiver python -m tools.migrate_legacy

Im Parallelbetrieb kommt dasselbe Bild auch ueber Gundi (gleiche imei, gleiche Dateigroesse, <= 10 min). Nach der Migration den Gundi-Zwilling entfernen; behalten wird der Legacy-Zwilling, an dem die KI-Ergebnisse haengen:

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

Vor dem Portal-Cutover und nach dem Stoppen des Pollers beides erneut ausfuehren. --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

Der Pfad schreibt unter icu/gundi/ (siehe gundi: in config.yaml); bis 2026-10-16 war es icu/gundi-test/. Der genaue Schluessel steht je Bild in image.processed_key / thumbnail_key - Konsumenten bauen ihn nicht selbst zusammen.

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%