Add Gundi v2 push receiver for ICU and normalized data model
ICU now pushes camera events via a Gundi-v2-compatible API instead of dropping file triplets into S3. The new gundi-receiver service accepts them directly, so images are in the system within seconds instead of waiting out the 90s age gate + poll interval. OCR of the burnt-in camera timestamp stays mandatory (ICU only sends server times; OCR detects drifting camera clocks) but now runs asynchronously after ingest. The push path writes a normalized model that separates what the legacy metadata table conflates: camera_status (status time series), image (image properties) and detection (classifications), plus the image_with_status view as the portal's migration target. A repeatable, batched migration splits existing metadata/category rows into it. The legacy poller is unchanged and keeps writing metadata/category until the portal is switched over. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
@@ -21,8 +21,8 @@ Secrets werden **ausschliesslich** ueber Umgebungsvariablen geladen; die Werte i
|
||||
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`, `CONFIG_YAML`,
|
||||
`DEBUG`.
|
||||
`S3_SECRET_KEY`, `PG_DSN`, `DEERMAPPER_API_URL`, `DEERMAPPER_API_KEY`, `GUNDI_API_KEY`,
|
||||
`CONFIG_YAML`, `DEBUG`.
|
||||
|
||||
## Betrieb (Docker)
|
||||
|
||||
@@ -33,6 +33,76 @@ docker compose up -d --build
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
## 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:
|
||||
|
||||
```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`.
|
||||
|
||||
Reference in New Issue
Block a user