Host(`example.tld`) entscheidet, welcher Request zum Service gehört.
Docker & Traefik
Traefik im Docker-Swarm sauber betreiben
Traefik ist in vielen Docker-Setups der zentrale Einstiegspunkt für Webdienste. Im Swarm entscheidet die Kombination aus Labels, Overlay-Netzwerken, Service-Port, TLS, Middlewares und Placement darüber, ob eine Seite sauber erreichbar ist — oder ob man bei 403, 404 oder 502 landet.
Grundsatz
Ein Traefik-Router ist nur so gut wie sein Netzwerk.
In Docker Swarm reicht es nicht, nur Labels zu setzen. Traefik muss den Zielservice
auch im richtigen Overlay-Netz erreichen können. Wenn Router und Labels korrekt aussehen,
aber der Service nicht im erwarteten Netzwerk hängt, entstehen typische Fehler wie
404, 502 oder scheinbar zufälliges Routing.
loadbalancer.server.port muss zum internen Container-Port passen.
Traefik und App-Service müssen im selben Swarm-Netzwerk hängen.
Header, CrowdSec, Auth und Redirects können Requests verändern oder blockieren.
Minimaler Label-Satz
Ein sauberer Swarm-Service braucht klare Traefik-Labels.
Die Labels liegen bei Docker Swarm auf dem Service, nicht nur auf einem einzelnen Container. Der Router-Name, die Host-Regel, der EntryPoint, TLS, der Service-Port und das Swarm-Netzwerk müssen zusammenpassen.
Beispiel
Traefik-Labels für einen Website-Service.
Grundkonfiguration
traefik.enable=true
traefik.http.routers.website.rule=Host(`example.tld`) || Host(`www.example.tld`)
traefik.http.routers.website.entrypoints=websecure
traefik.http.routers.website.tls=true
traefik.http.routers.website.tls.certresolver=le
traefik.http.routers.website.service=website
traefik.http.services.website.loadbalancer.server.port=80
traefik.swarm.network=proxy-swarm
Wichtig: traefik.swarm.network ist kein Ersatz dafür, den Service wirklich
mit diesem Netzwerk zu verbinden. Es sagt Traefik nur, welches Netzwerk genutzt werden soll.
Netzwerk prüfen
Ist der Service wirklich im Proxy-Netz?
Einer der häufigsten Fehler: Das Label zeigt auf proxy-swarm, aber der
Service hängt gar nicht in diesem Netzwerk. Dann kann Traefik zwar den Router kennen,
erreicht aber das Backend nicht sauber.
Service-Netzwerke anzeigen
docker service inspect SERVICE --format '{{json .Spec.TaskTemplate.Networks}}' | jq
docker network inspect proxy-swarm --format '{{.ID}} {{.Name}} {{.Driver}} {{.Scope}}'
Service an Overlay-Netz hängen
docker service update --network-add proxy-swarm SERVICE
docker service update --force SERVICE
Traefik API
Router und Services sichtbar machen.
Die Traefik-API ist beim Debugging extrem wertvoll. Sie zeigt, ob Router, Services und Middlewares überhaupt geladen wurden. Wenn ein Router dort nicht auftaucht, matcht Traefik den Host nicht.
Router prüfen
curl -s http://127.0.0.1:8082/api/http/routers | jq '.[] | select(.name | contains("website"))'
Services prüfen
curl -s http://127.0.0.1:8082/api/http/services | jq '.[] | select(.name | contains("website"))'
Fehlerbilder
403, 404 und 502 richtig einordnen.
HTTP-Statuscodes sind beim Traefik-Debugging Hinweise. Wichtig ist, ob die Antwort von Traefik, von einer Middleware oder vom Backend kommt.
Router matcht nicht
Häufige Ursachen: falscher Hostname, falsche Router-Rule, Labels nicht geladen, Service nicht von Traefik erkannt oder falscher EntryPoint.
Middleware blockt
Security-Middleware, CrowdSec-Bouncer, Auth oder IP-Regeln können Requests blockieren, obwohl der Router grundsätzlich korrekt ist.
Backend nicht erreichbar
Traefik findet den Router, kann aber das Backend nicht erreichen. Typisch bei falschem Netzwerk oder falschem internen Service-Port.
Zertifikat fehlt
DNS, ACME, Certresolver, EntryPoint oder SNI müssen stimmen. Sonst liefert Traefik nicht das erwartete Zertifikat.
Root und www getrennt
digital-world.dev und www.digital-world.dev sind unterschiedliche Hosts.
Beide müssen in DNS und Router-Rule berücksichtigt werden.
Replica hat alten Stand
Bei mehreren Replicas auf mehreren Nodes müssen statische Dateien oder Volumes auf allen Nodes identisch sein.
Praxisfall
Wenn die Website lokal läuft, aber extern 404 liefert.
Ein häufiger Denkfehler: Man testet den Nginx-Container direkt und bekommt 200 OK,
aber extern liefert die Domain 404. Dann ist der Webserver nicht das Problem.
Der Fehler liegt in Traefik: Host-Rule, Router, Middleware oder Netzwerk.
wget http://127.0.0.1/ im Nginx-Container funktioniert.
Traefik matcht den Router nicht oder lädt die Labels nicht richtig.
Router und Services in der Traefik-API kontrollieren.
Host-Rule, Overlay-Netzwerk und Backend-Port korrigieren.
Host-Header
127.0.0.1 ist kein echter Domain-Test.
Wenn du lokal gegen Traefik testest, brauchst du den passenden Host-Header oder
--resolve. Sonst weiß Traefik nicht, welcher Router gemeint ist.
Mit Host-Header testen
curl -I -H "Host: digital-world.dev" http://127.0.0.1/
Mit SNI testen
curl -kI --resolve digital-world.dev:443:127.0.0.1 https://digital-world.dev/
Container-Test
Backend isoliert prüfen.
Um Traefik auszuschließen, testest du direkt im Backend-Container. Wenn dort
200 OK kommt, ist der Backend-Webserver sauber.
Direkt im Container testen
docker exec CONTAINER sh -c 'wget -S -O /dev/null http://127.0.0.1/'
Webroot prüfen
docker exec CONTAINER ls -la /usr/share/nginx/html
docker inspect CONTAINER --format '{{json .Mounts}}' | jq
Swarm & Datenstand
Mehrere Replicas brauchen identische Inhalte.
Wenn ein statischer Webroot per Bind-Mount auf jedem Node liegt, muss der Datenstand auf allen Nodes identisch sein. Sonst liefert Traefik je nach Ziel-Replica unterschiedliche Ergebnisse.
1 Replica für Stabilität
- Service nur auf vorbereitetem Node laufen lassen
- Placement Constraint setzen
- Lokalen Datenstand kontrollieren
- Erst dann skalieren
Ansible Sync
- Webroot vom Quellnode holen
- Auf Website-Nodes verteilen
- Dateien prüfen
- Swarm-Service neu ausrollen
3 Replicas erst später
- Alle Nodes synchron
- Gleiche Mount-Pfade
- Gleiches Proxy-Netz
- Cluster-Test ohne 404
Debug-Runbook
Kurze Reihenfolge bei Traefik-Problemen.
Diese Reihenfolge spart Zeit, weil sie Backend, Traefik, Netzwerk und Middleware getrennt prüft.
Backend testen
docker exec CONTAINER wget -q --spider http://127.0.0.1/
Labels prüfen
docker service inspect SERVICE --pretty
Netzwerke prüfen
docker service inspect SERVICE --format '{{json .Spec.TaskTemplate.Networks}}'
Traefik API prüfen
curl -s http://127.0.0.1:8082/api/http/routers | jq
Middleware reduzieren
CrowdSec/Auth temporär entfernen und Route isoliert testen.
Extern testen
curl -I https://digital-world.dev/
Fazit
Traefik-Probleme sind fast immer systematisch lösbar.
Wenn du Backend, Router, Service, Netzwerk und Middleware getrennt prüfst, wird aus „die Seite geht nicht“ ein nachvollziehbarer Betriebsfehler mit klarer Ursache.