300f0 - pacman — Besucher-Tracking (IP/GeoIP) für die Schulung
Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/300f0-pacman-visitor-tracking.md
pacman — Besucher-Tracking (IP/GeoIP) für die Schulung
Cluster: TECH · Ordner
argocd/apps/tech/pacman/· URLhttps://pacman.prod.homeserverundhttps://pacman-prod.pke-lab.de.kubectl-Befehle in diesem Doc gelten für den TECH-Cluster (Zugriff je Cluster).
argocd/apps/tech/pacman/ liefert neben dem eigentlichen Spiel
(siehe dessen README) auch
eine bewusst sichtbare Demonstration dessen, was ein gewöhnlicher
Webserver über einen Besucher herausfindet — Client-IP (v4 und v6),
User-Agent und (optional) der aus der IP abgeleitete GeoIP-Standort. Zweck
ist eine IT-Security-Schulung mit informierten, einverstandenen
Teilnehmenden (vgl. den bewussten Seitenhieb "IT-Security kennen wir
nicht!" in argocd/apps/prod/demo-app/) — kein heimliches
Tracking von Endnutzern.
Datenschutz-Hinweis: IP-Adressen sind personenbezogene Daten. Dieses
Setup ist nur für einen abgegrenzten Schulungskontext mit informierten
Teilnehmenden gedacht, nicht für den produktiven Betrieb einer
öffentlichen Seite ohne Hinweis. Aufbewahrung ist an die
VictoriaLogs-Retention gekoppelt (argocd/apps/tech/logging/values.yaml,
aktuell 14 Tage) — es gibt keine zusätzliche, längerfristige Speicherung.
Architektur
Besucher (IPv4/IPv6)
→ Cloudflare Edge (setzt CF-Connecting-IP)
→ cloudflared (Tunnel)
→ Traefik (Ingress, Host-Header-Routing)
→ pacman-server (Go, siehe server/cmd/server/main.go)
- liest CF-Connecting-IP (Fallback: X-Forwarded-For, dann TCP-Peer), aber nur,
wenn die TCP-Gegenstelle im Pod-CIDR liegt (`TRUSTED_PROXY_CIDRS`)
- optional: GeoIP-Lookup gegen lokale DB-IP-City-Lite-DB
- loggt eine JSON-Zeile pro Request nach stdout
→ victoria-logs-collector (DaemonSet, liest Container-stdout)
→ VictoriaLogs (argocd/apps/tech/logging/)
→ Grafana-Dashboard "pacman — Besucher (IP/GeoIP)"
Warum CF-Connecting-IP und nicht nur X-Forwarded-For: Cloudflare setzt
diesen Header einmalig und verbindlich an seiner Edge auf die tatsächliche
Client-IP (v4 oder v6) — im Gegensatz zu X-Forwarded-For, das über
mehrere Hops akkumulieren kann. pacman-server nutzt ihn deshalb
vorrangig, siehe clientIP() in main.go. Die Header werden nur ausgewertet, wenn der Request aus dem Pod-Netz
(TRUSTED_PROXY_CIDRS, Standard 10.42.0.0/16, Traefik) kommt; ein direkter Aufruf aus anderen Netzen kann die
IP nicht fälschen.
Warum kein Eingriff an Traefik/cloudflared nötig war: Beide Komponenten
reichen die von Cloudflare gesetzten Header unverändert an das Backend
weiter — die Erfassung passiert komplett in pacman-server selbst, andere
Apps im Cluster sind davon nicht betroffen (bewusste Entscheidung: nur
pacman, nicht zentral am Ingress, siehe Commit-Historie).
GeoIP: lokale DB-IP-Lite-DB statt Live-API
Bewusste Wahl gegen eine externe Lookup-API (z. B. ip-api.com): Mit einer
lokalen City-DB verlässt keine Besucher-IP das Cluster für die
Standortauflösung. Ebenso bewusste Wahl gegen MaxMind GeoLite2 (das einen
Account + License-Key verlangt): DB-IP City Lite
(CC BY 4.0) ist komplett kostenlos und braucht keinen Account/Key —
direkter monatlicher Download ohne Auth, verifiziert per curl gegen die
echte DB-IP-URL beim Erstellen dieses Setups (siehe Commit-Historie).
Gleiches MMDB-Format wie MaxMind, oschwald/geoip2-golang in main.go
liest beide unverändert.
Standardmäßig aktiv (geoip.enabled: true), da das der eigentliche Zweck
dieser App ist — bei Bedarf abschaltbar, siehe
Chart-README.
Ein initContainer (curlimages/curl) lädt bei jedem Pod-Start die
aktuelle DB-IP-City-Lite-DB neu in ein gemeinsames emptyDir — kein
CronJob, keine PVC, bewusst einfach gehalten für diesen
Schulungs-Anwendungsfall. Schlägt der Download fehl, läuft der Pod
trotzdem an: pacman-server erkennt die fehlende .mmdb-Datei beim Start
und loggt dann nur die rohe IP ohne Standort (siehe openGeoIP() in
main.go) — kein CrashLoop.
Grafana-Dashboard
Das frühere Besucher-Dashboard (dashboard-pacman-visitors.yaml) wurde entfernt. Die Zugriffslogs (http_access) stehen weiter in VictoriaLogs (Datasource VictoriaLogs, Stream-Label kubernetes.pod_namespace="pacman", Nachrichtenfeld _msg) und lassen sich in Grafana Explore abfragen.
Training Mode: Autofill-Ernte über das Nickname-Feld
Zusätzlich zu fingerprint.js's eigenem Ecken-Widget (oben beschrieben,
läuft unconditional) gibt es einen zweiten, expliziten Schalter
trainingMode.enabled (Chart-Value, Env TRAINING_MODE) — koppelt das
Namensfeld der Bestenliste (src/nickname.js, siehe
Chart-README)
an dieselbe versteckte E-Mail/Tel/Adresse/PLZ-Ernte. Anders als das
Ecken-Widget ist dieser Weg standardmäßig aus und muss bewusst über
ein Chart-Release aktiviert werden.
Wichtig für den Schuleinsatz: Der Schalter wirkt serverseitig pro Host,
nicht pro Person — solange trainingMode.enabled: true auf einem
öffentlich erreichbaren Host (pacman-prod.pke-lab.de) steht, betrifft er
jeden Besucher dieser URL in dem Zeitraum, nicht nur die informierte
Klasse. Details, Risiko-Abwägung und Betriebsempfehlung (nur für das
Zeitfenster der Stunde aktivieren) stehen im Chart-README unter "Training
Mode".
Bekannte Grenzen
- Nur
pacmanist erfasst, nicht der restliche Cluster-Traffic — bewusste
Entscheidung, um den Eingriff auf eine isolierte Demo-App zu begrenzen. - GeoIP-Auflösung ist so genau wie DB-IPs kostenlose City-Lite-DB (reduzierte
Genauigkeit gegenüber der kommerziellen DB-IP-Datenbank; Stadt-Ebene ist
eine Schätzung, keine exakte Ortung). - IPv6-Besucher werden korrekt geloggt (
net.ParseIPinmain.go
unterstützt beide Familien) und lokal gegen die IPv6-Ranges der DB-IP-DB
aufgelöst — beim Erstellen dieses Setups gegen2001:4860:4860::8888
verifiziert (siehe Commit-Historie).
Fehlersuche
Logs sind strukturierte JSON-Zeilen auf stdout (slog), Level INFO und höher, ohne Einstellmöglichkeit. Im Logging-Stack: VictoriaLogs (Logging). Direkt: kubectl -n pacman logs deploy/pacman --tail=100.
| Meldung oder Symptom | Ursache | Lösung |
|---|---|---|
geoip: database not found, continuing without geo enrichment |
DB-IP-Lite-Datei fehlt (Download des initContainers fehlgeschlagen) | der Pod läuft ohne GeoIP weiter. kubectl -n pacman logs deploy/pacman -c <geoip-init> prüfen, Pod neu starten (Download einmal pro Pod-Start, monatliche Datei) |
geoip: failed to open database … |
beschädigte oder unpassende Datei | Pod neu starten, Download-Quelle prüfen |
| Besucher-IP im Log ist die Traefik-Pod-IP | TRUSTED_PROXY_CIDRS passt nicht zum Pod-Netz, Header nicht ausgewertet |
CIDR prüfen (Standard 10.42.0.0/16), Meldung parseCIDRs im Log |
| Keine Besucherdaten im Grafana-Dashboard | Logs erreichen VictoriaLogs nicht oder Dashboard-Filter | Logging, Abschnitt „Grafana-Dashboard“ |
training mode ENABLED … (Warnung beim Start) |
trainingMode.enabled: true |
gewollt für die Schulung, sonst ausschalten: erfasst Autofill-Daten aller Besucher (Training Mode) |
Antwort 429 mit Retry-After auf /api/* |
Rate-Limit je Client-IP (RATE_LIMIT_PER_MINUTE, Standard 60) überschritten, oder Tabelle voll |
kurz warten, Limit prüfen |
Pod startet nicht (ImagePullBackOff) |
Image ghcr.io/pkr-lab/pacman:<tag> privat oder Tag fehlt |
Images bauen, Paket-Sichtbarkeit |
Pod crasht mit server exited |
Port belegt oder Konfiguration | Log lesen |
Weitere Fehlerbilder zur Anwendung und zur Bestenliste: pacman (Komponente). Allgemeine Fehlersuche: zentrale Fehlersuche.