Пик сезона? Пора ускоряться

-25 на резидентские прокси
–15% на резидентские прокси Light

Пик сезона? Пора ускоряться

Запасайтесь трафиком выгоднее! 

-25 на резидентские прокси
–15% на резидентские прокси Light
НАЧАТЬ

Как настроить прокси в Docker и контейнерах

Как настроить прокси в Docker и контейнерах

Краткий ответ

Для запросов приложения внутри контейнера передайте адрес прокси через переменные окружения или собственные настройки приложения. Для сетевых команд при сборке используйте аргументы сборки. Если не скачиваются сами образы, настройте Docker Engine либо прокси в Docker Desktop.

Начните с операции, которая должна работать через прокси: загрузка образа, установка зависимостей или обращение запущенного приложения к внешнему сервису. У этих операций разные источники настроек. Один файл с адресом сервера не задает маршрут сразу для всех трех.

Главное

  1. Параметры прокси для Docker Engine относятся к его собственным соединениям. Они не настраивают HTTP-клиент внутри приложения.
  2. Секцию proxies в клиентском config.json и одноименную секцию в daemon.json записывают по разным схемам.
  3. Пароль, записанный через ENV в Dockerfile, может остаться в образе. Настройки сборки и запуска лучше передавать отдельно.
  4. Успешная загрузка образа еще не показывает, как приложение отправляет запросы. Для этого нужна проверка из контейнера.

Где именно нужно указать прокси?

Укажите его тому компоненту, который открывает нужное соединение. Команда Docker может только поручать работу другому процессу: например, загрузку образа выполняет движок.

Что нужно направить через прокси
Где задать параметры
Чем проверить
Загрузку образа из реестра
Docker Engine на Linux или настройки Docker Desktop
Отдельной командой docker pull
Загрузку пакетов внутри RUN при сборке
Предопределенные аргументы прокси для сборки
Сборкой, которая действительно скачивает зависимости
HTTP-запросы работающего контейнера
Окружение контейнера или настройки HTTP-клиента
Запросом из самого приложения
HTTP-запросы сервиса Docker Compose
environment или env_file нужного сервиса
Новым запуском этого сервиса

Далее используются Linux-контейнеры и команды для Bash. Для варианта с системным Docker Engine нужны версия 23.0 или новее, Linux с systemd и доступ к настройкам службы. Docker Desktop рассматривается отдельно. Docker и Compose должны быть уже установлены.

В примерах proxy.example.com:3128 – вымышленный адрес. Замените его данными своего сервера. Для корпоративной сети это могут быть параметры, выданные администратором; для внешнего прокси – параметры действующего подключения. Покупать новый прокси для изменения конфигурации Docker не требуется.

Три независимые строки показывают настройку прокси для загрузки образа, команд сборки и запросов приложения.

Как подготовить адрес прокси и данные доступа?

Сначала уточните протокол подключения к серверу, его адрес, порт и способ авторизации. Имя HTTPS_PROXY описывает назначения HTTPS, но не требует схемы https:// у самого прокси. Если выдан обычный HTTP-прокси с поддержкой CONNECT, его адрес может начинаться с http:// в обеих переменных.

Схема https:// подходит, когда сервер действительно принимает защищенное соединение от клиента к прокси. Не меняйте ее только потому, что открываемый сайт использует HTTPS. SOCKS5 также требует поддержки со стороны конкретного клиента; далее разобрана конфигурация HTTP-прокси.

При Basic-авторизации через обычный HTTP-прокси соединение к нему не защищает пароль с помощью TLS. Если нужна защита этого участка, используйте поддерживаемое сервером и клиентом HTTPS-подключение к прокси.

Для одноразового контейнера и примера Compose создайте в рабочем каталоге файл proxy.env:

dotenv
http_proxy=http://proxy.example.com:3128
https_proxy=http://proxy.example.com:3128
HTTP_PROXY=http://proxy.example.com:3128
HTTPS_PROXY=http://proxy.example.com:3128
no_proxy=localhost,127.0.0.1,::1
NO_PROXY=localhost,127.0.0.1,::1

Здесь значения для двух регистров совпадают. Это полезно для программ с разными правилами чтения окружения: например, curl принимает http_proxy только в нижнем регистре. Само наличие переменных еще не заставляет любую программу их использовать.

Если сервер принимает логин и пароль в URL, общая форма будет такой:

text
http://USER:ENCODED_PASSWORD@proxy.example.com:3128

Замените обе условные части. Специальные символы кодируют отдельно в логине и пароле до сборки адреса: например, символ @ внутри пароля записывают как %40. Не кодируйте целиком URL вместе с разделителями. Применимость такого формата и метода авторизации зависит от клиента и прокси.

Файл proxy.env остается обычным текстом. Не добавляйте его в репозиторий или контекст сборки с реальными паролями. В Linux и macOS ограничьте чтение файла:

bash
chmod 600 proxy.env

Значения, переданные в окружение контейнера, доступны пользователям с правом его инспектировать. env_file не превращает их в секреты Docker. Для постоянного сервиса выбирайте механизм хранения учетных данных, который поддерживает само приложение.

Как настроить прокси для загрузки образов?

Если ошибка возникает на docker pull или при получении базового образа, начните с движка. Параметры будущего контейнера еще не участвуют в этой операции.

Docker Engine на Linux

Для системной службы Docker Engine 23.0+ добавьте секцию proxies в /etc/docker/daemon.json. Если файл уже существует, сохраните его копию и объедините настройки, оставив остальные ключи. Пример целого файла подходит только для конфигурации без других параметров:

json
{
  "proxies": {
    "http-proxy": "http://proxy.example.com:3128",
    "https-proxy": "http://proxy.example.com:3128",
    "no-proxy": "localhost,127.0.0.1,::1,registry.internal.example.com"
  }
}

Последнее имя – условный внутренний реестр, к которому предполагается прямое подключение. Замените его своим именем или удалите, если такого исключения нет. Не добавляйте Docker Hub в исключения, если доступ к нему как раз должен идти через прокси.

Проверьте конфигурацию без запуска второго движка:

bash
sudo dockerd --validate --config-file=/etc/docker/daemon.json

Проверка файла не устанавливает соединение с сервером. Если она прошла, примените настройки в подходящее для остановки службы время: перезапуск Docker может затронуть работающие контейнеры.

bash
sudo systemctl restart docker
docker pull curlimages/curl:latest

Конфигурация движка имеет приоритет над его переменными окружения. Не дублируйте одинаковые параметры в файле и аргументах запуска dockerd: такой конфликт может помешать запуску. Другой способ через окружение службы описан в официальной инструкции настройки прокси Docker Engine.

Для диагностики здесь используется latest. В рабочем проекте закрепите проверенный тег или digest образа. Если Docker подключен к удаленному движку, настройки и доступ к прокси проверяют на машине этого движка.

Docker Desktop

В Docker Desktop откройте Settings → VM resources → Proxies. Названия интерфейса здесь приведены на английском. В текущей документации настройки разделены на Docker Desktop proxy и Containers proxy; в более старой версии расположение элементов может отличаться.

Для загрузки образов проверьте Containers proxy. Выберите Same as host proxy, если нужен маршрут из настроек Docker Desktop proxy, либо Manual configuration и укажите свои адреса в полях Web Server (HTTP) и Secure Web Server (HTTPS). При системном корпоративном прокси используйте соответствующий режим System proxy.

Docker Desktop proxy обслуживает собственные обращения Desktop и служит резервным вариантом для загрузки образов, когда Containers proxy не настроен отдельно. Примените изменения и повторите команду загрузки образа из предыдущего подраздела. Параметры proxies из daemon.json Docker Desktop игнорирует.

Раздел Containers proxy также связан с исходящим трафиком работающих контейнеров при включенном корпоративном режиме принудительного ограничения сети. Такая политика отличается от передачи переменных отдельному приложению. Область действия режимов и авторизация описаны в настройках прокси Docker Desktop.

Как передать прокси при сборке образа?

Для команд RUN используйте предопределенные аргументы прокси. Они позволяют скачивать зависимости во время сборки, не записывая адрес через ENV в готовый образ.

Создайте отдельный пустой каталог для примера и поместите в него файл Dockerfile:

dockerfile
FROM debian:bookworm-slim

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

ENTRYPOINT ["curl"]
CMD ["-q", "--silent", "--show-error", "--fail", "--connect-timeout", "5", "--max-time", "20", "https://api.ipify.org?format=json"]

Он устанавливает curl и доверенные сертификаты из репозиториев Debian. Откройте Bash в этом каталоге и передайте параметры в сборку:

bash
export http_proxy='http://proxy.example.com:3128'
export https_proxy="$http_proxy"
export no_proxy='localhost,127.0.0.1,::1'

docker build \
  --build-arg http_proxy \
  --build-arg https_proxy \
  --build-arg no_proxy \
  -t docker-proxy-demo .

В этой форме Docker берет значения аргументов из текущего окружения. Если секреты уже переданы в окружение вашей системой запуска, используйте их вместо повторного ввода. Не оставляйте реальные пароли в истории команд.

Объявлять эти аргументы через ARG в Dockerfile не требуется. Docker документирует особую обработку предопределенных аргументов прокси: по умолчанию они исключены из истории образа и кеша сборки. Явное обращение к ним в Dockerfile меняет эту защиту. Утилита внутри RUN также может раскрыть значения, если вывести ее окружение или подробный журнал.

Не добавляйте ENV с паролем и не рассчитывайте убрать следы поздним обнулением переменной. Параметры запуска контейнера задайте отдельно, даже если сборка прошла успешно.

Для обычной локальной сборки загрузку FROM обслуживает инфраструктура Docker. Аргументы для RUN не исправляют ее доступ к реестру. При отдельном или удаленном BuildKit нужно также настроить сеть самого сервиса сборки; файл на ноутбуке не меняет окружение удаленного процесса.

Если зависимость уже взята из кеша, успешная сборка не показывает нового скачивания через прокси. Для повторной диагностики можно добавить —no-cache к команде сборки. Это повторит инструкции и потребует времени и сетевого трафика.

Как запустить контейнер с прокси и увидеть результат?

Передайте proxy.env при создании контейнера, а затем выполните запрос из него. Следующая команда использует ранее загруженный образ curl; флаг —pull=never отделяет проверку приложения от возможной новой загрузки образа:

bash
docker run --rm --pull=never \
  --env-file ./proxy.env \
  curlimages/curl:latest \
  -q --silent --show-error --fail \
  --connect-timeout 5 --max-time 20 \
  --write-out '\nproxy_used=%{proxy_used}\n' \
  'https://api.ipify.org?format=json'

Команду запускают из каталога с proxy.env. Для поля proxy_used требуется curl 8.7.0 или новее. Если образа нет локально, сначала вернитесь к его загрузке. Опция -q стоит первой среди аргументов curl и отключает чтение пользовательского файла настроек этой утилиты.

При успешном обращении внешний сервис ipify возвращает JSON с публичным IPv4, с которого он получил запрос. Это отдельный сервис, не инструмент MangoProxy. Строка proxy_used=1 указывает, что curl использовал прокси для этой передачи. При ошибке сначала разберите сообщение и код завершения: сама единица не подтверждает успешный ответ.

Не сравнивайте полученное значение с внутренним адресом контейнера: они выполняют разные роли. Адрес подключения к шлюзу тоже может отличаться от выходного IP, особенно при ротации. Совпадение с IP хоста само по себе не исключает локальный прокси с общим выходом в интернет.

Чтобы запустить собранный выше образ с тем же файлом, используйте:

bash
docker run --rm --pull=never --env-file ./proxy.env docker-proxy-demo

В нем curl уже задан командой запуска и вернет ответ ipify без дополнительной диагностической строки. Для настоящего проекта повторите нужную операцию в его HTTP-клиенте. Проверка утилитой curl внутри контейнера не подтверждает настройки Python, Node.js или браузера, работающих рядом.

Как сохранить значения для новых контейнеров?

Если один маршрут нужен многим запускам через Docker CLI, добавьте настройки в ~/.docker/config.json:

json
{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy.example.com:3128",
      "httpsProxy": "http://proxy.example.com:3128",
      "noProxy": "localhost,127.0.0.1,::1"
    }
  }
}

При существующем файле сохраните остальные настройки, включая auths и credsStore. Обратите внимание на имена: клиент использует httpProxy, а движок – http-proxy. Вставлять одну секцию вместо другой нельзя.

Клиентский файл снабжает окружением новые контейнеры и аргументами новые сборки. Он не настраивает соединения самого движка и не меняет уже созданные контейнеры. Перезапуск Docker для этого файла не нужен. Правила и ограничения приведены в документации клиентской конфигурации прокси.

Как настроить прокси в Docker Compose?

Добавьте env_file только тем сервисам, которым нужен этот маршрут. Файл .env сам по себе обычно служит источником подстановок Compose; его наличие рядом с compose.yaml не передает все значения в контейнер автоматически.

Для повторения проверки сохраните рядом с proxy.env файл compose.yaml. Этот вариант требует Docker Compose 2.30.0 или новее:

yaml
services:
  probe:
    image: curlimages/curl:latest
    pull_policy: never
    env_file:
      - path: ./proxy.env
        format: raw
    command:
      - -q
      - --silent
      - --show-error
      - --fail
      - --connect-timeout
      - '5'
      - --max-time
      - '20'
      - --write-out
      - '\nproxy_used=%{proxy_used}\n'
      - 'https://api.ipify.org?format=json'

Режим raw сохраняет значения файла без подстановок Compose, в том числе символы доллара. В показанном proxy.env кавычек вокруг значений нет. При обычном env_file правила разбора другие; варианты описаны в справке Compose по env_file.

Проверьте синтаксис без вывода раскрытой конфигурации, затем создайте одноразовый контейнер:

bash
docker compose version
docker compose config --quiet
docker compose run --rm probe

Образ должен быть уже загружен. Здесь используется готовый image, поэтому настройки сборки отсутствуют. Для собственного сервиса с build параметры для RUN передают через build.args, а окружение работающего сервиса – через environment или env_file.

Если одно имя задано и в environment, и в env_file, учитывайте приоритет environment. Для существующего долгоживущего сервиса изменение файла требует пересоздания контейнера; обычный restart не загружает новое окружение. Перед пересозданием сохраните нужные данные в предусмотренных для приложения томах или внешнем хранилище.

Как подключиться к прокси на хосте или в соседнем контейнере?

Используйте адрес, доступный из сети контейнера. В обычной изолированной сети localhost внутри контейнера указывает на сам контейнер. Если прокси запущен на компьютере с Docker, адрес localhost:3128 может обращаться совсем не к тому процессу.

В Docker Desktop для доступа к хосту предусмотрено имя host.docker.internal. На обычном Linux Engine соответствие можно добавить при запуске. Следующий пример применим, только если на хосте уже работает доступный контейнеру HTTP-прокси на порту 3128:

bash
docker run --rm --pull=never \
  --add-host=host.docker.internal:host-gateway \
  curlimages/curl:latest \
  -q --silent --show-error --fail \
  --connect-timeout 5 --max-time 20 \
  --proxy 'http://host.docker.internal:3128' \
  --noproxy '' \
  'https://api.ipify.org?format=json'

Пустое значение —noproxy здесь отменяет исключения curl для этого отдельного запроса. Сопоставление host-gateway дает адрес хоста, но не меняет интерфейс, на котором слушает прокси, и не открывает порт в межсетевом экране. Эти условия проверяют отдельно. Механизм описан в справке Docker по доступу к хосту.

Если прокси работает в соседнем сервисе Compose, подключите оба сервиса к общей пользовательской сети и обращайтесь по имени сервиса и внутреннему порту, например proxy:3128. Публиковать его порт на хост только ради такого соединения не требуется. Этот адрес подходит контейнеру приложения; движок, скачивающий образы, не получает автоматически тот же доступ по имени сервиса.

Для внутренних HTTP-сервисов добавьте их реальные имена в no_proxy и NO_PROXY. Пример localhost не исключает соседний сервис internal-api. Правила сопоставления доменов и сетевых диапазонов зависят от клиента, поэтому для короткого списка лучше начать с точных имен, используемых приложением.

Практический пример: почему ошибка меняется после каждого исправления?

Рассмотрим условный случай: команда запуска не может скачать образ, после настройки движка сборка останавливается на установке пакетов, а затем уже запущенное приложение обращается к API напрямую. Это три последовательные проблемы с разными владельцами настроек, а не один сбой, который «возвращается».

Сначала команда загрузки должна получить доступ к реестру. На этом этапе изменение env_file приложения ничего не исправит: контейнер еще не создан. Успех фиксируют для операции загрузки, не для будущего HTTP-запроса.

Затем сборка должна выполнить сетевую команду RUN. Если базовый образ уже доступен, а пакетный менеджер не может скачать зависимости, проверьте переданные аргументы прокси и правила самого менеджера. Кешированная строка сборки не заменяет это наблюдение.

Наконец, приложение запускают с нужным окружением и проверяют его исходящую операцию. Если curl использует прокси, а приложение нет, проверьте поддержку переменных в его библиотеке и явные настройки клиента. Для внешнего адреса и внутреннего сервиса могут требоваться разные маршруты.

К этому разбору полезно приложить название стадии, время ошибки и сообщение без учетных данных. Полный вывод окружения или docker inspect с паролями для этого не нужен.

Что проверить при ошибках авторизации и сертификата?

Проверьте доступ к самому прокси отдельно от ответа целевого сервиса. Завершающий ошибкой ответ 407 относится к авторизации на прокси; docker login решает другую задачу – вход в реестр образов. Проверьте метод авторизации, выданный логин, кодирование пароля и разрешенный исходящий адрес.

При авторизации по списку IP обычно нужен публичный адрес, с которого к прокси приходит соединение Docker-хоста. Внутренний адрес контейнера вида 172.17.x.x не становится автоматически видимым внешнему прокси. Для удаленного движка или корпоративного шлюза исходящий адрес может отличаться от адреса вашего ноутбука.

Если соединение не устанавливается, начните с доступности адреса и порта из нужной среды. Ответ сайта 403 после установления туннеля относится уже к последующему обмену и не равен ошибке пароля прокси.

При проверке HTTPS в корпоративной сети возможна ошибка недоверенного сертификата. Если сеть намеренно проверяет защищенный трафик, утвержденный корневой сертификат может понадобиться и хосту Docker, и образу или приложению. Установка доверия только в браузере хоста не настраивает хранилище внутри контейнера. Используйте инструкцию Docker по доверенным CA-сертификатам; отключение проверки TLS скрывает проблему доверия и не исправляет маршрут.

Примеры кода в статье приведены для демонстрации. Они могут работать иначе или не запускаться из-за настроек вашей среды, версий программ и библиотек или изменений в используемых сервисах и API. Перед использованием проверьте примеры в своей среде и при необходимости адаптируйте их.

Проверьте адрес, который получил внешний сервис

Если нужно узнать больше о полученном IP, скопируйте адрес из ответа контейнера в Поиск информации по IP MangoProxy. Такой поиск рассматривает указанный адрес отдельно от подключения браузера. Сведения базы об адресе дополняют проверку, но не показывают маршрут всех запросов приложения.

Для следующего шага сохраните рабочие настройки именно нужного сервиса и повторите его обычную операцию. Если используете подключение MangoProxy, переносите действующие адрес, порт и данные авторизации без замены их условными значениями из примеров.

Глоссарий

Контейнер: изолированная среда запуска процессов с собственной файловой системой и сетевыми настройками.

Образ: подготовленные слои файлов и параметры, из которых создают контейнер.

Демон Docker (dockerd): фоновая служба Docker, которая управляет контейнерами, образами, сетями и томами.

Реестр образов: сервер хранения и выдачи образов контейнеров.

Dockerfile: файл инструкций для сборки образа.

Аргумент сборки: значение, передаваемое процессу сборки отдельно от постоянного окружения образа.

BuildKit: механизм выполнения сборок образов, который может работать отдельным сервисом.

Docker Compose: средство описания и запуска связанных сервисов по файлу конфигурации.

Переменная окружения: именованное строковое значение, доступное процессу.

HTTP / HTTPS: протокол веб-запросов и его вариант с защитой соединения.

CONNECT: метод HTTP для создания туннеля через прокси к указанному серверу.

TLS: протокол защиты соединения, используемый HTTPS.

CA: центр сертификации; доверие к его сертификату участвует в проверке сертификатов соединения.

SOCKS5: протокол подключения к назначениям через прокси, поддержку которого должен обеспечивать клиент.

URL: адрес ресурса или подключения со схемой, именем сервера и другими компонентами.

IP / IPv4: сетевой адрес и четвертая версия протокола IP.

API: программный интерфейс сервиса для выполнения определенных запросов.

JSON / YAML: текстовые форматы данных и конфигурации, использованные в примерах.

Кеш сборки: сохраненные результаты этапов, которые позволяют не выполнять их заново.

Digest образа: идентификатор содержимого образа, позволяющий закрепить конкретную версию.

Итоги

Считайте настройку завершенной для нужной операции: образ скачивается, зависимости устанавливаются или приложение получает ответ через выбранный прокси. При переносе проекта на другую машину сохраните это разделение. Оно позволяет понять, какой файл относится к новому сбою, и проверить изменение без ненужной перенастройки остальных компонентов.

Часто задаваемые вопросы

Здесь мы ответили на самые часто задаваемые вопросы. Все равно не можешь найти ответа?

Задать вопрос

Можно ли гарантировать через HTTP_PROXY, что контейнер никогда не выйдет напрямую?

Нет. Программа может игнорировать переменную или выбрать прямой маршрут по исключению. Для запрета обхода нужны сетевые ограничения и проверенная архитектура выхода. Окружение приложения само по себе такой запрет не создает.

Нужно ли публиковать порт контейнера для исходящего подключения к прокси?

Обычно нет. Публикация порта нужна, чтобы принимать обращения к контейнеру с хоста или извне. Исходящее подключение к уже доступному прокси не требует открывать входящий порт приложения.

Прокси с ротацией выдаст каждому контейнеру постоянный отдельный IP?

Не обязательно. Запуск отдельного контейнера не задает правила ротации провайдера. Если нужен устойчивый адрес для задачи, проверьте режим сессии или используйте подходящее подключение с фиксированным IP. Одинаковый адрес шлюза не означает одинаковый результат всех обращений.

Можно ли применить эти команды к rootless Docker без изменений?

Для настройки самого движка – нет. Rootless Docker работает как пользовательская служба и использует другие пути конфигурации и команды управления. Настройки окружения приложения сохраняют тот же смысл, но системный перезапуск из примера не управляет пользовательской службой.

Как отменить настройку прокси?

Удалите только добавленные параметры из того источника, где их задали. Для движка примените обновленную конфигурацию службы, для приложения создайте новый контейнер без этих значений. Проверьте также клиентский config.json, environment в Compose и окружение самого образа: один источник может снова передать значения после удаления другого.

★ ★ ★ ★ ★

Оставить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *