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>
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.yamloder ins Git schreiben - nur in.env. PG_DSNmit?sslmode=require; die Datenbank sollte nicht oeffentlich erreichbar sein (privates Netz / Firewall / SSH-Tunnel).- Debug-Port (
5678) ist standardmaessig aus; bei Bedarf nur an127.0.0.1binden. - 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.