Використання проксі з менеджерами пакетів

Щоб використовувати проксі з менеджерами пакетів, такими як npm, pip та composer, налаштуйте параметри проксі або через змінні середовища (HTTP_PROXY, HTTPS_PROXY), аргументи командного рядка, або спеціальні файли конфігурації, унікальні для кожного менеджера пакетів.

Багато середовищ розробки працюють за корпоративними брандмауерами або вимагають моніторингу трафіку, що зумовлює необхідність використання HTTP або HTTPS проксі-сервера для вихідних з'єднань. Менеджери пакетів, які завантажують залежності із зовнішніх реєстрів, повинні бути налаштовані на маршрутизацію своїх мережевих запитів через такі проксі для коректної роботи.

Загальні концепції конфігурації проксі

Проксі-сервери можуть перехоплювати та пересилати HTTP та HTTPS трафік. Для доступу до цих проксі часто потрібна автентифікація.

Формат URL проксі

Стандартний формат URL проксі, включаючи необов'язкову автентифікацію, виглядає так:

protocol://[user:password@]host:port

• protocol: http або https
• user:password: Необов'язкові облікові дані для автентифікації проксі.
• host: Ім'я хоста або IP-адреса проксі-сервера.
• port: Порт, який прослуховує проксі-сервер (наприклад, 8080, 3128).

Приклад: http://user:password@proxy.example.com:8080

Змінні середовища

Найпоширеніший і часто універсально визнаний метод конфігурації проксі для різних інструментів, включаючи менеджери пакетів, – це використання стандартних змінних середовища.

• HTTP_PROXY або http_proxy: Вказує проксі-сервер для HTTP-запитів.
• HTTPS_PROXY або https_proxy: Вказує проксі-сервер для HTTPS-запитів.
• NO_PROXY або no_proxy: Список імен хостів, доменів або IP-адрес, розділених комами, які повинні обходити проксі. Це має вирішальне значення для прямого доступу до внутрішніх ресурсів або локальних серверів розробки.

Ці змінні зазвичай нечутливі до регістру в Windows, але чутливі до регістру в Unix-подібних системах. Звичайною практикою є встановлення як UPPER_CASE, так і lower_case версій для максимальної сумісності.

# Приклад для Unix-подібних систем (Linux, macOS)
export HTTP_PROXY="http://user:password@proxy.example.com:8080"
export HTTPS_PROXY="http://user:password@proxy.example.com:8080" # Часто такий самий, як HTTP_PROXY
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"

# Для командного рядка Windows
set HTTP_PROXY=http://user:password@proxy.example.com:8080
set HTTPS_PROXY=http://user:password@proxy.example.com:8080
set NO_PROXY=localhost,127.0.0.1,.internal.domain.com

# Для Windows PowerShell
$env:HTTP_PROXY="http://user:password@proxy.example.com:8080"
$env:HTTPS_PROXY="http://user:password@proxy.example.com:8080"
$env:NO_PROXY="localhost,127.0.0.1,.internal.domain.com"

npm (Менеджер пакетів Node)

npm можна налаштувати за допомогою його вбудованої системи конфігурації або змінних середовища.

Конфігурація через npm config

Кращим методом для npm є встановлення параметрів проксі безпосередньо в його конфігурації. Це зберігає налаштування постійно.

# Встановити HTTP проксі
npm config set proxy http://user:password@proxy.example.com:8080

# Встановити HTTPS проксі (часто такий самий, як HTTP проксі)
npm config set https-proxy http://user:password@proxy.example.com:8080

# Щоб скасувати проксі
npm config rm proxy
npm config rm https-proxy

# Перевірити налаштування
npm config get proxy
npm config get https-proxy

Якщо ваш проксі не вимагає автентифікації, опустіть сегмент user:password@.

Проблеми з SSL-сертифікатами

При використанні HTTPS проксі або HTTPS реєстру через HTTP проксі, npm може зіткнутися з проблемами перевірки SSL-сертифікатів. Це може статися, якщо проксі перехоплює та повторно шифрує HTTPS трафік власним сертифікатом, якому ваша система не довіряє.

Щоб вирішити цю проблему, ви можете:
1. Додати сертифікат ЦС проксі до сховища довірених сертифікатів вашої системи. Це рекомендований безпечний підхід.
2. Вказати npm використовувати певний файл сертифіката ЦС:
bash npm config set cafile /path/to/proxy/ca-certificate.pem
3. Вимкнути сувору перевірку SSL (не рекомендується для виробництва):
bash npm config set strict-ssl false
Це обходить перевірку сертифіката і може піддати вас атакам "людина посередині". Використовуйте лише для тимчасового налагодження в контрольованих середовищах.

Конфігурація реєстру

Якщо ваша організація використовує приватний реєстр npm (наприклад, Nexus, Artifactory), який доступний безпосередньо або через інший проксі, переконайтеся, що налаштування registry правильне.

npm config set registry https://my-private-registry.example.com/npm/

pip (Інсталятор пакетів Python)

pip підтримує конфігурацію проксі через прапори командного рядка, змінні середовища або файл конфігурації.

Прапор командного рядка

Для однієї команди pip використовуйте прапор --proxy:

pip install some-package --proxy http://user:password@proxy.example.com:8080

Файл конфігурації

Для постійних налаштувань проксі змініть або створіть файл конфігурації pip.
* Linux/macOS: ~/.config/pip/pip.conf або ~/.pip/pip.conf
* Windows: %APPDATA%\pip\pip.ini або %HOME%\pip\pip.ini

Додайте наступне до розділу [global]:

# ~/.config/pip/pip.conf або %APPDATA%\pip\pip.ini
[global]
proxy = http://user:password@proxy.example.com:8080

Змінні середовища

pip враховує стандартні змінні середовища HTTP_PROXY, HTTPS_PROXY та NO_PROXY. Якщо вони встановлені, вони будуть використовуватися автоматично.

export HTTP_PROXY="http://user:password@proxy.example.com:8080"
export HTTPS_PROXY="http://user:password@proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"
pip install some-package

Проблеми з SSL-сертифікатами

Подібно до npm, pip може зіткнутися з помилками SSL.
1. Додайте сертифікат ЦС проксі до сховища довірених сертифікатів системи.
2. Вкажіть довірений хост для індексу:
ini # ~/.config/pip/pip.conf або %APPDATA%\pip\pip.ini [global] trusted-host = pypi.org
Це вказує pip довіряти вказаному хосту, навіть якщо перевірка SSL для нього не вдається. Використовуйте з обережністю.
3. Вкажіть власний пакет ЦС:
ini # ~/.config/pip/pip.conf або %APPDATA%\pip\pip.ini [global] cert = /path/to/proxy/ca-bundle.pem
Або через командний рядок: pip install some-package --cert /path/to/proxy/ca-bundle.pem

Приватні індекси пакетів

Якщо використовується приватний індекс пакетів Python (наприклад, Artifactory, Nexus), налаштуйте index-url або extra-index-url:

# ~/.config/pip/pip.conf або %APPDATA%\pip\pip.ini
[global]
index-url = https://my-private-pypi.example.com/simple/

Composer (Менеджер залежностей PHP)

Composer значною мірою покладається на змінні середовища для конфігурації проксі, а також може потребувати налаштувань проксі Git для репозиторіїв, отриманих через Git.

Змінні середовища

Composer переважно використовує стандартні змінні середовища HTTP_PROXY, HTTPS_PROXY та NO_PROXY.

export HTTP_PROXY="http://user:password@proxy.example.com:8080"
export HTTPS_PROXY="http://user:password@proxy.example.com:8080"
export NO_PROXY="localhost,127.0.0.1,.internal.domain.com"
composer install

Конфігурація Composer (config.json)

Хоча Composer не має прямого налаштування proxy у своєму config.json для загального HTTP/HTTPS трафіку, можна налаштувати параметри проксі для конкретних репозиторіїв VCS, якщо вони не підхоплюються змінними середовища або якщо потрібні різні проксі.

Наприклад, щоб налаштувати проксі для Git:

{
    "config": {
        "github-oauth": {
            "github.com": "YOUR_OAUTH_TOKEN"
        }
    }
}

Це не пряме налаштування проксі, але демонструє, куди можуть йти інші мережеві конфігурації. Для фактичного проксіювання Git дивіться наступний розділ.

Конфігурація проксі Git

Composer часто отримує пакети безпосередньо з репозиторіїв Git (наприклад, GitHub, GitLab). Якщо ваш трафік Git має проходити через проксі, ви повинні налаштувати сам Git.

# Встановити HTTP проксі для Git
git config --global http.proxy http://user:password@proxy.example.com:8080

# Встановити HTTPS проксі для Git
git config --global https.proxy http://user:password@proxy.example.com:8080

# Щоб скасувати
git config --global --unset http.proxy
git config --global --unset https.proxy

# Перевірити
git config --global --get http.proxy
git config --global --get https.proxy

Це особливо важливо, якщо ваш composer.json використовує репозиторії vcs або прямі URL-адреси Git.

Проблеми з SSL-сертифікатами

Composer, як і інші інструменти, може зіткнутися з проблемами SSL.
1. Додайте сертифікат ЦС проксі до сховища довірених сертифікатів системи.
2. Налаштуйте Git для вимкнення перевірки SSL (не рекомендується):
bash git config --global http.sslVerify false
Це має бути останній засіб і використовуватися з надзвичайною обережністю.

Усунення поширених проблем з проксі

• Неправильна адреса/порт проксі: Двічі перевірте ім'я хоста, IP-адресу та порт. Поширена помилка – використання HTTP для HTTPS проксі або навпаки.
• Помилка автентифікації: Переконайтеся, що ім'я користувача та пароль в URL проксі правильні та URL-кодовані, якщо вони містять спеціальні символи.
• Помилки SSL-сертифікатів: Якщо ви зустрічаєте SSL_ERROR_SYSCALL, certificate verify failed або подібні помилки, ваш проксі може виконувати перехоплення SSL. Встановіть кореневий сертифікат ЦС проксі до сховища довірених сертифікатів вашої системи або налаштуйте менеджер пакетів довіряти певному пакету ЦС (як описано вище).
• Проблеми з NO_PROXY: Якщо внутрішні служби все ще намагаються пройти через проксі, перевірте, чи правильне та вичерпне ваше налаштування NO_PROXY. Переконайтеся, що воно включає localhost, 127.0.0.1 та будь-які відповідні суфікси внутрішніх доменів.
• Блокування брандмауером: Переконайтеся, що брандмауер вашої машини або групи мережевої безпеки дозволяють вихідні з'єднання до IP-адреси та порту проксі-сервера.
• Змішана конфігурація HTTP/HTTPS: Деякі проксі обробляють HTTP та HTTPS по-різному. Переконайтеся, що ви налаштували як HTTP_PROXY, так і HTTPS_PROXY, якщо це застосовно, або їхні еквіваленти для конкретного менеджера пакетів.

Порівняння методів конфігурації проксі