Skip to content
Artikel / 2 Min. Lesezeit

Docker-Proxy- und SOCKS5-Konfiguration: Daemon, Build, Container und Bridges

Docker hat nicht einen einzigen Proxy-Schalter. Der Daemon, der Build-Prozess und jeder Container lesen Proxy-Einstellungen an unterschiedlichen Stellen — und SOCKS5 wird vom Daemon überhaupt nicht unterstützt. Hier erfahren Sie, wie Sie jede Ebene konfigurieren und deren Funktion überprüfen.

Docker-Proxy- und SOCKS5-Konfiguration: Daemon, Build, Container und Bridges

Wenn Sie nach einem 'SOCKS5-Konfigurator' suchen, weil Docker-Pulls ständig Timeouts haben, sind Sie nicht allein. Docker hat mindestens drei Proxy-Ebenen, und sie teilen keine Einstellungen. Ein Proxy, der für docker pull funktioniert, hilft möglicherweise nicht für apt-get innerhalb eines Builds, und SOCKS5 — bei vielen Proxy-Diensten üblich — wird von den Proxy-Variablen des Docker-Daemons nicht akzeptiert. Diese Anleitung führt durch jede Ebene mit Copy-and-Paste-Konfiguration und Verifikationsschritten, damit Sie nur routen, was geroutet werden muss, und vermeiden, dass DNS- oder Zugangsdaten leaken.

Die drei Docker-Proxy-Ebenen (und wo jede einzelne gilt)

Ebene Was sie beeinflusst Wo Sie sie festlegen Protokollunterstützung
Daemon docker pull, docker push, Registry-Authentifizierung systemd-Drop-in (Linux) oder Docker Desktop-Einstellungen HTTP/HTTPS-Proxy-URLs
Build RUN-Befehle während docker build (apt, pip, npm) --build-arg + ARG im Dockerfile HTTP/HTTPS-Proxy-URLs
Container-Laufzeit Datenverkehr Ihrer App innerhalb des Containers -e-Flags oder Compose environment Hängt von der App ab (HTTP, HTTPS, SOCKS5, wenn die App es unterstützt)

Ein vierter Ort, den Leute vergessen: der Paketmanager und die Tools des Hosts selbst. Wenn Sie die Docker-Registry nicht erreichen können, erreichen Sie auf dem Host normalerweise auch apt oder pip nicht. Legen Sie zuerst einen Proxy auf Host-Ebene fest und konfigurieren Sie dann Docker. Für anwendungsspezifisches Routing auf dem Host lesen Sie unseren SOCKS5-Konfigurator-Leitfaden für Browser, SSH, curl, git und Python.

Proxy auf Daemon-Ebene: für das Pullen von Images und die Kommunikation mit Registries

Der Docker-Daemon liest Standard-Proxy-Umgebungsvariablen aus seinem systemd-Dienst. Erstellen Sie eine Drop-in-Datei:

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/http-proxy.conf > /dev/null <<'EOF'
[Service]
Environment=HTTP_PROXY=http://user:[email protected]:3128
Environment=HTTPS_PROXY=http://user:[email protected]:3128
Environment=NO_PROXY=localhost,127.0.0.1,::1,.internal.example,registry.internal.example
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

Hinweise:

  • Der Wert ist die Proxy-URL. Für einen Standard-HTTP-Proxy, der CONNECT unterstützt, verwenden Sie http://. Wenn Ihr Proxy-Endpunkt selbst TLS-geschützt ist, verwenden Sie https://.
  • NO_PROXY sollte jede interne Registry oder jeden Host enthalten, die bzw. den Sie nicht über den Proxy leiten möchten. Der führende Punkt in .internal.example stimmt in vielen Implementierungen mit Subdomains überein, aber das Verhalten variiert.
  • Zugangsdaten in der systemd-Datei sind für root sichtbar. Für gemeinsam genutzte Maschinen ziehen Sie einen lokalen Forwarder in Betracht, der keine Zugangsdaten in der Umgebung erfordert.

Überprüfen:

docker info | grep -i -A2 'Proxy'

Sie sollten Zeilen für HTTP Proxy, HTTPS Proxy und No Proxy sehen. Wenn sie leer sind, hat der Daemon die Drop-in-Datei nicht übernommen.

Testen Sie dann einen Pull:

docker pull alpine:latest

Wenn es weiterhin fehlschlägt, prüfen Sie die Daemon-Logs:

journalctl -u docker.service --no-pager -n 50

Docker Desktop (macOS/Windows) hat eine GUI-Proxy-Einstellung unter Einstellungen, Ressourcen, Proxies. Sie schreibt dieselben Variablen für den Daemon.

Proxy zur Build-Zeit: wenn der Pull funktioniert, aber RUN apt-get nicht

Der Daemon-Proxy gilt nicht automatisch für Build-Container. Sie müssen Proxy-Argumente übergeben und sie im Dockerfile deklarieren.

FROM debian:bookworm-slim

ARG HTTP_PROXY
ARG HTTPS_PROXY
ARG NO_PROXY

RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && rm -rf /var/lib/apt/lists/*

Build:

docker build --build-arg HTTP_PROXY=http://user:[email protected]:3128 --build-arg HTTPS_PROXY=http://user:[email protected]:3128 --build-arg NO_PROXY=localhost,127.0.0.1 -t myapp .

Wichtig: --build-arg-Werte können in der Image-Historie und in Build-Logs sichtbar sein. Betten Sie niemals Zugangsdaten in ein finales Image ein. Verwenden Sie Multi-Stage-Builds und heben Sie die Argumente vor der finalen Stage auf, oder verwenden Sie BuildKit-Secret-Mounts für Zugangsdaten.

Proxy pro Container: Umgebungsvariablen zur Laufzeit festlegen

Legen Sie für Apps, die Proxy-Umgebungsvariablen lesen, diese beim Start des Containers fest:

docker run --rm -e HTTP_PROXY=http://proxy.example:3128 -e HTTPS_PROXY=http://proxy.example:3128 -e NO_PROXY=localhost,127.0.0.1 myapp

In Docker Compose:

services:
  app:
    image: myapp
    environment:
      HTTP_PROXY: http://proxy.example:3128
      HTTPS_PROXY: http://proxy.example:3128
      NO_PROXY: localhost,127.0.0.1,.internal.example

Nicht jede Anwendung beachtet diese Variablen. Manche lesen nur das kleingeschriebene http_proxy, manche ignorieren NO_PROXY vollständig, und manche haben ihre eigene Konfigurationsdatei. Prüfen Sie immer die Dokumentation der App.

SOCKS5: Warum die Proxy-Variablen von Docker es nicht akzeptieren

Der Docker-Daemon und die Proxy-Variablen von --build-arg erwarten HTTP- oder HTTPS-Proxy-URLs. socks5:// ist kein unterstütztes Schema für den Daemon. Wenn Ihr Proxy-Dienst Ihnen nur einen SOCKS5-Endpunkt gibt, haben Sie drei praktische Optionen:

  1. Führen Sie eine lokale HTTP-zu-SOCKS5-Bridge aus. Ein kleiner Forwarder lauscht auf 127.0.0.1:3128 und leitet an Ihren SOCKS5-Proxy weiter. Richten Sie dann Dockers HTTP_PROXY auf die Bridge. Dadurch bleiben SOCKS5-Zugangsdaten aus der Docker-Umgebung heraus.
  2. Verwenden Sie SSH-Dynamic-Forwarding plus eine Bridge. ssh -D 1080 gibt Ihnen einen lokalen SOCKS5-Proxy; die Bridge konvertiert ihn für Docker zu HTTP. Das funktioniert gut, wenn Sie bereits SSH-Zugriff auf einen Remote-Host haben.
  3. Konfigurieren Sie die Anwendung im Container so, dass sie SOCKS5 direkt verwendet. Viele Tools (curl, requests, git) unterstützen socks5h:// nativ. Dies umgeht die Proxy-Einstellungen von Docker vollständig und betrifft nur diese App.

Beispiel: SOCKS5 aus einem Container heraus ohne Bridge mit curl testen. Fügen Sie unter Linux --add-host=host.docker.internal:host-gateway hinzu, damit der Container einen auf dem Host laufenden Proxy erreichen kann.

docker run --rm --add-host=host.docker.internal:host-gateway curlimages/curl:latest --socks5-hostname host.docker.internal:1080 https://ifconfig.me

--socks5-hostname sendet den Hostnamen zur DNS-Auflösung an den Proxy, wodurch DNS-Leaks vermieden werden. Wenn Sie --socks5 verwenden, löst curl DNS lokal auf und tunnelt nur die TCP-Verbindung — eine häufige Quelle für falsche Geolokalisierung und Leaks.

Für Anwendungscode ist das Schema socks5h oft klarer:

curl --proxy socks5h://user:[email protected]:1080 https://ifconfig.me

Überprüfen, ob der Proxy tatsächlich verwendet wird (und Leaks aufdecken)

Nach der Konfiguration überprüfen Sie auf jeder Ebene:

  • Daemon: docker info | grep -i proxy zeigt die Variablen. Dann sollte docker pull den Proxy treffen. Sie können auch die Logs des Proxys selbst auf eine CONNECT-Anfrage an registry-1.docker.io:443 prüfen.
  • Build: Fügen Sie einen RUN-Schritt hinzu, der die beobachtete IP ausgibt: RUN curl -s https://ifconfig.me || true. Wenn die IP Ihre echte ist, wird der Build nicht über den Proxy geleitet. Entfernen Sie diese Zeile vor dem Ausliefern.
  • Container: docker exec -it <container> sh -c 'curl -s https://ifconfig.me' und vergleichen Sie mit Ihrer echten IP.
  • DNS: HTTP-Proxys lösen DNS für HTTPS normalerweise auf der Proxy-Seite auf (über CONNECT), aber einfache HTTP-Anfragen können DNS leaken, wenn der Client lokal auflöst. SOCKS5 mit socks5h löst immer remote auf. Wenn DNS wichtig ist, testen Sie mit einem DNS-Leak-Checker oder prüfen Sie die Proxy-Logs.

Häufige Fallstricke bei Docker und Proxys

  • NO_PROXY ist nicht automatisch. Wenn Ihre interne Registry oder ein Dienst auf dem Host unnötigerweise über den Proxy läuft, fügen Sie ihn zu NO_PROXY hinzu. Fügen Sie localhost, 127.0.0.1 und alle internen Domains hinzu.
  • Groß- vs. Kleinschreibung. Manche Tools lesen HTTP_PROXY, andere http_proxy. Legen Sie beide fest, wenn Sie unsicher sind. In Dockerfiles reicht ARG HTTP_PROXY aus, damit der Build-Prozess die großgeschriebene Variante liest; fügen Sie ARG http_proxy hinzu, wenn ein bestimmtes Tool die kleingeschriebene benötigt.
  • Zugangsdaten in der Build-Historie. --build-arg-Werte können in docker history auftauchen. Verwenden Sie BuildKit-Secret-Mounts (--mount=type=secret) für Tokens und Passwörter.
  • Docker Desktop vs. Linux-Daemon. Unter Linux bearbeiten Sie systemd; bei Docker Desktop verwenden Sie die GUI oder settings.json. Gehen Sie nicht davon aus, dass ein Linux-Tutorial für Docker Desktop gilt.
  • IPv6 und Dual-Stack. Wenn Ihr Proxy nur IPv4 unterstützt, zwingen Sie den Container oder Daemon, IPv4 zu bevorzugen. Manche Tools benötigen ein explizites Flag.

Ein praktischer Workflow für eingeschränkte oder gefilterte Netzwerke

Wenn Sie aus einem Netzwerk arbeiten, in dem der Registry-Zugriff langsam, gedrosselt oder gefiltert ist — was in manchen Unternehmens- und nationalen Netzwerken üblich ist —, beginnen Sie mit dem Daemon-Proxy, damit Image-Pulls erfolgreich sind. Fügen Sie dann Build-Zeit-Argumente für Paketmanager hinzu. Legen Sie schließlich Laufzeit-Umgebungsvariablen nur für Container fest, die Egress über den Proxy benötigen. Wenn Ihr einziger Proxy-Endpunkt SOCKS5 ist, führen Sie eine lokale Bridge aus und richten Sie die HTTP-Proxy-Variablen von Docker darauf, oder behalten Sie SOCKS5 im Container für Apps, die es direkt unterstützen.

Dieser geschichtete Ansatz vermeidet, den gesamten Container-Datenverkehr durch den Proxy zu leiten, wenn nur Image-Pulls und Build-Schritte ihn erfordern. Außerdem bleiben Zugangsdaten an weniger Stellen.

Fazit

Die Docker-Proxy-Konfiguration ist nicht eine Einstellung; sie besteht aus einer Daemon-Einstellung, einem Build-Zeit-Argument und einer Umgebungsvariable pro Container. SOCKS5 wird nur dort unterstützt, wo die Anwendung es unterstützt — der Daemon von Docker nicht. Indem Sie jede Ebene bewusst konfigurieren und mit docker info, einem Test-Pull und einer IP-Prüfung im Container verifizieren, halten Sie Builds am Laufen, ohne DNS zu leaken oder Zugangsdaten in Images einzubetten.