ICU sends "icu_cameratrap_rep" instead of the documented Gundi/EarthRanger type "cameratrap_rep". Events of the unknown type were stored as IGNORED, so the following attachment upload got 404 and no image was ingested. Treat both names as image events. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
155 lines
6.1 KiB
Markdown
155 lines
6.1 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
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):
|
|
|
|
```bash
|
|
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)
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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`.
|
|
|
|
### 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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`](deploy/nginx/icu.meles.eu):
|
|
|
|
```bash
|
|
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`](MIGRATION.md) fuer Secret-Rotation, Umzug auf einen neuen
|
|
Server und Stilllegung des Altservers.
|