Wprowadzenie: po co menedżerom pakietów własne ustawienia proxy

Na pewno zdarzyło Ci się to nie raz: w terminalu masz wyeksportowane zmienne http_proxy i https_proxy, curl ochoczo ściąga strony, a npm install wisi przez minutę i kończy się błędem ETIMEDOUT. Albo apt update po cichu próbuje dostać się do mirrora bezpośrednio, jakby żadne proxy nie istniało. Albo Docker przy budowaniu obrazu nie może pobrać warstwy bazowej, chociaż z tej samej konsoli docker pull działa. To nie błąd ani magia. Po prostu każde narzędzie czyta ustawienia sieci na swój sposób, a zmienne środowiskowe pokrywają je tylko częściowo.

Ten poradnik jest poświęcony właśnie własnym plikom konfiguracyjnym pięciu narzędzi, bez których nie obejdzie się żaden programista: npm (plik .npmrc), pip (pip.conf lub pip.ini), apt (katalog apt.conf.d), Docker (daemon.json i config.json) oraz git (git config). Celowo nie powtarzamy tu materiału o zmiennych środowiskowych w terminalu i CI. Tutaj chodzi o coś innego: pokazać, jak wpisać proxy tak, żeby działało zawsze, niezależnie od tego, kto i skąd uruchomi polecenie.

W efekcie dostaniesz pięć działających konfiguracji, które możesz skopiować na dowolną maszynę, zrozumienie, gdzie każde narzędzie szuka ustawień, oraz zestaw poleceń do weryfikacji. Dodatkowo będziesz wiedzieć, jak szybko wszystko cofnąć.

Dla kogo jest ten poradnik

  • Dla programistów, których służbowy laptop lub serwer znajduje się za firmowym albo domowym proxy.
  • Dla testerów i specjalistów od automatyzacji, którym zależy, żeby buildy szły przez wydzielony adres proxy.
  • Dla administratorów konfigurujących typowe obrazy stacji roboczych.
  • Dla wszystkich, którzy używają wynajętego proxy (także mobilnego) do pracy i chcą, żeby przez nie chodziło konkretne narzędzie, a nie cały system.

Co warto wiedzieć wcześniej

Wystarczą podstawowe umiejętności pracy w terminalu: otworzyć konsolę, przejść do katalogu, edytować plik tekstowy. Będziemy używać edytora nano w Linuksie i Notatnika w Windows, ale nada się każdy inny. Zrozumienie, czym jest adres IP i port, też się przyda, choć podstawy przypomnimy w sekcji o pojęciach.

Ile czasu to zajmie

Jeśli konfigurujesz wszystkie pięć narzędzi po kolei, zarezerwuj od 60 do 90 minut. Każde pojedyncze narzędzie zajmuje 10-15 minut wraz z weryfikacją. Najdłuższy etap to Docker, bo są tam dwa poziomy ustawień i wymagany restart usługi.

Przygotowanie wstępne

Zanim zaczniesz edytować konfiguracje, zbierz wszystko, co potrzebne. Pominięcie tego etapu to główna przyczyna tego, że potem godzinami zastanawiasz się, gdzie jest błąd.

Niezbędne dane o proxy

Potrzebujesz czterech parametrów. Zapisz je w pliku tekstowym, żeby nie szukać ich po wiadomościach:

  • Typ proxy: HTTP lub HTTPS (czasem SOCKS5, ale większość menedżerów pakietów oczekuje właśnie HTTP proxy).
  • Adres: nazwa domenowa lub IP, na przykład proxy.corp.local albo 10.20.30.40.
  • Port: najczęściej 3128, 8080 lub 8888.
  • Login i hasło, jeśli proxy wymaga autoryzacji. Zwróć uwagę na znaki specjalne w haśle: będą wymagały kodowania, o tym poniżej.

Wymagania systemowe i wersje

Instrukcja została sprawdzona na aktualnych wersjach z 2026 roku i pasuje do:

  • Ubuntu 22.04 i 24.04, Debian 12 i 13 (dla apt).
  • Node.js 20 i 22 z npm 10 i 11.
  • Python 3.10 i nowszy z pip 24 i nowszy.
  • Docker Engine 25 i nowszy (klucz proxies w daemon.json pojawił się w wersji 23, na starszych wersjach użyj systemd drop-in, pokażemy oba warianty).
  • Git 2.40 i nowszy.

Jeśli masz Windows, wszystkie polecenia dla npm, pip i git działają w PowerShellu bez zmian, różnią się tylko ścieżki do plików. Dla Docker Desktop ustawienia proxy robi się przez interfejs graficzny, to też omówimy.

Uprawnienia dostępu

Dla npm, pip i git wystarczą uprawnienia zwykłego użytkownika: ich konfiguracje leżą w katalogu domowym. Dla apt i Docker potrzebny będzie sudo, bo pliki leżą w /etc i zmieniają zachowanie usług systemowych.

Kopie zapasowe

Przed rozpoczęciem skopiuj istniejące konfiguracje. Jedno polecenie na każdy plik i zawsze możesz wrócić do stanu początkowego:

cp ~/.npmrc ~/.npmrc.bak 2>/dev/null; cp ~/.config/pip/pip.conf ~/pip.conf.bak 2>/dev/null; cp ~/.gitconfig ~/.gitconfig.bak 2>/dev/null; sudo cp /etc/docker/daemon.json /etc/docker/daemon.json.bak 2>/dev/null; sudo cp -r /etc/apt/apt.conf.d /etc/apt/apt.conf.d.bak 2>/dev/null

Końcówka 2>/dev/null jest potrzebna, żeby polecenie nie zrzędziło, jeśli pliku jeszcze nie ma. To normalne: u wielu użytkowników .npmrc i pip.conf początkowo nie istnieją.

Wskazówka: załóż w katalogu domowym folder proxy-configs i trzymaj tam wzorcowe wersje wszystkich pięciu konfiguracji. Przeprowadzka na nową maszynę zamieni się w kopiowanie pięciu plików.

Podstawowe pojęcia: dlaczego zmiennych środowiskowych nie wystarczy

Zrozummy, co dzieje się pod maską, bo inaczej kolejne kroki będą wyglądać jak zestaw magicznych zaklęć.

Czym jest proxy w kontekście menedżera pakietów

Serwer proxy to pośrednik. Zamiast łączyć się z registry.npmjs.org bezpośrednio, Twój npm łączy się z proxy i prosi je, żeby poszło do registry.npmjs.org. Dla zasobów HTTPS używa się metody CONNECT: proxy ustanawia tunel i zaszyfrowany ruch przechodzi przez niego bez odszyfrowywania. Dla menedżera pakietów ważne jest, żeby znać adres proxy, port i, w razie potrzeby, dane uwierzytelniające.

Jak narzędzia dowiadują się o proxy

Istnieją trzy warstwy ustawień, które składają się w łańcuch priorytetów:

  1. Flagi wiersza poleceń: na przykład pip install --proxy. Działają na jedno uruchomienie.
  2. Własna konfiguracja narzędzia: .npmrc, pip.conf i inne. Działają zawsze dla tego narzędzia.
  3. Zmienne środowiskowe: http_proxy, https_proxy, no_proxy. Działają dla wszystkich programów w bieżącej sesji, które je czytają.

Słowa kluczowe: które je czytają. I tu zaczynają się problemy.

Cztery powody, dlaczego zmiennych środowiskowych nie wystarczy

Powód pierwszy: zmiana użytkownika. Kiedy piszesz sudo apt update, polecenie wykonuje się jako root, a sudo domyślnie czyści środowisko (opcja env_reset). Twoje http_proxy zostają u zwykłego użytkownika. Co więcej, sam apt pobiera pliki jako użytkownik usługowy _apt, który w ogóle nie ma Twojej sesji.

Powód drugi: demony i usługi. Docker Engine to usługa działająca w tle, uruchomiona przez systemd przy starcie systemu. Nigdy nie widziała Twojego terminala. Polecenie docker pull jedynie wysyła żądanie do demona, a obraz pobiera demon. Dlatego zmienne w Twojej konsoli w ogóle nie wpływają na docker pull.

Powód trzeci: różna interpretacja. Jedne programy czytają tylko małymi literami http_proxy, inne tylko HTTP_PROXY, jeszcze inne oba warianty. Stare wersje npm ignorowały no_proxy. Niektóre narzędzia nie rozumieją danych uwierzytelniających w zmiennej. Własna konfiguracja oszczędza zgadywania.

Powód czwarty: szczegółowość. Zmienna środowiskowa albo jest, albo jej nie ma. A Tobie może być potrzebne wysyłanie przez proxy tylko github.com, ale nie wewnętrznego GitLaba. Albo chodzenie do publicznego PyPI przez proxy, a do wewnętrznego indeksu bezpośrednio. Takie reguły potrafią tylko konfiguracje: git obsługuje ustawienie proxy dla konkretnego URL, apt - dla konkretnego hosta, Docker - listę wyjątków na poziomie demona.

Kodowanie znaków specjalnych w haśle

Login i hasło w konfiguracjach przekazywane są wewnątrz URL-a postaci http://user:password@host:port. Znaki @, :, /, #, ?, % i spacja wewnątrz hasła psują parsowanie adresu. Trzeba je zastąpić kodami procentowymi: @ staje się %40, : staje się %3A, # staje się %23, / staje się %2F, % staje się %25, spacja - %20. Na przykład hasło p@ss:1 w konfiguracji zapisze się jako p%40ss%3A1. Zapamiętaj tę regułę, uratuje Cię we wszystkich pięciu narzędziach.

Krok 1: Sprawdzamy proxy i przygotowujemy wzorcowy ciąg

Cel etapu: upewnić się, że proxy w ogóle działa, i uzyskać jeden sprawdzony ciąg połączenia, który będziemy wstawiać do wszystkich konfiguracji.

  1. Otwórz terminal. W Linuksie to Ctrl+Alt+T, w Windows - PowerShell z menu Start.
  2. Złóż ciąg połączenia według szablonu http://LOGIN:HASŁO@ADRES:PORT. Bez autoryzacji - po prostu http://ADRES:PORT. Przykład: http://dev:s3cret@10.20.30.40:3128.
  3. Wykonaj testowe żądanie przez curl, jawnie podając proxy flagą -x, żeby nie zależeć od zmiennych:
    curl -x http://dev:s3cret@10.20.30.40:3128 -I https://registry.npmjs.org/
  4. Poczekaj na odpowiedź. Powinna zaczynać się od wiersza HTTP/2 200 lub HTTP/1.1 200 OK. Jeśli widzisz 407 Proxy Authentication Required - zły login lub hasło. Jeśli Could not resolve proxy - literówka w adresie. Jeśli connection refused - zły port lub proxy wyłączone.
  5. Powtórz sprawdzenie dla pozostałych celów: https://pypi.org/simple/, https://deb.debian.org/, https://registry-1.docker.io/v2/, https://github.com/. Dla Docker normalna jest odpowiedź 401, to znaczy, że dotarłeś do rejestru i on prosi o token.
  6. Zapisz końcowy ciąg w swoim pliku tekstowym. To Twój wzorcowy ciąg proxy.

Uwaga: jeśli hasło zawiera znaki specjalne, zakoduj je właśnie na tym etapie i sprawdź zakodowany wariant przez curl. Wtedy we wszystkich kolejnych konfiguracjach będziesz wstawiać już sprawdzony ciąg.

Wskazówka: jeśli dostawca daje Ci nie jedno proxy, a pulę adresów lub mobilne proxy z rotacją IP, zwykle ma jeden punkt wejścia: jeden host i port, za którym IP zmieniają się automatycznie. Wpisuj do konfiguracji właśnie ten punkt wejścia, a nie konkretne IP z puli, bo inaczej ustawienia zdezaktualizują się przy pierwszej rotacji.

Weryfikacja: curl z flagą -x zwraca kod 200 (albo 401 dla Docker Hub) po wszystkich pięciu adresach. Jeśli choć jeden nie odpowiada, nie idź dalej: konfiguracje nie naprawią niedziałającego proxy.

Krok 2: Konfigurujemy npm przez plik .npmrc

Cel etapu: npm install, npm view i npm publish działają przez proxy z dowolnego projektu i dowolnej konsoli, w tym ze środowisk programistycznych, które same uruchamiają npm.

Gdzie mieszka konfiguracja npm

npm czyta ustawienia z kilku plików w rosnącym priorytecie: wartości wbudowane, plik globalny w katalogu instalacji npm, użytkownika ~/.npmrc (w Windows - C:\Users\NAZWA\.npmrc) oraz projektowy .npmrc w korzeniu projektu obok package.json. Dla proxy prawie zawsze używa się pliku użytkownika: działa we wszystkich projektach, ale nie trafia do repozytorium.

Konfiguracja krok po kroku

  1. Ustaw proxy dla zwykłego ruchu HTTP:
    npm config set proxy http://dev:s3cret@10.20.30.40:3128
  2. Ustaw proxy dla ruchu HTTPS (rejestr npm działa po HTTPS, dlatego to ustawienie jest najważniejsze):
    npm config set https-proxy http://dev:s3cret@10.20.30.40:3128
    Zwróć uwagę: wartość zaczyna się od http://, nie https://. To adres samego proxy, a ono zwykle przyjmuje połączenia po zwykłym HTTP, nawet gdy tuneluje HTTPS.
  3. Jeśli masz wewnętrzny rejestr lub mirror, do którego trzeba chodzić bezpośrednio, dodaj wyjątki oddzielone przecinkami:
    npm config set noproxy localhost,127.0.0.1,.corp.local
    Kropka przed domeną oznacza wszystkie subdomeny.
  4. Otwórz plik i upewnij się, że wiersze się zapisały:
    cat ~/.npmrc
    W Windows: type $env:USERPROFILE\.npmrc. Powinieneś zobaczyć trzy wiersze postaci klucz=wartość.
  5. Jeśli firmowe proxy podmienia certyfikaty, dodaj certyfikat główny firmy:
    npm config set cafile /etc/ssl/certs/corp-root.pem
    Nie wyłączaj weryfikacji certyfikatów przez strict-ssl=false bez skrajnej potrzeby: to otwiera drogę do podmiany pakietów.

Alternatywna droga to utworzenie pliku ręcznie. Zawartość ~/.npmrc będzie taka:

proxy=http://dev:s3cret@10.20.30.40:3128 https-proxy=http://dev:s3cret@10.20.30.40:3128 noproxy=localhost,127.0.0.1,.corp.local

Każda para musi być w osobnym wierszu. Bez cudzysłowów i spacji wokół znaku równości.

A co z yarn i pnpm

Yarn Classic (1.x) czyta ten sam ~/.npmrc i dodatkowo swój ~/.yarnrc z kluczami proxy i https-proxy. Yarn Berry (2+) trzyma ustawienia w .yarnrc.yml: klucze httpProxy i httpsProxy. pnpm jest w pełni zgodny z .npmrc, nie trzeba nic dodatkowo robić. Warto też pamiętać, że npm ci i firmowe IDE uruchamiają npm tym samym użytkownikiem, dlatego użytkownika .npmrc pokrywa również je.

Wskazówka: polecenie npm config list --json pokaże końcową konfigurację z uwzględnieniem wszystkich plików. Jeśli widzisz proxy=null, znaczy, że plik się nie wczytał: sprawdź, że leży w katalogu domowym właśnie tego użytkownika, pod którym uruchamiasz npm.

Weryfikacja: wykonaj npm view lodash version. Po 1-3 sekundach powinien wrócić wiersz z numerem wersji. Dla jasności możesz tymczasowo zdjąć zmienne środowiskowe (unset http_proxy https_proxy) i powtórzyć: npm i tak powinien działać, bo czyta .npmrc.

Możliwe problemy

  • ETIMEDOUT lub ECONNRESET: zły adres lub port proxy, albo proxy blokuje CONNECT na port 443. Sprawdź wzorcowy ciąg przez curl.
  • 407 Proxy Authentication Required: błąd w loginie lub haśle, najczęściej niezakodowany znak specjalny.
  • UNABLE_TO_GET_ISSUER_CERT_LOCALLY: proxy podmienia certyfikat, potrzebny cafile z firmowym certyfikatem głównym.

Krok 3: Konfigurujemy pip przez pip.conf

Cel etapu: pip install i pip download działają przez proxy, również wewnątrz środowisk wirtualnych i przy uruchamianiu ze skryptów Pythona.

Gdzie szukać pip.conf

pip używa trzech poziomów plików: globalny (dla całego systemu), użytkownika i poziom środowiska wirtualnego. Ścieżki zależą od systemu:

  • Linux, użytkownika: ~/.config/pip/pip.conf (przestarzały wariant ~/.pip/pip.conf też jest czytany).
  • Linux, globalny: /etc/pip.conf.
  • macOS, użytkownika: ~/Library/Application Support/pip/pip.conf, a jeśli tego folderu nie ma - ~/.config/pip/pip.conf.
  • Windows, użytkownika: %APPDATA%\pip\pip.ini, czyli C:\Users\NAZWA\AppData\Roaming\pip\pip.ini.
  • Wewnątrz środowiska wirtualnego: plik pip.conf (lub pip.ini) bezpośrednio w korzeniu katalogu venv.

Żeby nie zgadywać, zapytaj samego pip: polecenie pip config debug wypisze wszystkie ścieżki, które sprawdza, i oznaczy istniejące pliki.

Konfiguracja krok po kroku

  1. Upewnij się, że pip jest aktualny: pip --version. Powinna być wersja 24 lub nowsza.
  2. Ustaw proxy jednym poleceniem, pip sam utworzy plik w odpowiednim miejscu:
    pip config set global.proxy http://dev:s3cret@10.20.30.40:3128
    Tutaj global oznacza sekcję [global] w pliku, a nie poziom systemowy. Plik tworzy się użytkownika.
  3. Jeśli proxy podmienia certyfikaty, wskaż certyfikat główny:
    pip config set global.cert /etc/ssl/certs/corp-root.pem
  4. Zobacz, co wyszło:
    pip config list
    Oczekiwany wynik: global.proxy='http://dev:s3cret@10.20.30.40:3128'.
  5. Otwórz plik i sprawdź format. Powinien wyglądać tak:
    [global] proxy = http://dev:s3cret@10.20.30.40:3128 cert = /etc/ssl/certs/corp-root.pem
    Każdy wiersz osobno, sekcja w nawiasach kwadratowych u góry.

Ważna różnica pip od npm: pip nie ma osobnego ustawienia dla HTTPS proxy. Jeden klucz proxy służy do wszystkich połączeń. I pip nie ma bezpośredniego odpowiednika noproxy w konfiguracji: wyjątki bierze tylko ze zmiennej środowiskowej no_proxy. Jeśli musisz chodzić do wewnętrznego indeksu bezpośrednio, prościej wskazać dla niego osobny index-url i uruchamiać pip z flagą --proxy z pustą wartością dla tego przypadku, albo użyć projektowego pip.conf wewnątrz venv bez wiersza proxy.

Wskazówka: jeśli masz kilka projektów i w jednym potrzebne jest proxy, a w drugim nie, połóż pip.conf w korzeniu odpowiedniego środowiska wirtualnego. Ustawienia venv mają priorytet nad użytkownika i uzyskasz różne zachowanie bez przełączania globalnych plików.

Uwaga: nie dodawaj trusted-host = pypi.org, żeby zagłuszyć błędy certyfikatów. To wyłącza weryfikację autentyczności i pozwala dowolnemu pośrednikowi podsunąć Ci podrobiony pakiet. Właściwym rozwiązaniem jest klucz cert z firmowym certyfikatem.

Weryfikacja: wykonaj pip download requests --no-deps -d /tmp/piptest. Po kilku sekundach w katalogu pojawi się plik requests-*.whl. Potem usuń katalog testowy. Jeśli chcesz się upewnić, że działa właśnie konfiguracja, zdejmij zmienne środowiskowe i powtórz.

Możliwe problemy

  • ProxyError lub Cannot connect to proxy: literówka w adresie lub zły port. Porównaj ze wzorcowym ciągiem.
  • Tunnel connection failed: 407: błąd autoryzacji. Sprawdź kodowanie hasła.
  • SSLError CERTIFICATE_VERIFY_FAILED: potrzebny klucz cert z certyfikatem głównym proxy.
  • Plik się zapisał, ale pip go nie widzi: uruchamiasz pip innego interpretera (na przykład python3 -m pip od innego Pythona). Wykonaj pip config debug właśnie tym poleceniem, którym instalujesz pakiety.

Krok 4: Konfigurujemy apt przez katalog apt.conf.d

Cel etapu: sudo apt update i sudo apt install pobierają pakiety przez proxy, a odwołania do wewnętrznego mirrora idą bezpośrednio.

Dlaczego właśnie apt.conf.d

apt czyta ustawienia z /etc/apt/apt.conf i wszystkich plików w katalogu /etc/apt/apt.conf.d/ w kolejności alfabetycznej. Dobrą praktyką jest nie ruszać cudzych plików, a utworzyć swój z numerycznym prefiksem. Liczba ustala kolejność czytania: plik 80proxy zastosuje się po 01autoremove i innych systemowych. Właśnie tutaj ustawienia przetrwają wszelkie aktualizacje pakietu apt.

Konfiguracja krok po kroku

  1. Utwórz nowy plik ustawień:
    sudo nano /etc/apt/apt.conf.d/80proxy
    Otworzy się pusty edytor.
  2. Wpisz dwa wiersze dla repozytoriów HTTP i HTTPS. Zwróć uwagę na cudzysłowy i średniki - w składni apt są obowiązkowe:
    Acquire::http::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::https::Proxy "http://dev:s3cret@10.20.30.40:3128";
  3. Jeśli masz wewnętrzny mirror, dla którego proxy nie jest potrzebne, dodaj wiersz z wyjątkiem. Słowo DIRECT wielkimi literami oznacza połączenie bezpośrednie:
    Acquire::http::Proxy::mirror.corp.local "DIRECT";
  4. Zapisz plik: w nano naciśnij Ctrl+O, potem Enter, potem Ctrl+X, żeby wyjść.
  5. Ogranicz uprawnienia do pliku, bo jest w nim hasło:
    sudo chmod 600 /etc/apt/apt.conf.d/80proxy
    Tylko root będzie mógł przeczytać zawartość.
  6. Sprawdź, że apt przeczytał plik bez błędów składniowych:
    apt-config dump | grep -i proxy
    Powinieneś zobaczyć wiersze Acquire::http::Proxy i Acquire::https::Proxy ze swoimi wartościami.

Oto pełny przykład pliku dla jasności:

Acquire::http::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::https::Proxy "http://dev:s3cret@10.20.30.40:3128"; Acquire::http::Proxy::mirror.corp.local "DIRECT"; Acquire::https::Proxy::mirror.corp.local "DIRECT";

Alternatywa na jedno uruchomienie bez pliku: sudo apt -o Acquire::http::Proxy="http://10.20.30.40:3128" update. Flaga -o jest wygodna, żeby przetestować wartość przed zapisem do konfiguracji.

Wskazówka: serwery proxy, które same cache'ują pakiety deb, często mają osobny port dla apt. Dopytaj administratora: jeśli taki istnieje, apt update przyspieszy kilkukrotnie dzięki lokalnemu cache'owi.

Weryfikacja: wykonaj sudo apt update. W wyniku pojawią się wiersze Hit lub Get z adresami repozytoriów i nie będzie wierszy z Err. Zwróć uwagę, że nie ustawialiśmy zmiennych środowiskowych, a sudo i tak by je zresetowało, a apt mimo to wyszedł do sieci. To właśnie efekt własnej konfiguracji.

Możliwe problemy

  • Err: 407 Proxy Authentication Required: autoryzacja nie przeszła, sprawdź kodowanie znaków specjalnych.
  • Could not connect lub Connection timed out: apt poszedł bezpośrednio. Najprawdopodobniej w pliku jest literówka, a apt-config dump jej nie pokazuje. Sprawdź wielkość liter w Acquire i podwójne dwukropki.
  • E: Syntax error: brakuje średnika lub cudzysłowu na końcu wiersza.
  • Plik jest na miejscu, ale wyjątek DIRECT nie działa: upewnij się, że nazwa hosta w wierszu wyjątku zgadza się z nazwą w sources.list co do litery, bez http:// i bez portu.

Krok 5: Konfigurujemy Docker na dwóch poziomach

Cel etapu: docker pull, docker build i docker compose pull pobierają obrazy przez proxy, a kontenery w razie potrzeby dostają ustawienia proxy automatycznie.

Dwa poziomy, które często się myli

Docker ma dwa niezależne miejsca, w których proxy jest potrzebne inaczej:

  • Poziom demona (usługa dockerd). To on pobiera obrazy z rejestru. Konfiguruje się w /etc/docker/daemon.json lub przez systemd. Wymaga restartu usługi.
  • Poziom klienta (plik ~/.docker/config.json). Nie wpływa na pobieranie obrazów. Za to automatycznie przekazuje zmienne proxy do uruchamianych kontenerów i do procesu budowania, żeby apt lub pip wewnątrz kontenera też widziały proxy.

Skonfigurujesz tylko klienta - docker pull nie zadziała. Skonfigurujesz tylko demona - obrazy się pobierają, ale RUN apt-get update wewnątrz Dockerfile padnie. Potrzebne są oba.

Część A: demon przez daemon.json

  1. Sprawdź wersję: docker version. Jeśli wersja serwera to 23.0 lub nowsza, użyj daemon.json. Jeśli starsza, przejdź do części B.
  2. Otwórz plik ustawień demona:
    sudo nano /etc/docker/daemon.json
    Jeśli plik już istnieje i zawiera inne klucze, dodaj blok proxies wewnątrz tych samych nawiasów klamrowych, oddzielając przecinkiem. Jeśli pliku nie ma, utwórz go od zera.
  3. Wpisz blok ustawień:
    { "proxies": { "http-proxy": "http://dev:s3cret@10.20.30.40:3128", "https-proxy": "http://dev:s3cret@10.20.30.40:3128", "no-proxy": "localhost,127.0.0.0/8,registry.corp.local" } }
    Zwróć uwagę: klucze pisze się z myślnikiem i małymi literami właśnie tak. To format demona, u klienta klucze będą inne.
  4. Zapisz plik (Ctrl+O, Enter, Ctrl+X).
  5. Sprawdź, czy JSON jest poprawny, inaczej demon nie wystartuje:
    python3 -m json.tool /etc/docker/daemon.json
    Jeśli polecenie wypisało zawartość pliku z wcięciami - składnia jest poprawna. Jeśli zrzędzi na Expecting value lub Extra data - szukaj zbędnego lub brakującego przecinka.
  6. Zrestartuj usługę:
    sudo systemctl restart docker
    Restart zajmie 5-15 sekund. Wszystkie uruchomione kontenery przy tym się zatrzymają, dlatego rób to w spokojnym momencie.
  7. Upewnij się, że demon wstał: sudo systemctl status docker. Powinien być napis active (running) na zielono.

Uwaga: jeden zbędny przecinek w daemon.json - i Docker w ogóle nie wystartuje, a wraz z nim padną wszystkie kontenery na maszynie. Zawsze sprawdzaj plik przez json.tool przed restartem i trzymaj kopię zapasową obok.

Część B: demon przez systemd (dla starszych wersji i jako alternatywa)

  1. Utwórz katalog na dodatkowe ustawienia usługi: sudo mkdir -p /etc/systemd/system/docker.service.d
  2. Utwórz plik: sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf
  3. Wpisz:
    [Service] Environment="HTTP_PROXY=http://dev:s3cret@10.20.30.40:3128" Environment="HTTPS_PROXY=http://dev:s3cret@10.20.30.40:3128" Environment="NO_PROXY=localhost,127.0.0.0/8,registry.corp.local"
  4. Zapisz i zastosuj: sudo systemctl daemon-reload, potem sudo systemctl restart docker.

Tak, używa się tu zmiennych środowiskowych, ale nie są ustawione w Twojej konsoli, tylko w definicji usługi: demon dostaje je przy starcie od systemd. To jedyny sposób dla Dockera starszego niż wersja 23. Jeśli masz ustawione i daemon.json, i plik systemd, priorytet ma daemon.json.

Część C: klient przez ~/.docker/config.json

  1. Otwórz lub utwórz plik nano ~/.docker/config.json. Jeśli plik zawiera już blok auths z Twoimi loginami do rejestrów, nie usuwaj go, tylko dodaj nowy blok obok przez przecinek.
  2. Wpisz:
    { "proxies": { "default": { "httpProxy": "http://dev:s3cret@10.20.30.40:3128", "httpsProxy": "http://dev:s3cret@10.20.30.40:3128", "noProxy": "localhost,127.0.0.0/8,.corp.local" } } }
    Tutaj klucze w stylu camelCase: httpProxy, httpsProxy, noProxy. To różnica od daemon.json i nie wolno ich mylić.
  3. Zapisz plik. Restart nie jest potrzebny, klient czyta go przy każdym poleceniu.

Teraz przy docker run i docker build do kontenera automatycznie trafią zmienne HTTP_PROXY, HTTPS_PROXY i NO_PROXY (w obu wariantach wielkości liter). Czyli apt-get i pip wewnątrz Dockerfile też pójdą przez proxy bez ręcznych ARG i ENV.

Docker Desktop na Windows i macOS

Otwórz ustawienia przez ikonę w zasobniku systemowym, sekcja Resources, podsekcja Proxies. Przełącz Manual proxy configuration, wpisz adres w pola Web Server (HTTP) i Secure Web Server (HTTPS), listę wyjątków - w Bypass proxy settings for these hosts and domains. Naciśnij Apply and restart. Klienta config.json w Windows leży w C:\Users\NAZWA\.docker\config.json i konfiguruje się tak samo, jak opisano wyżej.

Wskazówka: polecenie docker info wypisuje sekcję z HTTP Proxy, HTTPS Proxy i No Proxy. To najszybszy sposób, żeby zrozumieć, czy demon zobaczył Twoje ustawienia, bez uruchamiania pobierania.

Weryfikacja: wykonaj docker pull hello-world. Obraz waży kilka kilobajtów i pobierze się w parę sekund, na końcu pojawi się Status: Downloaded newer image. Potem sprawdź część kliencką: docker run --rm alpine env | grep -i proxy. W wyniku powinny być wiersze HTTP_PROXY i HTTPS_PROXY z Twoim adresem.

Możliwe problemy

  • Docker nie startuje po edycji daemon.json: błąd składni. Zobacz sudo journalctl -u docker -n 30, tam będzie wskazany wiersz z błędem. Przywróć z kopii zapasowej.
  • docker pull wisi i pada po timeoucie, chociaż docker info pokazuje proxy: demon nie był restartowany po edycji, albo proxy nie przepuszcza CONNECT do registry-1.docker.io. Sprawdź wzorcowy ciąg przez curl.
  • Wewnątrz buildu apt-get update pada, a docker pull działa: nie jest skonfigurowany kliencki config.json, albo build idzie przez zdalny builder, który czyta inny plik.
  • Kontener dostał proxy, ale nie może dosięgnąć sąsiedniego kontenera: dodaj nazwy wewnętrznych serwisów i podsieć Dockera do noProxy.

Krok 6: Konfigurujemy git przez git config

Cel etapu: git clone, fetch, pull i push po HTTPS idą przez proxy, przy czym dla wewnętrznego serwera można zostawić połączenie bezpośrednie, a dla konkretnego hostingu - ustawić osobne proxy.

Gdzie git trzyma ustawienia

Trzy poziomy: systemowy (/etc/gitconfig), globalny dla użytkownika (~/.gitconfig, w Windows - C:\Users\NAZWA\.gitconfig) i lokalny wewnątrz repozytorium (.git/config). Proxy zwykle ustawia się globalnie, a punktowe wyjątki - też globalnie, ale z przypisaniem do URL.

Konfiguracja krok po kroku

  1. Ustaw proxy dla wszystkich połączeń HTTPS i HTTP jednym poleceniem:
    git config --global http.proxy http://dev:s3cret@10.20.30.40:3128
    W odróżnieniu od npm, git nie ma osobnego https.proxy dla protokołu HTTPS: klucz http.proxy stosuje się do obu. Ustawienie https.proxy pojawia się w starych instrukcjach, ale to nie jest standardowy klucz git i jest ignorowany.
  2. Jeśli dla wewnętrznego serwera proxy nie jest potrzebne, ustaw pustą wartość właśnie dla jego URL:
    git config --global http.https://git.corp.local.proxy ""
    Pusty ciąg oznacza połączenie bezpośrednie. Część między http. a .proxy to prefiks URL, do którego stosuje się reguła.
  3. Jeśli dla osobnego hostingu potrzebne jest inne proxy (na przykład wydzielone mobilne), wskaż je tak samo z przypisaniem do URL:
    git config --global http.https://github.com.proxy http://dev:s3cret@10.20.30.41:3128
  4. Jeśli proxy podmienia certyfikaty, dodaj certyfikat główny:
    git config --global http.sslCAInfo /etc/ssl/certs/corp-root.pem
  5. Sprawdź końcowy plik:
    git config --global --list | grep -i proxy
    Zobaczysz wiersze http.proxy=... i http.https://git.corp.local.proxy= z pustą wartością.

Plik ~/.gitconfig po tych poleceniach będzie wyglądał tak:

[http] proxy = http://dev:s3cret@10.20.30.40:3128 sslCAInfo = /etc/ssl/certs/corp-root.pem [http "https://git.corp.local"] proxy = [http "https://github.com"] proxy = http://dev:s3cret@10.20.30.41:3128

Taka szczegółowość jest nieosiągalna przez zmienne środowiskowe: no_proxy potrafi tylko wykluczać hosty, ale nie przypisywać różne proxy różnym serwerom.

A co z adresami SSH

Ustawienie http.proxy nie wpływa na adresy postaci git@github.com:user/repo.git, bo to protokół SSH, a nie HTTP. Jeśli Twoje proxy dopuszcza tunelowanie na port 22 przez CONNECT, można skonfigurować klienta SSH w pliku ~/.ssh/config z dyrektywą ProxyCommand i narzędziem nc lub corkscrew. Ale wiele firmowych proxy zabrania takich połączeń. Najprostsza i najbardziej przewidywalna droga - przełączyć zdalne adresy na HTTPS: git remote set-url origin https://github.com/user/repo.git i używać tokena dostępu zamiast hasła.

Wskazówka: żeby nie trzymać hasła proxy w ~/.gitconfig jawnym tekstem, można wyjąć je do osobnego pliku z uprawnieniami 600 i podłączyć dyrektywą include. Utwórz ~/.gitconfig-proxy z sekcją [http], a w głównym pliku dodaj [include] path = ~/.gitconfig-proxy. Główną konfigurację można wtedy spokojnie pokazywać kolegom.

Weryfikacja: wykonaj git ls-remote https://github.com/git/git.git HEAD. Po paru sekundach wróci wiersz z hashem commita i słowem HEAD. Polecenie nie tworzy plików i nic nie klonuje, to idealny test części sieciowej. Potem sprawdź wyjątek: git ls-remote do wewnętrznego serwera powinien działać nawet przy niedostępnym proxy.

Możliwe problemy

  • Failed to connect to proxy lub Could not resolve proxy: literówka w adresie.
  • Received HTTP code 407 from proxy after CONNECT: błąd autoryzacji, sprawdź kodowanie hasła.
  • SSL certificate problem: unable to get local issuer certificate: potrzebny http.sslCAInfo. Nie używaj http.sslVerify false na stałe.
  • Reguła dla URL nie stosuje się: prefiks musi zgadzać się z początkiem adresu w remote. Jeśli remote jest zapisany jako https://www.github.com, to reguła dla https://github.com nie zadziała.

Weryfikacja wyniku: zbiorcza lista kontrolna

Po skonfigurowaniu wszystkich pięciu narzędzi przejdź końcową weryfikację. Jest celowo zbudowana tak, żeby wykluczyć wpływ zmiennych środowiskowych i upewnić się, że działają właśnie konfiguracje.

  1. Otwórz nowy terminal i zdejmij zmienne, jeśli są ustawione: unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY. W PowerShellu: Remove-Item Env:HTTP_PROXY i analogicznie dla pozostałych.
  2. Sprawdź npm: npm view express version. Oczekiwany numer wersji.
  3. Sprawdź pip: pip download six --no-deps -d /tmp/t. Oczekiwany pobrany plik whl.
  4. Sprawdź apt: sudo apt update. Oczekiwane wiersze Hit lub Get bez Err.
  5. Sprawdź Docker: docker pull hello-world i docker run --rm alpine env | grep -i proxy. Oczekiwany pobrany obraz i zmienne w kontenerze.
  6. Sprawdź git: git ls-remote https://github.com/git/git.git HEAD. Oczekiwany hash commita.

Wskaźniki udanego wykonania

  • Wszystkie sześć poleceń zadziałało bez zmiennych środowiskowych w konsoli.
  • W plikach .npmrc, pip.conf, 80proxy, daemon.json, config.json i .gitconfig zapisany jest ten sam wzorcowy ciąg proxy.
  • Pliki z hasłami (80proxy, daemon.json, .npmrc, pip.conf, .gitconfig) mają uprawnienia 600 lub są dostępne tylko dla roota.
  • Wyjątki dla wewnętrznych hostów działają: odwołanie do nich przechodzi nawet przy wyłączonym proxy.
  • Kopie zapasowe oryginalnych plików leżą obok i wiesz, jak je przywrócić.

Weryfikacja: jeśli choć jeden punkt się nie zgadza, wróć do sekcji odpowiedniego narzędzia i porównaj swój plik z przykładem z poradnika znak po znaku. W dziewięciu przypadkach na dziesięć przyczyną jest literówka lub niezakodowany znak w haśle.

Typowe błędy i rozwiązania

Błąd 1: kod 407 Proxy Authentication Required wszędzie

Przyczyna: hasło zawiera znak specjalny (@, :, #, %), który nie został zakodowany, i narzędzie sparsowało adres niepoprawnie.

Rozwiązanie: zakoduj znaki kodami procentowymi (@ na %40, : na %3A, # na %23, % na %25) i sprawdź nowy ciąg przez curl -x przed zapisem do konfiguracji.

Błąd 2: działa z terminala, nie działa przez sudo

Przyczyna: sudo resetuje środowisko, a konfiguracji jeszcze nie utworzyłeś. Klasyka dla apt.

Rozwiązanie: utwórz /etc/apt/apt.conf.d/80proxy jak w Kroku 4. Dla innych narzędzi pod rootem pamiętaj, że root czyta swój katalog domowy /root, a nie Twój: jeśli potrzebny jest npm lub pip od roota, konfiguracja musi leżeć w /root/.npmrc lub /root/.config/pip/pip.conf.

Błąd 3: Docker nie startuje po edycji daemon.json

Przyczyna: niepoprawny JSON: zbędny przecinek po ostatnim elemencie, brakujący nawias, pojedyncze cudzysłowy zamiast podwójnych.

Rozwiązanie: wykonaj sudo journalctl -u docker -n 30, znajdź wiersz z błędem, popraw plik i sprawdź go przez python3 -m json.tool przed kolejnym restartem. W ostateczności przywróć daemon.json.bak.

Błąd 4: docker pull działa, a apt-get wewnątrz Dockerfile pada

Przyczyna: skonfigurowany demon, ale nie klient. Procesy wewnątrz kontenera nie dziedziczą ustawień demona.

Rozwiązanie: utwórz ~/.docker/config.json z blokiem proxies.default jak w części C Kroku 5. Potem docker build automatycznie przekaże zmienne do etapów RUN.

Błąd 5: błędy certyfikatów SSL we wszystkich narzędziach

Przyczyna: proxy przeprowadza kontrolę ruchu i podstawia swój certyfikat, któremu system nie ufa.

Rozwiązanie: zdobądź certyfikat główny proxy w formacie PEM od administratora i wskaż go: npm cafile, pip cert, git http.sslCAInfo. Dla apt i Docker wystarczy dodać certyfikat do systemowego magazynu: skopiuj do /usr/local/share/ca-certificates/ i wykonaj sudo update-ca-certificates, potem zrestartuj Docker. Nie wyłączaj weryfikacji certyfikatów flagami strict-ssl, trusted-host i sslVerify.

Błąd 6: pip ignoruje pip.conf

Przyczyna: na maszynie jest kilka wersji Pythona i poprawiasz konfigurację dla jednej, a uruchamiasz inną. Albo plik leży w przestarzałym miejscu, którego konkretna wersja nie czyta.

Rozwiązanie: uruchom python3 -m pip config debug tym samym poleceniem, którym instalujesz pakiety. Wynik pokaże, które pliki zostały znalezione. Przenieś ustawienia do znalezionej ścieżki użytkownika.

Błąd 7: git idzie przez proxy nawet do wewnętrznego serwera

Przyczyna: reguła wyjątku jest ustawiona dla URL, który nie zgadza się z adresem w remote. Albo ustawiona w lokalnym .git/config innego repozytorium.

Rozwiązanie: zobacz dokładny adres przez git remote -v, skopiuj jego początek aż do nazwy hosta i ustaw regułę http.DOKŁADNY_URL.proxy z pustą wartością przez --global.

Błąd 8: wszystko działało, a po zmianie hasła proxy się zepsuło

Przyczyna: hasło jest wpisane w pięciu różnych plikach, zaktualizowałeś nie wszystkie.

Rozwiązanie: użyj polecenia grep -rl 'stare_hasło' ~/.npmrc ~/.config/pip ~/.gitconfig ~/.docker i sudo grep -rl dla /etc/apt/apt.conf.d i /etc/docker, żeby znaleźć wszystkie wystąpienia, i zaktualizuj każde. Potem przejdź zbiorczą listę kontrolną.

Dodatkowe możliwości

Lokalny agregator proxy jako jeden punkt wejścia

Jeśli dane uwierzytelniające proxy często się zmieniają albo pula adresów rotuje, wygodnie jest postawić na swojej maszynie lekkie lokalne proxy (na przykład na 127.0.0.1:3128), które samo wie, gdzie i z jakimi danymi chodzić. Wtedy do wszystkich pięciu konfiguracji wpisuje się jeden adres bez hasła, a zmiana danych robi się w jednym miejscu. To rozwiązuje też problem narzędzi, które słabo radzą sobie z autoryzacją w URL.

Mirrory i cache'ujące proxy dla pakietów

Proxy nie musi być uniwersalne. Dla apt istnieją cache'ujące proxy, które trzymają pliki deb lokalnie i rozdają je całemu biuru. Dla npm i pip korporacje stawiają prywatne rejestry, które proxy'ują publiczne i przy okazji cache'ują. W takim przypadku zamiast klucza proxy używa się registry w .npmrc i index-url w pip.conf, a proxy dla świata zewnętrznego konfiguruje się już w tym rejestrze. Dla Dockera podobną rolę pełni klucz registry-mirrors w daemon.json.

Rozdzielne ustawienia dla różnych projektów

Projektowy .npmrc obok package.json, pip.conf wewnątrz venv i lokalny .git/config pozwalają jednemu projektowi chodzić przez proxy, a drugiemu - bezpośrednio. Tylko nie commituj plików z hasłami do repozytorium: dodaj je do .gitignore albo użyj podstawień postaci ${PROXY_URL}, które npm potrafi rozwinąć ze środowiska przy czytaniu .npmrc.

Automatyzacja wdrożenia

Wszystkie pięć konfiguracji to proste pliki tekstowe. Wygodnie je rozdzielać skryptem albo systemem zarządzania konfiguracją: skrypt dostaje wzorcowy ciąg jednym parametrem i generuje pliki w potrzebnych formatach. Do weryfikacji po wdrożeniu używaj poleceń ze zbiorczej listy kontrolnej: nie wymagają interaktywności i nadają się do automatycznych testów.

Bezpieczeństwo przechowywania haseł

Minimum - uprawnienia 600 na każdym pliku z hasłem. Lepiej - wyjęcie sekretów do osobnych podłączanych plików (include w git, osobny plik w apt.conf.d tylko dla wierszy z autoryzacją). Jeszcze lepiej - proxy bez autoryzacji hasłem, ale z ograniczeniem po IP albo lokalny agregator, o którym mowa wyżej. I nigdy nie wysyłaj konfiguracji z hasłami do czatów i zgłoszeń w całości.

FAQ: częste pytania o konfigurację

Czy trzeba teraz usuwać zmienne http_proxy z .bashrc

Nie jest to konieczne. Konfiguracje narzędzi mają priorytet nad zmiennymi, konfliktu nie będzie. Ale jeśli chcesz, żeby przez proxy chodziły tylko menedżery pakietów, a przeglądarka i inne programy szły bezpośrednio, zmienne lepiej usunąć: wpływają na wszystko.

Dlaczego w https-proxy dla npm wpisuje się adres z http://, a nie https://

Bo to adres samego serwera proxy, a nie protokół docelowego zasobu. Większość proxy przyjmuje połączenia po zwykłym HTTP i tuneluje HTTPS wewnątrz. Jeśli Twoje proxy rzeczywiście przyjmuje połączenia TLS, wtedy pisz https://, ale to rzadkość.

Czy można używać proxy SOCKS5

npm - nie, obsługuje tylko HTTP proxy. pip - tak, przy zainstalowanym pakiecie pysocks i adresie postaci socks5://host:port. git - tak, format socks5h://host:port, litera h oznacza rozwiązywanie nazw po stronie proxy. apt - tylko przez dodatkowe transporty, standardowo nie. Docker - nie. W praktyce prościej dostać od dostawcy port HTTP.

Jak szybko wyłączyć proxy we wszystkich narzędziach

npm: npm config delete proxy i npm config delete https-proxy. pip: pip config unset global.proxy. git: git config --global --unset http.proxy. apt: usuń lub zmień nazwę /etc/apt/apt.conf.d/80proxy. Docker: usuń blok proxies z daemon.json i config.json, zrestartuj usługę. Albo po prostu przywróć pliki .bak z kopii zapasowych.

Gdzie trzymać konfiguracje w Windows

npm: C:\Users\NAZWA\.npmrc. pip: C:\Users\NAZWA\AppData\Roaming\pip\pip.ini. git: C:\Users\NAZWA\.gitconfig. Docker: C:\Users\NAZWA\.docker\config.json dla klienta i ustawienia Docker Desktop dla demona. apt w Windows nie jest używany, poza WSL, gdzie stosuje się ścieżki linuksowe wewnątrz podsystemu.

Czy to działa wewnątrz WSL

Tak, WSL to zwykły Linux, wszystkie konfiguracje leżą po ścieżkach linuksowych wewnątrz dystrybucji. Pamiętaj, że Docker Desktop z integracją WSL używa demona po stronie Windows, dlatego ustawienia demona robi się w Docker Desktop, a klienta config.json - wewnątrz WSL w katalogu domowym.

Jak zrozumieć, które narzędzie który plik przeczytało

npm config list --json, pip config debug, apt-config dump, docker info, git config --show-origin --list. Każde polecenie pokazuje nie tylko wartości, ale i źródło, z którego zostały wzięte. To pierwsza rzecz, którą warto uruchomić przy debugowaniu.

Dlaczego Docker Compose nie widzi proxy

Compose to klient, używa tego samego demona i tego samego ~/.docker/config.json. Jeśli docker pull działa, a docker compose pull nie, sprawdź, że uruchamiasz compose tym samym użytkownikiem i że w pliku compose nie są nadpisane zmienne środowiskowe kontenerów, które przesłaniają proxy.

Czy można ustawić różne proxy dla npm i pip

Tak, w tym właśnie zaleta własnych konfiguracji. Każdy plik jest niezależny. Na przykład npm może chodzić przez jedno proxy, a pip przez inne, z innym IP i inną geolokalizacją, jeśli tak wymaga zadanie.

Podsumowanie

Podsumujmy. Sprawdziłeś proxy przez curl i uzyskałeś wzorcowy ciąg połączenia z poprawnie zakodowanym hasłem. Potem wpisałeś go w pięciu miejscach: w ~/.npmrc dla npm, w pip.conf dla pip, w /etc/apt/apt.conf.d/80proxy dla apt, w daemon.json i ~/.docker/config.json dla Dockera oraz w ~/.gitconfig dla git. Dla każdego narzędzia ustawiłeś wyjątki dla wewnętrznych hostów tam, gdzie jest to obsługiwane, i upewniłeś się, że wszystko działa nawet przy całkowicie oczyszczonym środowisku. Właśnie to odróżnia własne konfiguracje od zmiennych środowiskowych: nie zależą od tego, kto, skąd i przez jaką usługę uruchomił polecenie.

Co dalej. Zapisz pięć wzorcowych plików w osobistym folderze i napisz krótki skrypt, który wdraża je na nową maszynę. Sprawdź uprawnienia do plików z hasłami. Jeśli masz kolegów z tym samym problemem, podziel się z nimi zbiorczą listą kontrolną: oszczędza godziny debugowania.

W co się rozwijać. Następny poziom to cache'ujące proxy i prywatne rejestry pakietów, lokalny agregator proxy jako jeden punkt wejścia i automatyczna weryfikacja ustawień sieciowych w pipeline'ach. A jeśli będziesz potrzebować skonfigurować proxy nie dla narzędzi, a dla konkretnej sesji terminala lub zadania w CI, jest na to osobny poradnik o zmiennych środowiskowych. Teraz już dokładnie wiesz, gdzie kończą się jego możliwości, a zaczynają możliwości konfiguracji.