Konfiguracja proxy w terminalu Linux i CI: krok po kroku dla HTTP_PROXY, HTTPS_PROXY, NO_PROXY

Wyobraź sobie: otwierasz terminal, wpisujesz komendę instalacji pakietu, a w odpowiedzi cisza lub błąd połączenia. Często przyczyną jest to, że dostęp do sieci odbywa się tylko przez serwer proxy, a system o tym nie wie. Ten poradnik nauczy Cię konfigurować proxy wszędzie tam, gdzie jest to potrzebne w Linuxie i CI.

Wstęp: co otrzymasz i dla kogo jest ten poradnik

Po przeczytaniu tego poradnika będziesz pewnie konfigurować proxy w terminalu Linux oraz w systemach ciągłej integracji. Zrozumiesz, jak działają zmienne środowiskowe, jak poprawnie złożyć URL proxy i jak sprawić, aby przez proxy działały absolutnie wszystkie kluczowe narzędzia deweloperskie.

Co dokładnie otrzymasz:

• Działającą konfigurację proxy w bieżącej sesji terminala.
• Stałą konfigurację, która przetrwa restart.
• Poprawną konfigurację dla apt, dnf, git, npm, pip, curl, wget, Docker.
• Działające pipeline'y CI w GitHub Actions i GitLab Runner.
• Zrozumienie, jak sprawdzić, czy ruch faktycznie idzie przez proxy.
• Umiejętności bezpiecznego przechowywania hasła do proxy.

Dla kogo jest ten poradnik: dla początkujących administratorów systemów, programistów i inżynierów DevOps, którzy pracują w środowisku z korporacyjnym proxy. Są też elementy dla zaawansowanych: niuanse systemd, ProxyCommand dla SSH i maskowanie sekretów w CI.

Co musisz wiedzieć wcześniej: musisz umieć otworzyć terminal, wpisywać komendy i rozumieć, czym jest plik i folder. Reszta jest wyjaśniona po drodze prostym językiem.

Ile czasu to zajmie: podstawowa konfiguracja zajmie około 15 minut. Pełne przejście przez poradnik z konfiguracją wszystkich narzędzi i CI – około 60-90 minut. Nie spiesz się, lepiej robić to z rozwagą.

Rada: miej ten poradnik otwarty w osobnym oknie i wykonuj komendy po kolei. Wtedy na pewno nie przegapisz ważnego kroku.

Przygotowanie wstępne: adres, port, login i poprawny URL proxy

Zanim cokolwiek skonfigurujesz, musisz zebrać dane o swoim serwerze proxy. Bez tego nie ma sensu iść dalej.

Skąd wziąć dane proxy

Zazwyczaj proxy udostępnia jedna z następujących stron:

• Administrator systemu w firmie – jeśli pracujesz w sieci korporacyjnej. Poproś go o adres, port i dane do autoryzacji.
• Usługa wynajmu proxy – w panelu klienta zazwyczaj znajduje się sekcja z ustawieniami dostępu.
• Twój własny serwer – jeśli samodzielnie uruchomiłeś proxy, dane znasz.

Potrzebujesz czterech elementów: adres (host), port, login (username) i hasło (password). Czasami login i hasło nie są wymagane – wtedy proxy jest bez autoryzacji.

Jak zbudować URL proxy

Proxy podaje się w postaci pojedynczego ciągu – URL. Ogólny format jest taki:

schemat://login:hasło@adres:port

Rozłóżmy to na przykładzie. Załóżmy, że adres proxy to proxy.example.com, port – 3128, login – ivan, hasło – secret123. Wtedy URL będzie wyglądał tak:

http://ivan:secret123@proxy.example.com:3128

Jeśli autoryzacja nie jest potrzebna, URL jest prostszy:

http://proxy.example.com:3128

O schemacie: najczęściej używa się schematu http, nawet do dostępu do stron HTTPS. To normalne – schemat oznacza tutaj protokół komunikacji z samym proxy, a nie z docelową stroną. Czasami spotyka się proxy ze schematem https lub socks5.

Dlaczego znaki specjalne w haśle trzeba kodować

To jedna z najczęstszych przyczyn tajemniczych błędów. Jeśli w haśle znajdują się znaki specjalne, takie jak @, :, /, #, ?, to psują one parsowanie URL. Na przykład znak @ oddziela dane autoryzacyjne od adresu. Jeśli znajdzie się on w haśle, system się pomyli i nie będzie wiedział, gdzie kończy się hasło, a zaczyna adres.

Rozwiązaniem jest percent-encoding (kodowanie procentowe). Każdy problematyczny znak zastępuje się znakiem procentu i jego kodem w systemie szesnastkowym.

Podstawowe zamienniki:

• Znak @ zamienia się na %40
• Znak : zamienia się na %3A
• Znak / zamienia się na %2F
• Znak # zamienia się na %23
• Znak ? zamienia się na %3F
• Znak spacji zamienia się na %20
• Znak % zamienia się na %25

Przykład: jeśli hasło to p@ss:word, to w URL powinno wyglądać jak p%40ss%3Aword. Wtedy pełny URL będzie:

http://ivan:p%40ss%3Aword@proxy.example.com:3128

Rada: aby szybko zakodować hasło, użyj polecenia python3 -c "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1], safe=''))" 'twoje_haslo'. Poda ono gotowy ciąg do wstawienia do URL.

⚠️ Uwaga: nigdy nie wpisuj prawdziwego hasła bezpośrednio w wierszu poleceń na współdzielonym komputerze – trafi ono do historii. O bezpiecznym wprowadzaniu porozmawiamy osobno na końcu poradnika.

✅ Sprawdzenie: masz w ręku jeden lub kilka zebranych URL-i proxy, w których wszystkie znaki specjalne w haśle są zakodowane. Zapisz je w bezpiecznym miejscu, najlepiej w menedżerze haseł.

Podstawowe pojęcia: zmienne środowiskowe, wielkość liter i format NO_PROXY

Aby konfiguracja nie była magią, omówimy trzy fundamentalne pojęcia. Zajmie to pięć minut, ale zaoszczędzi godzin debugowania.

Czym są zmienne środowiskowe

Zmienna środowiskowa to nazwana wartość, którą system operacyjny przechowuje w pamięci i przekazuje uruchamianym programom. Wyobraź sobie to jako karteczkę, którą system pokazuje każdemu nowemu programowi: oto adres proxy, użyj go.

Wiele narzędzi sieciowych w Linuxie podczas uruchamiania odczytuje specjalne zmienne i jeśli je znajdzie, automatycznie kieruje ruch przez proxy. Najważniejsze z nich to:

• HTTP_PROXY – proxy dla nieszyfrowanych zapytań HTTP.
• HTTPS_PROXY – proxy dla szyfrowanych zapytań HTTPS.
• NO_PROXY – lista adresów, do których trzeba się łączyć bezpośrednio, z pominięciem proxy.
• FTP_PROXY – proxy dla protokołu FTP, obecnie rzadko używane.
• ALL_PROXY – proxy dla wszystkich protokołów naraz, często używane dla socks.

Różnica między http_proxy a HTTP_PROXY – wielkość liter

To subtelny, ale ważny szczegół. Linux rozróżnia wielkość liter, więc http_proxy i HTTP_PROXY to formalnie dwie różne zmienne. Różne programy odczytują różne warianty.

Historycznie ukształtowało się tak:

• Narzędzie curl odczytuje zarówno małe, jak i duże litery, ale mała wersja http_proxy ma szczególną cechę bezpieczeństwa – dużej HTTP_PROXY curl ignoruje w środowisku CGI, aby zapobiec atakom.
• Narzędzie wget tradycyjnie preferuje małe litery.
• Wiele programów napisanych w różnych językach odczytuje duże warianty.

Praktyczny wniosek: aby nie zgadywać, ustaw obie wersje – zarówno małe, jak i duże litery. To najbezpieczniejsza strategia, którą będziemy stosować.

Format NO_PROXY i dlaczego nie rozumie CIDR

Zmienna NO_PROXY zawiera listę adresów oddzielonych przecinkami, do których należy się łączyć bezpośrednio. Jest to krytyczne dla wewnętrznych zasobów: bazy danych, lokalne usługi, metadane chmury.

Przykład poprawnej wartości:

localhost,127.0.0.1,.example.com,.internal,169.254.169.254

Zwróć uwagę na kropkę przed example.com. Kropka oznacza, że reguła dotyczy wszystkich subdomen: api.example.com, git.example.com itd.

⚠️ Uwaga: NO_PROXY z reguły nie rozumie notacji CIDR ani masek podsieci. Zapis typu 10.0.0.0/8 w większości narzędzi nie zadziała. Niektóre nowoczesne wersje bibliotek to obsługują, ale nie można na tym polegać. Wymieniaj konkretne adresy i sufiksy domenowe jawnie.

NO_PROXY również zazwyczaj nie obsługuje gwiazdek jako uniwersalnego wzorca. Nie pisz *.example.com – użyj kropki na początku: .example.com.

Rada: zawsze dodawaj do NO_PROXY adres localhost i 127.0.0.1. W przeciwnym razie lokalne zapytania pójdą przez proxy i najprawdopodobniej się zepsują.

✅ Sprawdzenie: rozumiesz, do czego służą HTTP_PROXY, HTTPS_PROXY i NO_PROXY, wiesz o różnicy w wielkości liter i pamiętasz, że NO_PROXY nie lubi CIDR. Teraz można przejść do praktyki.

Krok 1: włączamy proxy w bieżącej sesji i sprawdzamy curlem

Cel etapu: nauczyć się szybko włączać proxy w otwartym terminalu i upewnić się, że działa. Te ustawienia żyją tylko do zamknięcia okna terminala – idealne do testowania.

Ustawiamy zmienne przez export

Polecenie export tworzy zmienną środowiskową w bieżącej sesji. Wykonaj następujące komendy, podstawiając swój URL proxy.

1. Otwórz terminal.
2. Wpisz komendę dla HTTP: export http_proxy="http://ivan:secret123@proxy.example.com:3128"
3. Wpisz komendę dla HTTPS: export https_proxy="http://ivan:secret123@proxy.example.com:3128"
4. Zduplikuj w dużej literze: export HTTP_PROXY="$http_proxy"
5. I jeszcze raz: export HTTPS_PROXY="$https_proxy"
6. Ustaw wyjątki: export no_proxy="localhost,127.0.0.1,.example.com"
7. Zduplikuj: export NO_PROXY="$no_proxy"

Konstrukcja "$http_proxy" podstawia wartość już ustawionej małej zmiennej, aby nie wpisywać URL ponownie.

Rada: zauważ, że cały URL jest w podwójnych cudzysłowach. Chroni to przed błędną interpretacją znaków specjalnych przez twoją powłokę bash.

Sprawdzamy przez curl

Teraz sprawdzimy, czy zmienne są odczytywane. Narzędzie curl doskonale się do tego nadaje.

1. Sprawdź, czy zmienna jest ustawiona: echo $http_proxy – powinieneś zobaczyć swój URL.
2. Wykonaj zapytanie ze szczegółowym wyjściem: curl -v http://example.com
3. W wynikach szukaj wiersza, w którym jest Connected to proxy.example.com – to oznacza, że curl poszedł przez proxy.

Jeśli autoryzacja jest prawidłowa i proxy jest dostępne, otrzymasz w odpowiedzi stronę HTML. Jeśli widzisz błąd 407, problem tkwi w loginie lub haśle – wróć do sekcji o kodowaniu hasła.

Rada: flaga -v (verbose) pokazuje szczegóły połączenia. To twoje główne narzędzie do debugowania proxy. Bez niej nie zobaczysz, dokąd dokładnie trafia zapytanie.

Aby wyłączyć proxy w bieżącej sesji, użyj polecenia unset: unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY. Wszystkie zmienne znikną.

✅ Sprawdzenie: polecenie curl -v http://example.com pokazuje połączenie przez twój serwer proxy i zwraca treść strony. Jeśli tak – pierwszy krok udany.

Krok 2: ustawiamy trwałą konfigurację

Cel etapu: sprawić, aby proxy włączało się automatycznie przy każdym logowaniu i przetrwało restart. Jest kilka poziomów, wybierz odpowiedni.

Opcja A: tylko dla twojego użytkownika przez ~/.bashrc

Plik ~/.bashrc jest wykonywany za każdym razem przy otwieraniu interaktywnego terminala dla twojego użytkownika. To najbezpieczniejsza opcja – nie ingerujesz w innych użytkowników systemu.

1. Otwórz plik edytorem: nano ~/.bashrc
2. Przewiń na sam koniec pliku.
3. Dodaj te same linie export, co w Kroku 1.
4. Zapisz plik: naciśnij Ctrl+O, potem Enter, potem Ctrl+X, aby wyjść.
5. Zastosuj zmiany bez restartu: source ~/.bashrc

Rada: przed edycją zrób kopię zapasową poleceniem cp ~/.bashrc ~/.bashrc.backup. Jeśli coś pójdzie nie tak, łatwo przywrócisz oryginał.

Opcja B: dla całego systemu przez /etc/environment

Plik /etc/environment ustawia zmienne dla wszystkich użytkowników i działa nawet poza bashem. Format jest tutaj specjalny: bez słowa export, po prostu IMIĘ=wartość.

1. Otwórz plik z uprawnieniami administratora: sudo nano /etc/environment
2. Dodaj linie bez export, np.: http_proxy="http://ivan:secret123@proxy.example.com:3128"
3. Dodaj analogicznie https_proxy, HTTP_PROXY, HTTPS_PROXY, no_proxy, NO_PROXY.
4. Zapisz i wyjdź.
5. Aby zastosować, wyloguj się i zaloguj ponownie, albo uruchom ponownie system.

Opcja C: przez /etc/profile.d

Bardziej elastyczna systemowa metoda – utwórz osobny skrypt w folderze /etc/profile.d. Wszystkie pliki .sh stamtąd są wykonywane przy logowaniu.

1. Utwórz plik: sudo nano /etc/profile.d/proxy.sh
2. Wewnątrz użyj zwykłych poleceń export, jak w Kroku 1.
3. Zapisz plik.
4. Ustaw go jako wykonywalny: sudo chmod +x /etc/profile.d/proxy.sh

Ta metoda jest wygodniejsza niż /etc/environment, ponieważ obsługuje pełną składnię powłoki.

Opcja D: dla usług systemowych przez systemd drop-in

Uwaga, to ważny niuans. Usługi działające w tle, zarządzane przez systemd, nie czytają twojego ~/.bashrc i często ignorują /etc/environment. Dla nich potrzebne jest osobne podejście – plik drop-in.

Zakładając, że potrzebujesz, aby przez proxy działała konkretna usługa, np. some-service.

1. Utwórz katalog drop-in i plik poleceniem: sudo systemctl edit some-service
2. Otworzy się edytor. Wpisz blok ustawień.
3. W sekcji [Service] dodaj linie w postaci Environment="HTTP_PROXY=http://ivan:secret123@proxy.example.com:3128"
4. Dodaj analogiczne linie Environment dla HTTPS_PROXY i NO_PROXY.
5. Zapisz plik.
6. Przeładuj konfigurację: sudo systemctl daemon-reload
7. Uruchom ponownie usługę: sudo systemctl restart some-service

Dyrektywa Environment ustawia zmienną właśnie dla tej usługi. To jedyny poprawny sposób dla serwisów systemd.

⚠️ Uwaga: w RHEL, CentOS, Fedorze i AlmaLinux ścieżki i narzędzia są takie same – systemd działa identycznie. Różnice pojawią się później, w sekcji o menedżerach pakietów.

✅ Sprawdzenie: otwórz nowy terminal (nie ten, gdzie robiłeś export ręcznie) i wykonaj echo $http_proxy. Jeśli widzisz swój URL – trwała konfiguracja działa.

Krok 3: konfigurujemy menedżery pakietów i narzędzia osobno

Cel etapu: wiele narzędzi nie czyta zmiennych środowiskowych lub ma własne pliki konfiguracyjne. Skonfigurujemy każde osobno, aby nic nie wysiadło.

apt na Ubuntu i Debian

Menedżer pakietów apt często uruchamiany jest przez sudo i może nie widzieć twoich zmiennych. Bezpieczniej jest ustawić proxy w jego własnym pliku konfiguracyjnym.

1. Utwórz plik: sudo nano /etc/apt/apt.conf.d/95proxies
2. Dodaj linię: Acquire::http::Proxy "http://ivan:secret123@proxy.example.com:3128";
3. Dodaj linię dla HTTPS: Acquire::https::Proxy "http://ivan:secret123@proxy.example.com:3128";
4. Zapisz plik.
5. Sprawdź: sudo apt update

Zwróć uwagę na średnik na końcu każdej linii – to obowiązkowy element składni apt.

dnf i yum na RHEL, Fedora, AlmaLinux

W systemach rodziny RHEL zamiast apt używa się dnf i yum. Proxy ustawia się w głównym pliku konfiguracyjnym.

1. Otwórz plik: sudo nano /etc/dnf/dnf.conf (dla starszych systemów /etc/yum.conf)
2. W sekcji [main] dodaj linię: proxy=http://proxy.example.com:3128
3. Jeśli potrzebna jest autoryzacja, dodaj osobno: proxy_username=ivan i proxy_password=secret123
4. Zapisz plik.
5. Sprawdź: sudo dnf makecache

W dnf wygodniej jest ustawić login i hasło oddzielnymi dyrektywami, a nie w URL.

npm przez .npmrc

1. Ustaw proxy poleceniem: npm config set proxy "http://ivan:secret123@proxy.example.com:3128"
2. Ustaw dla HTTPS: npm config set https-proxy "http://ivan:secret123@proxy.example.com:3128"
3. Ustawienia zostaną automatycznie zapisane w pliku ~/.npmrc.
4. Sprawdź: npm config get proxy

pip przez pip.conf

1. Utwórz katalog: mkdir -p ~/.config/pip
2. Otwórz plik: nano ~/.config/pip/pip.conf
3. Dodaj sekcję [global] i linię proxy = http://ivan:secret123@proxy.example.com:3128
4. Zapisz plik.
5. Sprawdź przez instalację dowolnego pakietu: pip install requests

Alternatywnie możesz podać proxy bezpośrednio w poleceniu: pip install requests --proxy http://proxy.example.com:3128

git przez http.proxy

1. Ustaw globalnie: git config --global http.proxy "http://ivan:secret123@proxy.example.com:3128"
2. W razie potrzeby osobno dla HTTPS: git config --global https.proxy "http://ivan:secret123@proxy.example.com:3128"
3. Sprawdź: git config --global --get http.proxy

Aby usunąć ustawienie: git config --global --unset http.proxy

git przez SSH przez ProxyCommand

Jeśli klonujesz repozytoria przez SSH (adres typu git@github.com), ustawienie http.proxy nie pomoże – SSH to inny protokół. Tutaj potrzebny jest ProxyCommand.

1. Otwórz plik: nano ~/.ssh/config
2. Dodaj blok dla potrzebnego hosta: linia Host github.com, a następnie z wcięciem linia ProxyCommand nc -X connect -x proxy.example.com:3128 %h %p
3. Zapisz plik.
4. Zainstaluj narzędzie netcat, jeśli go nie masz: sudo apt install netcat-openbsd na Ubuntu, sudo dnf install nmap-ncat na RHEL.

Tutaj %h i %p są automatycznie zastępowane przez host i port docelowy. Flaga -X connect informuje netcat, aby użył proxy HTTP.

curl przez .curlrc

1. Otwórz plik: nano ~/.curlrc
2. Dodaj linię: proxy = "http://ivan:secret123@proxy.example.com:3128"
3. Zapisz plik.

Teraz curl będzie używać proxy zawsze, nawet bez zmiennych środowiskowych.

wget przez .wgetrc

1. Otwórz plik: nano ~/.wgetrc
2. Dodaj linie: http_proxy = http://proxy.example.com:3128 i https_proxy = http://proxy.example.com:3128
3. Dodaj use_proxy = on
4. Zapisz plik.

composer dla PHP

Composer odczytuje zmienną środowiskową HTTP_PROXY, więc często nie jest potrzebna osobna konfiguracja. Jeśli chcesz ustawić jawnie, użyj zmiennej w momencie uruchamiania: HTTP_PROXY=http://proxy.example.com:3128 composer install

Go i GOPROXY: ważne ostrzeżenie

⚠️ Uwaga: zmienna GOPROXY to NIE serwer proxy w naszym rozumieniu. Nie można ich mylić. GOPROXY wskazuje na mirror modułów Go – usługę, z której pobiera się biblioteki. To adres repozytorium, a nie proxy sieciowe.

Aby Go łączył się z internetem przez twoje zwykłe proxy, używaj standardowych HTTP_PROXY i HTTPS_PROXY. GOPROXY pozostaw w wartości domyślnej, chyba że masz osobne zadanie zmiany mirrora modułów.

Rada: zapamiętaj zasadę – jeśli w nazwie zmiennej jest słowo PROXY, nie oznacza to jeszcze, że chodzi o twoje proxy sieciowe. GOPROXY, npm registry i tym podobne – to źródła pakietów.

✅ Sprawdzenie: wykonaj operację testową dla każdego skonfigurowanego narzędzia: sudo apt update, npm install, git ls-remote itd. Wszystkie powinny z powodzeniem połączyć się z siecią.

Krok 4: konfigurujemy Dockera i Kubernetes

Cel etapu: Docker to wyjątkowy przypadek. Ma trzy różne miejsca konfiguracji proxy, i mylenie ich to typowy błąd. Omówimy każde.

Miejsce 1: demon Dockera przez systemd drop-in

To ustawienie jest potrzebne, aby sam Docker mógł pobierać obrazy z rejestru. Demon Dockera jest zarządzany przez systemd, więc używamy znanego już mechanizmu drop-in.

1. Utwórz katalog: sudo mkdir -p /etc/systemd/system/docker.service.d
2. Utwórz plik: sudo nano /etc/systemd/system/docker.service.d/proxy.conf
3. Dodaj sekcję [Service].
4. Dodaj linię Environment="HTTP_PROXY=http://proxy.example.com:3128"
5. Dodaj analogiczne linie dla HTTPS_PROXY i NO_PROXY.
6. Przeładuj konfigurację: sudo systemctl daemon-reload
7. Uruchom ponownie Dockera: sudo systemctl restart docker

Sprawdzić można poleceniem: sudo systemctl show --property=Environment docker

Miejsce 2: budowanie obrazu przez build-arg

Podczas budowania obrazu komendy wewnątrz Dockerfile (np. apt install) wykonują się w izolowanym środowisku, które nie widzi proxy hosta. Należy przekazać proxy jawnie.

1. W Dockerfile dodaj instrukcje ARG http_proxy i ARG https_proxy przed komendami RUN.
2. Zbuduj obraz, przekazując argumenty: docker build --build-arg http_proxy=http://proxy.example.com:3128 --build-arg https_proxy=http://proxy.example.com:3128 -t myimage .

⚠️ Uwaga: nie wpisuj hasła do proxy bezpośrednio w Dockerfile instrukcją ENV. Pozostanie ono w warstwach obrazu, a każdy, kto otrzyma obraz, zobaczy hasło. Używaj właśnie build-arg, a jeszcze lepiej proxy bez hasła do budowania.

Miejsce 3: kontenery przy uruchamianiu przez ~/.docker/config.json

Aby uruchomione kontenery automatycznie otrzymywały zmienne proxy, skonfiguruj plik konfiguracyjny klienta Dockera.

1. Otwórz plik: nano ~/.docker/config.json
2. Dodaj blok proxies z sekcją default.
3. Wewnątrz podaj httpProxy, httpsProxy i noProxy ze swoimi wartościami.
4. Zapisz plik.

Teraz przy każdym docker run zmienne zostaną automatycznie przekazane do wnętrza kontenera.

Zmienne w manifeście Kubernetes

W Kubernetes proxy ustawia się przez zmienne środowiskowe w specyfikacji kontenera. W sekcji env manifestu Pod lub Deployment dodaj elementy z name HTTP_PROXY, HTTPS_PROXY, NO_PROXY i odpowiednimi value.

Rada: wartości tajne w Kubernetes przechowuj w obiekcie Secret i podłączaj przez valueFrom, zamiast wpisywać hasło bezpośrednio w manifest. W ten sposób hasło nie trafi do systemu kontroli wersji.

✅ Sprawdzenie: wykonaj docker pull hello-world – obraz powinien się pobrać. Następnie docker run --rm alpine env | grep -i proxy – zobaczysz przekazane zmienne wewnątrz kontenera.

Krok 5: konfigurujemy proxy w CI – GitHub Actions i GitLab Runner

Cel etapu: sprawić, aby pipeline'y CI działały przez proxy, jednocześnie bezpiecznie przechowując dostęp i nie ujawniając hasła w logach.

Przechowywanie dostępu w sekretach

Główna zasada CI: nigdy nie wpisuj hasła do proxy bezpośrednio w pliku YAML pipeline'u. Plik leży w repozytorium i hasło zobaczą wszyscy. Używaj mechanizmu sekretów.

W GitHub Actions sekrety dodaje się w ustawieniach repozytorium, sekcja Settings, następnie Secrets and variables, potem Actions. Utwórz sekret o nazwie PROXY_URL i wklej tam pełny URL proxy.

W GitLab sekrety nazywają się CI/CD variables. Dodaje się je w Settings, potem CI/CD, potem Variables. Koniecznie włącz opcje Masked i Protected dla wrażliwych wartości.

Konfiguracja GitHub Actions

1. W pliku pipeline'u .github/workflows dodaj na poziomie job blok env.
2. Ustaw HTTP_PROXY na wartość z sekretu używając składni podwójnych nawiasów klamrowych z secrets.PROXY_URL.
3. Analogicznie ustaw HTTPS_PROXY i NO_PROXY.
4. Te zmienne będą dostępne dla wszystkich kroków job.

Konfiguracja GitLab Runner

W GitLab są dwa poziomy. Możesz ustawić zmienne w samym pliku .gitlab-ci.yml przez blok variables, albo na poziomie runnera w jego pliku config.toml przez sekcję environment.

1. Dla projektu: dodaj w .gitlab-ci.yml blok variables z odwołaniami do chronionych zmiennych.
2. Dla wszystkich projektów runnera: otwórz config.toml runnera i w sekcji [[runners]] dodaj parametr environment z listą potrzebnych zmiennych.

Maskowanie hasła w logach

Nawet z sekretami hasło może przypadkowo trafić do logów, jeśli jakaś komenda je wypisze. GitHub Actions automatycznie maskuje wartości sekretów gwiazdkami. W GitLab odpowiada za to opcja Masked – ale działa tylko wtedy, gdy wartość spełnia wymagania (bez niektórych znaków specjalnych i odpowiedniej długości).

⚠️ Uwaga: unikaj komend z flagą -v lub echo, które wypisują pełny URL proxy w logach. Nawet z maskowaniem lepiej nie ryzykować. Do debugowania wypisuj tylko adres i port bez loginu i hasła.

Rada: przechowuj URL proxy bez wbudowanego hasła, a login i hasło – jako osobne sekrety. Dzięki temu łatwiej je maskować i rotować.

✅ Sprawdzenie: uruchom pipeline ręcznie. Krok, który wykonuje zapytanie sieciowe (np. instalację zależności), powinien zakończyć się sukcesem. W logach hasło nie powinno być widoczne.

Sprawdzenie wyniku: upewniamy się, że ruch faktycznie idzie przez proxy

Skofigurować to mało – trzeba udowodnić, że ruch faktycznie przechodzi przez proxy, a nie idzie bezpośrednio. Oto lista kontrolna.

Lista kontrolna – co powinno działać

• Polecenie echo $http_proxy w nowym terminalu pokazuje twój URL.
• curl -v http://example.com pokazuje wiersz Connected to proxy.
• sudo apt update aktualizuje listy pakietów.
• git ls-remote do zdalnego repozytorium przechodzi.
• docker pull pobiera obraz.
• Pipeline CI kończy się na zielono.

Jak solidnie przetestować

Najuczciwszy sposób – dowiedzieć się, jaki zewnętrzny adres IP widzi serwer docelowy. Wykonaj zapytanie do usługi pokazującej twój IP. Jeśli przez proxy, zobaczysz adres IP serwera proxy, a nie swój własny.

1. Wykonaj zapytanie bez proxy: env -u http_proxy -u https_proxy curl -s http://ifconfig.me – zobaczysz swój prawdziwy IP.
2. Wykonaj z proxy: curl -s http://ifconfig.me – zobaczysz IP proxy.
3. Jeśli dwa adresy się różnią – proxy działa.

Inny sposób – zajrzeć do logów samego serwera proxy, jeśli masz do nich dostęp. Twoje zapytania powinny się tam pojawiać.

Rada: polecenie env -u tymczasowo usuwa zmienną tylko dla jednego polecenia, nie naruszając sesji. Wygodne do porównania zachowania z proxy i bez.

✅ Sprawdzenie: adres IP z proxy różni się od bezpośredniego. To stuprocentowy dowód, że ruch idzie przez proxy.

Typowe błędy i ich rozwiązania

Omówmy częste problemy. Prosty format: problem, przyczyna, rozwiązanie.

Problem 1: sudo nie dziedziczy zmiennych

Przyczyna: sudo domyślnie czyści środowisko ze względów bezpieczeństwa. Twoje export nie docierają do polecenia uruchamianego przez sudo.

Rozwiązanie: użyj flagi -E, aby zachować środowisko: sudo -E apt update. Albo skonfiguruj trwałe zachowanie poprzez plik sudoers. Wykonaj sudo visudo i dodaj linię Defaults env_keep += "http_proxy https_proxy HTTP_PROXY HTTPS_PROXY no_proxy NO_PROXY". Potem sudo będzie zawsze przepuszczać te zmienne.

Problem 2: błędy certyfikatów

Przyczyna: niektóre korporacyjne proxy przechwytują HTTPS i podmieniają certyfikaty na swój własny certyfikat główny. System go nie zna i zgłasza problem z połączeniem.

Rozwiązanie: pobierz od administratora certyfikat główny proxy. Na Ubuntu i Debian skopiuj go do /usr/local/share/ca-certificates z rozszerzeniem .crt i wykonaj sudo update-ca-certificates. Na RHEL umieść w /etc/pki/ca-trust/source/anchors i wykonaj sudo update-ca-trust. Potem wszystkie narzędzia zaczną ufać proxy.

Problem 3: curl działa, apt nie działa

Przyczyna: curl odczytuje zmienne środowiskowe, a apt uruchomiony przez sudo ich nie widzi i nie ma własnego pliku konfiguracyjnego proxy.

Rozwiązanie: skonfiguruj proxy w /etc/apt/apt.conf.d, jak opisano w Kroku 3. To osobne ustawienie od zmiennych środowiskowych i właśnie to jest potrzebne apt.

Problem 4: hasło ze znakami specjalnymi

Przyczyna: znaki @, :, / w niezakodowanym haśle psują parsowanie URL.

Rozwiązanie: zastosuj percent-encoding z sekcji Przygotowania. Zamień @ na %40, : na %3A itd.

Problem 5: błąd 407 Proxy Authentication Required

Przyczyna: nieprawidłowy login lub hasło, albo proxy wymaga autoryzacji, a ty jej nie podałeś.

Rozwiązanie: sprawdź ponownie login i hasło. Upewnij się, że dane autoryzacyjne znajdują się w URL. Sprawdź kodowanie znaków specjalnych.

Problem 6: wewnętrzne zasoby są niedostępne

Przyczyna: zapytania do lokalnych i wewnętrznych adresów idą przez proxy, które ich nie zna.

Rozwiązanie: dodaj te adresy do NO_PROXY. Nie zapomnij o localhost, 127.0.0.1 i wewnętrznych domenach z kropką na początku.

Problem 7: demon Dockera nie widzi proxy

Przyczyna: skonfigurowałeś zmienne w bashrc, ale demon Dockera jest zarządzany przez systemd i ich nie odczytuje.

Rozwiązanie: użyj systemd drop-in z Kroku 4, nie zapomnij o daemon-reload i restart docker.

Problem 8: ustawienia nie zostały zastosowane

Przyczyna: edytowałeś bashrc, ale nie uruchomiłeś ponownie terminala.

Rozwiązanie: wykonaj source ~/.bashrc lub otwórz nowe okno terminala.

Dodatkowe możliwości i zaawansowane ustawienia

Gdy podstawowe ustawienia działają, można poprawić wygodę i elastyczność.

Funkcje przełączające proxy

Wygodnie jest dodać w ~/.bashrc dwie funkcje: proxy_on do włączania i proxy_off do wyłączania. Wewnątrz proxy_on umieść komendy export, a wewnątrz proxy_off – komendy unset. Wtedy przełączanie stanie się jednym poleceniem.

Różne proxy dla różnych zadań

Możesz ustawić proxy tylko dla jednego polecenia, nie zmieniając całego środowiska. Przykład: https_proxy=http://other:3128 curl https://example.com. Zmienna działa tylko dla tego polecenia.

Proxy SOCKS

Jeśli masz proxy typu SOCKS5, użyj schematu socks5 w URL i zmiennej ALL_PROXY. Dla curl jest flaga --socks5. Pamiętaj, że nie wszystkie narzędzia potrafią pracować z SOCKS.

Rada: dla narzędzi, które w ogóle nie obsługują proxy, istnieją nakładki, takie jak proxychains. Ale używaj ich świadomie, zmieniają one zachowanie wywołań sieciowych programu.

Tabela podsumowująca ustawienia

Miej tę tabelę pod ręką. Format: narzędzie – plik konfiguracyjny – zmienna lub dyrektywa.

• Sesja shell – tymczasowo w pamięci – export http_proxy i HTTP_PROXY.
• Użytkownik – ~/.bashrc – export zmiennych.
• Cały system – /etc/environment – http_proxy bez export.
• Cały system – /etc/profile.d/proxy.sh – export zmiennych.
• Usługa systemd – drop-in przez systemctl edit – dyrektywa Environment.
• apt (Ubuntu, Debian) – /etc/apt/apt.conf.d/95proxies – Acquire::http::Proxy.
• dnf, yum (RHEL) – /etc/dnf/dnf.conf – proxy, proxy_username, proxy_password.
• npm – ~/.npmrc – proxy i https-proxy.
• pip – ~/.config/pip/pip.conf – proxy w sekcji global.
• git przez HTTPS – globalna konfiguracja git – http.proxy.
• git przez SSH – ~/.ssh/config – ProxyCommand.
• curl – ~/.curlrc – proxy.
• wget – ~/.wgetrc – http_proxy, https_proxy, use_proxy.
• composer – środowisko – HTTP_PROXY.
• Demon Dockera – /etc/systemd/system/docker.service.d/proxy.conf – Environment.
• Budowanie Dockera – polecenie build – build-arg http_proxy.
• Kontenery Dockera – ~/.docker/config.json – blok proxies.
• Kubernetes – manifest Pod – env z HTTP_PROXY.
• GitHub Actions – plik workflow – blok env z secrets.
• GitLab – .gitlab-ci.yml lub config.toml – variables lub environment.

FAQ: często zadawane pytania dotyczące konfiguracji proxy

Czy muszę ustawiać zarówno małe, jak i duże zmienne?

Tak, to najbezpieczniejsza strategia. Różne programy odczytują różną wielkość liter, więc ustawienie obu wersji eliminuje niespodzianki.

Dlaczego curl widzi proxy, a apt nie?

Ponieważ apt uruchomiony przez sudo nie dziedziczy zmiennych środowiskowych i ma własny plik konfiguracyjny. Skonfiguruj apt osobno przez plik w /etc/apt/apt.conf.d.

Jak tymczasowo wyłączyć proxy dla jednego polecenia?

Użyj env -u http_proxy -u https_proxy przed poleceniem. Usunie to zmienne tylko dla tego uruchomienia.

Czy można podać podsieć w NO_PROXY?

Z reguły nie. NO_PROXY w niezawodny sposób nie rozumie notacji CIDR. Wymieniaj konkretne adresy i sufiksy domenowe z kropką na początku.

Czy GOPROXY to mój serwer proxy?

Nie. GOPROXY wskazuje na mirror modułów Go, a nie na proxy sieciowe. Do proxy sieciowego w Go używaj HTTP_PROXY i HTTPS_PROXY.

Jak bezpiecznie przechowywać hasło do proxy?

W CI używaj sekretów. Lokalnie stosuj plik .netrc z uprawnieniami 600 lub menedżer haseł. Unikaj hasła w historii poleceń.

Dlaczego git przez SSH nie idzie przez http.proxy?

Ponieważ SSH to osobny protokół. Skonfiguruj ProxyCommand w pliku ~/.ssh/config dla potrzebnego hosta.

Co robić przy błędach certyfikatu przez proxy?

Zainstaluj certyfikat główny proxy w systemowym magazynie i zaktualizuj zaufanie poleceniem update-ca-certificates na Debianie lub update-ca-trust na RHEL.

Ustawienia w bashrc nie działają w nowej sesji, dlaczego?

Być może edytowałeś niewłaściwy plik, nie zapisałeś zmian lub nie otworzyłeś nowego terminala. Sprawdź przez echo i source.

Jak sprawdzić, że ruch faktycznie idzie przez proxy?

Porównaj zewnętrzny IP z proxy i bez niego, używając curl do usługi określającej IP. Różne adresy potwierdzają działanie proxy.

Zakończenie: co opanowałeś i dokąd iść dalej

Gratulacje, przeszedłeś długą drogę. Podsumujmy, co teraz umiesz.

Nauczyłeś się składać poprawny URL proxy i kodować znaki specjalne w haśle. Rozumiesz zmienne HTTP_PROXY, HTTPS_PROXY i NO_PROXY, w tym niuanse wielkości liter i formatu wyjątków. Umiesz włączać proxy w sesji i robić konfigurację trwałą na kilka sposobów, w tym systemd drop-in dla usług.

Skonfigurowałeś proxy dla wszystkich kluczowych narzędzi: apt i dnf, npm i pip, git przez HTTPS i SSH, curl i wget, composer, a także zrozumiałeś ważną różnicę z GOPROXY. Opanowałeś trzy miejsca konfiguracji Dockera i zmienne w Kubernetes. Wreszcie, skonfigurowałeś proxy w GitHub Actions i GitLab z bezpiecznym przechowywaniem sekretów i maskowaniem hasła.

Co robić dalej: utrwal wiedzę przez praktykę. Skonfiguruj proxy na testowej maszynie od zera, kierując się poradnikiem. Utwórz funkcje przełączające dla wygody. Poznaj logi swojego serwera proxy, aby na własne oczy zobaczyć ruch.

Gdzie się rozwijać: następny krok to automatyzacja konfiguracji za pomocą narzędzi do zarządzania konfiguracją, takich jak Ansible, aby wdrażać proxy na dziesiątkach maszyn jednym poleceniem. Przyda się też głębsze zrozumienie certyfikatów i różnych typów proxy.

Rada: zachowaj tabelę podsumowującą z tego poradnika jako ściągawkę. Zaoszczędzi ci mnóstwo czasu, gdy będziesz musiał szybko przypomnieć sobie, gdzie konfiguruje się proxy dla konkretnego narzędzia.

Świetnie sobie poradziłeś. Teraz proxy w terminalu Linux i w CI nie stanowi dla ciebie żadnej zagadki. Życzę udanych konfiguracji i stabilnych połączeń.