- detection from legacy category only for scores >= 0.5, without ''/none - category_label + view detection_labeled unify ICU and legacy labels - schema/003 + migrate_legacy --dedupe removes Gundi twins of legacy images (same imei, same size, <= 10 min), archived in image_superseded - migrate_legacy --plan: read-only preview of the migration - Gundi S3 prefix icu/gundi-test/ -> icu/gundi/ Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
8.3 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 / 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.